Catalyst

Catalyst is a release building tool, used by Gentoo Linux. With Catalyst, you are able to completely customize your Gentoo install by customizing the very tools that are used to install a system. Official Gentoo Linux release media is built with 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

Installation
To install Catalyst simply run:

Optional USE flags for Catalyst:

Configuration
After emerging/installing Catalyst, the first (and probably only) thing that you will have to do is edit to your liking.

How to Build Simple Stage3
Optional USE flags for ReText:

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 doesn't pollute your system.

The seed tarball needs to create

directory unless you changed the catalyst configuration where you specify the temporary directory. In that case you should put the seed in the directory you specified.

The seed tarball can be a current stage3 you can get from the mirrors. example:

Snapshot
We need to have a snapshot of the gentoo-x86 portage tree. Catalyst can create a snapshot of your /usr/portage tree with the command: catalyst -s ${NAME} The snapshot will be saved on /var/tmp/catalyst/snapshots/portage-${NAME}.tar.bz2 example: Another option is using one of the snapshots available on the mirrors

Specs
Catalyst uses specs files for reading the parameters to create a stage. For building a stage3 we currently need to build before a stage1 and a stage2. Therefore we need a spec 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

In this guide i'm going to use the specs for x86: http://git.overlays.gentoo.org/gitweb/?p=proj/releng.git;a=tree;f=releases/weekly/specs/x86;hb=HEAD

You need to download those three files. These specs are really simple and the three of them contain the same parameters except some differences, lets check stage1.spec:


 * subarch: is the subarchitecture we are building for, you can check the available subarchitectures in /usr/lib/catalyst/arch/${ARCH}.py, ${ARCH} being the arch we're building for. subarch simply sets the CHOST and CFLAGS/CXXFLAGS accordingly.


 * version_stamp: 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...


 * target: this is what makes an spec differ from another, this specifies we'll build a stage1.


 * rel_type: 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 /var/tmp/catalyst/builds from default to whatever you set here.


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


 * snapshot: 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 /var/tmp/catalyst/snapshots/portage-2008.0.tar.bz2


 * source_subpath: This is the relative path where the seed tarball is to be found. In the example, it will use /var/tmp/catalyst/builds/default/stage3-sh4a-2008.0.tar.bz2 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 we have reviewed the specs, we can run catalyst. Its really simple:

If everything went fine, we should have our stage3 built on /var/tmp/catalyst/builds/default/.