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 in 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 many of the same parameters.

Inside a file
Check out the file:

On stage2 and stage3, the  needs to be the stage1 and stage2 built respectively. For an example, if 2015.04.07 is used as the, 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

 * Catalyst project page - The official project main documentation page.
 * Catalyst FAQ - A frequently asked questions article for official Catalyst documentation.
 * Official Catalyst source code - Hosted on Gentoo's GitWeb site.