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 840191381F3 for ; Fri, 12 Apr 2013 18:44:50 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id E93D9E09EE; Fri, 12 Apr 2013 18:44:48 +0000 (UTC) Received: from smtp.gentoo.org (smtp.gentoo.org [140.211.166.183]) (using TLSv1 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id 57581E09EE for ; Fri, 12 Apr 2013 18:44:48 +0000 (UTC) Received: from [192.168.1.11] (pool-71-245-176-92.pitbpa.fios.verizon.net [71.245.176.92]) (using TLSv1 with cipher ECDHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) (Authenticated sender: zerochaos) by smtp.gentoo.org (Postfix) with ESMTPSA id 3911533E51D for ; Fri, 12 Apr 2013 18:44:47 +0000 (UTC) Message-ID: <516856A9.5030909@gentoo.org> Date: Fri, 12 Apr 2013 14:47:05 -0400 From: "Rick \"Zero_Chaos\" Farina" User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:17.0) Gecko/20130406 Thunderbird/17.0.5 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 MIME-Version: 1.0 To: gentoo-catalyst@lists.gentoo.org Subject: Re: [gentoo-catalyst] [PATCH v2 1/2] doc/catalyst-config.5.txt: Add man page for catalyst.conf References: <51683217.3070805@gentoo.org> <60fb3b46ea7b9741d088c4ff2d9b158858214ba0.1365790593.git.wking@tremily.us> In-Reply-To: <60fb3b46ea7b9741d088c4ff2d9b158858214ba0.1365790593.git.wking@tremily.us> X-Enigmail-Version: 1.6a1pre Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit X-Archives-Salt: e6cfbfe2-5a4f-4cab-8953-8dc855598727 X-Archives-Hash: b46855a77f0db209062f76148ee744f9 -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 The worms... the worms they are everywhere.... why did you open the can? Scroll down On 04/12/2013 02:21 PM, W. Trevor King wrote: > 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. 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 `tbz2` of your built kernel and modules. This is useful if > +your build dies during `livecd-stage2`. kerncache keeps a full dir of everything like seedcache does. > + > +pkgcache:: > +Keep a ``tbz2`` of every built package. This is useful if your build > +dies prematurely. Might be easier to just say this enables the binpkg feature of portage... - -ZC > + > +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. - -, 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. mention the default location > + > +*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 > -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.19 (GNU/Linux) Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/ iQIcBAEBAgAGBQJRaFaoAAoJEKXdFCfdEflKC2sP+wS1f4RlU0WAKBzocF1cJKh1 Xd4RaxOruDUkOPvtHNvMMmwgSaZD0iiYmGnUZEG5lYEfIIA9wlqGrYHzpL/Mtbvv iKTYNPtZycfVvtSE2UEC9BhPQe3+VzjqrB4Rs1utdAfCvgYjRTNiOutcHyyr1kWz G1su+g2dMX7FFb29gfm0kRoYBdwi8XSep62QLoAvEMGRPkM10jo3sFIqb4RWDG1r XajCEgNFxvrAy7HV1HOLgFg8Oq7N60aJAZQLc353EMHzmCT0K7t+/2Bg8Rl1AH5j Gnwj1lol5tvfu76MHDTZeykZFln53S9BoewM0RlHqIT1sfIywwxLl/kh/z5z44K8 at1NvnLAllE/tiR99ovaeTUlMPTigoLuuIOqH5gPAdVETQ3cQEhskSWYlc7wKZcs SU28aa1xcUwdhPaNhplyNaf+VHp8PJPkHUeeItafFGw8Hn7J2angrS5ouOPjRBHh MG6usDIjRxhJGgCrV28dXksYxCSocmFEO6npuZe8rGkP6k7uLt3di/wt5lsQWdCq gNtaiYKrnb1u6oWwZJHZdNF9jU9pjoQjBRYkkbn/3N9ItrxUHO+5+Yz1FFV3q7Bs B+NuxstRLC1imrsz9nHsp0XMkk9p+Un6xUIRvOP8LRRrmdUvwFooClH6vyPasG7C WnvzbEV0y+xr02Lmdpv7 =Ly6k -----END PGP SIGNATURE-----