aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--Makefile18
-rw-r--r--doc/.gitignore2
-rw-r--r--doc/catalyst-spec.5.txt508
-rw-r--r--doc/catalyst.1.txt16
-rwxr-xr-xdoc/make_target_table.py42
-rw-r--r--files/.gitignore2
-rw-r--r--modules/embedded_target.py19
-rw-r--r--modules/generic_stage_target.py11
-rw-r--r--modules/generic_target.py9
-rw-r--r--modules/grp_target.py7
-rw-r--r--modules/livecd_stage1_target.py7
-rw-r--r--modules/livecd_stage2_target.py7
-rw-r--r--modules/netboot2_target.py7
-rw-r--r--modules/netboot_target.py7
-rw-r--r--modules/snapshot_target.py6
-rw-r--r--modules/stage1_target.py7
-rw-r--r--modules/stage2_target.py7
-rw-r--r--modules/stage3_target.py7
-rw-r--r--modules/stage4_target.py7
-rw-r--r--modules/tinderbox_target.py7
20 files changed, 649 insertions, 54 deletions
diff --git a/Makefile b/Makefile
index 30a0411..016120a 100644
--- a/Makefile
+++ b/Makefile
@@ -2,23 +2,33 @@
# Licensed under GPL v2 or later
PACKAGE_VERSION = `fgrep '__version__=' catalyst | sed 's|^__version__="\(.*\)"$$|\1|'`
-EXTRA_DIST = files/catalyst.1
-CLEAN_FILES = $(EXTRA_DIST) doc/subarches.generated.txt
+MAN_PAGE_SOURCES = $(wildcard doc/*.?.txt)
+MAN_PAGES = $(patsubst doc/%.txt,files/%,$(MAN_PAGE_SOURCES))
+MAN_PAGE_INCLUDES = doc/subarches.generated.txt doc/targets.generated.txt
+EXTRA_DIST = $(MAN_PAGES)
+GENERATED_FILES = $(MAN_PAGES) $(MAN_PAGE_INCLUDES)
distdir = catalyst-$(PACKAGE_VERSION)
all: $(EXTRA_DIST)
-files/catalyst.1: doc/catalyst.1.txt doc/subarches.generated.txt doc/asciidoc.conf Makefile catalyst
+files/%: doc/%.txt doc/asciidoc.conf Makefile catalyst
a2x --conf-file=doc/asciidoc.conf --attribute="catalystversion=$(PACKAGE_VERSION)" \
--format=manpage -D files "$<"
+# Additional dependencies due to inclusion
+files/catalyst.1: doc/subarches.generated.txt
+files/catalyst-spec.5: doc/subarches.generated.txt doc/targets.generated.txt
+
doc/subarches.generated.txt: $(wildcard arch/*.py) doc/make_subarch_table_guidexml.py
./doc/make_subarch_table_guidexml.py
+doc/targets.generated.txt: doc/make_target_table.py $(wildcard modules/*_target.py)
+ "./$<" > "$@"
+
clean:
- rm -f $(CLEAN_FILES)
+ rm -f $(GENERATED_FILES)
find -name '*.pyo' -delete
check-git-repository:
diff --git a/doc/.gitignore b/doc/.gitignore
index b998e26..2b8a08c 100644
--- a/doc/.gitignore
+++ b/doc/.gitignore
@@ -1,2 +1,4 @@
subarches.generated.txt
subarches.generated.xml
+targets.generated.txt
+targets.generated.xml
diff --git a/doc/catalyst-spec.5.txt b/doc/catalyst-spec.5.txt
new file mode 100644
index 0000000..3be96fe
--- /dev/null
+++ b/doc/catalyst-spec.5.txt
@@ -0,0 +1,508 @@
+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.
+
+*grp*::
+Since GRP is capable of building packages/source sets for more than
+one CD, this defines the layout for the directories under
+`$storedir/builds` (example: `src cd2`).
+
+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*::
+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/lib/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>/machine_type*::
+This option is only for ppc64 machines (example: `ibm`). If used it
+will create the `/etc/yaboot.conf` entry used for booting an ibm
+powerpc machine. `<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/lib/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`, `tinderbox`, and `grp` 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`).
+
+*<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.
+
+*grp/<label>/type*::
+This tells catalyst what type of GRP set this list of packages will
+create (example: `srcset`). Valid options here are `srcset` or
+`pkgset` to either download the source, or to build packages,
+respectively. `<label>` should match one of the labels given to
+*grp*.
+
+*grp/<label>/packages*::
+This is our list of packages that will comprise our package set
+(example: `dante tsocks sys-apps/eject minicom`). Packages listed for
+a `srcset` label should be used for grabbing things that need a
+compiled kernel to build, or things listed in the Handbook that should
+be available before the first reboot during an install. Pagekages
+listed for a `pkgset` label will be fetched, compiled, and installed
+in the target. `<label>` should match one of the labels given to
+*grp*.
+
+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'.
+An example configuration file can be found at '/etc/catalyst/catalyst.conf'.
+
+
+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 'http://bugs.gentoo.org'.
+
+
+SEE ALSO
+--------
+*catalyst(1)*
diff --git a/doc/catalyst.1.txt b/doc/catalyst.1.txt
index b7807a5..4d51eb0 100644
--- a/doc/catalyst.1.txt
+++ b/doc/catalyst.1.txt
@@ -114,13 +114,6 @@ An up-to-date list of Catalyst bugs can always be found listed on the Gentoo
Linux bug-tracking system at 'http://bugs.gentoo.org'.
-SEE ALSO
---------
-A more in-depth examination of Catalyst options and procedures can be found
-linked from the *catalyst* project page, which is located at
-'http://www.gentoo.org/proj/en/releng/catalyst'.
-
-
NOTES
-----
*catalyst* is conceptually derived from the Gentoo livecd-ng and Gentoo
@@ -138,3 +131,12 @@ AUTHORS
- Raul Porcel <armin76@gentoo.org>
- Sebastian Pipping <sping@gentoo.org>
- Matt Turner <mattst88@gentoo.org>
+
+
+SEE ALSO
+--------
+*catalyst-spec(5)*
+
+Also, a more in-depth examination of Catalyst options and procedures can be found
+linked from the *catalyst* project page, which is located at
+'http://www.gentoo.org/proj/en/releng/catalyst'.
diff --git a/doc/make_target_table.py b/doc/make_target_table.py
new file mode 100755
index 0000000..e5e25f0
--- /dev/null
+++ b/doc/make_target_table.py
@@ -0,0 +1,42 @@
+#!/usr/bin/env python
+# Copyright (C) 2012 W. Trevor King <wking@drexel.edu>
+# Copyright (C) 2012 Sebastian Pipping <sebastian@pipping.org>
+# Licensed under GPL v2 or later
+
+# This script should be run from the root of the catalyst source.
+
+from __future__ import print_function
+
+import sys as _sys
+
+_sys.path.insert(0, 'modules') # so we can find the `catalyst` module
+
+import glob
+import re
+
+
+def key_netboot_before_netboot2((target_name, module)):
+ return target_name + '1'
+
+
+if __name__ == '__main__':
+ extractor = re.compile('^modules/(([^ ]+)_target).py$')
+ targets = list()
+ for filename in sorted(glob.glob('modules/*_target.py')):
+ if 'generic' in filename:
+ continue
+
+ match = extractor.match(filename)
+ target_name = match.group(2).replace('_', '-')
+ module_name = match.group(1)
+
+ __import__(module_name)
+ module = _sys.modules[module_name]
+
+ targets.append((target_name, module))
+
+ for target_name, module in sorted(targets, key=key_netboot_before_netboot2):
+ print('`%s`;;' % target_name)
+ # Replace blank lines with `+` (asciidoc list item continuation)
+ print(module.__doc__.strip().replace('\n\n', '\n+\n'))
+ print('')
diff --git a/files/.gitignore b/files/.gitignore
index 10acc02..4a4f038 100644
--- a/files/.gitignore
+++ b/files/.gitignore
@@ -1 +1,3 @@
catalyst.1
+catalyst-spec.5
+
diff --git a/modules/embedded_target.py b/modules/embedded_target.py
index 2ab8cc5..6d34a57 100644
--- a/modules/embedded_target.py
+++ b/modules/embedded_target.py
@@ -1,13 +1,14 @@
-
"""
-This class works like a 'stage3'. A stage2 tarball is unpacked, but instead
-of building a stage3, it emerges a 'system' into another directory
-inside the 'stage2' system. This way we do not have to emerge gcc/portage
-into the staged system.
+Enbedded target, similar to the stage2 target, builds upon a stage2 tarball.
-It sounds real complicated but basically it runs
-ROOT=/tmp/submerge emerge --blahblah foo bar
+A stage2 tarball is unpacked, but instead
+of building a stage3, it emerges @system into another directory
+inside the stage2 system. This way, we do not have to emerge GCC/portage
+into the staged system.
+It may sound complicated but basically it runs
+ROOT=/tmp/submerge emerge --something foo bar .
"""
+# NOTE: That^^ docstring has influence catalyst-spec(5) man page generation.
import os,string,imp,types,shutil
from catalyst_support import *
@@ -15,7 +16,9 @@ from generic_stage_target import *
from stat import *
class embedded_target(generic_stage_target):
-
+ """
+ Builder class for embedded target
+ """
def __init__(self,spec,addlargs):
self.required_values=[]
self.valid_values=[]
diff --git a/modules/generic_stage_target.py b/modules/generic_stage_target.py
index 5947e9a..c4ef239 100644
--- a/modules/generic_stage_target.py
+++ b/modules/generic_stage_target.py
@@ -1,9 +1,3 @@
-
-"""
-This class does all of the chroot setup, copying of files, etc. It is
-the driver class for pretty much everything that Catalyst does.
-"""
-
import os,string,imp,types,shutil
from catalyst_support import *
from generic_target import *
@@ -11,7 +5,10 @@ from stat import *
import catalyst_lock
class generic_stage_target(generic_target):
-
+ """
+ This class does all of the chroot setup, copying of files, etc. It is
+ the driver class for pretty much everything that Catalyst does.
+ """
def __init__(self,myspec,addlargs):
self.required_values.extend(["version_stamp","target","subarch",\
"rel_type","profile","snapshot","source_subpath"])
diff --git a/modules/generic_target.py b/modules/generic_target.py
index 82a4c56..fe96bd7 100644
--- a/modules/generic_target.py
+++ b/modules/generic_target.py
@@ -1,12 +1,9 @@
-
-"""
-The toplevel class for generic_stage_target. This is about as generic as we get.
-"""
-
from catalyst_support import *
class generic_target:
-
+ """
+ The toplevel class for generic_stage_target. This is about as generic as we get.
+ """
def __init__(self,myspec,addlargs):
addl_arg_parse(myspec,addlargs,self.required_values,self.valid_values)
self.settings=myspec
diff --git a/modules/grp_target.py b/modules/grp_target.py
index b077d9c..88a91c7 100644
--- a/modules/grp_target.py
+++ b/modules/grp_target.py
@@ -1,13 +1,16 @@
-
"""
-The builder class for GRP (Gentoo Reference Platform) builds.
+Gentoo Reference Platform (GRP) target
"""
+# NOTE: That^^ docstring has influence catalyst-spec(5) man page generation.
import os,types,glob
from catalyst_support import *
from generic_stage_target import *
class grp_target(generic_stage_target):
+ """
+ The builder class for GRP (Gentoo Reference Platform) builds.
+ """
def __init__(self,spec,addlargs):
self.required_values=["version_stamp","target","subarch",\
"rel_type","profile","snapshot","source_subpath"]
diff --git a/modules/livecd_stage1_target.py b/modules/livecd_stage1_target.py
index 0d5c97c..58e2e80 100644
--- a/modules/livecd_stage1_target.py
+++ b/modules/livecd_stage1_target.py
@@ -1,12 +1,15 @@
-
"""
-Builder class for LiveCD stage1.
+LiveCD stage1 target
"""
+# NOTE: That^^ docstring has influence catalyst-spec(5) man page generation.
from catalyst_support import *
from generic_stage_target import *
class livecd_stage1_target(generic_stage_target):
+ """
+ Builder class for LiveCD stage1.
+ """
def __init__(self,spec,addlargs):
self.required_values=["livecd/packages"]
self.valid_values=self.required_values[:]
diff --git a/modules/livecd_stage2_target.py b/modules/livecd_stage2_target.py
index 2b126ed..11dcc63 100644
--- a/modules/livecd_stage2_target.py
+++ b/modules/livecd_stage2_target.py
@@ -1,13 +1,16 @@
-
"""
-Builder class for a LiveCD stage2 build.
+LiveCD stage2 target, builds upon previous LiveCD stage1 tarball
"""
+# NOTE: That^^ docstring has influence catalyst-spec(5) man page generation.
import os,string,types,stat,shutil
from catalyst_support import *
from generic_stage_target import *
class livecd_stage2_target(generic_stage_target):
+ """
+ Builder class for a LiveCD stage2 build.
+ """
def __init__(self,spec,addlargs):
self.required_values=["boot/kernel"]
diff --git a/modules/netboot2_target.py b/modules/netboot2_target.py
index 444f873..c4d8311 100644
--- a/modules/netboot2_target.py
+++ b/modules/netboot2_target.py
@@ -1,13 +1,16 @@
-
"""
-Builder class for a netboot build, version 2
+netboot target, version 2
"""
+# NOTE: That^^ docstring has influence catalyst-spec(5) man page generation.
import os,string,types
from catalyst_support import *
from generic_stage_target import *
class netboot2_target(generic_stage_target):
+ """
+ Builder class for a netboot build, version 2
+ """
def __init__(self,spec,addlargs):
self.required_values=[
"boot/kernel"
diff --git a/modules/netboot_target.py b/modules/netboot_target.py
index 92c1b04..2f2435e 100644
--- a/modules/netboot_target.py
+++ b/modules/netboot_target.py
@@ -1,13 +1,16 @@
-
"""
-Builder class for a netboot build.
+netboot target, version 1
"""
+# NOTE: That^^ docstring has influence catalyst-spec(5) man page generation.
import os,string,types
from catalyst_support import *
from generic_stage_target import *
class netboot_target(generic_stage_target):
+ """
+ Builder class for a netboot build.
+ """
def __init__(self,spec,addlargs):
self.valid_values = [
"netboot/kernel/sources",
diff --git a/modules/snapshot_target.py b/modules/snapshot_target.py
index 0609377..a427b19 100644
--- a/modules/snapshot_target.py
+++ b/modules/snapshot_target.py
@@ -1,6 +1,5 @@
-
"""
-Builder class for snapshots.
+Snapshot target
"""
import os
@@ -8,6 +7,9 @@ from catalyst_support import *
from generic_stage_target import *
class snapshot_target(generic_stage_target):
+ """
+ Builder class for snapshots.
+ """
def __init__(self,myspec,addlargs):
self.required_values=["version_stamp","target"]
self.valid_values=["version_stamp","target"]
diff --git a/modules/stage1_target.py b/modules/stage1_target.py
index a6eb435..32e6334 100644
--- a/modules/stage1_target.py
+++ b/modules/stage1_target.py
@@ -1,12 +1,15 @@
-
"""
-Builder class for a stage1 installation tarball build.
+stage1 target
"""
+# NOTE: That^^ docstring has influence catalyst-spec(5) man page generation.
from catalyst_support import *
from generic_stage_target import *
class stage1_target(generic_stage_target):
+ """
+ Builder class for a stage1 installation tarball build.
+ """
def __init__(self,spec,addlargs):
self.required_values=[]
self.valid_values=["chost"]
diff --git a/modules/stage2_target.py b/modules/stage2_target.py
index a5135b2..f529721 100644
--- a/modules/stage2_target.py
+++ b/modules/stage2_target.py
@@ -1,12 +1,15 @@
-
"""
-Builder class for a stage2 installation tarball build.
+stage2 target, builds upon previous stage1 tarball
"""
+# NOTE: That^^ docstring has influence catalyst-spec(5) man page generation.
from catalyst_support import *
from generic_stage_target import *
class stage2_target(generic_stage_target):
+ """
+ Builder class for a stage2 installation tarball build.
+ """
def __init__(self,spec,addlargs):
self.required_values=[]
self.valid_values=["chost"]
diff --git a/modules/stage3_target.py b/modules/stage3_target.py
index 6ebdc49..8c839df 100644
--- a/modules/stage3_target.py
+++ b/modules/stage3_target.py
@@ -1,12 +1,15 @@
-
"""
-Builder class for a stage3 installation tarball build.
+stage3 target, builds upon previous stage2/stage3 tarball
"""
+# NOTE: That^^ docstring has influence catalyst-spec(5) man page generation.
from catalyst_support import *
from generic_stage_target import *
class stage3_target(generic_stage_target):
+ """
+ Builder class for a stage3 installation tarball build.
+ """
def __init__(self,spec,addlargs):
self.required_values=[]
self.valid_values=[]
diff --git a/modules/stage4_target.py b/modules/stage4_target.py
index cc8e6c0..591f9b2 100644
--- a/modules/stage4_target.py
+++ b/modules/stage4_target.py
@@ -1,12 +1,15 @@
-
"""
-Builder class for stage4.
+stage4 target, builds upon previous stage3/stage4 tarball
"""
+# NOTE: That^^ docstring has influence catalyst-spec(5) man page generation.
from catalyst_support import *
from generic_stage_target import *
class stage4_target(generic_stage_target):
+ """
+ Builder class for stage4.
+ """
def __init__(self,spec,addlargs):
self.required_values=["stage4/packages"]
self.valid_values=self.required_values[:]
diff --git a/modules/tinderbox_target.py b/modules/tinderbox_target.py
index 42ad6eb..9cc1acc 100644
--- a/modules/tinderbox_target.py
+++ b/modules/tinderbox_target.py
@@ -1,12 +1,15 @@
-
"""
-builder class for the tinderbox target
+Tinderbox target
"""
+# NOTE: That^^ docstring has influence catalyst-spec(5) man page generation.
from catalyst_support import *
from generic_stage_target import *
class tinderbox_target(generic_stage_target):
+ """
+ Builder class for the tinderbox target
+ """
def __init__(self,spec,addlargs):
self.required_values=["tinderbox/packages"]
self.valid_values=self.required_values[:]