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