diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 131 |
1 files changed, 131 insertions, 0 deletions
@@ -0,0 +1,131 @@ +catalyst is released under the GNU General Public License version 2, +and is copyright Gentoo Technologies, Inc. Will be adding official +COPYING file and source file preambles soon. + +How do I use this thing? +======================== + +Here's how you use catalyst. These instructions are for people using +the cvs version of catalyst, not the to-be-created ebuild version. + +First, check out the gentoo/src/catalyst tree (which I'm guessing you +have done.) Then, create an /etc/catalyst.conf file that looks like +this: + +distdir="/mnt/misc/distfiles" +options="ccache pkgcache" +sharedir="/home/drobbins/cvs/gentoo/src/catalyst" + +The "sharedir" variable tells catalyst where to find its various +plugins, and should point to the main catalyst directory that you +checked out. the "options" variable is used to turn on .tbz2 package +caching, which is off by default (you'll likely want it on, however.) +Also, "distdir" is used here to tell catalyst where to look/store +distfiles. The default is "/usr/portage/distfiles". + +Here are other variables you can set, and their default values. +Please remember that *strings must be quoted*, as /etc/catalyst.conf +uses python syntax: + +storedir /var/tmp/catalyst (where to build/write stuff) +sharedir /usr/share/catalyst (where our plugins/scripts are) +distdir /usr/portage/distfiles (where our distfiles are) +portdir /usr/portage (where to grab snapshots from) +options ccache what catalyst options are enabled + +You may also want to create a /usr/bin/catalyst symlink that points +to the real location of your catalyst executable script. + +Creating a Portage tree snapshot +================================ + +First, make sure that your Portage tree is up-to-date as of 06 Nov 2003 +at the earliest, and that portage-2.0.49-r15 or 16 is unmasked for your +specific build. These ebuilds (as of 06 Nov 2003) contain important fixes +to allow catalyst to build properly. If you're not using the default-x86-1.4 +profile for building, please take a look at this profile and ensure that +you are relatively in-sync with it. In particular, make sure that the +GRP_STAGE23_USE variable is set in make.defaults, since catalyst uses +this variable for building stage2 and stage3. + +Before building anything, you need to generate a snapshot of the portage +tree that catalyst should use for building. To do this, ensure that your +to-be-snapshotted portage tree is at /usr/portage, or set the "portdir" +variable in /etc/catalyst.conf to point to the appropriate location, and +then type: + +# catalyst target=snapshot version_stamp=20031102 + +This will create the following file, assuming a /var/tmp/catalyst "storedir" +setting: + +/var/tmp/catalyst/snapshots/portage-20031102.tar.bz2 + +Grabbing a "seed" stage +======================= + +Now, you need to grab a "seed" stage1, 2 or 3 tarball from somewhere to +use to build other stages. Put the stage in /var/tmp/catalyst/builds/<profile>/; + +For example, if I have a stage3-pentium4-20031102.tar.bz2 file, I'd put it in: + +/var/tmp/catalyst/builds/default-x86-1.4/stage3-pentium4-20031102.tar.bz2 + +...since that pentium4 stage was built using the "default-x86-1.4" profile. + +Building your first stage +========================= + +Once you have your seed stage, you're now ready to build your first new stage. +Here is a guideline for what components you'll need to build each type of stage: + +stage1 requires "generic" (ie. "x86" or "ppc") stage2 or 3 + +stage2 requires "generic" stage1 (the only kind you should have :) + +stage3 requires stage2 of same type (ie. to build a "pentium3" stage3, you need +a "pentium3" stage2, etc.) + +** Currently, only "stage1", "stage2" and "stage3" targets are supported. ** + +Of course, to build each stage you will also need the Portage tree snapshot +that you created above. + +To build a stage, type a command like this: + +# 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 + +Wow -- that's a huge command! What does it mean? Let's look at the various arguments: + +cmdline arg meaning +----------- ------- +subarch=x86 build "generic" x86 stage (could also be "pentium3", "athlon-xp", "g4", etc.) +version_stamp=20031102 give this stage being built a version stamp of "20031102" +target=stage2 the type of stage we want to build is a stage2 +rel_type=default use a "default-<mainarch>-??" profile (other possibilities: "hardened", etc.) +rel_version=1.4 use a "??-<mainarch>-1.4" profile (note: mainarch is auto-determined from the subarch you provide) +snapshot=20031102 use the Portage tree snapshot you created that has the "20031102" version_stamp +source_subpath=default-x86-1.4/stage1-x86-20031102 + To build our stage2, use a stage1 found at /var/tmp/catalyst/builds/ + this path. You are responsible + for ensuring that you choose an appopriate source stage for building your desired target stage. + +After you type this command, building should begin, and hopefully complete +successfully, at which point the following tarball will be created: + +/var/tmp/catalyst/builds/default-x86-1.4/stage2-x86-20031102.tar.bz2 + +The build directory used to build this stage can be found at: + +/var/tmp/catalyst/tmp/default-x86-1.4/stage2-x86-20031102/ + +Building amd64 stages on x86 +============================ + +Catalyst currently supports building x86 stages on 64-bit AMD64 systems. To do this, +simply use as you would on x86, but ensure that the linux32 ebuild is emerged before +starting. Catalyst will detect that you are building a 32-bit stage and will use the +linux32 tool automatically when setting up chroots. Everything should work identically +to if you were using a 32-bit system. + +Questions, bug reports: +drobbins@gentoo.org |