path: root/doc/catalyst-config.5.txt

CATALYST-CONFIG(5)
================
:man source:   catalyst {catalystversion}
:man manual:   catalyst {catalystversion}


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"
envscript="/etc/catalyst/catalystrc"
options="autoresume bindist kerncache pkgcache seedcache"
---------------------------------

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.

*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"
---------------------------------

**options*::
Set different build-time options (example: `autoresume bindist
kerncache pkgcache seedcache`).  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.

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

Repository settings
~~~~~~~~~~~~~~~~~~~

*distdir*::
Defines the location of your local source file repository.
Defaults to the host's DISTDIR.

*repos*::
The directory in which git repositories exist for use by the snapshot target.
Defaults to `${storedir}/repos`.

*repo_name*::
The name of the main repository (e.g. gentoo). The git repository at
`${repos}/${repo_name}.git` will be used to produce the portdir sqfs
snapshot.

*target_distdir*::
Defines the location of the local source file repository in the
target.  This will be written to the target's make.conf if it is not
the default value of `/var/cache/distfiles`.

*target_pkgdir*::
Defines the location of binary packages in the target.  This will be
written to the target's make.conf if it is not the default value of
`/var/cache/binpkgs`.

*target_portdir*::
Defines the location of the main ebuild repository in the target.
This will be written to the target's make.conf if it is not the
default value of `/var/db/repos/gentoo`.

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
----------------
The list of supported hashes is dependent on the version of Python. To
see the list of hashes supported by the version of Python in use, run

    $ python3 -c 'import hashlib; print(hashlib.algorithms_available)'


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)*