CATALYST-SPEC(5)

NAME
catalyst-spec - Catalyst build specification files

SYNOPSIS

catalyst [OPTIONS] -f FILE

DESCRIPTION

catalyst(1) reads the specification file given with -f on the command line. The file contains keyword-argument pairs, one per line, separated by a colon (:). Subsequent indented lines continue the argument. Lines starting with # and empty lines are interpreted as comments. For example:

    # Select the subarch
    subarch: athlon-xp
    boot/use:
      -*
      multicall
      readline
      ssl

The possible keywords and their meanings are as follows:

  Basic configuration

subarch
    The subarch can be any of the supported catalyst subarches (example: athlon-xp). See the SUPPORTED ARCHITECTURES section for a list of supported subarches.

version_stamp
    The version stamp is an identifier for the build. It can be anything, but something date-like is recommended (example: 2006.1).

target
    The target specifies what target we want catalyst to build (example: stage3). Supported targets are:

    embedded
        Enbedded target, similar to the stage2 target, builds upon a stage2 tarball.

        A stage2 tarball is unpacked, but instead of building a stage3, it emerges @system into another directory inside the stage2 system. This way, we do not have to emerge GCC/portage into the staged system. It may sound complicated but basically it runs ROOT=/tmp/submerge emerge --something foo bar .

    grp
        Gentoo Reference Platform (GRP) target

    livecd-stage1
        LiveCD stage1 target

    livecd-stage2
        LiveCD stage2 target, builds upon previous LiveCD stage1 tarball

    netboot
        netboot target, version 1

    netboot2
        netboot target, version 2

    snapshot
        Snapshot target

    stage1
        stage1 target

    stage2
        stage2 target, builds upon previous stage1 tarball

    stage3
        stage3 target, builds upon previous stage2/stage3 tarball

    stage4
        stage4 target, builds upon previous stage3/stage4 tarball

    tinderbox
        Tinderbox target

rel_type
    The rel_type defines what kind of build we are doing (example: default). This is merely another identifier, but it useful for allowing multiple concurrent builds. Usually, default will suffice.

profile
    This is the system profile to be used by catalyst to build this target (example: default/linux/x86/10.0/). It is specified as a relative path from profiles in your portage snapshot

snapshot
    This specifies which snapshot to use for building this target (example: 2006.1).

source_subpath
    This specifies where the seed stage for this target comes from (example: default/stage3-x86-2006.1). The path is relative to $storedir/builds. The rel_type is also used as a path prefix for the seed.

distcc_hosts
    These are the hosts used as distcc slaves when distcc is enabled in your catalyst.conf (example: 127.0.0.1 192.168.0.1). It follows the same syntax as distcc-config --set-hosts and is entirely optional.

portage_confdir
    This is an optional directory containing portage configuration files (example: /etc/portage). It follows the same syntax as /etc/portage and should be consistent across all targets to minimize problems.

portage_overlay
    This option specifies the location to a portage overlay that you would like to use when building this target (example: /usr/local/portage).

pkgcache_path
    This allows the optional directory containing the output packages for catalyst (example: /tmp/packages). Mainly used as a way for different spec files to access the same cache directory. Default behavior for this location is to be autogenerated under $storedir based on the spec file.

kerncache_path
    This allows the optional directory containing the output packages for kernel builds (example: /tmp/kernel). Mainly used as a way for different spec files to access the same cache directory. Default behavior is for this location to be autogenerated under $storedir based on the spec file.

<target>/type
    This option controls quite a bit of catalyst internals and sets up several defaults. Each type behaves slightly differently and is explained below.

    gentoo-release-minimal
        This creates an official minimal InstallCD.

    gentoo-release-universal
        This creates an official universal InstallCD.

    gentoo-release-livecd
        This creates an official LiveCD environment.

    gentoo-gamecd
        This creates an official Gentoo GameCD.

    generic-livecd
        This should be used for all non-official media.

This setting is supported by the livecd targets.

<target>/builddate
    Set the build date of the <target> (example: 20060107). This setting is supported by the netboot2 target.

<target>/readme
    This is for the README.txt on the root of the CD. For Gentoo releases, we use a default README.txt, and this will be used on your CD if you do not provide one yourself. We do not use this for the official releases. This setting is supported by the livecd targets.

grp
    Since GRP is capable of building packages/source sets for more than one CD, this defines the layout for the directories under $storedir/builds (example: src cd2).

update_seed
    This is an optional setting supported by stage1 to tell catalyst if it should update the seed stage or not (valid values: yes no).

update_seed_command
    This is an optional command to pass to emerge for updating the seed stage (example: --update dev-libs/mpfr dev-libs/mpc dev-libs/gmp) If not specified, catalyst will update gcc deps. This setting requires enabling update_seed.

  Compilation

These options are only available when building a stage1 or stage2 target and are all optional. These allow for emulating the changes possible during a bootstrap. Some possible uses of these would be building embedded stages requiring a different CHOST or building a stage2 with NPTL support from a stage1 tarball that is built without it. If left blank, then the catalyst defaults from arch.py are used.

chost
    This option is used to change the CHOST from what is default in the profile to whatever you specify (example: i686-pc-linux-gnu). This is useful for building NPTL, for example.

cflags
    This option allows you to change the default CFLAGS that will be used in building this stage (example: -Os -pipe -fomit-frame-pointer -mcpu=i686). This really should remain generic, as putting optimizations flags here will build a stage1 tarball that is no longer generic.

cxxflags
    This is for setting the CXXFLAGS (example: -Os -pipe -fomit-frame-pointer -mcpu=i686). Generally, this would be set to the same as CFLAGS. In fact, it will mirror CFLAGS by default.

ldflags
    Setting this option sets LDFLAGS in make.conf in your stage (example: -Wl,-O1 -Wl,-z,now). This would be useful for setting up an embedded or hardened system.

  Filesystem

livecd/fstype
    The fstype is used to determine what sort of CD we should build. This is used to set the type of loopback filesystem that we will use on our CD. Possible values are as follows:

    squashfs
        This gives the best compression, but requires a kernel patch.

    zisofs
        This uses in-kernel compression and is supported on all platforms.

    normal
        This creates a loop without compression.

    noloop
        This copies the files to the CD directly, without using a loopback.

livecd/fsops
    The fsops are a list of optional parameters that can be passed to the tool which will create the filesystem specified in livecd/fstype (example: -root-owned). It is valid for the following fstypes: squashfs, jffs, jffs2, and cramfs.

livecd/iso
    This is the full path and filename to the ISO image that the livecd-stage2 target will create (example: /tmp/installcd-x86-minimal.iso).

livecd/volid
    This option sets the volume ID of the CD created (example: Gentoo Linux 2006.1 X86).

  Bootloader

livecd/cdtar
    This is required for livecd-stage2 on all arches except amd64 and x86 which can autogenerate one if USE=system-bootloader is set. The cdtar is essentially the bootloader for the CD. It also holds the main configuration for the bootloader. On x86/amd64, it also can include a small memory testing application, called memtest86+ (example: /usr/share/catalyst/livecd/cdtar/isolinux-2.13-memtest86+-cdtar.tar.bz2).

  Kernel and boot issues

<target>/splash_theme
    This is where you set the splash theme (example: livecd-2006.1). This theme must be present in /etc/splash, before the kernel has completed building. This setting is supported by the stage4 and livecd targets.

boot/kernel
    This option is used to specify the number of kernels to build and also the labels that will be used by the CD bootloader to refer to each kernel image (example: gentoo).

boot/kernel/<label>/sources, netboot/kernel/sources
    This option tells catalyst which kernel sources to merge for this kernel label (example: gentoo-sources). This can use normal portage atoms to specify a specific version. <label> should match one of the labels given to boot/kernel.

boot/kernel/<label>/config, netboot/kernel/config
    This option is the full path and filename to a kernel .config file that is used by genkernel to compile the kernel this label applies to. <label> should match one of the labels given to boot/kernel.

boot/kernel/<label>/gk_kernargs
    This option sets genkernel parameters on a per-kernel basis and applies only to this kernel label. This can be used for building options into only a single kernel, where compatibility may be an issue. We do not use this on the official release media, but it follows the same syntax as stage4/gk_mainargs. <label> should match one of the labels given to boot/kernel.

<target>/gk_mainargs
    This is a set of arguments that will be passed to genkernel for all kernels defined in this target (example: --lvm --dmraid). It is useful for passing arguments to genkernel that are not otherwise available via the stage4-stage2 spec file. This option is supported by the stage4 and livecd targets.

boot/kernel/<label>/extraversion
    This option appends an extension to the name of your kernel, as viewed by a uname -r. This also affects any modules built under this kernel label. This is useful for having two kernels using the same sources to keep the modules from overwriting each other. We do not use this on the official media. <label> should match one of the labels given to boot/kernel.

boot/kernel/<label>/machine_type
    This option is only for ppc64 machines (example: ibm). If used it will create the /etc/yaboot.conf entry used for booting an ibm powerpc machine. <label> should match one of the labels given to boot/kernel.

boot/kernel/<label>/console
    This is only supported on ppc64 currently. This entry sets up the console boot parameters required for sending the output to the appropriate console (example: tty0 ttyS0). <label> should match one of the labels given to boot/kernel.

<target>/modblacklist
    This is for blacklisting modules from being hotplugged that are known to cause problems (example: 8139cp). Putting a module name here will keep it from being auto-loaded, even if it is detected by hotplug. This setting is supported by the stage4 and livecd targets.

netboot/kernel/use, boot/kernel/<label>/use
    This option sets the USE flags used to build the kernel and also any packages which are defined under this kernel label (example: pcmcia usb -X). These USE flags are additive from the default USE for the specified profile. <label> should match one of the labels given to boot/kernel.

boot/kernel/<label>/packages
    This option is for merging kernel-dependent packages and external modules that are configured against this kernel label (example: pcmcia-cs speedtouch slmodem). <label> should match one of the labels given to boot/kernel.

livecd/bootargs
    This is a set of arguments that get passed to the bootloader for your CD (example: dokeymap). It is used on the x86/amd64 release media to enable keymap selection.

  Netboot

<target>/busybox_config
    The netboot target builds busybox for its root filesystem. This option is where you specify the full path and filename to your busybox configuration (example: /tmp/busybox.config). This setting is supported by the netboot and netboot2 targets.

netboot/base_tarball
    This is the full path and filename to the tarball to use as the base for the netboot image (example: /usr/share/catalyst/netboot/netboot-base.tar.bz2).

  Runlevels

<target>/linuxrc
    This option allows you to specify your own linuxrc script for genkernel to use when building your CD. This is not checked for functionality, so it is up to you to debug your own script. We do not use one for the official release media. This option is supported by the stage4 and livecd targets.

<target>/rcadd
    This is for adding init scripts to runlevels. The syntax for the init script is the script name, followed by a pipe, followed by the runlevel in which you want the script to run. It looks like spind|default and is space delimited. We do not use this on the official media, as catalyst sets up the runlevels correctly for us. This setting is supported by the stage4 and livecd targets.

<target>/rcdel
    This is for removing init script from runlevels. It is executed after the defaults shipped with catalyst, so it is possible to remove the defaults using this option. It can follow the same syntax as stage4/rcadd, or you can leave the runlevel off to remove the script from any runlevels detected. We do not use this on the official media. This setting is supported by the stage4 and livecd targets.

  Packages

<target>/use
    This is where you will build packages for updating a stage3. These packages can be built with customized USE settings (example: ipv6 socks5 fbcon ncurses readline ssl). The settings here are additive to the default USE configured by the profile. Leaving this blank will default to the system use flags. It is very possible to cause quite a few problems with these, so be careful with whatever USE flags you add here. This is generally used for adding some functionality that we do not want on by default for all Gentoo users, but that we want on by default in our binaries. This setting is supported by the stage4, netboot2, tinderbox, and grp targets.

<target>/packages
    This is the set of packages that we will merge into the stage4 tarball (example: livecd-tools dhcpcd acpid apmd gentoo-sources coldplug fxload irssi wpa_supplicant). They will be built with the USE flags configured above. These packages must not depend on a configured kernel. If the package requires a configured kernel, then it will be defined elsewhere. This setting is supported by the stage4, netboot2, and tinderbox targets.

netboot/packages
    These package names are also labels used later when determining what files to copy into your netboot image (example: raidtools e2fsprogs).

<target>/packages/<label>/files
    This is where you tell catalyst which files from each package to copy into the netboot image. <label> should match one of the labels given to netboot/packages. For example:

        netboot/packages/raidtools/files: /sbin/raidstart /sbin/mkraid

This option is supported by the netboot and netboot2 targets.

netboot/extra_files
    This is a list of any other files, not belonging to the above packages, that you would wish to have copied into your netboot image (example: /lib/libresolv.so.2 /lib/libnss_compat.so.2).

livecd/depclean
    This feature controls the depclean run after fsscript and before unmerge. The default is unset, and will run emerge --depclean --with-bdeps=n which results in the smallest possible livecd. For some use cases it may be nice to not run depclean at all, or to keep build deps. For those cases, the following two special cases are available: livecd/depclean: no livecd/depclean: keepbdeps This setting is only supported by the livecd target.

<target>/unmerge
    This is a list of packages that will be unmerged after all the kernels have been built (example: autoconf automake libtool m4 bison). There are no checks on these packages, so be careful what you add here. They can potentially break your target. This setting is supported by the stage4 and livecd targets.

grp/<label>/type
    This tells catalyst what type of GRP set this list of packages will create (example: srcset). Valid options here are srcset or pkgset to either download the source, or to build packages, respectively. <label> should match one of the labels given to grp.

grp/<label>/packages
    This is our list of packages that will comprise our package set (example: dante tsocks sys-apps/eject minicom). Packages listed for a srcset label should be used for grabbing things that need a compiled kernel to build, or things listed in the Handbook that should be available before the first reboot during an install. Pagekages listed for a pkgset label will be fetched, compiled, and installed in the target. <label> should match one of the labels given to grp.

  Miscellaneous

<target>/fsscript
    A fsscript is simply a shell script that is copied into the chroot of the build after the kernel(s) and any external modules have been compiled and is executed within the chroot. It can contain any commands that are available via the packages installed by our stages or by the packages installed during the stage4-stage1 build. We do not use one for the official release media, so there will not be one listed below. The syntax is simply the full path and filename to the shell script that you wish to execute (example: /path/to/fsscript.sh). The script is copied into the chroot by catalyst automatically. This setting is supported by the stage4 and livecd targets.

<target>/motd
    This is for the message of the day. It is not required for release media, as catalyst builds a default motd when the <target>/type is set to one of the gentoo-* options. This setting overrides the default motd even on official media. This setting is supported by the stage4 and livecd targets.

<target>/root_overlay
    This overlay is dropped onto the filesystem within the loop. This can be used for such things as updating configuration files or adding anything else you would want within your target filesystem. Files added here are available when docache is used. We do not use this on the official media. This setting is supported by the stage4 and livecd targets.

livecd/overlay
    This overlay is dropped onto the target filesystem and is outside any loop which has been configured (example: /tmp/overlay-minimal). This is typically used for adding the documentation, distfiles, snapshots, and stages to the official media. These files will not be available if docache is enabled, as they are outside the loop.

<target>/xinitrc
    This is used by catalyst to copy the specified file to /etc/X11/xinit/xinitrc and is used by the <target>/type gentoo-gamecd and generic-livecd. While the file will still be copied for any <target>/type, catalyst will only create the necessary /etc/startx for those types, so X will not be automatically started. This is useful also for setting up X on a CD where you do not wish X to start automatically. We do not use this on the release media. This setting is supported by the stage4 and livecd targets.

livecd/xdm
    This is used by catalyst to determine which display manager you wish to become the default (example: gdm). This is used on the official Gentoo LiveCD and is valid for any livecd/type.

livecd/xsession
    This is used by catalyst to determine which X session should be started by default by the display manager (example: gnome). This is used on the official Gentoo LiveCD and is valid for any livecd/type.

<target>/users
    This option is used to create non-root users on your target. It takes a space separated list of user names. These users will be added to the following groups: users, wheel, audio, games, cdrom, and usb. If this is specified in your spec file, then the first user is also the user used to start X. We do not use this on the release media. This setting is supported by the stage4 and livecd targets.

<target>/empty
    This option is used to empty the directories listed (example: /var/tmp /var/cache /var/db). It is useful for getting rid of files that don’t belong to a particular package, or removing files from a package that you wish to keep, but won’t need the full functionality. This setting is supported by the stage4 and livecd targets.

<target>/rm*
    This option tells catalyst to clean specific files from the filesystem and is very useful in cleaning up stray files in /etc left over after stage4/unmerge (example: /lib/*.a /usr/lib/*.a). This setting is supported by the stage4 and livecd targets.

gamecd/conf
    This option is only used when creating a GameCD. This specifies the file that contains the definitions for GAME_NAME and GAME_EXECUTABLE, which are used by the GameCD scripts to set some specific options for the game. This is not used on the release media.

FILES

Example specfiles can be found in /usr/share/doc/catalyst-3.0.12/examples.

SUPPORTED ARCHITECTURES

The following table shows the list of supported architectures as well as the list of valid strings for key subarch.

alpha
    alpha, ev4, ev45, ev5, ev56, ev6, ev67, pca56

amd64
    amd64, amdfam10, athlon64, athlon64-sse3, athlonfx, barcelona, core2, k8, k8-sse3, nocona, opteron, opteron-sse3, x32

arm
    arm, armeb, armv4l, armv4tl, armv5teb, armv5tejl, armv5tel, armv5tl, armv6j, armv6j_hardfp, armv6z, armv6zk, armv7a, armv7a_hardfp

arm64
    arm64

hppa
    hppa, hppa1.1, hppa2.0

ia64
    ia64

m68k
    m68k

mips
    cobalt, loongson2e, loongson2f, loongson3a, mips, mips1, mips2, mips3, mips32, mips32_softfloat, mips32el, mips32el_softfloat, mips32r2, mips32r2_softfloat, mips32r2el, mips32r2el_softfloat, mips4, mips4_r10k, mips4_r12k, mips64, mips64el, mips64r2, mips64r2el, mipsel, mipsel1, mipsel2, mipsel3, mipsel4

mips64
    cobalt_n32, loongson2e_multilib, loongson2e_n32, loongson2e_n64, loongson2f_multilib, loongson2f_n32, loongson2f_n64, loongson3a_multilib, loongson3a_n32, loongson3a_n64, mips3_multilib, mips3_n32, mips3_n64, mips4_multilib, mips4_n32, mips4_n64, mips4_r10k_multilib, mips4_r10k_n32, mips4_r10k_n64, mips4_r12k_multilib, mips4_r12k_n32, mips4_r12k_n64, mips64_multilib, mips64_n32, mips64_n64, mips64el_multilib, mips64el_n32, mips64el_n64, mips64r2_multilib, mips64r2_n32, mips64r2_n64, mips64r2el_multilib, mips64r2el_n32, mips64r2el_n64, mipsel3_multilib, mipsel3_n32, mipsel3_n64, mipsel4_multilib, mipsel4_n32, mipsel4_n64

ppc
    g3, g4, g5, power, power-ppc, ppc

ppc64
    970, cell, power3, power4, power5, power6, power7, power7le, power8, power8le, ppc64, ppc64le

riscv
    riscv

s390
    s390

s390x
    s390x

sh
    sh, sh2, sh2a, sh2aeb, sh2eb, sh3, sh3eb, sh4, sh4a, sh4aeb, sh4eb, sheb

sparc
    sparc

sparc64
    sparc64

x86
    athlon, athlon-4, athlon-mp, athlon-tbird, athlon-xp, i386, i486, i586, i686, k6, k6-2, k6-3, pentium, pentium-m, pentium-mmx, pentium2, pentium3, pentium3m, pentium4, pentium4m, pentiumpro, prescott, x86

BUGS

An up-to-date list of Catalyst bugs can always be found listed on the Gentoo Linux bug-tracking system at https://bugs.gentoo.org.

SEE ALSO

catalyst(1) catalyst-config(5)