Catalyst

is Article description::Gentoo's release building tool. With 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.

is capable of:


 * Building installation stages.
 * Building bootable LiveCDs.
 * Building netboot images.

Emerge
To install, run:

Files
After emerging, the first (and probably only) configuration step is to edit.


 * : Controls the runtime behavior of catalyst.
 * : Environment script sourced by catalyst at runtime. It allows users to set options such as HTTP proxies, MAKEOPTS, GENTOO_MIRRORS, or any other environment variables as needed for building.

Seed tarball
For creating a stage3 a seed tarball is needed. Catalyst will into the seed and  the packages for the new stages inside of so that packages build for stage tarballs are isolated from the host system's.

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.

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

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

can be used to download from the command line. For example, to download an tarball:

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

The snapshot will be saved to

In the example below  (April 17, 2021 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. To use the current year/month following format above, simply:

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

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

Specs files
Catalyst uses specs files from which to read parameters to create a stage. Before building a stage3 tarball, stage1 and stage2 tarballs must first be built. Spec file are needed for each of the stages.

The specs files maintained by the Gentoo Release Engineering team can be found in the RelEng git repository. Moving forward, the target of this article is to produce a standard (OpenRC-based) stage3 tarball using spec files provided by Gentoo's Release Engineering team:

Download the three files above. These specs are very simple; all three of them contain many of the same parameters.

Inside a file
Check out the file, it should look something like this:

Four lines in the file will need to be modified for the purposes of this guide. After modification it should look like the following:

When using the pixz_x compression mode as shown in the above examples, be sure the host has the package installed:

.spec file option list
The following table provides a list of file options and their descriptions.

On and  files,   needs to reference the stage1 and stage2 tarballs respectively. In other words, with exception of the first file in the sequence,   should be set to the tarball build previously. For an example, if 2015.04 was used as the, the   for stage2 should be: default/stage1-amd64-2015.04, and the   for stage3 should be: default/stage2-amd64-2015.04.

Create distfiles directories
By default, catalyst will download distfiles into the directory. Make sure it exists before starting the build:

Start the build
Once the specs have been reviewed, start by running the following command:

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

Error: not a valid profile
The snapshot is likely to have some issue.
 * Try generating a snapshot with
 * Try disabling snapcache in