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 | 192 ++++++++++++++++++++++++++++++++++++++++++++++ |
10 |
doc/catalyst-spec.5.txt | 2 +- |
11 |
doc/catalyst.1.txt | 1 + |
12 |
files/.gitignore | 1 + |
13 |
4 files changed, 195 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..27bc0bb |
19 |
--- /dev/null |
20 |
+++ b/doc/catalyst-config.5.txt |
21 |
@@ -0,0 +1,192 @@ |
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. WARNING: ccache has been known to |
133 |
+cause random build failures and bugs reported with ccache enabled may |
134 |
+be closed invalid. |
135 |
+ |
136 |
+distcc:: |
137 |
+Enable distcc support for building. You have to set distcc_hosts in |
138 |
+your spec file. |
139 |
+ |
140 |
+icecream:: |
141 |
+Enable icecream compiler cluster support for building. |
142 |
+ |
143 |
+kerncache:: |
144 |
+Keep a copy of the built kernel and modules. This is useful if your |
145 |
+build dies during `livecd-stage2`. |
146 |
+ |
147 |
+pkgcache:: |
148 |
+Enable `--usepkg` and `--buildpkg` for most *emerge(1)* runs. This is |
149 |
+useful if your build dies prematurely. However, you may experience |
150 |
+linking problems. |
151 |
+ |
152 |
+seedcache:: |
153 |
+Use the build output of a previous target if it exists to speed up the |
154 |
+creation of a new stage. This avoids unpacking the seed tarball. |
155 |
+ |
156 |
+snapcache:: |
157 |
+Cache the snapshot so that it can be bind-mounted into the chroot. |
158 |
+WARNING: moving parts of the portage tree from within fsscript *will* |
159 |
+break your cache. The cache is unlinked before any empty or rm |
160 |
+processing. |
161 |
+-- |
162 |
+ |
163 |
+*portdir*:: |
164 |
+Portage tree location. `/usr/portage/` should work for most default |
165 |
+installations. |
166 |
+ |
167 |
+*sharedir*:: |
168 |
+Catalyst runtime script location. `/usr/lib/catalyst` should work for |
169 |
+most default installations. If you are running catalyst from a Git |
170 |
+checkout, you should change this to point to your checkout directory. |
171 |
+ |
172 |
+*storedir*:: |
173 |
+Location for built seeds, temporary files, and caches (example: |
174 |
+`/var/tmp/catalyst`). |
175 |
+ |
176 |
+*port_logdir*:: |
177 |
+Location for build logs (example: `/var/tmp/catalyst/tmp`). This dir |
178 |
+will be automatically cleaned of all logs over 30 days old. If left |
179 |
+undefined the logs will remain in the build directory as usual and get |
180 |
+cleaned every time a stage build is restarted. |
181 |
+ |
182 |
+*var_tmpfs_portage*:: |
183 |
+Set the size of a `/var/tmp/portage` tmpfs in gigabytes (example: |
184 |
+`16`). If set, this mounts a tmpfs for `/var/tmp/portage` so building |
185 |
+takes place in RAM. This feature requires a pretty large tmpfs |
186 |
+({open,libre}office needs ~8GB to build). WARNING: If you use too |
187 |
+much RAM everything will fail horribly and it is not our fault. |
188 |
+ |
189 |
+ |
190 |
+SUPPORTED HASHES |
191 |
+---------------- |
192 |
+Supported hashes: adler32, crc32, crc32b, gost, haval128, haval160, |
193 |
+haval192, haval224, haval256, md2, md4, md5, ripemd128, ripemd160, |
194 |
+ripemd256, ripemd320, sha1, sha224, sha256, sha384, sha512, snefru128, |
195 |
+snefru256, tiger, tiger128, tiger160, whirlpool. |
196 |
+ |
197 |
+ |
198 |
+FILES |
199 |
+----- |
200 |
+An example configuration file can be found at |
201 |
+`/etc/catalyst/catalyst.conf`. |
202 |
+ |
203 |
+ |
204 |
+BUGS |
205 |
+---- |
206 |
+An up-to-date list of Catalyst bugs can always be found listed on the Gentoo |
207 |
+Linux bug-tracking system at `http://bugs.gentoo.org`. |
208 |
+ |
209 |
+ |
210 |
+SEE ALSO |
211 |
+-------- |
212 |
+*catalyst(1)* |
213 |
+*catalyst-spec(5)* |
214 |
diff --git a/doc/catalyst-spec.5.txt b/doc/catalyst-spec.5.txt |
215 |
index 4a6e06c..b3e2bf5 100644 |
216 |
--- a/doc/catalyst-spec.5.txt |
217 |
+++ b/doc/catalyst-spec.5.txt |
218 |
@@ -496,7 +496,6 @@ specific options for the game. This is not used on the release media. |
219 |
FILES |
220 |
----- |
221 |
Example specfiles can be found in '/usr/share/doc/catalyst-{catalystversion}/examples'. |
222 |
-An example configuration file can be found at '/etc/catalyst/catalyst.conf'. |
223 |
|
224 |
|
225 |
SUPPORTED ARCHITECTURES |
226 |
@@ -516,3 +515,4 @@ Linux bug-tracking system at 'http://bugs.gentoo.org'. |
227 |
SEE ALSO |
228 |
-------- |
229 |
*catalyst(1)* |
230 |
+*catalyst-config(5)* |
231 |
diff --git a/doc/catalyst.1.txt b/doc/catalyst.1.txt |
232 |
index 4d51eb0..9f70f78 100644 |
233 |
--- a/doc/catalyst.1.txt |
234 |
+++ b/doc/catalyst.1.txt |
235 |
@@ -135,6 +135,7 @@ AUTHORS |
236 |
|
237 |
SEE ALSO |
238 |
-------- |
239 |
+*catalyst-config(5)* |
240 |
*catalyst-spec(5)* |
241 |
|
242 |
Also, a more in-depth examination of Catalyst options and procedures can be found |
243 |
diff --git a/files/.gitignore b/files/.gitignore |
244 |
index 9dbf1f1..7773aeb 100644 |
245 |
--- a/files/.gitignore |
246 |
+++ b/files/.gitignore |
247 |
@@ -1,4 +1,5 @@ |
248 |
catalyst.1 |
249 |
+catalyst-config.5 |
250 |
catalyst-spec.5 |
251 |
*.html |
252 |
*.css |
253 |
-- |
254 |
1.8.2 |