Catalyst

Catalyst is a release building tool, used by Gentoo Linux. With Catalyst, users are able to completely customize a Gentoo install by customizing the very tools that are used to install a system. Official Gentoo Linux release media is built using Catalyst.

Catalyst is capable of:


 * Building installation stages;
 * Building bootable LiveCDs;
 * Building GRP (Gentoo Reference Platform) sets;
 * Setting up a Tinderbox target for test building;
 * Building netboot images.

Emerge
To install Catalyst, run:

Configuration
After emerging Catalyst, the first (and probably only) configuration step is to edit

Seed tarball
For creating a stage3 we first need a seed tarball. The seed is needed because Catalyst will chroot onto it and emerge the packages for the new stages inside it, so it does not pollute the build system.

The seed tarball the following temporary directory created unless the temporary directory location was modified during the Catalyst configuration in the in the configuration section above. If the temporary was modified put the seed in the specified directory, otherwise:

The seed tarball can be a current stage3 tarball downloaded from one of the Gentoo mirrors.

Relatively recent AMD64 tarballs can be found here, and x86 tarballs can be found here.

Use wget to download from the command line. For example, to download an AMD64 tarball.

Local generation
Along with the tarball a snapshot of the Gentoo-x86 Portage tree is required. Catalyst can create a snapshot of the system's current directory with the catalyst -s  command.

The snapshot will be saved to

In the example below  (April 7th, 2015 in an easy to read command-line format) is the argument passed to the   option as the snapshot date:

The  argument can be anything that makes sense to the user.

Remote download
Another option is to use one of the Portage tree snapshots available on one of the mirrors. Current snapshots can be found here.

As mentioned above, the wget command can be used to download a remote snapshot hosted on a HTTP(S) server:

Specs
Catalyst uses specs files for reading the parameters to create a stage. For building a stage3 a stage1 and stage2 must be built, then the stage3 will be created. Therefore a spec file is needed for each of the stages.

The specs the Gentoo Release team use for autobuilds can be found in the releng git repository: http://git.overlays.gentoo.org/gitweb/?p=proj/releng.git;a=tree;f=releases/weekly/specs;hb=HEAD

This article will use the specs for x86: http://git.overlays.gentoo.org/gitweb/?p=proj/releng.git;a=tree;f=releases/weekly/specs/x86;hb=HEAD

Download the three files files above. These specs are very simple; all three of them contain the same parameters except some small differences. Check out the file:


 * - the sub-architecture we are building for, you can check the available sub-architectures in,  being the arch we're building for.   simply sets the   and  /  accordingly.


 * - The version of the stage we're building, on the autobuilds we use the date. This parameter will be used on the output tarball (stage1-${ARCH}-${version_stamp}.tar.bz2), temporary directories, etc...


 * - this is what makes one spec file differ from another, this specifies we'll build a stage1.


 * - leaving default is fine, its simply used in case you want to differentiate the builds, for example if you were building hardened or uclibc stages. Changing it will change the subdirectory inside from default to whatever you set here.


 * - this is the profile it will use to build the new stage. It must be one of the profiles available on


 * - The snapshot of the portage tree it will use. See the chapter of creating an snapshot to see how you can create it. If you use 2008.0 like in the example, it will use the snapshot available on


 * - This is the relative path where the seed tarball is to be found. In the example, it will use as the seed tarball.

On stage2 and stage3, the source_subpath needs to be the stage1 and stage2 built respectively. An example: if we use 20100908 as version_stamp, the source_subpath for stage2 should be: default/stage1-sh4a-20100908, and the source_subpath for stage3 should be: default/stage2-sh4a-20100908.

Running Catalyst
Once the specs have been reviewed, start catalyst by running the following command:

If everything went as expected a stage3 should be show up in the directory.

External resources

 * Gentoo Release Engineer Catalyst project page
 * Gentoo Catalyst FAQ
 * Official Gentoo Catalyst source code page