1 .TH "PORTAGE" "5" "Aug 2008" "Portage 2.2" "Portage"
3 portage \- the heart of Gentoo
5 The current portage code uses many different configuration files, most of which
6 are unknown to users and normal developers. Here we will try to collect all
7 the odds and ends so as to help users more effectively utilize portage. This
8 is a reference only for files which do not already have a man page.
10 All files in the make.profile directory may be tweaked via parent profiles
11 when using cascading profiles. For more info, please see
12 http://www.gentoo.org/proj/en/releng/docs/cascading-profiles.xml
14 If you are looking for information on how to emerge something, please see
24 \fB/etc/make.profile/\fR or \fB/etc/portage/make.profile/\fR
25 site\-specific overrides go in \fB/etc/portage/profile/\fR
54 package.accept_keywords
65 package-specific bashrc files
67 .BR /etc/portage/profile/
68 site-specific overrides of \fB/etc/make.profile/\fR
70 .BR /usr/portage/metadata/
75 .BR /usr/portage/profiles/
91 misc internal cache files
94 database to track installed packages
103 In the following sections, some terminology may be foreign to you or used
104 with meaning specific to Portage. Please see the referenced manpages for
105 more detailed explanations.
109 An atom is either of the form category/package or consists of an operator
110 followed by category/package followed by a hyphen and a version specification.
111 An atom might be prefixed by a slot specification.
112 The extended atom syntax allows atoms of the form category/package, where an
113 arbitrary number of characters has been replaced by a '*'. An extended atom may contain
114 more than one '*', but not two next to each other. The extend atom syntax is only
115 available in user configuration files and for some command line options.
121 Each architecture has a unique KEYWORD.
127 A DEPEND atom that is part of the "virtual" category. They are used
128 when different packages can satisfy a dependency and only one of them is
134 .SH "SPECIFIC FILE DESCRIPTIONS"
140 The global default settings for Portage. This comes from the portage package
141 itself. Settings in \fBmake.conf\fR override values here. The format
142 is described extensivly in \fBmake.conf\fR(5).
145 The global custom settings for Portage. See \fBmake.conf\fR(5).
148 \fB/etc/make.profile/\fR or \fB/etc/portage/make.profile/\fR
149 This is usually just a symlink to the correct profile in
150 \fB/usr/portage/profiles/\fR. Since it is part of the portage tree, it
151 may easily be updated/regenerated by running `emerge \-\-sync`. It defines
152 what a profile is (usually arch specific stuff). If you need a custom
153 profile, then you should make your own \fB/etc/make.profile/\fR
154 directory and populate it. However, if you just wish to override some
155 settings, use \fB/etc/portage/profile/\fR (it supports all of the same file
156 types that \fB/etc/make.profile/\fR does, except parent). Do NOT edit the
157 settings in \fB/etc/make.profile/\fR because they WILL be lost with the next
158 `emerge \-\-sync`. If both \fB/etc/make.profile/\fR and
159 \fB/etc/portage/make.profile/\fR exist, then \fB/etc/make.profile/\fR
162 Any file in this directory, directories of other profiles or top-level
163 "profiles" directory that begins with "package." or "use." can be more than
164 just a flat file. If it is a directory, then all the files in that directory
165 will be sorted in ascending alphabetical order by file name and summed together
166 as if it were a single file. Note that this behavior is only supported since
167 portage-2.1.6.7, and it is not included in PMS at this time.
171 ${PORTDIR}/profiles/package.mask/removals
172 ${PORTDIR}/profiles/package.mask/testing
177 The existence of this file marks a profile as deprecated, meaning it is
178 not supported by Gentoo anymore. The first line must be the profile to which
179 users are encouraged to upgrade, optionally followed by some instructions
180 explaining how they can upgrade.
184 default-linux/x86/2005.0
185 # emerge -n '>=sys-apps/portage-2.0.51'
186 # rm -f /etc/make.profile
187 # ln -s /usr/portage/profiles/default-linux/alpha/2005.0 /etc/make.profile
191 The first line of this file specifies the \fBEAPI\fR to which files in the
192 same directory conform. See \fBebuild\fR(5) for information about \fBEAPI\fR
193 and related features.
196 The profile default settings for Portage. The general format is described
197 in \fBmake.conf\fR(5). The \fImake.defaults\fR for your profile defines a
198 few specific variables too:
204 Architecture type (x86/ppc/hppa/etc...).
206 .B USERLAND = \fI"GNU"\fR
207 Support BSD/cygwin/etc...
209 .B ELIBC = \fI"glibc"\fR
210 Support uClibc/BSD libc/etc...
212 .B PROFILE_ONLY_VARIABLES = \fI"ARCH"\fR
213 Prevent critical variables from being changed by the user in make.conf
217 Distinguish machines classes that have the same \fBARCH\fR. All sparc
218 machines have ARCH=sparc but set this to either 'sparc32' or 'sparc64'.
221 Special USE flags which may be needed when bootstrapping from stage1 to stage2.
226 Provides the list of packages that compose the special \fIsystem\fR set.
230 \- comments begin with # (no inline comments)
231 \- one DEPEND atom per line
232 \- packages to be added to the system set begin with a *
235 In a cascading profile setup, you can remove packages in children
236 profiles which were added by parent profiles by prefixing the atom with
242 # pull in a version of glibc less than 2.3
243 *<sys\-libs/glibc\-2.3
244 # pull in any version of bash
246 # pull in a version of readline earlier than 4.2
247 *<sys\-libs/readline\-4.2
251 A list of packages (one per line) that make up a stage1 tarball. Really only
252 useful for stage builders.
255 A list of packages (one per line) that portage should assume have been
256 provided. Useful for porting to non-Linux systems. Basically, it's a
257 list that replaces the \fBemerge \-\-inject\fR syntax.
259 For example, if you manage your own copy of a 2.6 kernel, then you can
260 tell portage that 'sys-kernel/development-sources-2.6.7' is already taken
261 care of and it should get off your back about it.
263 Portage will not attempt to update a package that is listed here unless
264 another package explicitly requires a version that is newer than what
265 has been listed. Dependencies that are satisfied by package.provided
266 entries may cause installed packages satisfying equivalent dependencies
267 to be removed by \fBemerge\fR(1) \fB\-\-depclean\fR actions (see the
268 \fBACTIONS\fR section of the \fBemerge\fR(1) man page for more information).
270 Virtual packages (virtual/*) should not be specified in package.provided.
271 Depending on the type of virtual, it may be necessary to add an entry to the
272 virtuals file and/or add a package that satisfies a virtual to
277 \- comments begin with # (no inline comments)
278 \- one DEPEND atom per line
279 \- relational operators are not allowed
280 \- must include a version
285 # you take care of the kernel
286 sys-kernel/development-sources-2.6.7
288 # you installed your own special copy of QT
291 # you have modular X but packages want monolithic
292 x11-base/xorg-x11-6.8
295 .BR package.use.force
296 Per\-package USE flag forcing.
299 In a cascading profile setup, you can remove USE flags in children
300 profiles which were added by parent profiles by prefixing the flag with
305 \- comments begin with # (no inline comments)
306 \- one DEPEND atom per line with space-delimited USE flags
311 # force docs for GTK 2.x
312 =x11\-libs/gtk+\-2* doc
313 # unforce mysql support for QT
318 Per\-package USE flag masks.
321 In a cascading profile setup, you can remove USE flags in children
322 profiles which were added by parent profiles by prefixing the flag with
327 \- comments begin with # (no inline comments)
328 \- one DEPEND atom per line with space-delimited USE flags
333 # mask docs for GTK 2.x
334 =x11\-libs/gtk+\-2* doc
335 # unmask mysql support for QT
340 This contains a path to the parent profile. It may be either relative or
341 absolute. The paths will be relative to the location of the profile. Most
342 commonly this file contains '..' to indicate the directory above. Utilized
343 only in cascading profiles.
346 If needed, this file can be used to set up a special environment for ebuilds,
347 different from the standard root environment. The syntax is the same as for
348 any other bash script.
351 Some USE flags don't make sense to disable under certain conditions. Here we
355 In a cascading profile setup, you can remove USE flags in children
356 profiles which were added by parent profiles by prefixing the flag with
361 \- comments begin with # (no inline comments)
362 \- one USE flag per line
366 Some USE flags don't make sense on some archs (for example altivec on
367 non\-ppc or mmx on non\-x86), or haven't yet been tested. Here we list
371 In a cascading profile setup, you can remove USE flags in children
372 profiles which were added by parent profiles by prefixing the flag with
377 \- comments begin with # (no inline comments)
378 \- one USE flag per line
382 This controls what packages will provide a virtual by default. For example,
383 if a package needs to send e\-mail, it will need virtual/mta. In the absence
384 of a package that provides virtual/mta (like qmail, sendmail, postfix, etc...),
385 portage will look here to see what package to use. In this case, Gentoo uses
386 net\-mail/ssmtp as the default (as defined in the virtuals file) because it's
387 the package that does the very bare minimum to send e\-mail.
391 \- comments begin with # (no inline comments)
392 \- one virtual and DEPEND atom base pair per line
397 # use net\-mail/ssmtp as the default mta
398 virtual/mta net\-mail/ssmtp
399 # use app\-dicts/aspell\-en as the default dictionary
400 virtual/aspell\-dict app\-dicts/aspell\-en
405 Any file in this directory that begins with "package." can be more than just a
406 flat file. If it is a directory, then all the files in that directory will be
407 sorted in ascending alphabetical order by file name and summed together as if
408 it were a single file.
412 /etc/portage/package.accept_keywords/common
413 /etc/portage/package.accept_keywords/e17
414 /etc/portage/package.accept_keywords/kde
419 If needed, this file can be used to set up a special environment for ebuilds,
420 different from the standard root environment. The syntax is the same as for
421 any other bash script.
423 Additional package-specific bashrc files can be created in /etc/portage/env.
426 A simple list of valid categories that may be used in /usr/portage,
427 PORTDIR_OVERLAY, and PKGDIR (see \fBmake.conf\fR(5)). This allows for custom
428 categories to be created.
432 \- one category per line
442 Contains variables customizing colors. See \fBcolor.map\fR(5).
445 The global custom settings for Portage. See \fBmake.conf\fR(5).
446 If present, this file will override settings from /etc/make.conf.
449 Whenever portage encounters a mirror:// style URI it will look up the actual
450 hosts here. If the mirror set is not found here, it will check the global
451 mirrors file at /usr/portage/profiles/thirdpartymirrors. You may also set a
452 special mirror type called "local". This list of mirrors will be checked
453 before GENTOO_MIRRORS and will be used even if the package has
454 RESTRICT="mirror" or RESTRICT="fetch".
458 \- comments begin with # (no inline comments)
459 \- mirror type followed by a list of hosts
464 # local private mirrors used only by my company
465 local ftp://192.168.0.3/mirrors/gentoo http://192.168.0.4/distfiles
467 # people in japan would want to use the japanese mirror first
468 sourceforge http://keihanna.dl.sourceforge.net/sourceforge
470 # people in tawain would want to use the local gnu mirror first
471 gnu ftp://ftp.nctu.edu.tw/UNIX/gnu/
475 This file can be used to override the metadata cache implementation. In
476 practice, portdbapi.auxdbmodule is the only variable that the user will want to
481 portdbapi.auxdbmodule = portage.cache.sqlite.database
484 After changing the portdbapi.auxdbmodule setting, it may be necessary to
485 transfer or regenerate metadata cache. Users of the rsync tree need to
486 run `emerge \-\-metadata` if they have enabled FEATURES="metadata-transfer"
487 in \fBmake.conf\fR(5). In order to regenerate metadata for repositories
488 listed in \fBPORTDIR_OVERLAY\fR or a cvs tree, run `emerge \-\-regen`
489 (see \fBemerge\fR(1)). If you use something like the sqlite module and want
490 to keep all metadata in that format alone (useful for querying), enable
491 FEATURES="metadata-transfer" in \fBmake.conf\fR(5).
493 \fBpackage.accept_keywords\fR and \fBpackage.keywords\fR
494 Per\-package ACCEPT_KEYWORDS. Useful for mixing unstable packages in with a normally
495 stable system or vice versa. This will allow ACCEPT_KEYWORDS to be augmented
496 for a single package. If both \fBpackage.accept_keywords\fR and
497 \fBpackage.keywords\fR are present, both of them will be used, and values
498 from \fBpackage.accept_keywords\fR will override values from
499 \fBpackage.keywords\fR. The \fBpackage.accept_keywords\fR file is
500 intended to replace the \fBpackage.keywords\fR file, since
501 profiles support a different form of \fBpackage.keywords\fR which
502 modifies effective KEYWORDS (rather than ACCEPT_KEYWORDS).
506 \- comment lines begin with # (no inline comments)
507 \- one DEPEND atom per line followed by additional KEYWORDS
508 \- lines without any KEYWORDS imply unstable host arch
511 # always use unstable libgd
512 media\-libs/libgd ~x86
513 # only use stable mplayer
514 media\-video/mplayer \-~x86
515 # always use unstable netcat
521 In addition to the normal values from ACCEPT_KEYWORDS package.keywords supports
522 three special tokens:
525 \fB*\fR package is visible if it is stable on any architecture
526 \fB~*\fR package is visible if it is in testing on any architecture
527 \fB**\fR package is always visible (KEYWORDS are ignored completely)
531 If you encounter the \fB-*\fR KEYWORD, this indicates that the package is known
532 to be broken on all systems which are not otherwise listed in KEYWORDS. For
533 example, a binary only package which is built for x86 will look like:
535 games-fps/quake3-demo-1.11.ebuild:KEYWORDS="-* x86"
537 If you wish to accept this package anyways, then use one of the other keywords in your
538 package.accept_keywords like this:
540 games-fps/quake3-demo x86
544 This will allow ACCEPT_LICENSE to be augmented for a single package.
548 \- comment lines begin with # (no inline comments)
549 \- one DEPEND atom per line followed by additional licenses or groups
553 A list of package atoms to mask. Useful if specific versions of packages do
554 not work well for you. For example, you swear by the Nvidia drivers, but only
555 versions earlier than 1.0.4496. No problem!
559 \- comment lines begin with # (no inline comments)
560 \- one DEPEND atom per line
565 # mask out versions 1.0.4496 of the nvidia
567 >=media\-video/nvidia\-kernel\-1.0.4496
568 >=media\-video/nvidia\-glx\-1.0.4496
571 .BR package.properties
572 This will allow ACCEPT_PROPERTIES to be augmented for a single package.
576 \- comment lines begin with # (no inline comments)
577 \- one DEPEND atom per line followed by additional properties
581 Just like package.mask above, except here you list packages you want to
582 unmask. Useful for overriding the global package.mask file (see
583 above). Note that this does not override packages that are masked via
587 Per\-package USE flags. Useful for tracking local USE flags or for
588 enabling USE flags for certain packages only. Perhaps you develop GTK
589 and thus you want documentation for it, but you don't want
590 documentation for QT. Easy as pie my friend!
594 \- comments begin with # (no inline comments)
595 \- one DEPEND atom per line with space-delimited USE flags
600 # turn on docs for GTK 2.x
601 =x11\-libs/gtk+\-2* doc
602 # disable mysql support for QT
607 Specifies \fIsite\-specific\fR repository configuration information. Note that
608 configuration settings which are specified here do not apply to tools
609 such as \fBrepoman\fR(1) and \fBegencache\fR(1), since operations
610 performed by these tools
611 are inherently \fBnot\fR \fIsite\-specific\fR. \fBWARNING:\fR Use of
612 \fBrepos.conf\fR is generally not recommended since resulting changes in
613 eclass inheritance (especially due to \fBeclass\-overrides\fR) may trigger
614 performance issues under some circumstances (see \fBbug #124041\fR). When
615 using \fBeclass\-overrides\fR, due to bug #276264, you must ensure that
616 your portage tree does not contain a metadata/cache/ directory. If that
617 directory exists then you should remove it entirely, and set
618 PORTAGE_RSYNC_EXTRA_OPTS="\-\-exclude=/metadata/cache" in
619 make.conf in order to exclude the metadata/cache/ directory during
620 \fBemerge\fR(1) \-\-sync operations.
625 # make all repositories inherit eclasses from the java\-overlay and
626 # java\-experimental repositories, with eclasses from java\-experimental
627 # taking precedence over those from java\-overlay
628 eclass\-overrides = java\-overlay java\-experimental
631 # disable all eclass overrides for ebuilds from the gentoo repository
633 # when processing metadata/layout.conf from other repositories, substitute
634 # 'gentoo' in place of references to repositories named 'foo' and 'bar'
638 # override the metadata/layout.conf masters setting from the kde-testing repo
643 .BR /etc/portage/env/
645 In this directory additional package-specific bashrc files can be created.
646 Portage will source all of them after \fB/etc/portage/bashrc\fR in the following
650 /etc/portage/env/${CATEGORY}/${PN}
652 /etc/portage/env/${CATEGORY}/${PN}:${SLOT}
654 /etc/portage/env/${CATEGORY}/${P}
656 /etc/portage/env/${CATEGORY}/${PF}
659 .BR /usr/portage/metadata/
663 Specifies information about the repository layout. Currently, only a single
664 "masters" attribute is supported, which is used to specify names of
665 repositories which satisfy dependencies on eclasses and/or ebuilds. Each
666 repository name should correspond the value of a \fBrepo_name\fR entry
667 from one of the repositories that is configured via the \fBPORTDIR\fR or
668 \fBPORTDIR_OVERLAY\fR variables (see \fBmake.conf\fR(5)). Repositories listed
669 toward the right of the \fBmasters\fR list take precedence over those listed
670 toward the left of the list. \fISite-specific\fR
671 overrides to \fBlayout.conf\fR settings may be specified in
672 \fB/etc/portage/repos.conf\fR. Settings in \fBrepos.conf\fR take
673 precedence over settings in \fBlayout.conf\fR, except tools such as
674 \fBrepoman\fR(1) and \fBegencache\fR(1) will entirely ignore
675 \fBrepos.conf\fR since their operations are inherently \fBnot\fR
676 \fIsite\-specific\fR.
680 # eclasses provided by java-overlay take precedence over identically named
681 # eclasses that are provided by gentoo
682 masters = gentoo java-overlay
686 .BR /usr/portage/profiles/
687 Global Gentoo settings that are controlled by the developers. To override
688 these settings, you can use the files in \fB/etc/portage/\fR.
692 A list of all valid KEYWORDS. This does not include modifiers.
696 \- one KEYWORD per line
707 A simple list of valid categories that may be used in /usr/portage,
708 PORTDIR_OVERLAY, and PKGDIR (see \fBmake.conf\fR(5)).
712 \- one category per line
724 A list of all the packages which will be displayed when you run `emerge info`.
727 A list of all the variables which will be displayed when you run `emerge info`.
730 This contains groups of licenses that may be specifed in the
731 \fBACCEPT_LICENSE\fR variable (see \fBmake.conf\fR(5)). Refer
732 to GLEP 23 for further information:
733 \fIhttp://www.gentoo.org/proj/en/glep/glep-0023.html\fR.
737 \- comments begin with # (no inline comments)
738 \- one group name, followed by list of licenses and nested groups
739 \- nested groups are prefixed with the '@' symbol
744 # The FSF-APPROVED group includes the entire GPL-COMPATIBLE group and more.
745 FSF-APPROVED @GPL-COMPATIBLE Apache-1.1 BSD-4 MPL-1.0 MPL-1.1
746 # The GPL-COMPATIBLE group includes all licenses compatible with the GNU GPL.
747 GPL-COMPATIBLE Apache-2.0 BSD BSD-2 GPL-2 GPL-3 LGPL-2.1 LGPL-3 X11 ZLIB
751 Per\-profile KEYWORDS. Useful for cases in which the effective KEYWORDS of a
752 given package should vary depending on which profile the user has selected.
756 \- comment lines begin with # (no inline comments)
757 \- one DEPEND atom per line followed by additional KEYWORDS
762 # add stable keyword to libgd
763 media\-libs/libgd x86
764 # remove stable keyword from mplayer and add unstable keyword
765 media\-video/mplayer \-x86 ~x86
766 # remove all keywords from netcat
767 net-analyzer/netcat -*
771 This contains a list of DEPEND atoms for packages that should not be installed
772 in any profile. Useful for adding the latest KDE betas and making sure no
773 one accidentally upgrades to them. Also useful for quickly masking specific
774 versions due to security issues. ALWAYS include a comment explaining WHY the
775 package has been masked and WHO is doing the masking.
779 \- comments begin with # (no inline comments)
780 \- one DEPEND atom per line
785 # masked for security reasons
786 <sys\-libs/zlib\-1.1.4
787 # <caleb@gentoo.org> (10 Sep 2003)
789 =kde\-base/kde\-3.2.0_beta1
790 =kde\-base/kdeaccessibility\-3.2.0_beta1
794 List all the current stable and development profiles. If a profile is listed
795 here, then it will be checked by repoman.
798 \- comments begin with # (no inline comments)
799 \- one profile list per line in format: arch dir status
800 \- arch must be listed in arch.list
801 \- dir is relative to profiles.desc
802 \- status must be 'stable', 'dev', or 'exp'
807 alpha default/linux/alpha/10.0 stable
808 m68k default/linux/m68k/10.0 dev
809 x86 default/linux/x86/10.0 stable
810 x86-linux prefix/linux/x86 exp
814 The first line of the file should define a unique repository name. The name
815 may contain any of the characters [A\-Za\-z0\-9_\-]. It must not begin with a
818 .BR thirdpartymirrors
819 Controls the mapping of mirror:// style URIs to actual lists of
820 mirrors. Keeps us from overloading a single server.
824 \- comments begin with # (no inline comments)
825 \- mirror type followed by a list of hosts
830 sourceforge http://aleron.dl.sourceforge.net/sourceforge http://unc.dl.sourceforge.net/sourceforge
832 gentoo http://distro.ibiblio.org/pub/linux/distributions/gentoo/distfiles/ ftp://ftp.gtlib.cc.gatech.edu/pub/gentoo/distfiles
834 kernel http://www.kernel.org/pub http://www.us.kernel.org/pub
838 All global USE flags must be listed here with a description of what they do.
842 \- comments begin with # (no inline comments)
843 \- use flag \- some description
848 3dfx \- Adds support for 3dfx video cards
849 acl \- Adds support for Access Control Lists
850 doc \- Adds extra documentation
854 All local USE flags are listed here along with the package and a
855 description. This file is automatically generated from the
856 metadata.xml files that are included with each individual package.
857 Refer to GLEP 56 for further information:
858 \fIhttp://www.gentoo.org/proj/en/glep/glep-0056.html\fR.
862 \- comments begin with # (no inline comments)
863 \- package:use flag \- description
866 app\-editors/nano:justify \- Toggles the justify option
867 dev\-libs/DirectFB:fusion \- Adds Multi Application support
868 games\-emulation/xmess:net \- Adds network support
874 This directory is used to store internal portage cache files. The names and
875 purpose of these files are not documented on purpose so as to keep down bitrot
876 as internals change. If you aren't working on portage internally, then the
877 details most likely do not matter to you.
879 This entire directory can be safely deleted. It is highly recommended you do
880 not do this however as it can be a time consuming process to generate them all
886 All installed package information is recorded here. If portage thinks you have
887 a package installed, it is usually because it is listed here.
889 The format follows somewhat closely that of the portage tree. There is a
890 directory for each category and a package-version subdirectory for each package
893 Inside each package directory are misc files that describe the installed
894 contents of the package as well as build time information (so that the package
895 can be unmerged without needing the portage tree).
897 The exact file contents and format are not described here again so that things
898 can be changed quickly. Generally though there is one file per environment
899 variable that "matters" (like CFLAGS) with the contents stored inside of it.
900 Another common file is the CONTENTS file which lists the path and hashes of
901 all objects that the package installed onto your system.
904 .BR /var/lib/portage/
908 Hashes which are used to determine whether files in config protected
909 directories have been modified since being installed. Files which have not
910 been modified will automatically be unmerged.
913 Every time you emerge a package, the package that you requested is
914 recorded here. Then when you run `emerge world \-up`, the list of
915 packages is read from this file. Note that this does not mean that the
916 packages that were installed as dependencies are listed here. For
917 example, if you run `emerge mod_php` and you do not have apache
918 already, then "dev\-php/mod_php" is recorded in the world file but
919 "net\-www/apache" is not. For more information, review \fBemerge\fR(1).
923 \- one DEPEND atom base per line
928 games\-misc/fortune\-mod\-gentoo\-dev
934 This is like the world file but instead of package atoms it contains
935 packages sets which always begin with the @ character.
943 Please report bugs via http://bugs.gentoo.org/
946 Marius Mauch <genone@gentoo.org>
947 Mike Frysinger <vapier@gentoo.org>
948 Drake Wyrm <wyrm@haell.com>