README

   1 catalyst is released under the GNU General Public License version 2,
   2 and is copyright Gentoo Technologies, Inc. Will be adding official
   3 COPYING file and source file preambles soon.
   4
   5 How do I use this thing?
   6 ========================
   7
   8 Here's how you use catalyst. These instructions are for people using
   9 the cvs version of catalyst, not the to-be-created ebuild version.
  10
  11 First, check out the gentoo/src/catalyst tree (which I'm guessing you
  12 have done.) Then, create an /etc/catalyst.conf file that looks like
  13 this:
  14
  15 distdir="/mnt/misc/distfiles"
  16 options="ccache pkgcache"
  17 sharedir="/home/drobbins/cvs/gentoo/src/catalyst"
  18
  19 The "sharedir" variable tells catalyst where to find its various
  20 plugins, and should point to the main catalyst directory that you
  21 checked out. the "options" variable is used to turn on .tbz2 package
  22 caching, which is off by default (you'll likely want it on, however.)
  23 Also, "distdir" is used here to tell catalyst where to look/store
  24 distfiles. The default is "/usr/portage/distfiles".
  25
  26 Here are other variables you can set, and their default values.
  27 Please remember that *strings must be quoted*, as /etc/catalyst.conf
  28 uses python syntax:
  29
  30 storedir        /var/tmp/catalyst               (where to build/write stuff)
  31 sharedir        /usr/share/catalyst             (where our plugins/scripts are)
  32 distdir         /usr/portage/distfiles          (where our distfiles are)
  33 portdir         /usr/portage                    (where to grab snapshots from)
  34 options         ccache                          what catalyst options are enabled
  35
  36 You may also want to create a /usr/bin/catalyst symlink that points
  37 to the real location of your catalyst executable script.
  38
  39 Creating a Portage tree snapshot
  40 ================================
  41
  42 First, make sure that your Portage tree is up-to-date as of 06 Nov 2003
  43 at the earliest, and that portage-2.0.49-r15 or 16 is unmasked for your
  44 specific build. These ebuilds (as of 06 Nov 2003) contain important fixes
  45 to allow catalyst to build properly. If you're not using the default-x86-1.4
  46 profile for building, please take a look at this profile and ensure that
  47 you are relatively in-sync with it. In particular, make sure that the
  48 GRP_STAGE23_USE variable is set in make.defaults, since catalyst uses
  49 this variable for building stage2 and stage3.
  50
  51 Before building anything, you need to generate a snapshot of the portage
  52 tree that catalyst should use for building. To do this, ensure that your
  53 to-be-snapshotted portage tree is at /usr/portage, or set the "portdir"
  54 variable in /etc/catalyst.conf to point to the appropriate location, and
  55 then type:
  56
  57 # catalyst target=snapshot version_stamp=20031102
  58
  59 This will create the following file, assuming a /var/tmp/catalyst "storedir"
  60 setting:
  61
  62 /var/tmp/catalyst/snapshots/portage-20031102.tar.bz2
  63
  64 Grabbing a "seed" stage
  65 =======================
  66
  67 Now, you need to grab a "seed" stage1, 2 or 3 tarball from somewhere to
  68 use to build other stages. Put the stage in /var/tmp/catalyst/builds/<profile>/;
  69
  70 For example, if I have a stage3-pentium4-20031102.tar.bz2 file, I'd put it in:
  71
  72 /var/tmp/catalyst/builds/default-x86-1.4/stage3-pentium4-20031102.tar.bz2
  73
  74 ...since that pentium4 stage was built using the "default-x86-1.4" profile.
  75
  76 Building your first stage
  77 =========================
  78
  79 Once you have your seed stage, you're now ready to build your first new stage.
  80 Here is a guideline for what components you'll need to build each type of stage:
  81
  82 stage1 requires "generic" (ie. "x86" or "ppc") stage2 or 3
  83
  84 stage2 requires "generic" stage1 (the only kind you should have :)
  85
  86 stage3 requires stage2 of same type (ie. to build a "pentium3" stage3, you need
  87 a "pentium3" stage2, etc.)
  88
  89 ** Currently, only "stage1", "stage2" and "stage3" targets are supported. **
  90
  91 Of course, to build each stage you will also need the Portage tree snapshot
  92 that you created above.
  93
  94 To build a stage, type a command like this:
  95
  96 # catalyst subarch=x86 version_stamp=20031102 target=stage2 rel_type=default rel_version=1.4 snapshot=20031102 source_subpath=default-x86-1.4/stage1-x86-20031102
  97
  98 Wow -- that's a huge command! What does it mean? Let's look at the various arguments:
  99
 100 cmdline arg                     meaning
 101 -----------                     -------
 102 subarch=x86                     build "generic" x86 stage (could also be "pentium3", "athlon-xp", "g4", etc.)
 103 version_stamp=20031102          give this stage being built a version stamp of "20031102"
 104 target=stage2                   the type of stage we want to build is a stage2
 105 rel_type=default                use a "default-<mainarch>-??" profile (other possibilities: "hardened", etc.)
 106 rel_version=1.4                 use a "??-<mainarch>-1.4" profile (note: mainarch is auto-determined from the subarch you provide)
 107 snapshot=20031102               use the Portage tree snapshot you created that has the "20031102" version_stamp
 108 source_subpath=default-x86-1.4/stage1-x86-20031102
 109                                 To build our stage2, use a stage1 found at /var/tmp/catalyst/builds/ + this path. You are responsible
 110                                 for ensuring that you choose an appopriate source stage for building your desired target stage.
 111
 112 After you type this command, building should begin, and hopefully complete
 113 successfully, at which point the following tarball will be created:
 114
 115 /var/tmp/catalyst/builds/default-x86-1.4/stage2-x86-20031102.tar.bz2
 116
 117 The build directory used to build this stage can be found at:
 118
 119 /var/tmp/catalyst/tmp/default-x86-1.4/stage2-x86-20031102/
 120
 121 Building x86 stages on amd64
 122 ============================
 123
 124 Catalyst currently supports building x86 stages on 64-bit AMD64 systems. To do
 125 this, simply use as you would on x86, but ensure that the linux32 ebuild is
 126 emerged before starting. Catalyst will detect that you are building a 32-bit
 127 stage and will use the linux32 tool automatically when setting up chroots.
 128 Everything should work identically to if you were using a 32-bit system.
 129
 130 Questions, bug reports:
 131 drobbins@gentoo.org