diff options
Diffstat (limited to 'man/portage.5')
| -rw-r--r-- | man/portage.5 | 588 |
1 files changed, 588 insertions, 0 deletions
diff --git a/man/portage.5 b/man/portage.5 new file mode 100644 index 00000000..f9cad8b0 --- /dev/null +++ b/man/portage.5 @@ -0,0 +1,588 @@ +.TH "PORTAGE" "5" "Jan 2004" "Portage 2.0.51" "Portage" +.SH NAME +portage \- the heart of Gentoo +.SH "DESCRIPTION" +The current portage code uses many different configuration files, most of which +are unknown to users and normal developers. Here we will try to collect all +the odds and ends so as to help users more effectively utilize portage. This +is a reference only for files which do not already have a man page. + +All files in the make.profile directory may be tweaked via parent profiles +when using cascading profiles. For more info, please see +http://www.gentoo.org/proj/en/releng/docs/cascading-profiles.xml +.IP Note: +If you are looking for information on how to emerge something, please see +.BR emerge (1). +.SH "SYNOPSIS" +.TP +.BR /etc/ +.nf +make.globals +.BR make.conf (5) +.fi +.TP +.BR /etc/make.profile/ +.nf +deprecated +make.defaults +packages +packages.build +package.provided +parent +use.defaults +use.mask +virtuals +.fi +.TP +.BR /etc/portage/ +.nf +bashrc +package.mask +package.unmask +package.keywords +package.use +mirrors +categories +.fi +.TP +.BR /etc/portage/profile/ +site-specific overrides of \fB/etc/make.profile/\fR +.TP +.BR /usr/portage/profiles/ +.nf +arch.list +categories +info_pkgs +info_vars +package.mask +profiles.desc +thirdpartymirrors +use.desc +use.local.desc +.fi +.TP +.BR /var/lib/portage/ +world +.SH "GLOSSARY" +In the following sections, some terminology may be foreign to you or used +with meaning specific to Portage. Please see the referenced manpages for +more detailed explanations. +.RS +.TP +.B DEPEND atom +A string which matches a package. It is of the form category/package. +It may also contain optional logical operators and versions. +.br +More reading: +.BR ebuild (5) +.TP +.B KEYWORD +Each architecture has a unique KEYWORD. +.br +More reading: +.BR ebuild (5) +.TP +.B virtual +A DEPEND atom that is part of the "virtual" category. They are used +when different packages can satisfy a dependency and only one of them is +needed. +.br +More reading: +.BR ebuild (5) +.RE +.SH "SPECIFIC FILE DESCRIPTIONS" +.TP +.BR /etc/ +.RS +.TP +.BR make.globals +The global default settings for Portage. This comes from the portage package +itself. Settings in \fBmake.conf\fR override values here. The format +is described extensivly in \fBmake.conf\fR(5). +.TP +.BR make.conf +The global custom settings for Portage. See \fBmake.conf\fR(5). +.RE +.TP +.BR /etc/make.profile/ +This is usually just a symlink to the correct profile in +\fB/usr/portage/profiles/\fR. Since it is part of the portage tree, it +may easily be updated/regenerated by running `emerge \-\-sync`. It defines +what a profile is (usually arch specific stuff). If you need a custom +profile, then you should make your own \fB/etc/make.profile/\fR +directory and populate it. However, if you just wish to override some +settings, do NOT edit these files because they WILL be lost with the +next `emerge \-\-sync`. See the section below on \fB/etc/portage/\fR for +overriding. +.RS +.TP +.BR deprecated +The existence of this file marks a profile as deprecated, meaning it is +not supported by Gentoo anymore. The first line must be the profile to which +users are encouraged to upgrade, optionally followed by some instructions +explaining how they can upgrade. + +.I Example: +.nf +default-linux/x86/2005.0 +# emerge -n '>=sys-apps/portage-2.0.51' +# rm -f /etc/make.profile +# ln -s /usr/portage/profiles/default-linux/alpha/2005.0 /etc/make.profile +.fi +.TP +.BR make.defaults +The profile default settings for Portage. The general format is described +in \fBmake.conf\fR(5). The \fImake.defaults\fR for your profile defines a +few specific variables too: + +.PD 0 +.RS +.TP +.BR ARCH +Architecture type (x86/ppc/hppa/etc...). +.TP +.B USERLAND = \fI"GNU"\fR +Support BSD/cygwin/etc... +.TP +.B PORTAGE_LIBC = \fI"glibc"\fR +Support uClibc/BSD libc/etc... +.TP +.BR PROFILE_ARCH +Distinguish machines classes that have the same \fBARCH\fR. All sparc +machines have ARCH=sparc but set this to either 'sparc32' or 'sparc64'. +.TP +.BR STAGE1_USE +Special USE flags which may be needed when bootstrapping from stage1 to stage2. +.TP +.BR GRP_STAGE23_USE +Special USE flags used by catalyst for building a stage3 and GRP sets. +.RE +.PD 1 +.TP +.BR packages +This file serves two purposes. The first is to mask out specific +packages/versions on a per\-profile basis. The second is to provide the +list of packages that compose the special \fIsystem\fR class. + +.I Format: +.nf +\- comments begin with # +\- one DEPEND atom per line of what to mask OUT +\- packages to be added to the system class begin with a * +.fi +.I Note: +In a cascading profile setup, you can remove packages in children +profiles which were added by parent profiles by prefixing the atom with +a '\-'. + +.I Example: +.nf +# i am a comment ! +# only allow versions of glibc less than 2.3 +<sys\-libs/glibc\-2.3 +# add any version of bash to the system class +*app\-shells/bash +# only allow versions of readline earlier than 4.2 +# and add it to the system class +*<sys\-libs/readline\-4.2 +.fi +.TP +.BR packages.build +A list of packages (one per line) that make up a stage1 tarball. Really only +useful for stage builders. +.TP +.BR package.provided +A list of packages (one per line) that portage should assume have been +provided. Useful for porting to non-Linux systems. Portage will not +attempt to update a package that is listed here unless another package +explicitly requires a version that is newer than what has been listed. +Basically, it's a list that replaces the \fBemerge \-\-inject\fR syntax. + +For example, if you manage your own copy of a 2.6 kernel, then you can +tell portage that 'sys-kernel/development-sources-2.6.7' is already taken +care of and it should get off your back about it. + +.I Format: +.nf +\- comments begin with # +\- one DEPEND atom per line +\- relational operators are not allowed +\- must include a version +.fi + +.I Example: +.nf +# you take care of the kernel +sys-kernel/development-sources-2.6.7 + +# you installed your own special copy of QT +x11-libs/qt-3.3.0 +.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. + +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 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 +.fi +.TP +.BR use.mask +Some USE flags don't make sense on some archs (for example altivec on +non\-ppc or mmx on non\-x86), or haven't yet been tested. Here we list +the masked ones. + +.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 +.fi +.TP +.BR virtuals +This controls what packages will provide a virtual by default. For example, +if a package needs to send e\-mail, it will need virtual/mta. In the absence +of a package that provides virtual/mta (like qmail, sendmail, postfix, etc...), +portage will look here to see what package to use. In this case, Gentoo uses +net\-mail/ssmtp as the default (as defined in the virtuals file) because it's +the package that does the very bare minimum to send e\-mail. + +.I Format: +.nf +\- comments begin with # +\- one virtual and DEPEND atom base pair per line +.fi + +.I Example: +.nf +# use net\-mail/ssmtp as the default mta +virtual/mta net\-mail/ssmtp +# use app\-dicts/aspell\-en as the default dictionary +virtual/aspell\-dict app\-dicts/aspell\-en +.fi +.RE +.TP +.BR /etc/portage/ +.RS +.TP +.BR 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 package.mask +A list of DEPEND 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! + +.I Format: +.nf +\- comments begin with # +\- one DEPEND atom per line +.fi + +.I Example: +.nf +# mask out versions 1.0.4496 of the nvidia +# drivers and later +>=media\-video/nvidia\-kernel\-1.0.4496 +>=media\-video/nvidia\-glx\-1.0.4496 +.fi +.TP +.BR package.unmask +Just like package.mask above, except here you list packages you want to +unmask. Useful for overriding the global package.mask file (see +below). Note that this does not override packages that are masked via +KEYWORDS. +.TP +.BR package.keywords +Per\-package KEYWORDS. Useful for mixing unstable packages in with a normally +stable machine or vice versa. This will allow you to augment ACCEPT_KEYWORDS +for a single package. + +.nf +\fINote:\fR There are two special KEYWORDS to help out here: +\fB*\fR Match any stable KEYWORD +\fB~*\fR Match any unstable KEYWORD + +.I Format: +\- comments begin with # +\- one DEPEND atom per line followed by additional KEYWORDS +\- blank lines imply unstable host arch + +.I Example: +# always use unstable libgd +media\-libs/libgd ~x86 +# only use stable mplayer +media\-video/mplayer \-~x86 +# always use unstable netcat +net-analyzer/netcat +.fi +.TP +.BR package.use +Per\-package USE flags. Useful for tracking local USE flags or for +enabling USE flags for certain packages only. Perhaps you develop GTK +and thus you want documentation for it, but you don't want +documentation for QT. Easy as pie my friend! + +.I Format: +.nf +\- comments begin with # +\- one DEPEND atom per line with space-delimited USE flags +.fi + +.I Example: +.nf +# turn on docs for GTK 2.x +=x11\-libs/gtk+\-2* doc +# disable mysql support for QT +x11\-libs/qt \-mysql +.fi +.TP +.BR mirrors +Whenever portage encounters a mirror:// style URL it will look up the actual +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="nomirror". + +.I Format: +.nf +\- comments begin with # +\- mirror type followed by a list of hosts +.fi + +.I Example: +.nf +# local private mirrors used only by my company +local ftp://192.168.0.3/mirrors/gentoo http://192.168.0.4/distfiles + +# people in japan would want to use the japanese mirror first +sourceforge http://keihanna.dl.sourceforge.net/sourceforge + +# people in tawain would want to use the local gnu mirror first +gnu ftp://ftp.nctu.edu.tw/UNIX/gnu/ +.fi +.TP +.BR categories +A simple list of valid categories that may be used in /usr/portage, +PORTDIR_OVERLAY, and PKGDIR (see \fBmake.conf\fR(5)). This allows for custom +categories to be created. + +.I Format: +.nf +\- one category per line +.fi + +.I Example: +.nf +app\-hackers +media\-other +.fi +.TP +.BR /usr/portage/profiles/ +Global Gentoo settings that are controlled by the developers. To override +these settings, you can use the files in \fB/etc/portage/\fR. +.RS +.TP +.BR arch.list +A list of all valid KEYWORDS. This does not include modifiers. + +.I Format: +.nf +\- one KEYWORD per line +.fi + +.I Example: +.nf +x86 +ppc +sparc +.fi +.TP +.BR categories +A simple list of valid categories that may be used in /usr/portage, +PORTDIR_OVERLAY, and PKGDIR (see \fBmake.conf\fR(5)). + +.I Format: +.nf +\- one category per line +.fi + +.I Example: +.nf +app\-admin +dev\-lang +games\-strategy +sys\-kernel +.fi +.TP +.BR info_pkgs +A list of all the packages which will be displayed when you run `emerge info`. +.TP +.BR info_vars +A list of all the variables which will be displayed when you run `emerge info`. +.TP +.BR package.mask +This contains a list of DEPEND atoms for packages that should not be installed +in any profile. Useful for adding the latest KDE betas and making sure no +one accidentally upgrades to them. Also useful for quickly masking specific +versions due to security issues. ALWAYS include a comment explaining WHY the +package has been masked and WHO is doing the masking. + +.I Format: +.nf +\- comments begin with # +\- one DEPEND atom per line +.fi + +.I Example: +.nf +# masked for security reasons +<sys\-libs/zlib\-1.1.4 +# <caleb@gentoo.org> (10 Sep 2003) +# new kde betas +=kde\-base/kde\-3.2.0_beta1 +=kde\-base/kdeaccessibility\-3.2.0_beta1 +.fi +.TP +.BR profiles.desc +List all the current stable and development profiles. If a profile is listed +here, then it will be checked by repoman. At the moment, only 1 profile is +allowed per stable/dev/KEYWORD; the last one found is the last one used. + +.I Format: +.nf +\- comments begin with # +\- one profile list per line in format: arch dir status +\- arch must be listed in arch.list +\- dir is relative to profiles.desc +\- status must be 'stable' or 'dev' +.fi + +.I Example: +.nf +alpha default-linux/alpha/2004.3 stable +m68k default-linux/m68k dev +x86 default-linux/x86/2004.3 stable +.fi +.TP +.BR thirdpartymirrors +Controls the mapping of mirror:// style URLs to actual lists of +mirrors. Keeps us from overloading a single server. + +.I Format: +.nf +\- comments begin with # +\- mirror type followed by a list of hosts +.fi + +.I Example: +.nf +sourceforge http://aleron.dl.sourceforge.net/sourceforge http://unc.dl.sourceforge.net/sourceforge + +gentoo http://distro.ibiblio.org/pub/linux/distributions/gentoo/distfiles/ ftp://ftp.gtlib.cc.gatech.edu/pub/gentoo/distfiles + +kernel http://www.kernel.org/pub http://www.us.kernel.org/pub +.fi +.TP +.BR use.desc +All global USE flags must be listed here with a description of what they do. + +.I Format: +.nf +\- comments begin with # +\- use flag \- some description +.fi + +.I Example: +.nf +3dfx \- Adds support for 3dfx video cards +acl \- Adds support for Access Control Lists +doc \- Adds extra documentation +.fi +.TP +.BR use.local.desc +All local USE flags must be listed here along with the package and a +description. + +.nf +.I Format: +\- comments begin with # +\- package:use flag \- description + +.I Example: +app\-editors/nano:justify \- Toggles the justify option +dev\-libs/DirectFB:fusion \- Adds Multi Application support +games\-emulation/xmess:net \- Adds network support +.fi +.RE +.TP +.BR /var/lib/portage/ +.RS +.TP +.BR world +Every time you emerge a package, the package that you requested is +recorded here. Then when you run `emerge world \-up`, the list of +packages is read from this file. Note that this does not mean that the +packages that were installed as dependencies are listed here. For +example, if you run `emerge mod_php` and you do not have apache +already, then "dev\-php/mod_php" is recorded in the world file but +"net\-www/apache" is not. For more information, review \fBemerge\fR(1). + +.I Format: +.nf +\- one DEPEND atom base per line +.fi + +.I Example: +.nf +games\-misc/fortune\-mod\-gentoo\-dev +dev\-libs/uclibc +app\-cdr/cdemu +.fi +.RE +.SH "AUTHORS" +.nf +Marius Mauch <genone@gentoo.org> +Mike Frysinger <vapier@gentoo.org> +Drake Wyrm <wyrm@haell.com> +.fi +.SH "REPORTING BUGS" +Please report bugs via http://bugs.gentoo.org/ +.SH "SEE ALSO" +.BR emerge (1), +.BR ebuild (1), +.BR ebuild (5), +.BR make.conf (5) +.SH "CVS HEADER" +$Header: /var/cvsroot/gentoo-src/portage/man/portage.5,v 1.17.2.12 2005/07/02 21:02:17 vapier Exp $ |