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 a seed tarball is needed. Catalyst will chroot into the seed and emerge the packages for the new stages inside it, so it does not pollute the build system.

The seed tarball should be placed the following temporary directory unless the temporary directory location was modified during the Catalyst configuration in the configuration section above. If the temporary directory was modified put the seed in the appropriate 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 any date format that makes sense to the user.

Remote download
Another option is to use one of the Portage tree snapshots available on 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:

https://gitweb.gentoo.org/proj/releng.git/tree/releases/weekly/specs

This article will use the specs for :

https://gitweb.gentoo.org/proj/releng.git/plain/releases/weekly/specs/amd64/

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 to be built. Check the available sub-architectures in,  being the arch to be built.   simply sets the   and  /  accordingly.


 * - The version of the stage. On the autobuilds the date is utilized for this setting. 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 a stage1 is to be built.


 * - Leaving default value here fine. Its simply used in case differentiation of the builds is needed, for example if hardened or uclibc stages were to be built. Changing it will change the sub-directory inside from default to whatever has been set here.


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


 * - The snapshot of the Gentoo tree it will use. See the chapter of creating an snapshot to see how it can be created. If 2015.04.07 is used 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  needs to be the stage1 and stage2 built respectively. An example: if we use 2015.04.07 as, the   for stage2 should be: default/stage1-sh4a-2015.04.07, and the   for stage3 should be: default/stage2-sh4a-2015.04.07.

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