CATALYST-SPEC(5) ================ :man source: catalyst {catalystversion} :man manual: catalyst {catalystversion} 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: include::targets.generated.txt[tabsize=4] *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. */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. `generic-livecd`;; This should be used for all non-official media. This setting is supported by the livecd targets. */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. *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 ~~~~~~~~~~~~~~~~~~~~~~ */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/