From: "W. Trevor King" <wking@tremily.us>
To: Catalyst <gentoo-catalyst@lists.gentoo.org>
Cc: "W. Trevor King" <wking@tremily.us>
Subject: [gentoo-catalyst] [PATCH v2 1/2] doc/catalyst-config.5.txt: Add man page for catalyst.conf
Date: Fri, 12 Apr 2013 14:21:42 -0400 [thread overview]
Message-ID: <60fb3b46ea7b9741d088c4ff2d9b158858214ba0.1365790593.git.wking@tremily.us> (raw)
In-Reply-To: <cover.1365790593.git.wking@tremily.us>
In-Reply-To: <cover.1365790593.git.wking@tremily.us>
From: "W. Trevor King" <wking@tremily.us>
This mostly translates the inline comments from files/catalyst.conf
into asciidoc. While it's nice to have that as stand-alone
documentation, it also makes it easier to refer to longer descriptions
of any tricky issues. This gives us a place to distill the collected
wisdom of current users for the benefit of others.
---
doc/catalyst-config.5.txt | 188 ++++++++++++++++++++++++++++++++++++++++++++++
doc/catalyst-spec.5.txt | 2 +-
doc/catalyst.1.txt | 1 +
files/.gitignore | 1 +
4 files changed, 191 insertions(+), 1 deletion(-)
create mode 100644 doc/catalyst-config.5.txt
diff --git a/doc/catalyst-config.5.txt b/doc/catalyst-config.5.txt
new file mode 100644
index 0000000..944f392
--- /dev/null
+++ b/doc/catalyst-config.5.txt
@@ -0,0 +1,188 @@
+CATALYST-CONFIG(5)
+================
+:man source: catalyst {catalystversion}
+:man manual: catalyst {catalystversion}
+
+
+NAME
+----
+catalyst-config - Catalyst configuration files
+
+
+SYNOPSIS
+--------
+*catalyst* ['OPTIONS'] *-c* 'FILE'
+
+
+DESCRIPTION
+-----------
+
+*catalyst(1)* reads the configuration file given with `-c` or
+`--config` on the command line. The file contains keyword-argument
+pairs using a POSIX Shell variable syntax. Lines starting with `#`
+and empty lines are interpreted as comments. For example:
+
+---------------------------------
+# /etc/catalyst/catalyst.conf
+digests="md5 sha1 sha512 whirlpool"
+contents="auto"
+distdir="/usr/portage/distfiles"
+envscript="/etc/catalyst/catalystrc"
+options="autoresume bindist kerncache pkgcache seedcache snapcache"
+portdir="/usr/portage"
+sharedir="/usr/lib/catalyst"
+snapshot_cache="/var/tmp/catalyst/snapshot_cache"
+storedir="/var/tmp/catalyst"
+---------------------------------
+
+The possible keywords and their meanings are as follows:
+
+Basic configuration
+~~~~~~~~~~~~~~~~~~~
+
+*digests*::
+Create a `.DIGESTS` file containing the hash output from any of the
+supported options below. Adding them all may take a long time.
+(example: `md5 sha1 sha512 whirlpool`). See the *SUPPORTED HASHES*
+section for a list of supported hashes.
+
+*contents*::
+Create a `.CONTENTS` file listing the contents of the file. If this
+variable is empty, no `.CONTENTS` will be generated at all. Supported
+values:
++
+--
+auto::
+Strongly recommended
+
+tar-tv::
+Do `tar tvf FILE`
+
+tar-tvz::
+Do `tar tvzf FILE`
+
+tar-tvy::
+Do `tar tvyf FILE`
+
+isoinfo-l::
+Do `isoinfo -l -i FILE`
+
+isoinfo-f::
+Do `isoinfo -f -i FILE`. 'isoinfo-f' is the only option not chosen
+by the automatic algorithm.
+--
+
+*distdir*::
+Distfiles location. `/usr/portage/distfiles` should work for most
+default installations.
+
+*envscript*::
+Environment script location, which allows users to set options such as
+HTTP proxies, `MAKEOPTS`, `GENTOO_MIRRORS`, or any other environment
+variables needed for building. The envscript file sets environment
+variables using POSIX shell notation:
++
+---------------------------------
+export FOO="bar"
+---------------------------------
+
+*hash_function*::
+Internal hash function catalyst should use for things like autoresume,
+seedcache, etc. The default and fastest is `crc32`. You should not
+ever need to change this unless your OS does not support it. See the
+*SUPPORTED HASHES* section for a list of supported hashes.
+
+**options*::
+Set different build-time options (example: `autoresume bindist
+kerncache pkgcache seedcache snapcache`). Supported values:
++
+--
+autoresume::
+Attempt to resume a failed build. Clear the autoresume flags with the
+`-a` option to the catalyst command line. `-p` will clear the
+autoresume flags as well as your pkgcache and kerncache.
+
+bindist::
+Enable the `bindist` `USE` flag. This is recommended if you will be
+redistributing builds, but see the package specific definitions for
+details.
+
+ccache::
+Enable build time ccache support.
+
+distcc::
+Enable distcc support for building. You have to set distcc_hosts in
+your spec file.
+
+icecream::
+Enable icecream compiler cluster support for building.
+
+kerncache::
+Keep a `tbz2` of your built kernel and modules. This is useful if
+your build dies during `livecd-stage2`.
+
+pkgcache::
+Keep a ``tbz2`` of every built package. This is useful if your build
+dies prematurely.
+
+seedcache::
+Use the build output of a previous target if it exists to speed up the
+creation of a new stage. This avoids unpacking the seed tarball.
+
+snapcache::
+Cache the snapshot so that it can be bind-mounted into the chroot.
+WARNING: moving parts of the portage tree from within fsscript *will*
+break your cache. The cache is unlinked before any empty or rm
+processing, though.
+--
+
+*portdir*::
+Portage tree location. `/usr/portage/` should work for most default
+installations.
+
+*sharedir*::
+Catalyst runtime script location. `/usr/lib/catalyst` should work for
+most default installations. If you are running catalyst from a Git
+checkout, you should change this to point to your checkout directory.
+
+*storedir*::
+Location for built seeds, temporary files, and caches.
+
+*port_logdir*::
+Location for build logs (example: `/var/tmp/catalyst/tmp`). This dir
+will be automatically cleaned of all logs over 30 days old. If left
+undefined the logs will remain in the build directory as usual and get
+cleaned every time a stage build is restarted.
+
+*var_tmpfs_portage*::
+Set the size of a `/var/tmp/portage` tmpfs in gigabytes (example:
+`16`). If set, this mounts a tmpfs for `/var/tmp/portage` so building
+takes place in RAM. This feature requires a pretty large tmpfs
+({open,libre}office needs ~8GB to build). WARNING: If you use too
+much RAM everything will fail horribly and it is not our fault.
+
+
+SUPPORTED HASHES
+----------------
+Supported hashes: adler32, crc32, crc32b, gost, haval128, haval160,
+haval192, haval224, haval256, md2, md4, md5, ripemd128, ripemd160,
+ripemd256, ripemd320, sha1, sha224, sha256, sha384, sha512, snefru128,
+snefru256, tiger, tiger128, tiger160, whirlpool.
+
+
+FILES
+-----
+An example configuration file can be found at
+`/etc/catalyst/catalyst.conf`.
+
+
+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)*
+*catalyst-config(5)*
diff --git a/doc/catalyst-spec.5.txt b/doc/catalyst-spec.5.txt
index 4a6e06c..b3e2bf5 100644
--- a/doc/catalyst-spec.5.txt
+++ b/doc/catalyst-spec.5.txt
@@ -496,7 +496,6 @@ 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
@@ -516,3 +515,4 @@ Linux bug-tracking system at 'http://bugs.gentoo.org'.
SEE ALSO
--------
*catalyst(1)*
+*catalyst-config(5)*
diff --git a/doc/catalyst.1.txt b/doc/catalyst.1.txt
index 4d51eb0..09dc119 100644
--- a/doc/catalyst.1.txt
+++ b/doc/catalyst.1.txt
@@ -136,6 +136,7 @@ AUTHORS
SEE ALSO
--------
*catalyst-spec(5)*
+*catalyst-config(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
diff --git a/files/.gitignore b/files/.gitignore
index 9dbf1f1..7773aeb 100644
--- a/files/.gitignore
+++ b/files/.gitignore
@@ -1,4 +1,5 @@
catalyst.1
+catalyst-config.5
catalyst-spec.5
*.html
*.css
--
1.8.2
next prev parent reply other threads:[~2013-04-12 18:22 UTC|newest]
Thread overview: 76+ messages / expand[flat|nested] mbox.gz Atom feed top
2013-02-26 16:20 [gentoo-catalyst] patch, fix broken seed stage update Brian Dolbec
2013-02-26 16:37 ` W. Trevor King
2013-02-26 16:47 ` Brian Dolbec
2013-02-26 16:48 ` Peter Stuge
2013-02-26 17:29 ` Rick "Zero_Chaos" Farina
2013-02-26 19:39 ` Matt Turner
2013-02-27 2:04 ` Brian Dolbec
2013-02-27 2:37 ` Matt Turner
2013-02-27 12:12 ` W. Trevor King
2013-02-27 2:37 ` Matt Turner
2013-02-27 3:03 ` Brian Dolbec
2013-02-27 3:22 ` Matt Turner
2013-02-27 3:49 ` Brian Dolbec
2013-03-08 17:27 ` [gentoo-catalyst] [PATCH v2] Remove update_seed_command and strengthen update_seed W. Trevor King
2013-03-08 18:34 ` Rick "Zero_Chaos" Farina
2013-03-08 18:47 ` [gentoo-catalyst] [PATCH v3] Strengthen update_seed to update @system and @world with dependencies W. Trevor King
2013-03-08 20:14 ` Matt Turner
2013-03-09 12:10 ` [gentoo-catalyst] " W. Trevor King
2013-04-11 17:09 ` [gentoo-catalyst] Binary package dependencies and update_seed W. Trevor King
2013-04-11 17:39 ` Rick "Zero_Chaos" Farina
2013-04-11 17:52 ` W. Trevor King
2013-04-12 15:12 ` [gentoo-catalyst] [PATCH] files/catalyst.conf: Document linking issues with binary packages W. Trevor King
2013-04-12 15:21 ` Rick "Zero_Chaos" Farina
2013-04-12 15:33 ` W. Trevor King
2013-04-12 16:11 ` Rick "Zero_Chaos" Farina
2013-04-12 18:21 ` [gentoo-catalyst] [PATCH v2 0/2] pkgcache warning in catalyst-config(5) W. Trevor King
2013-04-12 18:21 ` W. Trevor King [this message]
2013-04-12 18:27 ` [gentoo-catalyst] Re: [PATCH v2 1/2] doc/catalyst-config.5.txt: Add man page for catalyst.conf W. Trevor King
2013-04-12 18:47 ` [gentoo-catalyst] " Rick "Zero_Chaos" Farina
2013-04-12 19:05 ` W. Trevor King
2013-04-12 19:30 ` Rick "Zero_Chaos" Farina
2013-04-16 1:33 ` [gentoo-catalyst] [PATCH v3 0/2] pkgcache warning in catalyst-config(5) W. Trevor King
2013-04-16 1:33 ` [gentoo-catalyst] [PATCH v3 1/2] doc/catalyst-config.5.txt: Add man page for catalyst.conf W. Trevor King
2013-04-16 1:33 ` [gentoo-catalyst] [PATCH v3 2/2] doc/catalyst-config.5.txt: Document linking issues with binary packages W. Trevor King
2013-12-14 5:41 ` [gentoo-catalyst] Re: [PATCH v3 0/2] pkgcache warning in catalyst-config(5) W. Trevor King
2013-04-12 18:21 ` [gentoo-catalyst] [PATCH v2 2/2] doc/catalyst-config.5.txt: Document linking issues with binary packages W. Trevor King
2013-04-11 18:20 ` [gentoo-catalyst] Binary package dependencies and update_seed Matt Turner
2013-04-11 18:22 ` Matt Turner
2013-04-11 18:53 ` Rick "Zero_Chaos" Farina
2013-04-11 19:00 ` W. Trevor King
2013-04-11 19:03 ` Matt Turner
2013-04-11 19:18 ` Rick "Zero_Chaos" Farina
2013-04-11 20:24 ` Matt Turner
2013-04-11 20:34 ` W. Trevor King
2013-04-12 1:11 ` W. Trevor King
2013-04-11 20:37 ` Rick "Zero_Chaos" Farina
2013-04-11 18:53 ` W. Trevor King
2013-04-12 6:57 ` Brian Dolbec
2013-04-16 19:42 ` [gentoo-catalyst] [PATCH 0/2] Blacklisting binary packages W. Trevor King
2013-04-16 19:42 ` [gentoo-catalyst] [PATCH 1/2] spec: Add binpkg_blacklist option for troublesome packages W. Trevor King
2013-04-16 19:42 ` [gentoo-catalyst] [PATCH 2/2] Revert "don't build packages during update_seed" W. Trevor King
2013-04-16 20:35 ` [gentoo-catalyst] [PATCH 0/2] Blacklisting binary packages Matt Turner
2013-04-16 20:59 ` W. Trevor King
[not found] ` <516DD074.3090906@gentoo.org>
2013-04-16 22:53 ` W. Trevor King
2013-04-17 4:18 ` Brian Dolbec
2013-04-17 11:30 ` W. Trevor King
2013-04-17 14:57 ` Matt Turner
2013-04-19 14:11 ` Rick "Zero_Chaos" Farina
2013-04-19 16:18 ` W. Trevor King
2013-04-19 16:32 ` Rick "Zero_Chaos" Farina
2013-04-19 16:36 ` W. Trevor King
-- strict thread matches above, loose matches on Subject: below --
2013-01-08 8:32 [gentoo-catalyst] More proposed Catalyst changes Brian Dolbec
2013-01-08 18:08 ` Peter Stuge
2013-01-12 8:55 ` Brian Dolbec
2013-01-31 18:39 ` W. Trevor King
2013-01-31 19:46 ` W. Trevor King
2013-02-02 20:41 ` Brian Dolbec
2013-02-03 12:44 ` W. Trevor King
2013-04-11 2:06 ` [gentoo-catalyst] chmod +x all sh scripts so they can run from the git checkout W. Trevor King
2013-02-02 18:45 ` [gentoo-catalyst] More proposed Catalyst changes Brian Dolbec
2013-02-03 12:20 ` W. Trevor King
2013-02-26 18:04 ` [gentoo-catalyst] patch, fix broken seed stage update W. Trevor King
2013-02-27 1:30 ` Brian Dolbec
2013-02-27 1:40 ` W. Trevor King
2013-02-27 2:35 ` Brian Dolbec
2013-02-27 2:41 ` Matt Turner
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=60fb3b46ea7b9741d088c4ff2d9b158858214ba0.1365790593.git.wking@tremily.us \
--to=wking@tremily.us \
--cc=gentoo-catalyst@lists.gentoo.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox