Catalyst Stage4 Creation

This article is a stub. Please help out by expanding it - how to get started.

This is a guide will teach how to create to deployable image for a different machine using Catalyst. This can be useful for getting Gentoo running on weaker systems.

Build Environment Setup

Install dev-util/catalyst making sure the iso useflag is set

root #emerge --ask dev-util/catalyst

Create a directory to work in:

root #mkdir -p /var/tmp/catalyst/builds/default

root #mkdir -p /var/tmp/catalyst/config/stages/

/var/tmp/catalyst/build/default is where seed stage3 tarball will placed to build the custom stage4 and /var/tmp/catalyst/config/stages is used like /etc/portage to configure Catalyst to use items like package.use and package.accept_keywords.

Note
In this example a x86 Pentium 3 stage4 creation will be used, but this can be easily edited to match the target system.

Prepare

CFLAGS

Edit /usr/share/catalyst/arch/x86.toml to change the default cflags that works best with the target system:

FILE /usr/share/catalyst/x86.tomlx86.toml

[x86.pentium3]
COMMON_FLAGS = "-Os -march=pentium3 -pipe -fomit-frame-pointer"
CPU_FLAGS_X86 = [ "mmx", "mmxext", "sse",]

This example shows how to set the CPU instructions that the target supports and the use of CFLAGS to lower RAM usage at the cost of some CPU time.

Note
The word after .x86 is the subarch name which will be used later on.

~Arch Packages

To pull in packages from ~x86, it is possible to use the /var/tmp/catalyst/config/stages directory created eariler.

root #mkdir -p /var/tmp/catalyst/config/stages/package.keywords

root #nano /var/tmp/catalyst/config/stages/package.keywords/stage4

FILE /var/tmp/catalyst/config/stages/package.keywords/stage4

sys-kernel/gentoo-sources ~x86

As shown, this works very similarly to how adding testing packages normally in Portage. See /etc/portage/package.accept keywords for further infomation.

Build Stage1

Prepare Seed

A seed stage3 is needed to build the new stage4 for the target machine, this done by doing the following:

root #cd /var/tmp/catalyst/builds/default

Select the best stage3 for the needs of the system (in this example stage3-i686-openrc-tar.xz was used.) Stage3 tarballs can be found at https://www.gentoo.org/downloads/mirrors/.

root #wget <URL of file>

Portage Snapshot

Portage snapshots are now handled in git and can be created and updated using:

root #catalyst -s stable

You will see entry that states the Gentoo Portage snapshot name and will look similar to:

FILE catalyst.logOutput example

NOTICE:catalyst:Creating gentoo tree snapshot 0c5fd9cca1edc63e36234b3dc91c46db24647309 from /var/tmp/catalyst/repos/gentoo.git

In this example take note of 0c5fd9cca1edc63e36234b3dc91c46db24647309 as it will be needed for the spec file.

Stage1 Spec File

Many examples of specs files can be found on RELENG Github and it's highly recommended to have at look at them https://github.com/gentoo/releng/tree/master/releases/specs.

root #cd /var/tmp/catalyst

root #nano stage1-Pentium3-openrc.spec

FILE /var/tmp/catalyst/stage1-Pentium3-openrc.specstage1-Pentium3-openrc.spec

subarch: Pentium3
target: stage1
version_stamp: openrc-@Timestamp@
rel_type: default
profile: default/linux/x86/17.0
snapshot_treeish: 0c5fd9cca1edc63e36234b3dc91c46db24647309
source_subpath: default/stage3-i686-openrc
compression_mode: pixz
update_seed: yes
update_seed_command: --update --deep --newuse @world
portage_confdir: /var/tmp/catalyst/config/stages
portage_prefix: releng

Here it is shown where to place the name of the snapshot created earlier in snapshot_treeishand also how to set the sub arch.

Now, build the stage1:

root #catalyst -f stage1-Pentium3-openrc.spec

Build Stage3

root #nano stage3-Pentium3-openrc.spec

FILE /var/tmp/catalyst/stage3-Pentium3-openrc.specstage1-Pentium3-openrc.spec

subarch: pentium3
target: stage3
version_stamp: openrc-@TIMESTAMP@
rel_type: default
profile: default/linux/x86/17.0
snapshot_treeish: 0c5fd9cca1edc63e36234b3dc91c46db24647309
source_subpath: default/stage1-i686-openrc-@TIMESTAMP@
compression_mode: pixz
portage_confdir: /var/tmp/catalyst/stages
portage_prefix: releng

In this stage Catalyst will use the stage1 built earlier to build a full stage3 for the target system.

root #catalyst -f stage3-Pentium3-openrc.spec

Build Stage4

This is the stage where packages and other settings can be applied to the stage tarball. The example of the options available in this stage here .

root #nano stage4-Pentium3-openrc.spec

FILE /var/tmp/catalyst/stage4-Pentium3-openrc.specstage4-Pentium3-openrc.spec

subarch: pentium3
version_stamp: openrc-@TIMESTAMP@
target: stage4
rel_type: default 0c5fd9cca1edc63e36234b3dc91c46db24647309
profile: default/linux/x86/17.0
snapshot_treeish:
source_subpath: default/stage3-pentium3-openrc-@TIMESTAMP@
portage_confdir: /var/tmp/catalyst/config/portage/stages
stage4/packages:
        net-misc/dhcpcd
        sys-kernel/gentoo-sources
        sys-devel/llvm
        dev-util/cmake
        app-misc/neofetch
        app-misc/screen
        sys-boot/grub

stage4/packages

This section allows the user to select which extra packages should be added to the tarball ready the target to use, this can great speed up deployment time as there is no need to wait for large packages such as LLVM to compile on the slower system.

stage4/use

This section allows the setting of global USEFLAGS, see below for an example:

FILE /var/tmp/catalyst/stage4-Pentium3-openrc.specstage4-Pentium3-openrc.spec

stage4/use:
-qt5
-ipv6
gtk
gtk3

Build

root #catalyst -f stage3-Pentium3-openrc.spec

Once this is finished then the stage4 can be found in /var/tmp/catalyst/builds/default to transfer to the target to be unpacked.