Portage Variables

Introduction

Ebuild developers as well as users of Portage can control Portage behavior using a number of Portage variables. Also, when an ebuild executes, a number of variables are defined by ebuild.sh, the main ebuild script, so they are available for your ebuild. There are also variables that the ebuild writer can define within his or her ebuild to provide information about the ebuild as well as control behavior. Information on Ebuild Functions, which are used to define actions that are performed during various parts of a package's lifecycle, is also available on this wiki.

Note

An ebuild is a textual meta-description of a software package (stored in a filename suffixed by .ebuild and generally located in a subdirectory of /usr/portage) that provides the instructions to build and install the later on your system plus a number of additional informations like a brief summary of the package, the required dependencies to build and run the package, where to get the software package source code and so on. Due to the 1:1 matching between an ebuild file and a software package most of Gentoo and Funtoo developers uses the term ebuild to designate the meta-description of a package and the software package it relates in itself.

Profile Variables

These variables are set in the profile(s) selected on the user's system. These profiles live inside /usr/portage/profiles.

ARCH: ARCH defines the name for the underlying system architecture. As of late December 2010, Gentoo Linux supports defines the following architectures in various system profiles:

alpha amd64 amd64-fbsd arm cobalt fulong-2e hppa hppa-hpux ia64 ia64-hpux ip22 ip27 ip28 ip30 ip32 ip32r10k m68k m68k-mint mips mips-irix mips64 mips64el mipsel ppc ppc-aix ppc-macos ppc-openbsd ppc64 ppc64-macos s390 sgi sh sparc sparc-fbsd sparc-solaris sparc64 sparc64-fbsd sparc64-solaris x64-macos x64-openbsd x64-solaris x86 x86-cygwin x86-fbsd x86-interix x86-macos x86-netbsd x86-openbsd x86-solaris x86-winnt xbox yeeloong

This list was generated using the following command:

root # cd /usr/portage/profiles
root # grep -r ARCH= * | cut -f2 -d"=" | sed -e 's/"//g' | sort -u

Path Variables

PORTDIR: PORTDIR will be set to the path of the Portage directory that contains the ebuild that is currently executing, such as /usr/portage.

PORTAGE_TMPDIR: PORTAGE_TMPDIR defines the path to the location that Portage should use for all its temporary files, and defaults to /var/tmp.

DISTDIR: DISTDIR defines the path to the location of all distfiles (downloaded source code/artifacts), and defaults to /usr/portage/distfiles.

PKGDIR: PKGDIR defines the path to where Portage will store all built binary packages, and defaults to /usr/portage/packages.

RPMDIR: RPMDIR defines the path to where Portage will store all built binary RPM packages, and defaults to /usr/portage/rpm.

ROOT: ROOT defines the root of the filesystem to which packages should be installed, and may be set on the command-line. If not defined, Portage will set ROOT to / by the time your ebuild executes. When writing pkg_* ebuild functions, all your ebuild logic must respect the setting of the ROOT variable and compensate for situations when ROOT is not /. ROOT is used by stage1 builds to install to a sub-directory. ROOT=/tmp/stage1root emerge -e system is a command that might be run by a stage1 build. After src_install executes, Portage will always install the resultant files placed in $D to the filesystem defined by ROOT.

Prefix Variables

Portage supports the ability to act as a package manager for commercial operating systems such as MacOS X, or to install ebuilds on non-Gentoo systems, or to sub-directories on Gentoo or non-Gentoo systems. When used in this capacity, ebuilds are not installed to the root filesystem but are instead installed to a subdirectory, called a "prefix". Portage's prefix variables, available in EAPI 3, support this capability, and are designed to work with ebuilds that are maintained in a separate prefix overlay.

As part of the EAPI 3 prefix support, all ebuild helpers such as econf and einstall use $ED instead of $D. See below for full variable definitions.

EPREFIX: This variable is typically set in /etc/make.conf or make.globals, and defines the prefix that should be used by ebuilds. Prefix-aware ebuilds can reference this variable and use it appropriately. if EPREFIX is not defined, then EPREFIX will default to no value.

EROOT: EROOT is a more concise way of specifying $ROOT$EPREFIX, and is intended to be used in pkg_* ebuild functions.

ED: ED is a more concise way of specifying $D$EPREFIX, and is intended to be used in src_* ebuild functions.

For more information on Portage's prefix support, see the Gentoo Prefix Techdocs.

Path Variables For Your Use

WORKDIR: WORKDIR defines the temporary filesystem location that is used for extracting source code/artifacts, preparation, configuration and compilation, and will be defined for you by the time your ebuild executes, and its value must not be modified. By default, src_unpack will extract all source code/artifacts within WORKDIR. If you need to manually extract any archives, this must all be done somewhere within WORKDIR, T or D, with WORKDIR being the preferred location for doing this. WORKDIR is automatically cleaned up by Portage upon completion.

S: S defaults to $WORKDIR/$P, but may be redefined in your ebuild to be some other sub-directory of WORKDIR. Typically, S may be redefined to reflect the real directory name that is contained within the source tarball when it differs from the default of $WORKDIR/$P. When src_prepare, src_configure, src_compile, src_test and src_install run, they will attempt to set the current working directory to S if it exists, falling back to WORKDIR if S does not exist.

T: A temporary file storage location that is available to you during your ebuild's execution. T is automatically cleaned up by Portage upon completion.

D: D defines the filesystem tree to which the src_install function should install all files. All files defined here will be installed by Portage to the destination defined by ROOT.

FILESDIR: FILESDIR is shorthand for $PORTDIR/$CATEGORY/$PN/files -- the files/ sub-directory in the Portage tree for your particular ebuild. Typically used in src_prepare for applying patches, or by src_install for installing supplementary files such as initialization scripts that were committed to the Portage tree alongside your ebuild.

Metadata Variables

Metadata variables are variables that you set in your ebuild. They are cached by Portage so they can be quickly accessed for dependency resolution and searches -- in /var/cache/edb/dep. When an ebuild is updated, Portage automatically updates the cache the next time it notices the ebuild has changed.

EAPI: Periodically, the Gentoo Linux project defines new functionality and behavior related to how ebuilds are handled by Portage. These changes may require you to write your ebuilds slightly differently, or may allow you to take advantage of new capabilities in Portage. In your ebuild, you can specify the EAPI you are targeted by setting the EAPI variable as the first line in the ebuild. If no EAPI is specified, an EAPI of 0 ("classic" behavior) is assumed. To view a complete definition of EAPIs 1 through 3, please see The Gentoo Developer Guide's EAPI page. Note that the information on EAPI 4 is incomplete, and more detailed information can be found on in-progress EAPI 4 document maintained by Zac Medico. At some point, it may be possible to set an EAPI on a repository or overlay-wide basis, but for now, it is set by each individual ebuild.

DEPEND: DEPEND is used to specify an ebuild's build dependencies, and is a list of all ebuilds (and their corresponding versions/slots) that are required to be installed to a bare stage3 (or @system set + dependencies) in order for this package to build (compile, etc.). If one or more of these ebuilds are not installed, then it must cause the building of this package to fail; otherwise it is not a true build dependency. Do not list any dependencies for packages that are included in the underlying bare stage3 unless specific versions of the core packages (such as gcc, or glibc) are required, since these packages are expected to be available on all systems. All dependencies listed in DEPEND are satisfied prior to this package being built.

RDEPEND: RDEPEND is used to specify an ebuild's runtime dependencies, and is a list of all ebuilds (and their corresponding versions/slots) that are required to be installed to a bare stage3 (or @system set + dependencies) in order for this package to run (function). For our purposes, when runtime dependencies are satisfied, we would expect that package to function fully, for both build needs (linking) and runtime needs (its executables running properly), although the package may not yet be ready to be used interactively by end-users (see PDEPEND, below.)

If one or more of the dependencies listed in RDEPEND are not installed, then this ebuild would not be expected to function; otherwise it is not a true runtime dependency. Do not list any dependencies for packages that are included in the bare stage3 unless specific versions of the core packages (such as glibc) are required, since these packages are expected to be available on all systems. The dependencies listed in RDEPEND may or not be installed prior to this package being built, but you can assume that these packages will be installed to the filesystem prior to this package being installed to the filesystem.

DEPEND and RDEPEND: Note that if a dependency needs to be available both before the package is built, and also after the package is built, then the dependency must be listed in both DEPEND and RDEPEND, as it is both a build and runtime dependency. This is common with many packages, including virtually all shared libraries, which must be installed prior to compilation for headers and linking purposes but must continue to be available after the package is installed so that it can function properly.

(R)DEPEND if installed: It is often useful for an ebuild to conditionally depend on a specific version of another package, if it happens to be installed. Take sys-fs/lvm2 and sys-fs/udev, for example. sys-fs/lvm2 may not always be installed, but sys-fs/udev is a required ebuild. It would be nice if we could specify in the sys-fs/udev ebuild that a specific or higher version of lvm2 is required to work with this particular version of udev, or specify in the lvm2 ebuild that a specific version or higher of udev is required to work with this version of lvm2. While this is not currently possible in Portage, it is possible to use the blocker functionality in Portage to define that earlier versions are not compatible, which essentially accomplishes the same thing. To specify that another package should not be installed alongside your ebuild, use the double-exclamation form of a blocker: "!!<sys-fs/udev-160" might be an example. This will prevent both ebuilds from being installed on the system at the same time. The double-exclamation blocker is supported in EAPI 2 and above.

PDEPEND: PDEPEND is a useful type of dependency and is currently under-utilized. A PDEPEND is a post-merge dependency. Dependencies in PDEPEND will be satisfied after the ebuild in question is merged. PDEPEND dependencies apply to both from-source merges and binary package installs. You can also think of PDEPEND as a parallel dependency, and is useful for breaking circular dependencies by moving RDEPEND dependencies to PDEPEND. For example, consider a situation where gtk+ RDEPENDs on adwaita-icon-theme, because adwaita-icon-theme is the default icon set for gtk+. However, adwaita-icon-theme itself requires gtk+ to be installed in order to build. Upon closer inspection of dependencies, one might also notice that gtk+ does function properly for satisfying build (DEPEND) requirements without adwaita-icon-theme installed, although gtk+ might be considered incomplete from an end-user perspective without adwaita-icon-theme installed before emerge finishes. To properly express this via dependencies, adwaita-icon-theme should be listed as a PDEPEND of gtk+ -- it should be installed alongside (in Parallel with) gtk+, but can be installed later by emerge. You can also think of PDEPEND as a means to link ebuilds together into larger logical units without combining them into a single ebuild. It's a way for an ebuild to say "I need this (and this, and this) before I am truly complete."

Note

PDEPEND is a great tool for breaking circular dependencies, and PDEPEND can be used as necessary to do so. It is not necessary to avoid PDEPEND as indicated in the ebuild man page from Gentoo.

IUSE: IUSE specifies the USE variables that are recognized by this ebuild. Note that changing IUSE in existing ebuilds should be handled carefully, as if another ebuild depends on a particular USE variable in IUSE being enabled in your ebuild, and you remove it, then Portage will not be able to satisfy this dependency. Similarly, if another ebuild depends on a particular USE variable in IUSE being disabled in your ebuild, and you remove it, then Portage will no longer be able to satisfy this dependency either. For this reason, it can become difficult to remove USE variables from IUSE once other ebuilds explicitly depend upon them being enabled or disabled.

SRC_URI: SRC_URI contains a list of all remote files that are used by this ebuild during the unpack/prepare/compile/install phases. Starting with EAPI 2, it is possible to rename source tarballs, which comes in handy when pulling down tagged sources from GitHub, using the following trick. This approach also makes it quite easy to release source tarballs for ebuilds, as all you need to do is tag the release and then push the tags to GitHub with a git push tags command:

GITHUB_USER="foo"
SRC_URI="https://github.com/${GITHUB_USER}/${PN}/tarball/${PV} -> ${PN}-git-${PV}.tgz"

src_prepare() {
  cd "${WORKDIR}"/${GITHUB_USER}-${PN}-*
  S="$(pwd)"
}

KEYWORDS

KEYWORDS is a general keywording system for ebuilds (meta description of a software package), but is now used exclusively by the Gentoo architecture teams to define whether a particular package is marked as belonging to the stable or the current (testing in Gentoo terminology) branch on a given system architecture. Not all packages are tagged as belonging to stable/current on all architectures, some of them lacks of such tags and are considered as being masked on a particular architecture. This can happen for several reasons like:

The package makes no sense for the architecture (e.g. SILO sys-boot/silo which is a boot loader for SPARC machines).
The package points to a development repository (e.g. version numbered -9999 packages like dev-vcs/git-9999)
The package makes sense on a a given architecture but no one has tested it (yet)
The package has been pushed in the portage tree but remains to go in a intensive test cycle before being tagged as current then stable).

In a user's arch profile (see eselect profile list.) ACCEPT_KEYWORDS variable is defined which specifies what specific keywords should be unmasked for this system by default. On Funtoo Linux systems, ACCEPT_KEYWORDS is set to one of six values:

amd64: 64-bit PC-compatible stable tree
~amd64: 64-bit PC-compatible current tree
x86: 32-bit PC-compatible stable tree
~x86: 32-bit PC-compatible current tree
sparc: SPARC stable tree
~sparc: SPARC current tree

An ebuild uses the KEYWORDS variable to control what tree or trees the ebuild is part of, and will contain at most one setting for each system architecture. The KEYWORD settings are defined with the following meaning:

amd64: ebuild unmasked in 64-bit PC-compatible stable and current trees
~amd64: ebuild unmasked in 64-bit PC-compatible current tree only
-amd64: ebuild masked for all 64-bit PC-compatible trees
x86: ebuild unmasked in 32-bit PC-compatible stable and current trees
~x86: ebuild unmasked in 32-bit PC-compatible current tree only
-x86: ebuild masked for all 32-bit PC-compatible trees
sparc: ebuild unmasked in SPARC stable and current trees
~sparc: ebuild unmasked in SPARC current tree only
-sparc: ebuild masked for all sparc trees

Important

x86, amd64 or sparc setting in the ebuild's KEYWORDS will unmask the ebuild for both current and stable tree systems -- that is, any ebuild made available to stable is also made available to current.

Additional wildcard keywords are supported in ebuilds:

*: unmask for all trees. This variable can be modified by appending negative keywords: "* -ia64" means "all keywords except (~)ia64
-*: mask for all trees. This variable can be modified by appending positive keywords: "-* amd64 x86" means "no keywords except for x86 and amd64 stable trees

Gentoo Linux KEYWORDS Policies

Due to the exclusive use of KEYWORDS by the Gentoo Linux architecture teams, a number of unfortunate policy-related checks have been integrated into the Portage source code. One is banning the use of KEYWORDS="*" to enable KEYWORDS for all available architectures, since it is Gentoo Linux policy for each architecture team to independently verify an ebuild one architecture at a time - this rule currently applies to all ebuilds, including architecture-independent ebuilds. This means that virtually all ebuilds originating from Gentoo Linux will specify an exhaustive, explicit list of all architecture trees for which this package has been unmasked, which will look something like this:

KEYWORDS="~alpha ~amd64 ~arm ~hppa ~ia64 ~m68k ~mips ~ppc ~ppc64 ~s390 ~sh ~sparc ~sparc-fbsd ~x86 ~x86-fbsd"

For ebuilds in Funtoo Linux, the * form should be used when possible.

back to Development_Guide