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.

PPackage name and version (excluding revision, if any), for example vim-6.3.PNPackage name, for example vim.PVPackage version (excluding revision, if any), for example 6.3.PRPackage revision, or r0 if no revision exists.PVRPackage version and revision (if any), for example 6.3, 6.3-r1.PFFull 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). CATEGORYPackage's category, for example app-editors.FILESDIR Path to the ebuild's files/ directory, commonly used for small patches and files. Value: "${PORTDIR}/${CATEGORY}/${PN}/files". WORKDIR Path to the ebuild's root build directory. Value: "${PORTAGE_BUILDDIR}/work". T Path to a temporary directory which may be used by the ebuild. Value: "${PORTAGE_BUILDDIR}/temp". D Path to the temporary install directory. Value: "${PORTAGE_BUILDDIR}/image". ROOT Path to the root directory. When not using ${D}, always prepend ${ROOT} to the path. DISTDIR Contains the path to the directory where all the files fetched for the package are stored.
Variable Purpose
Required Variables

The following variables must be defined by every ebuild.

DESCRIPTION A short (less than 80 characters) description of the package's purpose. SRC_URI A list of source URIs for the package. Can contain USE-conditional parts, see . HOMEPAGE Package's homepage. 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. KEYWORDS See and . SLOT The package's SLOT. See . LICENSE The package's license, corresponding exactly (including case) to a file in licenses/. See . IUSE A list of all USE flags (excluding arch flags, but including USE_EXPAND flags) used within the ebuild. See .
Variable Purpose
Optional Variables

Specifying the following variables is optional:

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. DEPEND A list of the package's build dependencies. See . RDEPEND A list of the package's runtime dependencies. See . PDEPEND A list of packages to be installed after the package is merged. Should only be used where RDEPEND is not possible. See . 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. PROVIDE Any virtuals provided by this package, for example "virtual/editor virtual/emacs".
Variable Purpose
SLOT

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

See for more information on this variable.

KEYWORDS

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

See 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 ) ) )"
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. Also note that it's really really broken in portage versions before 2.0.51.

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.

Version Formatting Issues

Often upstream's tarball versioning format doesn't quite follow Gentoo conventions. Differences in how underscores and hyphens are used 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 version numbers, it is preferable to make a MY_PV variable and use that. The easy way to do this, which should be used unless you are sure you know what you are doing, is to use the versionator eclass:

inherit versionator MY_PV=$(replace_version_separator 2 '-')

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.

get_all_version_componentsSplit up a version string into its component parts.get_version_componentsGet important version components, excluding '.', '-' and '_'.get_major_versionGet the major version.get_version_component_rangeExtract a range of subparts from a version string.get_after_major_versionGet everything after the major version.replace_version_separatorReplace a particular version separator.replace_all_version_separatorsReplace all version separators.delete_version_separatorDelete a version separator.delete_all_version_separatorsDelete all version separators.
Function Purpose