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`).  The set of supported hashes
is dependent on the version of Python. To see the set of hashes
supported by the version of Python in use, run
+
---------------------------------
$ python3 -c 'import hashlib; print(hashlib.algorithms_available)'
---------------------------------

*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_basedir*::
The target repository directory to contain the primary repo (e.g.,
gentoo repo) and any overlays.  The default location is
`/var/db/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`.

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.


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

Packages generated by catalyst builds are namespaced:

If versioned_cache is set:
---------------------------------
.../packages/<rel_type>/<target>-<subarch>-<version_stamp>/Packages
---------------------------------
Otherwise:
---------------------------------
.../packages/<rel_type>/<target>-<subarch>/Packages
---------------------------------


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