CATALYST-CONFIG(5)

NAME
catalyst-config - Catalyst configuration files

SYNOPSIS

catalyst [OPTIONS] -c FILE

DESCRIPTION

catalyst(1) reads the configuration file given with -c or --config on the command line. The file contains keyword-argument pairs using a POSIX Shell variable syntax. Lines starting with # and empty lines are interpreted as comments. For example:

    # /etc/catalyst/catalyst.conf
    digests="auto"
    contents="auto"
    envscript="/etc/catalyst/catalystrc"
    options="autoresume bindist kerncache pkgcache seedcache snapcache"
    # source repo settings
    distdir="/var/cache/distfiles"
    portdir="/var/db/repos/gentoo"
    # target repo info
    repo_basedir="/var/db/repos"
    repo_name="gentoo"
    target_distdir="/var/cache/distfiles"
    target_pkgdir="/var/cache/binpkgs"
    # other catalyst settings
    sharedir="/usr/share/catalyst"
    snapshot_cache="/var/tmp/catalyst/snapshot_cache"
    storedir="/var/tmp/catalyst"

The possible keywords and their meanings are as follows:

  Basic configuration

digests
    Create a .DIGESTS file containing the hash output from any of the supported options below. Adding them all may take a long time. (example: md5 sha1 sha512 whirlpool). See the SUPPORTED HASHES section for a list of supported hashes.

contents
    Create a .CONTENTS file listing the contents of the file. If this variable is empty, no .CONTENTS will be generated at all. Supported values:

    auto
        Strongly recommended

    tar-tv
        Do tar tvf FILE

    tar-tvz
        Do tar tvzf FILE

    tar-tvy
        Do tar tvyf FILE

    isoinfo-l
        Do isoinfo -l -i FILE

    isoinfo-f
        Do isoinfo -f -i FILE. isoinfo-f is the only option not chosen by the automatic algorithm.

envscript
    Environment script location, which allows users to set options such as HTTP proxies, MAKEOPTS, GENTOO_MIRRORS, or any other environment variables needed for building. The envscript file sets environment variables using POSIX shell notation:

        export FOO="bar"

hash_function
    Internal hash function catalyst should use for things like autoresume, seedcache, etc. The default and fastest is crc32. You should not ever need to change this unless your OS does not support it. See the SUPPORTED HASHES section for a list of supported hashes.

*options
    Set different build-time options (example: autoresume bindist kerncache pkgcache seedcache snapcache). Supported values:

    autoresume
        Attempt to resume a failed build. Clear the autoresume flags with the -a option to the catalyst command line. -p will clear the autoresume flags as well as your pkgcache and kerncache.

    bindist
        Enable the bindist USE flag. This is recommended if you will be redistributing builds, but see the package specific definitions for details.

    ccache
        Enable build time ccache support. WARNING: ccache has been known to cause random build failures and bugs reported with ccache enabled may be closed invalid.

    distcc
        Enable distcc support for building. You have to set distcc_hosts in your spec file.

    icecream
        Enable icecream compiler cluster support for building.

    kerncache
        Keep a copy of the built kernel and modules. This is useful if your build dies during livecd-stage2.

    pkgcache
        Enable --usepkg and --buildpkg for most emerge(1) runs. This is useful if your build dies prematurely. However, you may experience linking problems. See the BINARY PACKAGE DEPENDENCIES section for details.

    seedcache
        Use the build output of a previous target if it exists to speed up the creation of a new stage. This avoids unpacking the seed tarball.

    snapcache
        Cache the snapshot so that it can be bind-mounted into the chroot. WARNING: moving parts of the portage tree from within fsscript will break your cache. The cache is unlinked before any empty or rm processing.

    versioned_cache
        Name the cache directories (packagecache, kerncache) based on the version of a spec file.

  Repository settings

distdir
    Source distfiles location used in generation of the stages. This is usually the hosts distfiles location. /var/cache/distfiles should work for most default installations, but it should be set to match your hosts configuration.

portdir
    Source Gentoo tree location (primary repo). /var/db/repos/gentoo/ should work for most default installations.

repo_basedir
    The target repository directory to contain the primary repo (gentoo repo) and any overlays. The default location is /var/db/repos.

repo_name
    The name of the main repository (ie: gentoo). This has had a directory name of portage in the past. But it has an internal name of gentoo, which is what its directory name should be. This name is used in the snapshot name generated and also the directory name of the repository created with the snapshot target. The new general rule is that the directory name and its internal repo_name value should be the same.

target_distdir
    This is the target distfiles directory location for the stage being created. This is important because this value will be stored in the stage’s make.conf and will become the default location used if it is not edited by users. The default location is /var/cache/distfiles.

target_pkgdir
    This is the target packages directory for storing binpkgs in the stage being built. This location is stored in the make.conf of the stage being built. The default location for this has typically been /var/cache/binpkgs

  Other settings

sharedir
    Catalyst runtime script location. /usr/share/catalyst should work for most default installations. If you are running catalyst from a Git checkout, you should change this to point to your checkout directory.

storedir
    Location for built seeds, temporary files, and caches (example: /var/tmp/catalyst).

port_logdir
    Location for build logs (example: /var/tmp/catalyst/tmp). This dir will be automatically cleaned of all logs over 30 days old. If left undefined the logs will remain in the build directory as usual and get cleaned every time a stage build is restarted.

var_tmpfs_portage
    Set the size of a /var/tmp/portage tmpfs in gigabytes (example: 16). If set, this mounts a tmpfs for /var/tmp/portage so building takes place in RAM. This feature requires a pretty large tmpfs ({open,libre}office needs ~8GB to build). WARNING: If you use too much RAM everything will fail horribly and it is not our fault.

SUPPORTED HASHES

Supported hashes: adler32, crc32, crc32b, gost, haval128, haval160, haval192, haval224, haval256, md2, md4, md5, ripemd128, ripemd160, ripemd256, ripemd320, sha1, sha224, sha256, sha384, sha512, snefru128, snefru256, tiger, tiger128, tiger160, whirlpool.

BINARY PACKAGE DEPENDENCIES

This section is only important if you are using binary packages to build your stages (by enabling the pkgcache option and restarting incomplete builds).

Before EAPI-5 introduced ABI sub-slots, the build-time compatibility of packages was not recorded. This leads to problems such as binary GCC packages built against mpc-0.8.2 (which installs libmpc.so.2) being installed on systems that only have mpc-1.0.1 (which installs libmpc.so.3), resulting in:

    /usr/libexec/gcc/i686-pc-linux-gnu/4.6.3/cc1:
      error while loading shared libraries: libmpc.so.2:
      cannot open shared object file: No such file or directory

As long as there are packages in your stage that don’t use ABI sub-slots, you may experience errors like this due to untracked ABI missmatches in binary packages. Packages generated by catalyst builds are currently namespaced:

If versioned_cache is set:

    .../packages/<rel_type>/<target>-<subarch>-<version_stamp>/Packages

Otherwise:

    .../packages/<rel_type>/<target>-<subarch>/Packages

so running into these out-of-date packages is unlikely. You may run into problems if:

    • you enable update_seed in your stage1 spec after a previous run which generated packages linking against out-of-date seed libraries or

    • you update your snapshot and an untracked ABI dependency is bumped without a similar bump in the dependent package.

without also bumping any of the package namespace variables in your spec. If you do make such a change, it’s a good idea to clear the package cache in question and rebuild the packages from scratch.

FILES

An example configuration file can be found at /etc/catalyst/catalyst.conf.

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-spec(5)