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

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.

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

*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>/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`, and `tinderbox` 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.

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-{catalystversion}/examples'.


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

include::subarches.generated.txt[tabsize=4]


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