Re: [gentoo-catalyst] [PATCH v2 1/2] doc/catalyst-config.5.txt: Add man page for catalyst.conf

["Rick \"Zero_Chaos\" Farina" <zerochaos@gentoo.org>]

-----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" <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.
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-----