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