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 downloaded from one of the mirrors.

For example:

Snapshot
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 ${NAME} command.

The snapshot will be saved to

For example:

Another option is to use one of the Portage Tree snapshots available on the mirrors.

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 we need a spec is needed for each of the stages.

You can find the specs we use for autobuilds in the releng 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 really simple and the three of them contain the same parameters except some differences, lets check stage1.spec:


 * - the subarchitecture we are building for, you can check the available subarchitectures 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, run catalyst will the following command:

If everything went well a stage3 should be built in the directory.

External resources

 * Gentoo Release Engineer Catalyst project page
 * Gentoo Catalyst FAQ
 * [git://git.overlays.gentoo.org/proj/catalyst.git Official Gentoo Catalyst source code page (git)]