Variables

There are a number of special variables which must be set in ebuilds, and many more which can optionally be specified. There are also some predefined variables which are of use throughout the ebuild.

Predefined Read-Only Variables

The following variables are defined for you. You must not attempt to set them. Developers must not rely on package manager specific values for these variables when writing ebuilds.

Variable	Purpose
`P`	Package name and version (excluding revision, if any), for example `vim-6.3`.
`PN`	Package name, for example `vim`.
`PV`	Package version (excluding revision, if any), for example `6.3`. It should reflect the upstream versioning scheme.
`PR`	Package revision, or `r0` if no revision exists.
`PVR`	Package version and revision (if any), for example `6.3`, `6.3-r1`.
`PF`	Full package name, `${PN}-${PVR}`, for example `vim-6.3-r1`.
`A`	All the source files for the package (excluding those which are not available because of `USE` flags).
`CATEGORY`	Package's category, for example `app-editors`.
`FILESDIR`	Path to the ebuild's `files/` directory, commonly used for small patches and files. For example: `"${PORTDIR}/${CATEGORY}/${PN}/files"`.
`WORKDIR`	Path to the ebuild's root build directory. For example: `"${PORTAGE_BUILDDIR}/work"`.
`T`	Path to a temporary directory which may be used by the ebuild. For example: `"${PORTAGE_BUILDDIR}/temp"`.
`D`	Path to the temporary install directory. For example: `"${PORTAGE_BUILDDIR}/image"`.
`HOME`	Path to a temporary directory for use by any programs invoked by an ebuild that may read or modify the home directory. For example: `"${PORTAGE_BUILDDIR}/homedir"`.
`ROOT`	The absolute path to the root directory into which the package is to be merged. Only allowed in pkg_* phases. See ROOT
`DISTDIR`	Contains the path to the directory where all the files fetched for the package are stored.
`EPREFIX`	The normalised offset-prefix path of an offset installation.
`ED`	Shorthand for `${D%/}${EPREFIX}/`.
`EROOT`	Shorthand for `${ROOT%/}${EPREFIX}/`.

Ebuild-defined Variables

The following variables may or must be defined by every ebuild.

Variable	Purpose
`EAPI`	The EAPI. See EAPI Usage and Description.
`DESCRIPTION`	A short (not more than 80 characters) description of the package's purpose. Mandatory.
`HOMEPAGE`	Package's homepage. Mandatory (except for virtuals). If you are unable to locate an official one, try to provide a link to freshmeat.net or a similar package tracking site. Never refer to a variable name in the string; include only raw text.
`SRC_URI`	A list of source URIs for the package. Can contain `USE`-conditional parts, see SRC_URI.
`LICENSE`	The package's license, corresponding exactly (including case) to a file in `licenses/`. Mandatory (except for virtuals). See LICENSE.
`SLOT`	The package's `SLOT`. Mandatory. See SLOT.
`KEYWORDS`	See KEYWORDS and Keywording.
`IUSE`	A list of all `USE` flags (excluding arch flags, but including `USE_EXPAND` flags) used within the ebuild. See IUSE.
`REQUIRED_USE`	A list of assertions that must be met by the configuration of `USE` flags to be valid for this ebuild. (Requires EAPI>=4.)
`RESTRICT`	A space-delimited list of portage features to restrict. Valid values are `fetch`, `mirror`, `strip`, `test` and `userpriv`. See `man 5 ebuild` for details.
`DEPEND`	A list of the package's build dependencies. See Dependencies.
`RDEPEND`	A list of the package's runtime dependencies. See Dependencies.
`PDEPEND`	A list of packages to be installed (if possible) after the package is merged. Use this only when `RDEPEND` would cause cyclic dependencies. See Dependencies.
`S`	Path to the temporary build directory, used by `src_compile` and `src_install`. Default: `"${WORKDIR}/${P}"`. Ebuilds should not provide a value for this variable if it is the same as the default value.
`PROPERTIES`	A space-delimited list of properties, with conditional syntax support. `interactive` is the only valid value for now.
`DOCS`	An array or space-delimited list of documentation files for the default src_install function to install using dodoc. If undefined, a reasonable default list is used. (Requires EAPI>=4.)

SLOT

When slots are not needed, use SLOT="0". Do not use SLOT="", as this will disable slotting for this package.

See Slotting for more information on this variable.

KEYWORDS

The only valid construct involving a * inside KEYWORDS is a -*. Do not use KEYWORDS="*" or KEYWORDS="~*".

See Keywording for how to handle this variable.

SRC_URI

Conditional Sources

Conditional source files based upon USE flags are allowed using the usual flag? ( ) syntax. This is often useful for arch-specific code or for binary packages — downloading sparc binaries on ppc would be a waste of bandwidth.

SRC_URI="http://example.com/files/${P}-core.tar.bz2
    x86?   ( http://example.com/files/${P}/${P}-sse-asm.tar.bz2 )
    ppc?   ( http://example.com/files/${P}/${P}-vmx-asm.tar.bz2 )
    sparc? ( http://example.com/files/${P}/${P}-vis-asm.tar.bz2 )
    doc?   ( http://example.com/files/${P}/${P}-docs.tar.bz2 )"

If a USE_EXPAND variable is used to control whether certain optional components are installed, the correct thing to do if the variable is unset is generally to install all available components.

SRC_URI="http://example.com/files/${P}-core.tar.bz2
        examplecards_foo?  ( http://example.com/files/${P}-foo.tar.bz2 )
        examplecards_bar?  ( http://example.com/files/${P}-bar.tar.bz2 )
        examplecards_baz?  ( http://example.com/files/${P}-baz.tar.bz2 )
        !examplecards_foo? ( !examplecards_bar? ( !examplecards_baz? (
            http://example.com/files/${P}-foo.tar.bz2
            http://example.com/files/${P}-bar.tar.bz2
            http://example.com/files/${P}-baz.tar.bz2 ) ) )"

Renaming Sources

Sometimes the upstream URI uses generic names that can easily clash with other packages when creating a single mirror. Using the -> syntax allows you to rename the file when it's fetched from upstream for storing on mirrors and in the local distdir.

Here we download a file from upstream which has a plain name like 1.0.tar.gz and save/mirror it with a better name like thepackage-1.0.tar.gz.

SRC_URI="http://example.com/files/${PV}.tar.gz -> ${P}.tar.gz"

IUSE

Note that the IUSE variable is cumulative, so there is no need to specify USE flags used only within inherited eclasses within the ebuild's IUSE.

Note: You need not assign the IUSE variable in your ebuild if it is empty.

Arch USE flags (sparc, mips, x86-fbsd and so on) should not be listed.

LICENSE

It is possible to specify multiple LICENSE entries, and entries which only apply if a particular USE flag is set. The format is the same as for DEPEND. See GLEP 23 for details.

ROOT

The idea behind ROOT is that one can build a system with ROOT=/somewhere and then chroot into it or tar up /somewhere as a system image. It is not designed to allow the user to run /somewhere/usr/bin/foo.

Ebuilds may reference ROOT only during pkg_* phases. It can't be used correctly in src_* phases, since ROOT may be different when merging a binary package. For example, a binary package may be built with ROOT=/ and then installed onto a system using ROOT=/somewhere.

When building a package, ROOT should not be used to satisfy the required dependencies on libraries, headers files etc. Instead, the files on the build system should be specified using /.

In a cross compiling environment, ebuilds must not call any of the binaries inside ROOT since they may not be executable on the build system.

Below is an example of an ebuild that uses ROOT in pkg_postinst() to conditionally print an error message if an old and obsolete configuration file still exists:

pkg_postinst() {
	if [[ -e "${ROOT}etc/oldconfig" ]]; then
		ewarn "You still have the obsolete config file "
		ewarn "    ${ROOT}etc/oldconfig."
		ewarn "Please migrate your settings to ${ROOT}etc/newconfig"
		ewarn "and remove ${ROOT}etc/oldconfig."
	fi
}

Version and Name Formatting Issues

Often upstream's tarball versioning or naming format doesn't quite follow Gentoo conventions. Using capital letters in names or differences in how underscores and hyphens are used in versions are particularly common. For example, what Gentoo calls foo-1.2.3b may be expecting a tarball named Foo-1.2-3b.tar.bz2. Rather than hard coding the package string, it is preferable to make MY_PN, MY_PV and MY_P variables and use those to define the upstream naming. The easy way of redefining the version, which should be used unless you are sure you know what you are doing, is to use the versionator eclass:

inherit versionator
MY_PN="Foo"
MY_PV=$(replace_version_separator 2 '-')
MY_P="${MY_PN}-${MY_PV}"

This code has the advantage that it will carry on working even if upstream switches to a format like Foo-1.3-4.5.tar.bz2 (yes, this really happens).

It is also possible to use bash substitution to achieve the same effect (this is how versionator works internally), but this is complicated, error prone and hard to read.

Some ebuilds use calls to sed, awk and / or cut to do this. This must not be done for any new code, and should be fixed to use either versionator or bash substitution where possible. Global scope non-bash code is highly discouraged.

The versionator eclass can also be used to extract particular components from a version string. See man versionator.eclass and the eclass source code for further documentation and examples. A brief summary of the functions follows.

Function	Purpose
`get_all_version_components`	Split up a version string into its component parts.
`get_version_components`	Get important version components, excluding '.', '-' and '_'.
`get_major_version`	Get the major version.
`get_version_component_range`	Extract a range of subparts from a version string.
`get_after_major_version`	Get everything after the major version.
`replace_version_separator`	Replace a particular version separator.
`replace_all_version_separators`	Replace all version separators.
`delete_version_separator`	Delete a version separator.
`delete_all_version_separators`	Delete all version separators.

Trailing Slashes in Variables

The following variables always end in a trailing slash by default: D, ED, ROOT, EROOT. Therefore, there is no need to suffix them with / when joining paths.

Note: Future EAPI may remove the trailing slash at the end per Bug 465722. To ease the transition, and ensure maximum compatibility with both the current and the future EAPI, developers are encouraged to use the bash suffix removal for the trailing slash and add an explicit / when joining paths. For example: ${D%/}/, ${ED%/}/, ${ROOT%/}/, ${EROOT%/}/.