From: Marius Mauch Date: Fri, 1 Dec 2006 08:44:55 +0000 (-0000) Subject: add ReST template to be used for manpage/make.globals/make.conf.example generation... X-Git-Tag: v2.1.2~419 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=c64c5b49e100857cfd706abe2a30a276a738ecb9;p=portage.git add ReST template to be used for manpage/make.globals/make.conf.example generation later on svn path=/main/trunk/; revision=5146 --- diff --git a/make.conf.txt b/make.conf.txt new file mode 100644 index 000000000..5a885a9e0 --- /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 +Nicholas Jones +Mike Frysinger +Saleem Abdulrasool +Marius Mauch + +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)