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 DC95D1381F3 for ; Fri, 12 Apr 2013 18:22:06 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 32687E096F; Fri, 12 Apr 2013 18:22:01 +0000 (UTC) Received: from vms173005pub.verizon.net (vms173005pub.verizon.net [206.46.173.5]) by pigeon.gentoo.org (Postfix) with ESMTP id A4B8FE096F for ; Fri, 12 Apr 2013 18:22:00 +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 <0ML5004BWN0BFZF0@vms173005.mailsrvcs.net> for gentoo-catalyst@lists.gentoo.org; Fri, 12 Apr 2013 13:21:49 -0500 (CDT) Received: by odin.tremily.us (Postfix, from userid 1000) id 9CD9C9677B4; Fri, 12 Apr 2013 14:21:47 -0400 (EDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=tremily.us; s=odin; t=1365790907; bh=dosN/rdxNbb2f2uGZhRhnqPH7QJFkUcMchuXmtY5KJQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:In-Reply-To: References; b=YPmvimrvnlZQUVMwm5QVWJGexNAOk3Dg5gifiA0VgmunVeGKI6HCpYmR1z03+iInh CAkPfvO3TtIf85DXtXwnkELP4PwIBj9PJ+afsFhlwNLcYMwktrOJIs4wEPqw92xBgZ TO+UPw8S30XHXg9HDV2ggs26XRUUF51KbNyM9MYg= From: "W. Trevor King" To: Catalyst Cc: "W. Trevor King" 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 Message-id: <60fb3b46ea7b9741d088c4ff2d9b158858214ba0.1365790593.git.wking@tremily.us> X-Mailer: git-send-email 1.8.1.5 In-reply-to: References: <51683217.3070805@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: 0a2ee03e-d013-4315-98bc-4a33674f3a6c X-Archives-Hash: 358f7297e8d294487bc0c6fc04639d1b 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 | 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