1 |
From: "W. Trevor King" <wking@×××××××.us> |
2 |
|
3 |
This mostly translates the inline comments from files/catalyst.conf |
4 |
into asciidoc. While it's nice to have that as stand-alone |
5 |
documentation, it also makes it easier to refer to longer descriptions |
6 |
of any tricky issues. This gives us a place to distill the collected |
7 |
wisdom of current users for the benefit of others. |
8 |
--- |
9 |
doc/catalyst-config.5.txt | 188 ++++++++++++++++++++++++++++++++++++++++++++++ |
10 |
doc/catalyst-spec.5.txt | 2 +- |
11 |
doc/catalyst.1.txt | 1 + |
12 |
files/.gitignore | 1 + |
13 |
4 files changed, 191 insertions(+), 1 deletion(-) |
14 |
create mode 100644 doc/catalyst-config.5.txt |
15 |
|
16 |
diff --git a/doc/catalyst-config.5.txt b/doc/catalyst-config.5.txt |
17 |
new file mode 100644 |
18 |
index 0000000..944f392 |
19 |
--- /dev/null |
20 |
+++ b/doc/catalyst-config.5.txt |
21 |
@@ -0,0 +1,188 @@ |
22 |
+CATALYST-CONFIG(5) |
23 |
+================ |
24 |
+:man source: catalyst {catalystversion} |
25 |
+:man manual: catalyst {catalystversion} |
26 |
+ |
27 |
+ |
28 |
+NAME |
29 |
+---- |
30 |
+catalyst-config - Catalyst configuration files |
31 |
+ |
32 |
+ |
33 |
+SYNOPSIS |
34 |
+-------- |
35 |
+*catalyst* ['OPTIONS'] *-c* 'FILE' |
36 |
+ |
37 |
+ |
38 |
+DESCRIPTION |
39 |
+----------- |
40 |
+ |
41 |
+*catalyst(1)* reads the configuration file given with `-c` or |
42 |
+`--config` on the command line. The file contains keyword-argument |
43 |
+pairs using a POSIX Shell variable syntax. Lines starting with `#` |
44 |
+and empty lines are interpreted as comments. For example: |
45 |
+ |
46 |
+--------------------------------- |
47 |
+# /etc/catalyst/catalyst.conf |
48 |
+digests="md5 sha1 sha512 whirlpool" |
49 |
+contents="auto" |
50 |
+distdir="/usr/portage/distfiles" |
51 |
+envscript="/etc/catalyst/catalystrc" |
52 |
+options="autoresume bindist kerncache pkgcache seedcache snapcache" |
53 |
+portdir="/usr/portage" |
54 |
+sharedir="/usr/lib/catalyst" |
55 |
+snapshot_cache="/var/tmp/catalyst/snapshot_cache" |
56 |
+storedir="/var/tmp/catalyst" |
57 |
+--------------------------------- |
58 |
+ |
59 |
+The possible keywords and their meanings are as follows: |
60 |
+ |
61 |
+Basic configuration |
62 |
+~~~~~~~~~~~~~~~~~~~ |
63 |
+ |
64 |
+*digests*:: |
65 |
+Create a `.DIGESTS` file containing the hash output from any of the |
66 |
+supported options below. Adding them all may take a long time. |
67 |
+(example: `md5 sha1 sha512 whirlpool`). See the *SUPPORTED HASHES* |
68 |
+section for a list of supported hashes. |
69 |
+ |
70 |
+*contents*:: |
71 |
+Create a `.CONTENTS` file listing the contents of the file. If this |
72 |
+variable is empty, no `.CONTENTS` will be generated at all. Supported |
73 |
+values: |
74 |
++ |
75 |
+-- |
76 |
+auto:: |
77 |
+Strongly recommended |
78 |
+ |
79 |
+tar-tv:: |
80 |
+Do `tar tvf FILE` |
81 |
+ |
82 |
+tar-tvz:: |
83 |
+Do `tar tvzf FILE` |
84 |
+ |
85 |
+tar-tvy:: |
86 |
+Do `tar tvyf FILE` |
87 |
+ |
88 |
+isoinfo-l:: |
89 |
+Do `isoinfo -l -i FILE` |
90 |
+ |
91 |
+isoinfo-f:: |
92 |
+Do `isoinfo -f -i FILE`. 'isoinfo-f' is the only option not chosen |
93 |
+by the automatic algorithm. |
94 |
+-- |
95 |
+ |
96 |
+*distdir*:: |
97 |
+Distfiles location. `/usr/portage/distfiles` should work for most |
98 |
+default installations. |
99 |
+ |
100 |
+*envscript*:: |
101 |
+Environment script location, which allows users to set options such as |
102 |
+HTTP proxies, `MAKEOPTS`, `GENTOO_MIRRORS`, or any other environment |
103 |
+variables needed for building. The envscript file sets environment |
104 |
+variables using POSIX shell notation: |
105 |
++ |
106 |
+--------------------------------- |
107 |
+export FOO="bar" |
108 |
+--------------------------------- |
109 |
+ |
110 |
+*hash_function*:: |
111 |
+Internal hash function catalyst should use for things like autoresume, |
112 |
+seedcache, etc. The default and fastest is `crc32`. You should not |
113 |
+ever need to change this unless your OS does not support it. See the |
114 |
+*SUPPORTED HASHES* section for a list of supported hashes. |
115 |
+ |
116 |
+**options*:: |
117 |
+Set different build-time options (example: `autoresume bindist |
118 |
+kerncache pkgcache seedcache snapcache`). Supported values: |
119 |
++ |
120 |
+-- |
121 |
+autoresume:: |
122 |
+Attempt to resume a failed build. Clear the autoresume flags with the |
123 |
+`-a` option to the catalyst command line. `-p` will clear the |
124 |
+autoresume flags as well as your pkgcache and kerncache. |
125 |
+ |
126 |
+bindist:: |
127 |
+Enable the `bindist` `USE` flag. This is recommended if you will be |
128 |
+redistributing builds, but see the package specific definitions for |
129 |
+details. |
130 |
+ |
131 |
+ccache:: |
132 |
+Enable build time ccache support. |
133 |
+ |
134 |
+distcc:: |
135 |
+Enable distcc support for building. You have to set distcc_hosts in |
136 |
+your spec file. |
137 |
+ |
138 |
+icecream:: |
139 |
+Enable icecream compiler cluster support for building. |
140 |
+ |
141 |
+kerncache:: |
142 |
+Keep a `tbz2` of your built kernel and modules. This is useful if |
143 |
+your build dies during `livecd-stage2`. |
144 |
+ |
145 |
+pkgcache:: |
146 |
+Keep a ``tbz2`` of every built package. This is useful if your build |
147 |
+dies prematurely. |
148 |
+ |
149 |
+seedcache:: |
150 |
+Use the build output of a previous target if it exists to speed up the |
151 |
+creation of a new stage. This avoids unpacking the seed tarball. |
152 |
+ |
153 |
+snapcache:: |
154 |
+Cache the snapshot so that it can be bind-mounted into the chroot. |
155 |
+WARNING: moving parts of the portage tree from within fsscript *will* |
156 |
+break your cache. The cache is unlinked before any empty or rm |
157 |
+processing, though. |
158 |
+-- |
159 |
+ |
160 |
+*portdir*:: |
161 |
+Portage tree location. `/usr/portage/` should work for most default |
162 |
+installations. |
163 |
+ |
164 |
+*sharedir*:: |
165 |
+Catalyst runtime script location. `/usr/lib/catalyst` should work for |
166 |
+most default installations. If you are running catalyst from a Git |
167 |
+checkout, you should change this to point to your checkout directory. |
168 |
+ |
169 |
+*storedir*:: |
170 |
+Location for built seeds, temporary files, and caches. |
171 |
+ |
172 |
+*port_logdir*:: |
173 |
+Location for build logs (example: `/var/tmp/catalyst/tmp`). This dir |
174 |
+will be automatically cleaned of all logs over 30 days old. If left |
175 |
+undefined the logs will remain in the build directory as usual and get |
176 |
+cleaned every time a stage build is restarted. |
177 |
+ |
178 |
+*var_tmpfs_portage*:: |
179 |
+Set the size of a `/var/tmp/portage` tmpfs in gigabytes (example: |
180 |
+`16`). If set, this mounts a tmpfs for `/var/tmp/portage` so building |
181 |
+takes place in RAM. This feature requires a pretty large tmpfs |
182 |
+({open,libre}office needs ~8GB to build). WARNING: If you use too |
183 |
+much RAM everything will fail horribly and it is not our fault. |
184 |
+ |
185 |
+ |
186 |
+SUPPORTED HASHES |
187 |
+---------------- |
188 |
+Supported hashes: adler32, crc32, crc32b, gost, haval128, haval160, |
189 |
+haval192, haval224, haval256, md2, md4, md5, ripemd128, ripemd160, |
190 |
+ripemd256, ripemd320, sha1, sha224, sha256, sha384, sha512, snefru128, |
191 |
+snefru256, tiger, tiger128, tiger160, whirlpool. |
192 |
+ |
193 |
+ |
194 |
+FILES |
195 |
+----- |
196 |
+An example configuration file can be found at |
197 |
+`/etc/catalyst/catalyst.conf`. |
198 |
+ |
199 |
+ |
200 |
+BUGS |
201 |
+---- |
202 |
+An up-to-date list of Catalyst bugs can always be found listed on the Gentoo |
203 |
+Linux bug-tracking system at `http://bugs.gentoo.org`. |
204 |
+ |
205 |
+ |
206 |
+SEE ALSO |
207 |
+-------- |
208 |
+*catalyst(1)* |
209 |
+*catalyst-config(5)* |
210 |
diff --git a/doc/catalyst-spec.5.txt b/doc/catalyst-spec.5.txt |
211 |
index 4a6e06c..b3e2bf5 100644 |
212 |
--- a/doc/catalyst-spec.5.txt |
213 |
+++ b/doc/catalyst-spec.5.txt |
214 |
@@ -496,7 +496,6 @@ specific options for the game. This is not used on the release media. |
215 |
FILES |
216 |
----- |
217 |
Example specfiles can be found in '/usr/share/doc/catalyst-{catalystversion}/examples'. |
218 |
-An example configuration file can be found at '/etc/catalyst/catalyst.conf'. |
219 |
|
220 |
|
221 |
SUPPORTED ARCHITECTURES |
222 |
@@ -516,3 +515,4 @@ Linux bug-tracking system at 'http://bugs.gentoo.org'. |
223 |
SEE ALSO |
224 |
-------- |
225 |
*catalyst(1)* |
226 |
+*catalyst-config(5)* |
227 |
diff --git a/doc/catalyst.1.txt b/doc/catalyst.1.txt |
228 |
index 4d51eb0..09dc119 100644 |
229 |
--- a/doc/catalyst.1.txt |
230 |
+++ b/doc/catalyst.1.txt |
231 |
@@ -136,6 +136,7 @@ AUTHORS |
232 |
SEE ALSO |
233 |
-------- |
234 |
*catalyst-spec(5)* |
235 |
+*catalyst-config(5)* |
236 |
|
237 |
Also, a more in-depth examination of Catalyst options and procedures can be found |
238 |
linked from the *catalyst* project page, which is located at |
239 |
diff --git a/files/.gitignore b/files/.gitignore |
240 |
index 9dbf1f1..7773aeb 100644 |
241 |
--- a/files/.gitignore |
242 |
+++ b/files/.gitignore |
243 |
@@ -1,4 +1,5 @@ |
244 |
catalyst.1 |
245 |
+catalyst-config.5 |
246 |
catalyst-spec.5 |
247 |
*.html |
248 |
*.css |
249 |
-- |
250 |
1.8.2 |