add ReST template to be used for manpage/make.globals/make.conf.example generation later on

svn path=/main/trunk/; revision=5146

1 files changed, 710 insertions, 0 deletions

diff --git a/make.conf.txt b/make.conf.txt
new file mode 100644
index 00000000..5a885a9e
--- /dev/null
+++ b/make.conf.txt
@@ -0,0 +1,710 @@
+.. Substitutions: arch, cflags, chost, portdir
+
+make.conf
+*********
+
+Available make.conf settings for portage
+
+SYNOPSIS
+========
+
+/etc/make.conf
+
+DESCRIPTION
+===========
+
+This file contains various variables that are used by Portage.
+Portage will check the currently\-defined environment variables
+first for any settings.  If no environment settings are found,
+Portage then checks /etc/make.conf.  If no setting is found
+in /etc/make.conf, Portage checks /etc/make.globals. If no
+setting is found there, the profile's default setting is grabbed
+from /etc/make.profile/make.defaults. Please note that all user
+settings should be made in the environment or in /etc/make.conf,
+which is intended to be customized by the user.
+
+VARIABLES
+=========
+
+ACCEPT_KEYWORDS
+---------------
+
+:suggest: ~|arch|
+:valdesc: space delimited list of KEYWORDS
+
+Enable testing of ebuilds that have not yet been deemed 'stable'.  Users
+of the 'x86' architecture would set this to '~x86' while ppc users would
+set this to '~ppc'.  This is an incremental variable.
+
+CCACHE_DIR
+----------
+
+:suggest: ${PORTAGE_TMPDIR}/ccache
+:valdesc: path
+
+Defines the location of the ccache working directory. See the ccache(1) man 
+page for more information.
+
+CCACHE_SIZE
+-----------
+
+:valdesc: size
+
+This controls the space use limitations for ccache.  The default is 2 gigabytes 
+('2G').  Sizes are specified with 'G', 'M', or 'K'.
+
+CFLAGS
+------
+
+:suggest: |cflags|
+:valdesc: valid gcc flags, see gcc manual
+
+Use these variables to set the desired optimization/CPU instruction settings
+for applications that you compile.  Nearly all ebuild files will take advantage
+of your custom settings, resulting in a Gentoo Linux that is fully customized
+to your specifications.  Please use sane settings as some packages will fail to
+compile/run if the optimizations are too extreme.
+
+CXXFLAGS
+--------
+
+:suggest: ${CFLAGS}
+:valdesc: valid gcc flags, see gcc manual
+
+_`CFLAGS`
+
+CHOST
+-----
+
+:suggest: |chost|
+
+This variable is passed by the ebuild scripts to the configure step as 
+--host=${CHOST}.  This way you can force the build-host.
+
+CLEAN_DELAY
+-----------
+
+:default: 5
+:valdesc: integer
+
+Determines how long the countdown delay will be for unmerge operations (including 
+autoclean).
+
+COLLISION_IGNORE
+----------------
+
+:valdesc: space delimited list of files and/or directories
+
+This variable allows the user to disable `collision-protect`_ for specific files 
+and/or directories.
+
+CONFIG_PROTECT
+--------------
+
+:default: /etc
+:valdesc: space delimited list of files and/or directories
+
+All  files  and/or  directories  that are defined here will have "config file 
+protection" enabled for them (unless overridden by _`CONFIG_PROTECT_MASK`).
+
+CONFIG_PROTECT_MASK
+-------------------
+
+:default: /etc/env.d
+:valdesc: space delimited list of files and/or directories
+
+All  files  and/or  directories  that are defined here will have "config file 
+protection" disabled for them.
+
+DISTCC_DIR
+----------
+
+:suggest: ${PORTAGE_TMPDIR}/.distcc
+:valdesc: path
+
+Defines the location of the distcc working directory. See the distcc(1) man 
+page for more information.
+
+DISTDIR
+-------
+
+:default: |portdir|/distfiles
+:valdesc: path
+
+Defines the location of your local source file repository.
+
+EBEEP_IGNORE
+------------
+
+Defines whether or not to ignore audible beeps when displaying important 
+informational messages.  This variable is unset by default.
+
+EMERGE_DEFAULT_OPTS
+-------------------
+
+:valdesc: emerge options
+
+Options  to append to the end of the emerge(1) command line on every invocation.
+These options will not be appended to the command line if --ignore-default-opts 
+is specified.
+
+EPAUSE_IGNORE
+-------------
+
+Defines whether or not to ignore short pauses that occur when displaying 
+important informational messages.  This variable is unset by default.
+
+FEATURES
+--------
+
+:default: sandbox distlocks metadata-transfer
+:suggest: userpriv usersandbox
+:valdesc: space separated list of feature flags
+
+Various settings affecting portage behavior. Don't disable the defaults without
+a good reason. This is an incremental variable. It can take a combination of the
+following flags:
+
+_`assume-digest`
+	When commiting work to cvs with repoman(1), assume that all existing SRC_URI 
+	digests are correct.  This feature also affects digest generation via 
+	ebuild(1) and emerge(1) (emerge generates digests only when the digest 
+	feature is enabled).
+
+_`buildpkg`
+	Binary packages will be created for all packages that are merged.
+
+`_buildsyspkg`
+	Build binary packages for just packages in the system set.
+
+_`ccache`
+	Enable portage support for the ccache package.  If ${CCACHE_DIR} is not set 
+	in the users environment, then  portage will default to ${PORTAGE_TMPDIR}/ccache 
+	(with userpriv) and to /root/.ccache otherwise.
+
+_`confcache`
+	Enable  confcache support; global configure caching, speeds up autotool based 
+	configure calls via the econf helper function. See ebuild(5) for more information.
+
+_`collision-protect`
+	A QA-feature to ensure that a package doesn't overwrite files it doesn't own.
+	The `COLLISION_IGNORE`_ variable can be used to selectively disable this feature.
+
+_`digest`
+	Autogenerate digests for packages when running the emerge(1) command. If
+	the `assume-digests`_ feature is also enabled then existing SRC_URI digests
+	will be reused whenever they are available.
+
+_`distcc`
+	Enable portage support for the distcc package.
+
+_`distlocks`
+	Portage uses lockfiles to ensure competing instances don't clobber
+	each other's files. This feature is enabled by default but may cause
+	heartache on less intelligent remote filesystems like NFSv2 and some
+	strangely configured Samba server (oplocks off, NFS re\-export). A tool
+	/usr/lib/portage/bin/clean_locks exists to help handle lock issues
+	when a problem arises (normally due to a crash or disconnect).
+
+_`fixpackages`
+	Updates dependencies in binary packages to match the current tree, for 
+	example after package moves. This can take a ot of time if you have many
+	binary packages in `PKGDIR`_.
+
+_`getbinpkg`
+	Force emerges to always try to fetch files from the `PORTAGE_BINHOST`_.
+
+_`installsources`
+	Install source code into /usr/src/debug/${CATEGORY}/${PF} (also see
+	`splitdebug`_). This feature works only if debugedit is installed.
+
+_`keeptemp`
+	Do not delete the temporary ebuild directory ${T} after the merge process.
+
+_`keepwork`
+	Do not delete the build directory ${WORKDIR} after the merge process. This
+	may occupy a lot of diskspace.
+
+_`metadata-transfer`
+	Automatically perform a metadata transfer when `emerge --sync` is run.
+
+_`mirror`
+	This will cause `FETCHCOMMAND`_ to always be run even if the file already 
+	exists in `DISTDIR`_.
+
+_`noauto`
+	When utilizing ebuild(1), only run the requested function.
+
+_`noclean`
+	Do no delete the source and temporary files after the merge process.
+
+_`nodoc`
+	Do not install documentation files in /usr/share/doc.
+
+_`noinfo`
+	Do not install info pages.
+
+_`noman`
+	Do not install manpages.
+
+_`nostrip`
+	Prevents the stripping of binaries that are merged to the live filesystem.
+
+_`notitles`
+	Disables xterm titlebar updates (which contains status info).
+
+_`parallel-fetch`
+	Fetch in the background while compiling.
+
+_`sandbox`
+	Use sys-apps/sandbox when building packages to protect the live filesystem.
+
+_`sfperms`
+	Stands for Smart Filesystem Permissions. Before merging packages to the
+	live filesystem, automatically search for and set permissions on setuid
+	and setgid files. Files that are setuid have the group and other read
+	bits removed while files that are setgid have the other read bit removed.
+	See also `suidctl`_ below.
+
+_`sign`
+	When commiting work to cvs with repoman(1), sign the Manifest with 
+	a GPG key. Read about the `PORTAGE_GPG_KEY`_ variable.
+
+_`splitdebug`
+	Prior to stripping ELF etdyn and etexec files, the debugging info is 
+	stored for later use by debuggers. This feature is disabled by
+	`nostrip`_. For installation of source code, see `installsources`_.
+
+_`strict`
+	Have portage react strongly to conditions that have the potential to be 
+	dangerous (like missing or incorrect Manifests entries).
+
+_`stricter`
+	Have portage react strongly to conditions that may conflict with system
+	security provisions (for example textrels, executable stack). Read about
+	the `QA_STRICT_*`_ variables below.
+
+_`suidctl`
+	Before merging packages to the live filesystem, automatically strip setuid 
+	bits from any file that is not listed in /etc/portage/suidctl.conf.
+
+_`test`
+	Run package-specific tests during each merge to help make sure 
+	the package compiled properly.  See *test* in ebuild(1) 
+	and *src_test()* in ebuild(5).
+
+_`userfetch`
+	When portage is run as root, drop privileges to portage:portage during the
+	fetching of package sources.
+
+_`userpriv`
+	Allow portage to drop root privileges and compile packages as 
+	portage:portage without `sandbox`_ (unless `usersandbox`_ is also used).
+
+_`usersandbox`
+	Enable the sandbox in the compile phase, when running without root privs 
+	(`userpriv`_).
+
+FETCHCOMMAND
+------------
+
+:default: /usr/bin/wget -t 5 -T 60 --passive-ftp -P \${DISTDIR} \${URI}
+:suggest: /usr/bin/wget -t 5 -T 60 --passive-ftp --limit-rate=200k \${URI} -P \${DISTDIR}
+
+This variable contains the command used for fetching package sources from
+the internet. It must contain the full path to the executable as well as the
+place-holders \${DISTDIR} and \${URI}.
+
+GENTOO_MIRRORS
+--------------
+
+:default: http://distfiles.gentoo.org http://distro.ibiblio.org/pub/linux/distributions/gentoo
+:valdesc: space separated list of mirror locations
+
+Insert your space-seperated list of local mirrors here. These locations are 
+used to download files before the ones listed in the ebuild scripts. Merging 
+'app-portage/mirrorselect' can help to select an appropriate mirror.
+
+INSTALL_MASK
+------------
+
+:valdesc: space delimited list of file names
+
+Use this variable if you want to selectively prevent certain files from being
+copied into your file system tree.  This does not work on symlinks, but only on
+actual files.  Useful if you wish to filter out files like HACKING.gz and
+TODO.gz.
+
+MAKEOPTS
+--------
+
+:suggest: -j2
+:valdesc: make options
+
+Use this variable if you want to use parallel make. For example, if you
+have a dual-processor system, set this variable to "-j2" or "-j3" for 
+enhanced build performance with many packages. Suggested settings are
+between CPUs+1 and 2*CPUs+1. For more information, see make(1).
+
+NOCOLOR
+-------
+
+:default: false
+:valdesc: true | false
+
+Defines if color should be disabled (this is overridden by CLI options).
+
+PKGDIR
+------
+
+:default: |portdir|/packages
+:valdesc: path
+
+Defines the location where created .tbz2 binary packages will be stored.
+
+PORT_LOGDIR
+-----------
+
+:suggest: /var/log/portage
+:valdesc: path
+
+This variable defines the directory in which per-ebuild logs are kept.
+Logs are created only when this is set and writable.
+
+PORTAGE_BINHOST
+---------------
+
+:suggest: ftp://login:pass@grp.mirror.site/pub/grp/i686/athlon-xp
+:valdesc: URI to a binary package server
+
+This is the host from which portage will grab prebuilt-binary packages.
+The list is a single entry specifying the full address of the directory 
+serving the tbz2's for your system.  This is only used when running with 
+the get binary pkg options are given to emerge.  Review emerge(1) 
+for more information.  Note that it should point to the 'All' directory on 
+the host that creates the binary packages and not to the root of the `PKGDIR`_.
+
+PORTAGE_ELOG_CLASSES
+--------------------
+
+:default: log warn error
+:valdesc: space separated list of logging levels
+
+This variable defines which ebuild messages should be logged by the elog 
+subsystem. Possible values are info, log, warn and error.
+
+PORTAGE_ELOG_SYSTEM
+-------------------
+
+:suggest: save mail
+:valdesc: space separated list of elog handlers
+
+Selects which elog message handlers are invoked by portage to deliver messages
+captured by elog. If no handler is specified logging is effectively disabled.
+Default handlers (other packages may contain additional handlers) are:
+
+save
+	saves one logfile per package in ${PORT_LOGDIR}/elog, /var/log/portage/elog 
+	if `PORT_LOGDIR`_ is unset
+
+custom
+	passes all messages to `PORTAGE_ELOG_COMMAND`_
+
+syslog
+	sends all messages to syslog
+
+mail
+	sends all messages to the address configured in `PORTAGE_ELOG_MAILURI`_
+
+PORTAGE_ELOG_COMMAND
+--------------------
+
+:suggest: /path/to/logprocessor -p '\${PACKAGE}' -f '\${LOGFILE}'
+
+Only used with the "custom" logging module. Specifies a command
+to process log messages. Two variables are expanded:
+
+${PACKAGE}
+	expands to the cpv entry of the processed package (see PVR in ebuild(5))
+
+${LOGFILE}
+	absolute path to the logfile
+
+Both variables have to be quoted with single quotes
+
+PORTAGE_ELOG_MAILURI
+--------------------
+
+:default: root
+:suggest: user@some.domain mail.some.domain
+
+This variable holds all important settings for the mail module. In most cases 
+listing the recipient address andthe receiving mailserver should be sufficient,
+but you can also use advanced settings like authentication or TLS. The full 
+syntax is:
+	``address [[user:passwd@]mailserver[:port]]``
+where
+
+address
+	recipient address
+
+user
+	username for smtp auth (defaults to none)
+
+passwd
+	password for smtp auth (defaults to none)
+
+mailserver
+	SMTP server that should be used to deliver the mail (defaults to localhost).
+	Alternatively this can also be a the path to a sendmail binary if you don't
+	want to use SMTP (e.g. if you only need local delivery to a mbox).
+
+port
+	port to use on the given SMTP server (defaults to 25, values > 100000 
+	indicate that starttls should be used on (port-100000))
+
+PORTAGE_ELOG_MAILFROM
+---------------------
+
+:default: portage
+:suggest: portage@some.domain
+:valdesc: sender address
+
+You can set the from-address of logmails with this variable, if unset mails 
+are sent by "portage" (this default may fail in some environments).
+
+PORTAGE_ELOG_MAILSUBJECT
+------------------------
+
+:default: [portage] ebuild log for \${PACKAGE} on \${HOST}
+:suggest: package \${PACKAGE} merged on \${HOST} with notice
+:valdesc: mail subject template
+
+Template string to be used as subject for logmails. The following variables 
+are exanded:
+
+${PACKAGE}
+	see description of `PORTAGE_ELOG_COMMAND`_
+
+${HOST}
+	FQDN of the host portage is running on
+
+PORTAGE_NICENESS
+----------------
+
+:suggest: 3
+:valdesc: integer
+
+The value of this variable will be added to the current nice level that 
+emerge is running at. In other words, this will not set the nice level, 
+it will increment it. For more information about nice levels and what 
+are acceptable ranges, see nice(1).
+
+PORTAGE_RSYNC_EXTRA_OPTS
+------------------------
+
+:suggest: --exclude=/etc/portage/rsync_exclude
+:valdesc: rsync options
+
+Additional rsync options to be used by `emerge --sync`.
+
+PORTAGE_RSYNC_OPTS
+------------------
+
+:default: --recursive --links --safe-links --perms --times --compress --force --whole-file --delete --delete-after --stats --timeout=180 --exclude=/distfiles --exclude=/local --exclude=/packages
+:valdesc: rsync options
+
+Default rsync options to be used by `emerge --sync`. **Don't change this unless
+you know exactly what you're doing!**
+
+PORTAGE_RSYNC_RETRIES
+---------------------
+
+:default: 3
+:valdesc: integer
+
+The number of times rsync should retry on failed connections before giving up.
+
+PORTAGE_TMPDIR
+--------------
+
+:default: /var/tmp
+:valdesc: path
+
+Defines the location of the temporary build directories.
+
+PORTDIR
+-------
+
+:default: |portdir|
+:valdesc: path
+
+Defines the location of your Portage tree.
+
+PORTDIR_OVERLAY
+---------------
+
+:suggest: |portdir|/local
+:valdesc: space separated list of overlay paths
+
+Defines the directories in which user made ebuilds are be stored.
+
+RESUMECOMMAND
+-------------
+
+:default: /usr/bin/wget -c -t 5 -T 60 --passive-ftp -P \${DISTDIR} \${URI}
+:suggest: /usr/bin/wget -c -t 5 -T 60 --passive-ftp --limit-rate=200k \${URI} -P \${DISTDIR}
+
+This variable contains the command used for resuming package sources that
+have been partially downloaded. It should be defined using the same format
+as `FETCHCOMMAND`_.
+
+.. _`QA_STRICT_*`
+
+QA_STRICT_EXECSTACK
+-------------------
+
+:suggest: set
+
+Set this to instruct portage to ignore any QA_EXECSTACK override settings from
+ebuilds. See also ebuild(5).
+
+QA_STRICT_WX_LOAD
+-----------------
+
+:suggest: set
+
+Set this to instruct portage to ignore any QA_WX_LOAD override settings from
+ebuilds. See also ebuild(5).
+
+QA_STRICT_TEXTRELS
+------------------
+
+:suggest: set
+
+Set this to instruct portage to ignore any QA_TEXTRELS override settings from
+ebuilds. See also ebuild(5).
+
+ROOT
+----
+
+:default: /
+:valdesc: path
+
+Use this variable to specify the target root filesystem to be used for merging 
+packages or ebuilds. All RDEPEND and PDEPEND will be installed 
+into ROOT while all DEPEND will be still be installed into /.  
+Typically, you should set this setting in the environment rather than in 
+/etc/make.conf itself. It's commonly used for creating new build 
+images. Make sure you use an absolute path.
+
+RPMDIR
+------
+
+:default: |portdir|/rpm
+:valdesc: path
+
+Defines the location where created RPM packages will be stored. Note that RPM 
+support in portage is experimental at best.
+
+SYNC
+----
+
+:default: rsync://rsync.gentoo.org/gentoo-portage
+:valdesc: URI to a portage tree server (rsync or cvs)
+
+Insert your preferred rsync mirror here.  This rsync server is used to sync 
+the local portage tree when `emerge --sync` is run. Only one server can be 
+specified.
+
+USE
+---
+
+:suggest: X gtk gnome -alsa
+:valdesc: space delimited list of USE items
+
+This variable contains options that control the build behavior of several
+packages.  More information in ebuild(5).  Possible USE values
+can be found in |portdir|/profiles/use.desc and |portdir|/profiles/use.local.desc.
+
+USE_EXPAND
+----------
+
+:suggest: LINGUAS VIDEO_CARDS
+:valdesc: space separated list of variable names
+
+Any variable listed here will be used to augment `USE`_ by inserting a new flag
+for every value in that variable, so USE_EXPAND="FOO" and FOO="bar bla" results
+in USE="foo_bar foo_bla".
+
+USE_EXPAND_HIDDEN
+-----------------
+
+:valdesc: space separated list of variable names
+
+Names of `USE_EXPAND`_ variables that should not be shown in the verbose merge
+list output of the emerge(1) command.
+
+USE_ORDER
+---------
+
+:default: env:pkg:conf:defaults:pkginternal
+:valdesc: colon separated list of portage config layers
+
+Determines the precedence of layers in the incremental stacking of the USE
+variable. Precedence decreases from left to right such that env overrides
+pkg, pkg overrides conf, and so forth. *Don't change this unless you know what 
+you're doing!* Available layers are:
+
+env
+	USE from the current USE environment variable if it exists
+
+pkg
+	Per-package USE from /etc/portage/package.use (see portage(5))
+
+conf
+	USE from make.conf
+
+defaults
+	USE from make.defaults and package.use in the profile (see portage(5))
+
+pkginternal
+	USE from ebuild IUSE defaults (flags enabled via a + prefix; see ebuild(5))
+
+REPORTING BUGS
+==============
+
+Please report bugs via http://bugs.gentoo.org/
+
+AUTHORS
+=======
+
+Daniel Robbins <drobbins@gentoo.org>
+Nicholas Jones <carpaski@gentoo.org>
+Mike Frysinger <vapier@gentoo.org>
+Saleem Abdulrasool <compnerd@gentoo.org>
+Marius Mauch <genone@gentoo.org>
+
+FILES
+=====
+
+/etc/make.conf
+	Contains user-supplied variables and overwrites those in make.defaults.
+
+/etc/make.globals
+	Contains portage defaults for many variables listed here. Don't change this,
+	edit /etc/make.conf instead.
+
+|portdir|/profiles/use.desc
+	Contains a list of all global USE flags with brief descriptions.
+
+|portdir|/profiles/use.local.desc
+	Contains a list of all local USE variables with brief descriptions.
+
+SEE ALSO
+========
+
+- emerge(1)
+- portage(5)
+- ebuild(1)
+- ebuild(5)