doc/catalyst-spec.5.txt

   1 CATALYST-SPEC(5)
   2 ================
   3 :man source:   catalyst {catalystversion}
   4 :man manual:   catalyst {catalystversion}
   5
   6
   7 NAME
   8 ----
   9 catalyst-spec - Catalyst build specification files
  10
  11
  12 SYNOPSIS
  13 --------
  14 *catalyst* ['OPTIONS'] *-f* 'FILE'
  15
  16
  17 DESCRIPTION
  18 -----------
  19
  20 *catalyst(1)* reads the specification file given with *-f* on the
  21 command line.  The file contains keyword-argument pairs, one per line,
  22 separated by a colon (`:`).  Subsequent indented lines continue the
  23 argument.  Lines starting with `#` and empty lines are interpreted as
  24 comments.  For example:
  25
  26 ---------------------------------
  27 # Select the subarch
  28 subarch: athlon-xp
  29
  30 boot/use:
  31   -*
  32   multicall
  33   readline
  34   ssl
  35 ---------------------------------
  36
  37 The possible keywords and their meanings are as follows:
  38
  39 Basic configuration
  40 ~~~~~~~~~~~~~~~~~~~
  41
  42 *subarch*::
  43 The subarch can be any of the supported catalyst subarches (example:
  44 `athlon-xp`).  See the *SUPPORTED ARCHITECTURES* section for a list of
  45 supported subarches.
  46
  47 *version_stamp*::
  48 The version stamp is an identifier for the build.  It can be anything,
  49 but something date-like is recommended (example: `2006.1`).
  50
  51 *target*::
  52 The target specifies what target we want catalyst to build (example:
  53 `stage3`).  Supported targets are:
  54
  55 include::targets.generated.txt[tabsize=4]
  56
  57 *rel_type*::
  58 The `rel_type` defines what kind of build we are doing (example:
  59 `default`).  This is merely another identifier, but it useful for
  60 allowing multiple concurrent builds.  Usually, `default` will suffice.
  61
  62 *profile*::
  63 This is the system profile to be used by catalyst to build this target
  64 (example: `default/linux/x86/10.0/`).  It is specified as a relative
  65 path from `profiles` in your portage snapshot
  66
  67 *snapshot*::
  68 This specifies which snapshot to use for building this target
  69 (example: `2006.1`).
  70
  71 *source_subpath*::
  72 This specifies where the seed stage for this target comes from
  73 (example: `default/stage3-x86-2006.1`).  The path is relative to
  74 `$storedir/builds`.  The `rel_type` is also used as a path prefix for
  75 the seed.
  76
  77 *distcc_hosts*::
  78 These are the hosts used as distcc slaves when distcc is enabled in
  79 your `catalyst.conf` (example: `127.0.0.1 192.168.0.1`).  It follows
  80 the same syntax as `distcc-config --set-hosts` and is entirely
  81 optional.
  82
  83 *portage_confdir*::
  84 This is an optional directory containing portage configuration files
  85 (example: `/etc/portage`).  It follows the same syntax as
  86 `/etc/portage` and should be consistent across all targets to minimize
  87 problems.
  88
  89 *portage_overlay*::
  90 This option specifies the location to a portage overlay that you would
  91 like to use when building this target (example: `/usr/local/portage`).
  92
  93 *pkgcache_path*::
  94 This allows the optional directory containing the output packages for
  95 catalyst (example: `/tmp/packages`).  Mainly used as a way for
  96 different spec files to access the same cache directory.  Default
  97 behavior for this location is to be autogenerated under `$storedir`
  98 based on the spec file.
  99
 100 *kerncache_path*::
 101 This allows the optional directory containing the output packages for
 102 kernel builds (example: `/tmp/kernel`).  Mainly used as a way for
 103 different spec files to access the same cache directory.  Default
 104 behavior is for this location to be autogenerated under `$storedir`
 105 based on the spec file.
 106
 107 *<target>/type*::
 108 This option controls quite a bit of catalyst internals and sets up
 109 several defaults.  Each type behaves slightly differently and is
 110 explained below.
 111   `gentoo-release-minimal`;; This creates an official minimal InstallCD.
 112   `gentoo-release-universal`;; This creates an official universal InstallCD.
 113   `gentoo-release-livecd`;; This creates an official LiveCD environment.
 114   `gentoo-gamecd`;; This creates an official Gentoo GameCD.
 115   `generic-livecd`;; This should be used for all non-official media.
 116
 117 This setting is supported by the livecd targets.
 118
 119 *<target>/builddate*::
 120 Set the build date of the `<target>` (example: `20060107`).  This
 121 setting is supported by the `netboot2` target.
 122
 123 *<target>/readme*::
 124 This is for the README.txt on the root of the CD.  For Gentoo
 125 releases, we use a default README.txt, and this will be used on your
 126 CD if you do not provide one yourself.  We do not use this for the
 127 official releases.  This setting is supported by the livecd targets.
 128
 129 *grp*::
 130 Since GRP is capable of building packages/source sets for more than
 131 one CD, this defines the layout for the directories under
 132 `$storedir/builds` (example: `src cd2`).
 133
 134 Compilation
 135 ~~~~~~~~~~~
 136
 137 These options are only available when building a stage1 or stage2
 138 target and are all optional.  These allow for emulating the changes
 139 possible during a bootstrap.  Some possible uses of these would be
 140 building embedded stages requiring a different `CHOST` or building a
 141 stage2 with NPTL support from a stage1 tarball that is built without
 142 it.  If left blank, then the catalyst defaults from `arch.py` are
 143 used.
 144
 145 *chost*::
 146 This option is used to change the CHOST from what is default in the
 147 profile to whatever you specify (example: `i686-pc-linux-gnu`).  This
 148 is useful for building NPTL, for example.
 149
 150 *cflags*::
 151 This option allows you to change the default `CFLAGS` that will be
 152 used in building this stage (example: `-Os -pipe -fomit-frame-pointer
 153 -mcpu=i686`).  This really should remain generic, as putting
 154 optimizations flags here will build a stage1 tarball that is no longer
 155 generic.
 156
 157 *cxxflags*::
 158 This is for setting the `CXXFLAGS` (example: `-Os -pipe
 159 -fomit-frame-pointer -mcpu=i686`).  Generally, this would be set to
 160 the same as `CFLAGS`.  In fact, it will mirror `CFLAGS` by default.
 161
 162 *ldflags*::
 163 Setting this option sets `LDFLAGS` in `make.conf` in your stage
 164 (example: `-Wl,-O1 -Wl,-z,now`).  This would be useful for setting up
 165 an embedded or hardened system.
 166
 167 Filesystem
 168 ~~~~~~~~~~
 169
 170 *livecd/fstype*::
 171 The fstype is used to determine what sort of CD we should build.  This
 172 is used to set the type of loopback filesystem that we will use on our
 173 CD.  Possible values are as follows:
 174   `squashfs`;; This gives the best compression, but requires a kernel patch.
 175   `zisofs`;; This uses in-kernel compression and is supported on all platforms.
 176   `normal`;; This creates a loop without compression.
 177   `noloop`;; This copies the files to the CD directly, without using a
 178              loopback.
 179
 180 *livecd/fsops*::
 181 The fsops are a list of optional parameters that can be passed to the
 182 tool which will create the filesystem specified in *livecd/fstype*
 183 (example: `-root-owned`).  It is valid for the following fstypes:
 184 `squashfs`, `jffs`, `jffs2`, and `cramfs`.
 185
 186 *livecd/iso*::
 187 This is the full path and filename to the ISO image that the
 188 livecd-stage2 target will create (example:
 189 `/tmp/installcd-x86-minimal.iso`).
 190
 191 *livecd/volid*::
 192 This option sets the volume ID of the CD created (example: `Gentoo
 193 Linux 2006.1 X86`).
 194
 195 Bootloader
 196 ~~~~~~~~~~
 197
 198 *livecd/cdtar*::
 199 The cdtar is essentially the bootloader for the CD.  It also holds the
 200 main configuration for the bootloader.  On x86/amd64, it also can
 201 include a small memory testing application, called memtest86+
 202 (example:
 203 `/usr/lib/catalyst/livecd/cdtar/isolinux-2.13-memtest86+-cdtar.tar.bz2`).
 204
 205 Kernel and boot issues
 206 ~~~~~~~~~~~~~~~~~~~~~~
 207
 208 *<target>/splash_theme*::
 209 This is where you set the splash theme (example: `livecd-2006.1`).
 210 This theme must be present in `/etc/splash`, before the kernel has
 211 completed building.  This setting is supported by the `stage4` and
 212 `livecd` targets.
 213
 214 *boot/kernel*::
 215 This option is used to specify the number of kernels to build and also
 216 the labels that will be used by the CD bootloader to refer to each
 217 kernel image (example: `gentoo`).
 218
 219 *boot/kernel/<label>/sources*::
 220 *netboot/kernel/sources*::
 221 This option tells catalyst which kernel sources to merge for this
 222 kernel label (example: `gentoo-sources`).  This can use normal portage
 223 atoms to specify a specific version.  `<label>` should match one of
 224 the labels given to *boot/kernel*.
 225
 226 *boot/kernel/<label>/config*::
 227 *netboot/kernel/config*::
 228 This option is the full path and filename to a kernel `.config` file
 229 that is used by genkernel to compile the kernel this label applies to.
 230 `<label>` should match one of the labels given to *boot/kernel*.
 231
 232 *boot/kernel/<label>/gk_kernargs*::
 233 This option sets genkernel parameters on a per-kernel basis and
 234 applies only to this kernel label.  This can be used for building
 235 options into only a single kernel, where compatibility may be an
 236 issue.  We do not use this on the official release media, but it
 237 follows the same syntax as *stage4/gk_mainargs*.  `<label>` should
 238 match one of the labels given to *boot/kernel*.
 239
 240 *<target>/gk_mainargs*::
 241 This is a set of arguments that will be passed to genkernel for all
 242 kernels defined in this target (example: `--lvm --dmraid`).  It is
 243 useful for passing arguments to genkernel that are not otherwise
 244 available via the stage4-stage2 spec file.  This option is supported
 245 by the `stage4` and `livecd` targets.
 246
 247 *boot/kernel/<label>/extraversion*::
 248 This option appends an extension to the name of your kernel, as viewed
 249 by a `uname -r`.  This also affects any modules built under this
 250 kernel label.  This is useful for having two kernels using the same
 251 sources to keep the modules from overwriting each other.  We do not
 252 use this on the official media.  `<label>` should match one of the
 253 labels given to *boot/kernel*.
 254
 255 *boot/kernel/<label>/machine_type*::
 256 This option is only for ppc64 machines (example: `ibm`).  If used it
 257 will create the `/etc/yaboot.conf` entry used for booting an ibm
 258 powerpc machine.  `<label>` should match one of the labels given to
 259 *boot/kernel*.
 260
 261 *boot/kernel/<label>/console*::
 262 This is only supported on ppc64 currently.  This entry sets up the
 263 console boot parameters required for sending the output to the
 264 appropriate console (example: `tty0 ttyS0`).  `<label>` should match
 265 one of the labels given to *boot/kernel*.
 266
 267 *<target>/modblacklist*::
 268 This is for blacklisting modules from being hotplugged that are known
 269 to cause problems (example: `8139cp`).  Putting a module name here
 270 will keep it from being auto-loaded, even if it is detected by
 271 hotplug.  This setting is supported by the `stage4` and `livecd`
 272 targets.
 273
 274 *netboot/kernel/use*::
 275 *boot/kernel/<label>/use*::
 276 This option sets the `USE` flags used to build the kernel and also any
 277 packages which are defined under this kernel label (example: `pcmcia
 278 usb -X`).  These `USE` flags are additive from the default `USE` for
 279 the specified profile.  `<label>` should match one of the labels given
 280 to *boot/kernel*.
 281
 282 *boot/kernel/<label>/packages*::
 283 This option is for merging kernel-dependent packages and external
 284 modules that are configured against this kernel label (example:
 285 `pcmcia-cs speedtouch slmodem`).  `<label>` should match one of the
 286 labels given to *boot/kernel*.
 287
 288 *livecd/bootargs*::
 289 This is a set of arguments that get passed to the bootloader for your
 290 CD (example: `dokeymap`).  It is used on the x86/amd64 release media
 291 to enable keymap selection.
 292
 293 Netboot
 294 ~~~~~~~
 295
 296 *<target>/busybox_config*::
 297 The netboot target builds busybox for its root filesystem.  This
 298 option is where you specify the full path and filename to your busybox
 299 configuration (example: `/tmp/busybox.config`).  This setting is
 300 supported by the `netboot` and `netboot2` targets.
 301
 302 *netboot/base_tarball*::
 303 This is the full path and filename to the tarball to use as the base
 304 for the netboot image (example:
 305 `/usr/lib/catalyst/netboot/netboot-base.tar.bz2`).
 306
 307 Runlevels
 308 ~~~~~~~~~
 309
 310 *<target>/linuxrc*::
 311 This option allows you to specify your own linuxrc script for
 312 genkernel to use when building your CD.  This is not checked for
 313 functionality, so it is up to you to debug your own script.  We do not
 314 use one for the official release media.  This option is supported by
 315 the `stage4` and `livecd` targets.
 316
 317 *<target>/rcadd*::
 318 This is for adding init scripts to runlevels.  The syntax for the init
 319 script is the script name, followed by a pipe, followed by the
 320 runlevel in which you want the script to run.  It looks like
 321 `spind|default` and is space delimited.  We do not use this on the
 322 official media, as catalyst sets up the runlevels correctly for us.
 323 This setting is supported by the `stage4` and `livecd` targets.
 324
 325 *<target>/rcdel*::
 326 This is for removing init script from runlevels.  It is executed after
 327 the defaults shipped with catalyst, so it is possible to remove the
 328 defaults using this option.  It can follow the same syntax as
 329 *stage4/rcadd*, or you can leave the runlevel off to remove the script
 330 from any runlevels detected.  We do not use this on the official
 331 media.  This setting is supported by the `stage4` and `livecd` targets.
 332
 333 Packages
 334 ~~~~~~~~
 335
 336 *<target>/use*::
 337 This is where you will build packages for updating a `stage3`.  These
 338 packages can be built with customized `USE` settings (example: `ipv6
 339 socks5 fbcon ncurses readline ssl`).  The settings here are additive
 340 to the default `USE` configured by the profile.  Leaving this blank
 341 will default to the system use flags.  It is very possible to cause
 342 quite a few problems with these, so be careful with whatever `USE`
 343 flags you add here.  This is generally used for adding some
 344 functionality that we do not want on by default for all Gentoo users,
 345 but that we want on by default in our binaries.  This setting is
 346 supported by the `stage4`, `netboot2`, `tinderbox`, and `grp` targets.
 347
 348 *<target>/packages*::
 349 This is the set of packages that we will merge into the stage4 tarball
 350 (example: `livecd-tools dhcpcd acpid apmd gentoo-sources coldplug
 351 fxload irssi wpa_supplicant`).  They will be built with the `USE`
 352 flags configured above.  These packages must not depend on a
 353 configured kernel.  If the package requires a configured kernel, then
 354 it will be defined elsewhere.  This setting is supported by the
 355 `stage4`, `netboot2`, and `tinderbox` targets.
 356
 357 *netboot/packages*::
 358 These package names are also labels used later when determining what
 359 files to copy into your netboot image (example: `raidtools
 360 e2fsprogs`).
 361
 362 *<target>/packages/<label>/files*::
 363 This is where you tell catalyst which files from each package to copy
 364 into the netboot image.  `<label>` should match one of the labels
 365 given to *netboot/packages*.  For example:
 366
 367   netboot/packages/raidtools/files: /sbin/raidstart /sbin/mkraid
 368
 369 This option is supported by the `netboot` and `netboot2` targets.
 370
 371 *netboot/extra_files*::
 372 This is a list of any other files, not belonging to the above
 373 packages, that you would wish to have copied into your netboot image
 374 (example: `/lib/libresolv.so.2 /lib/libnss_compat.so.2`).
 375
 376 *<target>/unmerge*::
 377 This is a list of packages that will be unmerged after all the kernels
 378 have been built (example: `autoconf automake libtool m4 bison`).
 379 There are no checks on these packages, so be careful what you add
 380 here.  They can potentially break your target.  This setting is
 381 supported by the `stage4` and `livecd` targets.
 382
 383 *grp/<label>/type*::
 384 This tells catalyst what type of GRP set this list of packages will
 385 create (example: `srcset`).  Valid options here are `srcset` or
 386 `pkgset` to either download the source, or to build packages,
 387 respectively.  `<label>` should match one of the labels given to
 388 *grp*.
 389
 390 *grp/<label>/packages*::
 391 This is our list of packages that will comprise our package set
 392 (example: `dante tsocks sys-apps/eject minicom`).  Packages listed for
 393 a `srcset` label should be used for grabbing things that need a
 394 compiled kernel to build, or things listed in the Handbook that should
 395 be available before the first reboot during an install.  Pagekages
 396 listed for a `pkgset` label will be fetched, compiled, and installed
 397 in the target.  `<label>` should match one of the labels given to
 398 *grp*.
 399
 400 Miscellaneous
 401 ~~~~~~~~~~~~~
 402
 403 *<target>/fsscript*::
 404 A fsscript is simply a shell script that is copied into the chroot of
 405 the build after the kernel(s) and any external modules have been
 406 compiled and is executed within the chroot.  It can contain any
 407 commands that are available via the packages installed by our stages
 408 or by the packages installed during the stage4-stage1 build.  We do
 409 not use one for the official release media, so there will not be one
 410 listed below.  The syntax is simply the full path and filename to the
 411 shell script that you wish to execute (example:
 412 `/path/to/fsscript.sh`).  The script is copied into the chroot by
 413 catalyst automatically.  This setting is supported by the `stage4` and
 414 `livecd` targets.
 415
 416 *<target>/motd*::
 417 This is for the message of the day.  It is not required for release
 418 media, as catalyst builds a default motd when the *<target>/type* is
 419 set to one of the `gentoo-*` options.  This setting overrides the
 420 default motd even on official media.  This setting is supported by the
 421 `stage4` and `livecd` targets.
 422
 423 *<target>/root_overlay*::
 424 This overlay is dropped onto the filesystem within the loop.  This can
 425 be used for such things as updating configuration files or adding
 426 anything else you would want within your target filesystem.  Files
 427 added here are available when `docache` is used.  We do not use this
 428 on the official media.  This setting is supported by the `stage4` and
 429 `livecd` targets.
 430
 431 *livecd/overlay*::
 432 This overlay is dropped onto the target filesystem and is outside any
 433 loop which has been configured (example: `/tmp/overlay-minimal`).
 434 This is typically used for adding the documentation, distfiles,
 435 snapshots, and stages to the official media.  These files will not be
 436 available if `docache` is enabled, as they are outside the loop.
 437
 438 *<target>/xinitrc*::
 439 This is used by catalyst to copy the specified file to
 440 `/etc/X11/xinit/xinitrc` and is used by the *<target>/type*
 441 `gentoo-gamecd` and `generic-livecd`.  While the file will still be
 442 copied for any *<target>/type*, catalyst will only create the
 443 necessary `/etc/startx` for those types, so X will not be
 444 automatically started.  This is useful also for setting up X on a CD
 445 where you do not wish X to start automatically.  We do not use this on
 446 the release media.  This setting is supported by the `stage4` and
 447 `livecd` targets.
 448
 449 *livecd/xdm*::
 450 This is used by catalyst to determine which display manager you wish
 451 to become the default (example: `gdm`).  This is used on the official
 452 Gentoo LiveCD and is valid for any `livecd/type`.
 453
 454 *livecd/xsession*::
 455 This is used by catalyst to determine which X session should be
 456 started by default by the display manager (example: `gnome`).  This is
 457 used on the official Gentoo LiveCD and is valid for any livecd/type.
 458
 459 *<target>/users*::
 460 This option is used to create non-root users on your target.  It takes
 461 a space separated list of user names.  These users will be added to
 462 the following groups: `users`, `wheel`, `audio`, `games`, `cdrom`, and
 463 `usb`.  If this is specified in your spec file, then the first user is
 464 also the user used to start X.  We do not use this on the release
 465 media.  This setting is supported by the `stage4` and `livecd` targets.
 466
 467 *<target>/empty*::
 468 This option is used to empty the directories listed (example:
 469 `/var/tmp /var/cache /var/db`).  It is useful for getting rid of files
 470 that don't belong to a particular package, or removing files from a
 471 package that you wish to keep, but won't need the full functionality.
 472 This setting is supported by the `stage4` and `livecd` targets.
 473
 474 *<target>/rm**::
 475 This option tells catalyst to clean specific files from the filesystem
 476 and is very useful in cleaning up stray files in `/etc` left over
 477 after *stage4/unmerge* (example: `/lib/*.a /usr/lib/*.a`).  This
 478 setting is supported by the `stage4` and `livecd` targets.
 479
 480 *gamecd/conf*::
 481 This option is only used when creating a GameCD.  This specifies the
 482 file that contains the definitions for `GAME_NAME` and
 483 `GAME_EXECUTABLE`, which are used by the GameCD scripts to set some
 484 specific options for the game.  This is not used on the release media.
 485
 486 FILES
 487 -----
 488 Example specfiles can be found in '/usr/share/doc/catalyst-{catalystversion}/examples'.
 489 An example configuration file can be found at '/etc/catalyst/catalyst.conf'.
 490
 491
 492 SUPPORTED ARCHITECTURES
 493 -----------------------
 494 The following table shows the list of supported architectures as well as
 495 the list of valid strings for key 'subarch'.
 496
 497 include::subarches.generated.txt[tabsize=4]
 498
 499
 500 BUGS
 501 ----
 502 An up-to-date list of Catalyst bugs can always be found listed on the Gentoo
 503 Linux bug-tracking system at 'http://bugs.gentoo.org'.
 504
 505
 506 SEE ALSO
 507 --------
 508 *catalyst(1)*