Catalyst is a release-buildcing tool for Gentoo. If you use Gentoo and want to roll your own live CD or bootable USB stick, this is the way to go. First, get a Gentoo development box and install the necessary tools: # emerge -av dev-util/catalyst Configure catalyst by editing `/etc/catalyst/catalyst.conf`, which is well commented. This sets up defaults such as hashing algorithms and storage directories. The defaults will probably be fine unless disk space is an issue. Assembling a starting point --------------------------- Portage snapshot ~~~~~~~~~~~~~~~~ Create a snapshot of your current Portage tree (you may want to `emerge --sync` first): # catalyst --snapshot 20130131 # ls /var/tmp/catalyst/snapshots/ portage-20130131.tar.bz2 portage-20130131.tar.bz2.CONTENTS portage-20130131.tar.bz2.DIGESTS where the storage location is relative to the default `$storedir=/var/tmp/catalyst`. Stage3 tarball ~~~~~~~~~~~~~~ Get a stage3 tarball (containing the build tools you'll need to construct your stage1) from your local http://www.gentoo.org/main/en/mirrors.xml[Gentoo mirror]. $GENTOO_MIRROR/releases/$ARCH/current-stage3/ For example, http://distfiles.gentoo.org/releases/amd64/current-stage3/stage3-amd64-20121213.tar.bz2 Grab the tarball and put it where catalyst will find it: # wget http://…/stage3-amd64-20121213.tar.bz2 # wget http://…/stage3-amd64-20121213.tar.bz2.CONTENTS # wget http://…/stage3-amd64-20121213.tar.bz2.DIGESTS.asc # sha512sum -c stage3-amd64-20121213.tar.bz2.DIGESTS.asc # gpg --verify stage3-amd64-20121213.tar.bz2.DIGESTS.asc # mv stage3-amd64-20121213.tar.bz2* /var/tmp/catalyst/builds/default/ where the storage dir is `$storedir/builds/$source_subpath` (`$storedir` from `catalyst.conf`, `$source_subpath` from your `*.spec` file). `.*spec` files ~~~~~~~~~~~~~~ `.*spec` files tell catalyst about the system you're trying to build. There are a number of examples distributed with catalyst. Look in `/usr/share/doc/catalyst-*/examples/`. A minimal `*.spec` file for this example is: # cat default-stage1-amd64-2013.1.spec subarch: amd64 version_stamp: 2013.1 target: stage1 rel_type: default profile: default/linux/amd64/10.0/no-multilib snapshot: 20130131 source_subpath: default/stage3-amd64-20121213 You may need to adjust the `subarch`, `snapshot`, and `source_subpath` fields of the `*.spec` to match your target host, Portage snapshot, and stage3 tarball name respectively. For more details on what can go into a `*.spec` file, see `catalyst-spec(5)`. Building stage1 --------------- Now that everything's setup, run catalyst: # catalyst -f default-stage1-amd64-2013.1.spec which will build the target and install something like: # ls /var/tmp/catalyst/builds/default/stage1-amd64-2013.1.* /var/tmp/catalyst/builds/default/stage1-amd64-2013.1.tar.bz2 /var/tmp/catalyst/builds/default/stage1-amd64-2013.1.tar.bz2.CONTENTS /var/tmp/catalyst/builds/default/stage1-amd64-2013.1.tar.bz2.DIGESTS The name is an expansion of `$storedir/builds/$rel_type/$target-$subarch-$version_stamp…`. Building stage2 and stage3 -------------------------- Once you've built the stage1 from your seed stage3, you can use that stage1 to build a stage2 and stage3. The `*.spec` files are similar: $ diff -u default-stage{1,2}-amd64-2013.1.spec --- default-stage1-amd64-2013.1.spec +++ default-stage2-amd64-2013.1.spec @@ -1,7 +1,7 @@ subarch: amd64 version_stamp: 2013.1 -target: stage1 +target: stage2 rel_type: default profile: default/linux/amd64/10.0/no-multilib snapshot: 20130131 -source_subpath: default/stage3-amd64-20121213 +source_subpath: default/stage1-amd64-2013.1 $ diff default-stage{2,3}-amd64-2013.1.spec --- default-stage2-amd64-2013.1.spec +++ default-stage3-amd64-2013.1.spec @@ -1,7 +1,7 @@ subarch: amd64 version_stamp: 2013.1 -target: stage2 +target: stage3 rel_type: default profile: default/linux/amd64/10.0/no-multilib snapshot: 20130131 -source_subpath: default/stage1-amd64-2013.1 +source_subpath: default/stage2-amd64-2013.1 Gentoo stages ------------- You can't compile a big pile of source code without an already compiled toolchain, which is where Gentoo's stages come in. The “base system” contains the necessary build tools and supporting infrastructure to get things going. The stages are: 1. System must be bootstrapped and the base system must be compiled (a new toolchain built with external seed tools). 2. Stage1 + bootstrapped (a new toolchain build with stage1 tools). 3. Stage2 + base system compiled (the base system built with stage2 tools). 4. Stage3 + non-base packages. For more details on the differences between the stages, look at the target helper scripts (e.g. `targets/stage1/*.sh`). Building with a kernel ---------------------- If you're shooting for a live CD or bootable USB stick, you'll need to compile your own kernel. Here's how that works. Genkernel ~~~~~~~~~ When you don't know exactly which kernel options you need, add something like the following to your `*.spec`: boot/kernel: gentoo boot/kernel/gentoo/sources: gentoo-sources You can still set `boot/kernel/