From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) by finch.gentoo.org (Postfix) with ESMTP id D821D1381F3 for ; Tue, 16 Apr 2013 01:33:47 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 612F4E09E1; Tue, 16 Apr 2013 01:33:47 +0000 (UTC) Received: from vms173005pub.verizon.net (vms173005pub.verizon.net [206.46.173.5]) by pigeon.gentoo.org (Postfix) with ESMTP id E148AE09E1 for ; Tue, 16 Apr 2013 01:33:41 +0000 (UTC) Received: from odin.tremily.us ([unknown] [72.68.100.81]) by vms173005.mailsrvcs.net (Sun Java(tm) System Messaging Server 7u2-7.02 32bit (built Apr 16 2009)) with ESMTPA id <0MLB00G54QZE6C70@vms173005.mailsrvcs.net> for gentoo-catalyst@lists.gentoo.org; Mon, 15 Apr 2013 20:33:15 -0500 (CDT) Received: by odin.tremily.us (Postfix, from userid 1000) id CF91A96C019; Mon, 15 Apr 2013 21:33:13 -0400 (EDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=tremily.us; s=odin; t=1366075993; bh=dpmcLL1flnX76eb6TAut4Y/5wlqBtjK40sbut/yY5gw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:In-Reply-To: References; b=mOxX+XaBHsUKZ4quJkZ95D0WM20RKzwAgodOKq1Q8PYcgJftCA59P/GOaXlh9zggL oiBZKpgwCBi3O2zm682XSPSUXy6VzozgJRGu2d1xuEsN+USPc8BQHyxHN3Kzb2gGKb FoljKg5ZooCD/IJpmJpsRiVsb41tZmSxpRU7H1kg= From: "W. Trevor King" To: Catalyst Cc: "W. Trevor King" Subject: [gentoo-catalyst] [PATCH v3 1/2] doc/catalyst-config.5.txt: Add man page for catalyst.conf Date: Mon, 15 Apr 2013 21:33:08 -0400 Message-id: <0d02179a4ff3f0bfb422bf5260aa020f4921d709.1366075786.git.wking@tremily.us> X-Mailer: git-send-email 1.8.1.5 In-reply-to: References: <516860BF.7000405@gentoo.org> In-reply-to: References: Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-catalyst@lists.gentoo.org Reply-to: gentoo-catalyst@lists.gentoo.org X-Archives-Salt: a01ad27f-b434-40e0-81c2-ce5bbfcce164 X-Archives-Hash: ef7d2e0ed9a7cd73438e074d981b48dd From: "W. Trevor King" 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 | 192 ++++++++++++++++++++++++++++++++++++++++++++++ doc/catalyst-spec.5.txt | 2 +- doc/catalyst.1.txt | 1 + files/.gitignore | 1 + 4 files changed, 195 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..27bc0bb --- /dev/null +++ b/doc/catalyst-config.5.txt @@ -0,0 +1,192 @@ +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. WARNING: ccache has been known to +cause random build failures and bugs reported with ccache enabled may +be closed invalid. + +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 copy of the built kernel and modules. This is useful if your +build dies during `livecd-stage2`. + +pkgcache:: +Enable `--usepkg` and `--buildpkg` for most *emerge(1)* runs. This is +useful if your build dies prematurely. However, you may experience +linking problems. + +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. +-- + +*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 (example: +`/var/tmp/catalyst`). + +*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-spec(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..9f70f78 100644 --- a/doc/catalyst.1.txt +++ b/doc/catalyst.1.txt @@ -135,6 +135,7 @@ AUTHORS SEE ALSO -------- +*catalyst-config(5)* *catalyst-spec(5)* Also, a more in-depth examination of Catalyst options and procedures can be found 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