From c6c55acda1a9cd0512defd7ba9ffd12d513d063a Mon Sep 17 00:00:00 2001 From: Fabian Groffen Date: Fri, 13 Oct 2006 18:05:14 +0000 Subject: [PATCH] Merged r2852:4673 from the trunk svn path=/main/branches/prefix/; revision=4674 --- man/ebuild.1 | 62 +++++++++++------------ man/ebuild.5 | 56 +++++++++++++++++---- man/emerge.1 | 129 ++++++++++++++++++++++++++++++------------------ man/make.conf.5 | 79 ++++++++++++++++++++++------- man/portage.5 | 116 ++++++++++++++++++++++++++++++++++--------- man/repoman.1 | 3 ++ 6 files changed, 316 insertions(+), 129 deletions(-) diff --git a/man/ebuild.1 b/man/ebuild.1 index 3584cf084..d271bee1c 100644 --- a/man/ebuild.1 +++ b/man/ebuild.1 @@ -1,7 +1,6 @@ .TH "EBUILD" "1" "Dec 2005" "Portage 2.1" "Portage" .SH "NAME" -ebuild \- manual page for the ebuild program, a low level interface to -the Portage system. +ebuild \- a low level interface to the Portage system .SH "SYNOPSIS" .B ebuild .I file command [command]\fR... @@ -9,9 +8,9 @@ the Portage system. The ebuild program is a direct interface to the Portage system. It allows for direct action upon an ebuild with specific subcommands or groups of commands to perform in a specific ebuild's context and -functions. Accepting an ebuild script and one or more commands +functions. Accepting an ebuild script and one or more commands as arguments, the ebuild program parses the ebuild script and -execute the specified commands. Commands exist to fetch sources, +executes the specified commands. Commands exist to fetch sources, unpack sources, compile sources, install object files into a temporary directory "image", merge the image to the local filesystem, create a bzipped tarball package out of the image, and more. @@ -21,11 +20,11 @@ This must be a valid ebuild script. For further information read .SH "COMMANDS" .TP .BR help -Show a condensed form of the man page along with a lot of package +Shows a condensed form of this man page along with a lot of package specific information. .TP .BR setup -Run all package specific setup actions and exotic system checks. +Runs all package-specific setup actions and exotic system checks. .TP .BR clean Cleans the temporary build directory that Portage has created for @@ -38,12 +37,11 @@ on what this variable is, run \fIemerge [\-v] info\fR, or to override this variable, see \fBmake.conf\fR(5). Note: Portage cleans up almost everything after a package has been -successfully merged unless FEATURES contains 'noclean'. Adding noclean +successfully merged unless FEATURES contains 'noclean'. Adding noclean to FEATURES will cause a lot of files to remain and will consume large -amounts of space, very quickly. It is not recommended to leave this on -unless you have use for the sources post\-merge. Optionally one may, -manual clean \fIrm \-rf /var/tmp/portage\fR will take care of all -of these files. +amounts of space, very quickly. It is not recommended to leave this on, +unless you have use for the sources post\-merge. Optionally, one may +manually clean these files with \fIrm \-rf /var/tmp/portage\fR. .TP .BR fetch Checks to see if all the sources specified in SRC_URI are available in @@ -53,15 +51,15 @@ download them from the locations specified in SRC_URI. If multiple download locations are listed for a particular file, Portage pings each location to see which location is closer. (May not be true presently.) The Gentoo Linux mirrors defined by GENTOO_MIRRORS is -always considered first. If for some reason the current or +always considered first. If for some reason the current or just\-downloaded sources' md5 digests don't match those recorded in files/digest\-[package]\-[version\-rev], a warning is printed and ebuild exits with an error code of 1. .TP .BR digest Creates a digest file for the package in -/usr/portage/[category]/[package]/files/. This digest file lists the -md5sum's of all the files found in the SRC_URI. If the fetched source +/usr/portage/[category]/[package]/files/. This digest file lists the +md5sums of all the files found in the SRC_URI. If the fetched source of the package is corrupt/bogus in some way, the md5sum will catch this. .TP .BR manifest @@ -75,29 +73,29 @@ Extracts the sources to a subdirectory in the \fIbuild directory\fR file. If no src_unpack() function has been specified, a default src_unpack() function is used that extracts all the files specified in SRC_URI. The sources are normally extracted to -${BUILD_PREFIX}/[package]\-[version\-rev]/work. This particular directory +${BUILD_PREFIX}/[package]\-[version\-rev]/work. This particular directory can be referenced by using the ${WORKDIR} variable. If you're creating an ebuild, you'll want to make sure that the S -(source directory) variable defined at at the top of your ebuild script -points to the directory that contains your extracted sources. This +(source directory) variable defined at the top of your ebuild script +points to the directory that contains your extracted sources. This directory is defined by default to be ${WORKDIR}/${P}, so it is not often required. The src_unpack() function is also responsible for making the appropriate patches to the sources so that they're ready for compilation. .TP .BR compile -Compiles the extracted sources by running the the \fIsrc_compile()\fR +Compiles the extracted sources by running the \fIsrc_compile()\fR function specified in the ebuild file. When src_compile() starts, the current working directory will be set to ${S}. When src_compile() completes, the sources should be fully compiled. .TP .BR test -Run package specific test cases to verify that everything was built +Runs package-specific test cases to verify that everything was built properly. .TP .BR preinst -Run package specific actions that need to be done before the package +Runs package-specific actions that need to be done before the package is installed into the live filesystem. .TP .BR install @@ -105,20 +103,20 @@ Installs the package to the temporary \fIinstall directory\fR by running the \fIsrc_install()\fR function. When completed, the \fIinstall directory\fR (${BUILD_PREFIX}/[package]\-[version\-rev]/image) will contain all the files that should either be merged to the local -file system or included in a binary package. +filesystem or included in a binary package. .TP .BR postinst -Run package specific actions that need to be done after the package +Runs package-specific actions that need to be done after the package is installed into the live filesystem. Usually helpful messages are shown here. .TP .BR qmerge This function installs all the files in the \fIinstall directory\fR -to the live filesystem. The process works as follows: first, the +to the live filesystem. The process works as follows: first, the \fIpkg_preinst()\fR function (if specified) is run. Then, the files are merged into the live filesystem, and the installed files' md5 digests are recorded in -\fI/var/db/pkg/${CATEOGRY}/${PN}\-[version\-rev]/CONTENTS\fR. After +\fI/var/db/pkg/${CATEGORY}/${PN}\-${PVR}/CONTENTS\fR. After all the files have been merged, the \fIpkg_postinst()\fR function (if specified) is executed. .TP @@ -130,26 +128,26 @@ will perform all these steps for you, stopping along the way if a particular step doesn't complete successfully. .TP .BR unmerge -This function first executes the \fIpkg_prerm\fR function (if specified). +This function first executes the \fIpkg_prerm()\fR function (if specified). Then it removes all files from the live filesystem that have a valid md5 checksum and mtime in the package contents file. Any empty directories -are recursively removed. Finally, it runs \fIpkg_postrm\fR function (if +are recursively removed. Finally, it runs \fIpkg_postrm()\fR function (if specified). It is safe to merge a new version of a package first and then unmerge the old one. In fact, this is the recommended package upgrade method. .TP .BR prerm -Run package specific actions that need to be executed before the package is +Runs package-specific actions that need to be executed before the package is removed from the filesystem. See also \fIunmerge\fR. .TP .BR postrm -Run package specific actions that need to be executed after the package is +Runs package-specific actions that need to be executed after the package is removed from the filesystem. See also \fIunmerge\fR. .TP .BR config -Run package specific actions needed to be executed after the emerge -process has completed. This usually entails configuration file -setup or other similar setups that the user may wish to run. +Runs package-specific actions that need to be executed after the emerge +process has completed. This usually entails setup of configuration files +or other similar setups that the user may wish to run. .TP .BR package This command is a lot like the \fImerge\fR command, except that after @@ -160,7 +158,7 @@ ${PKGDIR}/${CATEGORY} that points to the package in ${PKGDIR}/All. .TP .BR rpm Builds a RedHat RPM package from the files in the temporary -\fIinstall directory\fR. At the moment, the ebuild's dependency +\fIinstall directory\fR. At the moment, the ebuild's dependency information is not incorporated into the RPM. .SH "REPORTING BUGS" Please report bugs via http://bugs.gentoo.org/ diff --git a/man/ebuild.5 b/man/ebuild.5 index fb57fbebc..7492774c2 100644 --- a/man/ebuild.5 +++ b/man/ebuild.5 @@ -118,13 +118,18 @@ Contains the path to the temporary \fIinstall directory\fR. Every write operation that does not involve the helper tools and functions (found below) should be prefixed with ${D}. Do not modify this variable. .TP +\fBROOT\fR = \fI"/"\fR +Contains the path that portage should use as the root of the live filesystem. +When packages wish to make changes to the live filesystem, it should do so in +the tree prefixed by ${ROOT}. Do not modify this variable. +.TP \fBDESCRIPTION\fR = \fI"A happy little package"\fR Should contain a short description of the package. .TP \fBSRC_URI\fR = \fI"http://happy.com/little/${P}.tar.gz"\fR Contains a list of URI's for the required source files. It can contain multiple URI's for a single source file. The list is processed in order -if the file was not found on any of the \fIGENTOO_MIRROR\fRs. +if the file was not found on any of the \fIGENTOO_MIRRORS\fR. .TP \fBHOMEPAGE\fR = \fI"http://happy.com/"\fR Should contain a list of URL's for the sources main sites and other further @@ -314,6 +319,13 @@ This should be a space delimited list of portage features to restrict. .PD 0 .RS .TP +.I binchecks +Disable all QA checks for binaries (do not use without very good reason). See +the \fBQA CONTROL VARIABLES\fR section for more specific exemptions. +.TP +.I confcache +Prevent econf from using confcache. +.TP .I fetch like \fImirror\fR but the files will not be fetched via \fBSRC_URI\fR either. .TP @@ -342,6 +354,38 @@ This variable should only be used when a package provides a virtual target. For example, blackdown-jdk and sun-jdk provide \fIvirtual/jdk\fR. This allows for packages to depend on \fIvirtual/jdk\fR rather than on blackdown or sun specifically. +.SH "QA CONTROL VARIABLES" +.TP +.B USAGE NOTES +Several QA variables are provided which allow an ebuild to manipulate some +of the QA checks performed by portage. Use of these variables in ebuilds +should be kept to an absolute minimum otherwise they defeat the purpose +of the QA checks, and their use is subject to agreement of the QA team. +They are primarily intended for use by ebuilds that install closed-source +binary objects that cannot be altered. +.br +Note that objects that violate these rules may fail on some architectures. +.TP +\fBQA_TEXTRELS\fR +This variable can be set to a list of file paths, relative to the image +directory, of files that contain text relocations that cannot be eliminated. +The paths may contain regular expressions. +.br +This variable is intended to be used on closed-source binary objects that +cannot be altered. +.TP +\fBQA_EXECSTACK\fR +This should contain a list of file paths, relative to the image directory, of +objects that require executable stack in order to run. +The paths may contain regular expressions. +.br +This variable is intended to be used on objects that truly need executable +stack (i.e. not those marked to need it which in fact do not). +.TP +\fBQA_WX_LOAD\fR +This should contain a list of file paths, relative to the image directory, of +files that contain writable and executable segments. These are rare. +The paths may contain regular expressions. .SH "PORTAGE DECLARATIONS" .TP .B inherit @@ -490,8 +534,7 @@ installed, 1 otherwise. \fBbest_version\fR \fI\fR This function will look up \fIpackage name\fR in the database of currently installed programs and echo the "best version" of the package that is -currently installed. The function returns 0 if there is a package that -matches \fIpackage name\fR. Otherwise, the function will return 1. +currently installed. .RS .TP .I Example: @@ -642,9 +685,6 @@ multiple directories. .RE .PD 1 .TP -\fBdopython\fR \fI\fR -Performs \fIcommands\fR with python and returns the result. -.TP \fBdosed\fR \fI"s:orig:change:g" \fR Performs sed (including cp/mv \fIfilename\fR) on \fIfilename\fR. .br @@ -734,10 +774,6 @@ exclude (CVS excluded by default), \fI\-r\fR sets recursive. Installs info\-pages into \fIDESTDIR\fR/info. Files are automatically gzipped. Creates all necessary dirs. .TP -\fBdojar\fR \fI [list of more jar files]\fR -Installs jar files into /usr/share/${PN}/lib and adds them to -/usr/share/${PN}/classpath.env. -.TP \fBdomo\fR \fI [list of more locale\-files] \fR Installs locale\-files into \fIDESTDIR\fR/usr/share/locale/[LANG] depending on local\-file's ending. Creates all necessary dirs. diff --git a/man/emerge.1 b/man/emerge.1 index 746e70456..a06c0bebc 100644 --- a/man/emerge.1 +++ b/man/emerge.1 @@ -39,7 +39,8 @@ as \fBsys\-apps/portage\fR or \fB=python\-2.2.1\-r2\fR. ignores a trailing slash so that filename completion can be used. The \fIebuild\fR may also be an actual filename, such as \fB/usr/portage/app\-admin/python/python\-2.2.1\-r2.ebuild\fR. -WARNING: The implementation of \fBemerge /path/to/ebuild\fR is broken and so this syntax shouldn't be used. +WARNING: The implementation of \fBemerge /path/to/ebuild\fR is broken and so +this syntax shouldn't be used. .TP .BR tbz2file A \fItbz2file\fR must be a valid .tbz2 created with \fBebuild @@ -47,14 +48,14 @@ A \fItbz2file\fR must be a valid .tbz2 created with \fBebuild [category/]\fR or \fBquickpkg /var/db/pkg//\fR. .TP .BR set -Package sets are a convenient shorthand for large groups of +A \fIset\fR is a convenient shorthand for a large group of packages. Two sets are currently supported: \fBsystem\fR and \fBworld\fR. \fBsystem\fR refers to a set of packages deemed necessary for your system to run properly. \fBworld\fR -contains all of the packages in \fBsystem\fR, along with any +contains all the packages in \fBsystem\fR, plus any other packages listed in \fB/var/lib/portage/world\fR. [See -\fBFILES\fR below for more information.] Note that these -commands are generally used in conjunction with \fB\-\-update\fR. +\fBFILES\fR below for more information.] Note that a \fIset\fR +is generally used in conjunction with \fB\-\-update\fR. .TP .BR dependency A \fIdependency\fR describes bounds on a package that you wish to install. @@ -85,6 +86,11 @@ clean binutils\fR cleans out old versions of binutils; specific version of Mozilla. This is generally safe to use. \fBNote that\fR \-\-clean \fBdoes not remove unslotted packages.\fR .TP +.BR "\-\-config " +Run package specific actions needed to be executed after the emerge process +has completed. This usually entails configuration file setup or other similar +setups that the user may wish to run. +.TP .BR \-\-depclean Determines all packages installed on the system that have no explicit reason for being there. \fBemerge\fR generates a list @@ -95,9 +101,9 @@ installed; the differences are listed as unnecessary packages and then unmerged after a short timeout. \fBWARNING: Removing some packages may cause packages which link to the removed package to stop working and complain about missing libraries.\fR -Re\-emerge the complaining package to fix this issue. -\fBNote that changes in USE flags can drastically affect the -output of \-\-depclean.\fR +Re\-emerge the complaining package to fix this issue. Also see +\fB\-\-with\-bdeps\fR for behavior with respect to build time dependencies that +are not strictly required. .TP .BR "\-\-help " (\fB\-h\fR) Displays help information for emerge. Adding one of the additional @@ -107,8 +113,8 @@ updated more frequently than this man page; check it out if you are having problems that this man page does not help resolve. .TP .BR \-\-info -This is a list of information to include in bug reports which aids the -developers with fixing any problems you may report. \fBPlease include this +Produces a list of information to include in bug reports which aids the +developers when fixing the reported problem. \fBPlease include this information when submitting a bug report.\fR Expanded output can be obtained with the \fI\-\-verbose\fR option. .TP @@ -146,12 +152,15 @@ to do, then portage will exit with a message and a success condition. .TP .BR "\-\-search " (\fB\-s\fR) Searches for matches of the supplied string in the portage tree. -The \-\-search string is a regular expression. For example, \fBemerge -\-\-search "^kde"\fR searches for any package that starts with "kde"; -\fBemerge \-\-search "gcc$"\fR searches for any package that ends with -"gcc"; \fBemerge \-\-search "office"\fR searches for any package that -contains the word "office". If you want to search the package -descriptions as well, use the \fB\-\-searchdesc\fR action. +By default emerge uses a case-insensitive simple search, but you can +enable a regular expression search by prefixing the search string with %. +For example, \fBemerge \-\-search "%^kde"\fR searches for any package whose +name starts with "kde"; \fBemerge \-\-search "%gcc$"\fR searches for any +package that ends with "gcc"; \fBemerge \-\-search "office"\fR searches for +any package that contains the word "office". If you want to include the +category into the search string, prepend an @: \fBemerge --search +"%@^dev-java.*jdk"\fR. If you want to search the package descriptions as well, +use the \fB\-\-searchdesc\fR action. .TP .BR "\-\-searchdesc " (\fB\-S\fR) Matches the search string against the description field as well as @@ -175,16 +184,12 @@ system. Its arguments can be \fIebuilds\fR, \fIsets\fR, or .BR "\-\-update " (\fB\-u\fR) Updates packages to the best version available, which may not always be the highest version number due to masking for testing and development. This will -also update direct dependencies which may not be what you want. In general, -use this option only in combination with the world or system target. +also update direct dependencies which may not be what you want. Package atoms +specified on the command line are greedy, meaning that unspecific atoms may +match multiple installed versions of slotted packages. .TP .BR "\-\-version " (\fB\-V\fR) Displays the version number of \fBemerge\fR. -.TP -.BR "\-\-config " -Run package specific actions needed to be executed after the -emerge process has completed. This usually entails configuration -file setup or other similar setups that the user may wish to run. .SH "OPTIONS" .TP .BR "\-\-alphabetical " @@ -197,6 +202,10 @@ in the same format as when using \fB\-\-pretend\fR; then ask whether to continue with the merge or abort. Using \fB\-\-ask\fR is more efficient than using \fB\-\-pretend\fR and then executing the same command without \fB\-\-pretend\fR, as dependencies will only need to be calculated once. +\fBWARNING: If the "Enter" key is pressed at the prompt (with no other input), +it is interpreted as acceptance of the first choice. Note that the input +buffer is not cleared prior to the prompt, so an accidental press of the +"Enter" key at any time prior to the prompt will be interpreted as a choice!\fR .TP .BR "\-\-buildpkg " (\fB\-b\fR) Tells emerge to build binary packages for all ebuilds processed in @@ -227,11 +236,13 @@ causing it to output verbose debugging information to stdout. \fB\-\-debug\fR is great for finding bash syntax errors. .TP .BR "\-\-deep " (\fB\-D\fR) -When used in conjunction with \fB\-\-update\fR, this flag forces +This flag forces \fBemerge\fR to consider the entire dependency tree of packages, instead of checking only the immediate dependencies of the packages. As an example, this catches updates in libraries that are not directly -listed in the dependencies of a package. +listed in the dependencies of a package. Also see \fB\-\-with\-bdeps\fR for +behavior with respect to build time dependencies that are not strictly +required. .TP .BR "\-\-emptytree " (\fB\-e\fR) Reinstalls all world packages and their dependencies to the current USE @@ -252,7 +263,8 @@ files. Using the server and location defined in \fIPORTAGE_BINHOST\fR (see \fBmake.conf\fR(5)), portage will download the information from each binary package found and it will use that information to help build the dependency -list. This option implies \fB\-k\fR. (Use \fB\-gK\fR for binary\-only merging.) +list. This option implies \fB\-k\fR. (Use \fB\-gK\fR for binary\-only +merging.) .TP .BR "\-\-getbinpkgonly " (\fB\-G\fR) This option is identical to \fB\-g\fR, as above, except it will not use ANY @@ -269,7 +281,7 @@ compilation. An asterisk marks when a USE flag has changed since the package was compiled. .TP .BR "\-\-nocolor " -Make sure none of the output from portage contains color. +Suppresses all coloring of portage's output. .TP .BR "\-\-noconfmem" Causes portage to disregard merge records indicating that a config file @@ -305,23 +317,23 @@ specified, not the packages themselves. Instead of actually performing the merge, simply display what *would* have been installed if \fB\-\-pretend\fR weren't used. Using \fB\-\-pretend\fR is strongly recommended before installing an unfamiliar package. In -the printout, +the printout: .br .br -\fIN\fR = new, (not yet installed) +\fIN\fR = new (not yet installed) .br -\fIS\fR = new, SLOT installation (side-by-side versions) +\fIS\fR = new SLOT installation (side-by-side versions) .br -\fIU\fR = updating, (changing versions) +\fIU\fR = updating (to another version) .br -\fID\fR = downgrade, (Best version seems lower) +\fID\fR = downgrading (best version seems lower) .br -\fIR\fR = replacing, (Remerging same version)) +\fIR\fR = replacing (remerging same version)) .br -\fIF\fR = fetch restricted, (Manual download) +\fIF\fR = fetch restricted (must be manually downloaded) .br -\fIf\fR = fetch restricted, (Already downloaded) +\fIf\fR = fetch restricted (already downloaded) .br \fIB\fR = blocked by an already installed package .TP @@ -341,9 +353,10 @@ This is only really useful in combination with \fB\-\-emptytree\fR or \fB\-\-update\fR and \fB\-\-deep\fR. .TP .BR "\-\-usepkg " (\fB\-k\fR) -Tells emerge to use binary packages (from $PKGDIR) if they are available, thus possibly avoiding some -time\-consuming compiles. This option is useful for CD installs; you can export PKGDIR=/mnt/cdrom/packages -and then use this option to have emerge "pull" binary packages from the CD in order to satisfy dependencies. +Tells emerge to use binary packages (from $PKGDIR) if they are available, thus +possibly avoiding some time\-consuming compiles. This option is useful for CD +installs; you can export PKGDIR=/mnt/cdrom/packages and then use this option to +have emerge "pull" binary packages from the CD in order to satisfy dependencies. .TP .BR "\-\-usepkgonly " (\fB\-K\fR) Tells emerge to only use binary packages (from $PKGDIR). All the binary @@ -352,7 +365,27 @@ will simply abort. Portage does not use $PORTDIR when calculating dependency information so all masking information is ignored. .TP .BR "\-\-verbose " (\fB\-v\fR) -Tell emerge to run in verbose mode. Currently this flag causes emerge to print out GNU info errors, if any, and to show the USE flags that will be used for each package when pretending. +Tell emerge to run in verbose mode. Currently this flag causes emerge to print +out GNU info errors, if any, and to show the USE flags that will be used for +each package when pretending. The following symbols are affixed to USE flags +in order to indicate their status: +.br + +.br +\fI- prefix\fR = not enabled (either disabled or removed) +.br +\fI* suffix\fR = transition to or from the enabled state +.br +\fI% suffix\fR = newly added or removed +.br +\fI() circumfix\fR = forced, masked, or removed +.TP +.BR "\-\-with\-bdeps < y | n >" +In dependency calculations, pull in build time dependencies that are not +strictly required. This defaults to \'n\' for installation actions and +\'y\' for the \-\-depclean action. This setting can be added to +EMERGE_DEFAULT_OPTS (see make.conf(5)) and later overridden via the command +line. .SH "ENVIRONMENT OPTIONS" .TP \fBROOT\fR = \fI[path]\fR @@ -360,11 +393,11 @@ Use \fBROOT\fR to specify the target root filesystem to be used for merging packages or ebuilds. .br Defaults to /. -.SH "ENVIRONMENT OPTIONS" .TP -\fBROOT\fR = \fI[path]\fR -Use \fBROOT\fR to specify the target root filesystem to be used for -merging packages or ebuilds. +\fBPORTAGE_CONFIGROOT\fR = \fI[path]\fR +Use \fBPORTAGE_CONFIGROOT\fR to specify the location for various portage +configuration files +(see \fBFILES\fR for a detailed list). .br Defaults to /. .SH "OUTPUT" @@ -485,11 +518,11 @@ each package that let \fBportage\fR know which systems are compatible with the package. Packages which compile on an architecture, but have not been proven to be "stable", are masked with a tilde (\fB~\fR) in front of the architecture name. \fBemerge\fR examines the \fBACCEPT_KEYWORDS\fR environment -variable to allow or disallow the emerging of a package masked by \fBKEYWORDS\fR. -To inform \fBemerge\fR that it should build these 'testing' versions -of packages, you should update your \fI/etc/portage/package.keywords\fR file -to list the packages you want the 'testing' version. See \fBportage\fR(5) for -more information. +variable to allow or disallow the emerging of a package masked by +\fBKEYWORDS\fR. To inform \fBemerge\fR that it should build these 'testing' +versions of packages, you should update your +\fI/etc/portage/package.keywords\fR file to list the packages you want the +\'testing\' version. See \fBportage\fR(5) for more information. .SH "REPORTING BUGS" Please report any bugs you encounter through our website: .LP diff --git a/man/make.conf.5 b/man/make.conf.5 index cf4116953..eb04a8533 100644 --- a/man/make.conf.5 +++ b/man/make.conf.5 @@ -77,12 +77,16 @@ Determines how long the countdown delay will be after running `emerge clean`. .br Defaults to 5 seconds. .TP -\fBCONFIG_PROTECT\fR = \fI[space delimited list of dirs]\fR -All directories that are defined here will have "config file protection" +\fBCOLLISION_IGNORE\fR = \fI[space delimited list of files and/or directories]\fR +This variable allows the user to disable \fIcollision\-protect\fR for specific +files and/or directories. +.TP +\fBCONFIG_PROTECT\fR = \fI[space delimited list of files and/or directories]\fR +All files and/or directories that are defined here will have "config file protection" enabled for them. For more information, please see `emerge \-\-help config`. .TP -\fBCONFIG_PROTECT_MASK\fR = \fI[space delimited list of dirs]\fR -All directories that are defined here will have "config file protection" +\fBCONFIG_PROTECT_MASK\fR = \fI[space delimited list of files and/or directories]\fR +All files and/or directories that are defined here will have "config file protection" disabled for them. For more information, please see `emerge \-\-help config`. .TP .B CTARGET @@ -107,7 +111,7 @@ is specified. Defines whether or not to ignore short pauses that occur when displaying important informational messages. This variable is unset by default. .TP -\fBFEATURES\fR = \fI"sandbox ccache autoaddcvs"\fR +\fBFEATURES\fR = \fI"sandbox ccache"\fR Defines actions portage takes by default. These options should not be changed by anyone but developers and/or maintainers. 'sandbox' is an important part of \fBFEATURES\fR and should not be disabled by default. This is @@ -116,16 +120,16 @@ an incremental variable. .TP .B assume-digests When commiting work to cvs with \fBrepoman\fR(1), assume that all existing -SRC_URI digests are correct. -.TP -.B autoaddcvs -Causes portage to automatically try to add files to cvs that will have to be added -later. Done at generation times and only works when \fIcvs\fR is also in -\fBFEATURES\fR. +SRC_URI digests are correct. This feature also affects digest generation via +\fBebuild\fR(1) and \fBemerge\fR(1) (emerge generates digests only when the +\fIdigest\fR feature is enabled). .TP .B buildpkg Binary packages will be created for all packages that are merged. .TP +.B buildsyspkg +Build binary packages for just packages in the system set. +.TP .B ccache Enable portage support for the ccache package. If the ccache dir is not present in the user's environment, then portage will default to @@ -133,17 +137,21 @@ ${PORTAGE_TMPDIR}/ccache (with \fIuserpriv\fR) and to /root/.ccache otherwise. .TP .B confcache Enable confcache support; global configure caching, speeds up autotool based configure -calls. +calls via the econf helper function. See \fBebuild\fR(5) for more information. .TP .B collision\-protect A QA\-feature to ensure that a package doesn't overwrite files it doesn't own. +The \fICOLLISION_IGNORE\fR variable can be used to selectively disable this +feature. .TP .B cvs A feature for developers that causes portage to enable all USE flags in SRC_URI when creating digests. .TP .B digest -Autogenerate a digest for packages. +Autogenerate digests for packages when running the \fBemerge\fR(1) command. If +the \fIassume-digests\fR feature is also enabled then existing SRC_URI digests +will be reused whenever they are available. .TP .B distcc Enable portage support for the distcc package. @@ -168,6 +176,10 @@ Force emerges to always try to fetch files from the \fIPORTAGE_BINHOST\fR. See .B gpg Check the signatures of Manifests and make sure they are correct. .TP +.B installsources +Install source code into /usr/src/debug/${CATEGORY}/${PF} (also see +\fBsplitdebug\fR). This feature works only if debugedit is installed. +.TP .B keeptemp Do not delete the ${T} directory after the merge process. .TP @@ -225,12 +237,18 @@ a GPG key. Read about the \fIPORTAGE_GPG_KEY\fR variable in \fBmake.conf\fR(5). .TP .B splitdebug Prior to stripping ELF etdyn and etexec files, the debugging info is -stored for later use by various debuggers. +stored for later use by various debuggers. This feature is disabled by +\fBnostrip\fR. For installation of source code, see \fBinstallsources\fR. .TP .B strict Have portage react strongly to conditions that have the potential to be dangerous (like missing or incorrect Manifests). .TP +.B stricter +Have portage react strongly to conditions that may conflict with system +security provisions (for example textrels, executable stack). Read about +the \fIQA_STRICT_*\fR variables in \fBmake.conf\fR(5). +.TP .B suidctl Before merging packages to the live filesystem, automatically strip setuid bits from any file that is not listed in \fI/etc/portage/suidctl.conf\fR. @@ -240,8 +258,12 @@ Run package\-specific tests during each merge to help make sure the package compiled properly. See \fItest\fR in \fBebuild\fR(1) and \fIsrc_test()\fR in \fBebuild\fR(5). .TP +.B userfetch +When portage is run as root, drop privileges to portage:portage during the +fetching of package sources. +.TP .B userpriv -Allow portage to drop root privledges and compile packages as +Allow portage to drop root privileges and compile packages as portage:portage without a sandbox (unless \fIusersandbox\fR is also used). .TP .B usersandbox @@ -263,6 +285,12 @@ These vars are used if the sources must be downloaded from the internet by \fBwget\fR(1). They are only required if you use a proxy server for internet access. .TP +\fBINSTALL_MASK\fR = \fI[space delimited list of file names]\fR +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. +.TP .B MAKEOPTS 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 @@ -338,13 +366,25 @@ This variable contains the command used for resuming package sources that have been partially downloaded. It should be defined using the same format as \fBFETCHCOMMAND\fR. .TP +\fBQA_STRICT_EXECSTACK = \fI"set"\fR +Set this to cause portage to ignore any \fIQA_EXECSTACK\fR override +settings from ebuilds. See also \fBebuild\fR(5). +.TP +\fBQA_STRICT_WX_LOAD = \fI"set"\fR +Set this to cause portage to ignore any \fIQA_WX_LOAD\fR override +settings from ebuilds. See also \fBebuild\fR(5). +.TP +\fBQA_STRICT_TEXTRELS = \fI"set"\fR +Set this to cause portage to ignore any \fIQA_TEXTREL\fR override +settings from ebuilds. See also \fBebuild\fR(5). +.TP \fBROOT\fR = \fI[path]\fR Use \fBROOT\fR to specify the target root filesystem to be used for merging packages or ebuilds. All \fBRDEPEND\fR and \fBPDEPEND\fR will be installed into \fBROOT\fR while all \fBDEPEND\fR will be still be installed into /. Typically, you should set this setting in the environment rather than in \fI/etc/make.conf\fR itself. It's commonly used for creating new build -images. +images. Make sure you use an absolute path. .br Defaults to /. .TP @@ -364,6 +404,10 @@ This variable contains options that control the build behavior of several packages. More information in \fBebuild\fR(5). Possible USE values can be found in \fI/usr/portage/profiles/use.desc\fR. .TP +\fBUSE_EXPAND_HIDDEN\fR = \fI[space delimited list of variable names]\fR +Names of \fBUSE_EXPAND\fR variables that should not be shown in the verbose merge +list output of the \fBemerge\fR(1) command. +.TP \fBUSE_ORDER\fR = \fI"env:pkg:conf:auto:defaults"\fR Determines precedence for incrementing the setting of the USE variable. The above setting will cause the environment (env) to override per package (pkg) @@ -376,7 +420,7 @@ Do not modify this value unless you're a developer and you know what you're doing. If you change this and something breaks, we will not help you fix it. .br -Defaults to "env:pkg:conf:auto:defaults". +Defaults to "env:pkg:conf:defaults". .SH "REPORTING BUGS" Please report bugs via http://bugs.gentoo.org/ @@ -385,6 +429,7 @@ Please report bugs via http://bugs.gentoo.org/ Daniel Robbins Nicholas Jones Mike Frysinger +Saleem Abdulrasool .fi .SH "FILES" .TP diff --git a/man/portage.5 b/man/portage.5 index 51e6f32d8..565daaa58 100644 --- a/man/portage.5 +++ b/man/portage.5 @@ -28,8 +28,11 @@ make.defaults packages packages.build package.provided +package.use.force +package.use.mask parent -use.defaults +profile.bashrc +use.force use.mask virtuals .fi @@ -37,6 +40,7 @@ virtuals .BR /etc/portage/ .nf bashrc +modules package.mask package.unmask package.keywords @@ -222,36 +226,74 @@ x11-libs/qt-3.3.0 x11-base/xorg-x11-6.8 .fi .TP +.BR package.use.force +Per\-package USE flag forcing. + +.I Note: +In a cascading profile setup, you can remove USE flags in children +profiles which were added by parent profiles by prefixing the flag with +a '\-'. + +.I Format: +.nf +\- comments begin with # +\- one DEPEND atom per line with space-delimited USE flags +.fi + +.I Example: +.nf +# force docs for GTK 2.x +=x11\-libs/gtk+\-2* doc +# unforce mysql support for QT +x11\-libs/qt \-mysql +.fi +.TP +.BR package.use.mask +Per\-package USE flag masks. + +.I Note: +In a cascading profile setup, you can remove USE flags in children +profiles which were added by parent profiles by prefixing the flag with +a '\-'. + +.I Format: +.nf +\- comments begin with # +\- one DEPEND atom per line with space-delimited USE flags +.fi + +.I Example: +.nf +# mask docs for GTK 2.x +=x11\-libs/gtk+\-2* doc +# unmask mysql support for QT +x11\-libs/qt \-mysql +.fi +.TP .BR parent This contains a path to the parent profile. It may be either relative or absolute. The paths will be relative to the location of the profile. Most commonly this file contains '..' to indicate the directory above. Utilized only in cascading profiles. .TP -.BR use.defaults -Here we DO NOT define the default USE flags, but the so\-called auto\-USE -flags. This rather unknown portage feature activates a USE flag if a -specific package is installed and the flag was not explicitly -deactivated. This file contains the associations between USE flags and -packages that trigger the auto\-USE feature. +.BR profile.bashrc +If needed, this file can be used to set up a special environment for ebuilds, +different from the standard root environment. The syntax is the same as for +any other bash script. +.TP +.BR use.force +Some USE flags don't make sense to disable under certain conditions. Here we +list forced flags. -In other words, if we never put "sdl" or "\-sdl" into our USE, but we -have media\-libs/libsdl emerged, then portage automagically sticks "sdl" -into our USE for us. +.I Note: +In a cascading profile setup, you can remove USE flags in children +profiles which were added by parent profiles by prefixing the flag with +a '\-'. .I Format: .nf \- comments begin with # -\- one USE flag per line with a list of DEPEND atom bases -.fi - -.I Example: -.nf -# media\-libs/libsdl will activate "sdl" -sdl media\-libs/libsdl -# activate tcltk only if we have both -# dev\-lang/tcl and dev\-lang/tk -tcltk dev\-lang/tcl dev\-lang/tk +\- one USE flag per line .fi .TP .BR use.mask @@ -294,6 +336,16 @@ virtual/aspell\-dict app\-dicts/aspell\-en .RE .TP .BR /etc/portage/ +Any file in this directory that begins with "package." can be more than just a +flat file. If it is a directory, then all the files in that directory will be +summed together as if it were a single file. + +.I Example: +.nf +/etc/portage/package.keywords/kde +/etc/portage/package.keywords/common +/etc/portage/package.keywords/e17 +.fi .RS .TP .BR bashrc @@ -301,8 +353,28 @@ If needed, this file can be used to set up a special environment for ebuilds, different from the standard root environment. The syntax is the same as for any other bash script. .TP +.BR modules +This file can be used to override the metadata cache implementation. In +practice, portdbapi.auxdbmodule is the only variable that the user will want to +override. + +.I Example: +.nf +portdbapi.auxdbmodule = cache.metadata_overlay.database +.fi + +The metadata_overlay cache module makes it possible to disable +FEATURES="metadata-transfer" in \fBmake.conf\fR(5). When the user initially +enables metadata_overlay in /etc/portage/modules, all of the cache files +contained in /var/cache/edb/dep/${PORTDIR} must be manually removed in order +to avoid unecessary cache regeneration. In addition, users of the +metadata_overlay module must never modify eclasses in ${PORTDIR} because +portage will not be able to detect that cache regeneration is necessary. If +the user would like to modify eclasses, it is safe to use metadata_overlay +together with PORTDIR_OVERLAY in \fBmake.conf\fR. +.TP .BR package.mask -A list of DEPEND atoms to mask. Useful if specific versions of packages do +A list of package atoms to mask. Useful if specific versions of packages do not work well for you. For example, you swear by the Nvidia drivers, but only versions earlier than 1.0.4496. No problem! @@ -388,7 +460,7 @@ hosts here. If the mirror set is not found here, it will check the global mirrors file at /usr/portage/profiles/thirdpartymirrors. You may also set a special mirror type called "local". This list of mirrors will be checked before GENTOO_MIRRORS and will be used even if the package has -RESTRICT="mirror". +RESTRICT="mirror" or RESTRICT="fetch". .I Format: .nf diff --git a/man/repoman.1 b/man/repoman.1 index 7a70245f8..306ddd0a1 100644 --- a/man/repoman.1 +++ b/man/repoman.1 @@ -111,6 +111,9 @@ Ebuilds that have a missing or empty LICENSE variable .B LICENSE.syntax Syntax error in LICENSE (usually an extra/missing space/parenthesis) .TP +.B LIVEVCS.stable +Ebuild is a live ebuild (cvs, git, darcs, svn, etc) checkout with stable keywords. +.TP .B PDEPEND.bad User-visible ebuilds with bad PDEPEND settings (matched against *visible* ebuilds) .TP -- 2.26.2