EBUILD

Section: Portage (5)
Updated: Apr 2023
Index Return to Main Contents

NAME

ebuild - the internal format, variables, and functions in an ebuild script

DESCRIPTION

The ebuild(1) program accepts a single ebuild script as an argument. This script contains variables and commands that specify how to download, unpack, patch, compile, install and merge a particular software package from its original sources. In addition to all of this, the ebuild script can also contain pre/post install/remove commands, as required. All ebuild scripts are written in bash. The minimum version of Bash for an ebuild depends on the EAPI version.

Dependencies

A depend atom is simply a dependency that is used by portage when calculating relationships between packages. Please note that if the atom has not already been emerged, then the latest version available is matched.

Atom Bases

The base atom is just a full category/packagename. Another name for a full category/packagename is a "catpkg". You will find this shorthand-name used frequently in Gentoo. Here are some base atoms, a.k.a "catpkgs":

net-misc/dhcp
sys-apps/sed
sys-libs/zlib

Atom Versions

It is nice to be more specific and say that only certain versions of atoms are acceptable. Note that versions must be combined with a prefix (see below). Hence you may add a version number as a postfix to the base.

Examples:

        sys-apps/sed-4.0.5
        sys-libs/zlib-1.1.4-r1
        net-misc/dhcp-3.0_p2

Versions are normally made up of two or three numbers separated by periods, such as 1.2 or 4.5.2. This string may be followed by a character such as 1.2a or 4.5.2z. Note that this letter is not meant to indicate alpha, beta, etc... status. For that, use the optional suffix; either _alpha, _beta, _pre (pre-release), _rc (release candidate), or _p (patch). This means for the 3rd pre-release of a package, you would use something like 1.2_pre3. The suffixes here can be arbitrarily chained without limitation.

Atom Prefix Operators [> >= = <= <]

Sometimes you want to be able to depend on general versions rather than specifying exact versions all the time. Hence we provide standard boolean operators:

Examples:

        >media-libs/libgd-1.6
        >=media-libs/libgd-1.6
        =media-libs/libgd-1.6
        <=media-libs/libgd-1.6
        <media-libs/libgd-1.6

Extended Atom Prefixes [!ti] and Postfixes [*]

Now to get even fancier, we provide the ability to define blocking packages and version range matching. Also note that these extended prefixes/postfixes may be combined in any way with the atom classes defined above.

ti

means match any revision of the base version specified. So in the example below, we would match versions '1.0.2a', '1.0.2a-r1', '1.0.2a-r2', etc...

Example:

        tinet-libs/libnet-1.0.2a

!

means block packages from being installed at the same time.

Example:

        !app-text/dos2unix

!!

means block packages from being installed at the same time and explicitly disallow them from being temporarily installed simultaneously during a series of upgrades. This syntax is supported beginning with EAPI 2.

Example:

        !!<sys-apps/portage-2.1.4_rc1

*

means match any version of the package so long as the specified base is matched. So with a version of '2*', we can match '2.1', '2.2', '2.2.1', etc... and not match version '1.0', '3.0', '4.1', etc... The version part that comes before the '*' must be a valid version in the absence of the '*'. For example, '2' is a valid version and '2.' is not. Therefore, '2*' is allowed and '2.*' is not.

Examples:

        =dev-libs/glib-2*
        !=net-fs/samba-2*

Atom Slots

Beginning with EAPI 1, any atom can be constrained to match a specific SLOT. This is accomplished by appending a colon followed by a SLOT:

Examples:

        x11-libs/qt:3
        tix11-libs/qt-3.3.8:3
        >=x11-libs/qt-3.3.8:3
        =x11-libs/qt-3.3*:3

Sub Slots

Beginning with EAPI 5, a slot dependency may contain an optional sub-slot part that follows the regular slot and is delimited by a / character.

Examples:

        dev-lang/perl:0/5.12
        dev-libs/icu:0/0
        dev-libs/icu:0/49
        dev-libs/glib:2/2.30

Atom Slot Operators

Beginning with EAPI 5, slot operator dependency consists of a colon followed by one of the following operators:

*

Indicates that any slot value is acceptable. In addition, for runtime dependencies, indicates that the package will not break if the matched package is uninstalled and replaced by a different matching package in a different slot.

Examples:

        dev-lang/perl:*
        dev-libs/glib:*
        dev-libs/icu:*

=

Indicates that any slot value is acceptable. In addition, for runtime dependencies, indicates that the package will break unless a matching package with slot and sub-slot equal to the slot and sub-slot of the best installed version at the time the package was installed is available.

Examples:

        dev-libs/glib:=
        dev-lang/perl:=
        dev-libs/icu:=

slot=

Indicates that only a specific slot value is acceptable, and otherwise behaves identically to the plain equals slot operator.

Examples:

        dev-lang/perl:0=
        dev-libs/glib:2=
        dev-libs/icu:0=

To implement the equals slot operator, the package manager will need to store the slot/sub-slot pair of the best installed version of the matching package. This syntax is only for package manager use and must not be used by ebuilds. The package manager may do this by inserting the appropriate slot/sub-slot pair between the colon and equals sign when saving the package's dependencies. The sub-slot part must not be omitted here (when the SLOT variable omits the sub-slot part, the package is considered to have an implicit sub-slot which is equal to the regular slot).

Examples:

        dev-lang/perl:0/5.12=
        dev-libs/glib:2/2.30=
        dev-libs/icu:0/0=
        dev-libs/icu:0/49=

Atom USE

Beginning with EAPI 2, any atom can be constrained to match specific USE flag settings. When used together with SLOT dependencies, USE dependencies appear on the right hand side of SLOT dependencies.

Unconditional USE Dependencies

Example	Meaning

foo[bar,baz]	foo must have both bar and baz enabled
foo[-bar,baz]	foo must have bar disabled and baz enabled

Conditional USE Dependencies

Compact Form	Equivalent Expanded Form

foo[!bar?]	bar? ( foo ) !bar? ( foo[-bar] )
foo[bar=]	bar? ( foo[bar] ) !bar? ( foo[-bar] )
foo[!bar=]	bar? ( foo[-bar] ) !bar? ( foo[bar] )

Atom USE defaults

Beginning with EAPI 4, USE dependencies may specify default assumptions about values for flags that may or may not be missing from the IUSE of the matched package. Such defaults are specified by immediately following a flag with either (+) or (-). Use (+) to behave as if a missing flag is present and enabled, or (-) to behave as if it is present and disabled:

Examples:

        media-video/ffmpeg[threads(+)]
        media-video/ffmpeg[-threads(-)]

Dynamic Dependencies

Sometimes programs may depend on different things depending on the USE variable. Portage offers a few options to handle this. Note that when using the following syntaxes, each case is considered as 1 Atom in the scope it appears. That means that each Atom both conditionally include multiple Atoms and be nested to an infinite depth.

usevar? ( Atom )

To include the jpeg library when the user has jpeg in USE, simply use the following syntax:

jpeg? ( media-libs/libjpeg-turbo )

!usevar? ( Atom )

If you want to include a package only if the user does not have a certain option in their USE variable, then use the following syntax:

!nophysfs? ( dev-games/physfs )

This is often useful for those times when you want to want to add optional support for a feature and have it enabled by default.

usevar? ( Atom if true ) !usevar? ( Atom if false )

For functionality like the tertiary operator found in C you must use two statements, one normal and one inverted. If a package uses GTK3 or GTK2, but not both, then you can handle that like this:

gtk3? ( =x11-libs/gtk+-3* ) !gtk3? ( =x11-libs/gtk+-2* )

That way the default is the superior GTK3 library.

|| ( Atom Atom ... )

When a package can work with a few different packages but a virtual is not appropriate, this syntax can easily be used.

Example:

|| (
        app-games/unreal-tournament
        app-games/unreal-tournament-goty
)

Here we see that unreal-tournament has a normal version and it has a goty version. Since they provide the same base set of files, another package can use either. Adding a virtual is inappropriate due to the small scope of it.

Another good example is when a package can be built with multiple video interfaces, but it can only ever have just one.

Example:

|| (
        sdl? ( media-libs/libsdl )
        svga? ( media-libs/svgalib )
        opengl? ( virtual/opengl )
        ggi? ( media-libs/libggi )
        virtual/x11
)

Here only one of the packages will be chosen, and the order of preference is determined by the order in which they appear. So sdl has the best chance of being chosen, followed by svga, then opengl, then ggi, with a default of X if the user does not specify any of the previous choices.

Note that if any of the packages listed are already merged, the package manager will use that to consider the dependency satisfied.

Variable Usage Notes

*: Variables defined in make.conf(5) are available for use in ebuilds (except Portage-specific variables, which might be not supported by other package managers).
*: When assigning values to variables in ebuilds, you cannot have a space between the variable name and the equal sign.
*: Variable values should only contain characters that are members of the ascii(7) character set. This requirement is mandated by GLEP 31.

Variables Used In Ebuilds

ARCH

This variable contains the official Gentoo-specific acronym for the current architecture of the running system. For an authoritative list please review /var/db/repos/gentoo/profiles/arch.list.

P

This variable contains the package name without the ebuild revision. This variable must NEVER be modified.

Example:

        x11-base/xorg-server-1.20.5-r2 --> 'xorg-server-1.20.5'

PN

Contains the name of the script without the version number.

Example:

        x11-base/xorg-server-1.20.5-r2 --> 'xorg-server'

PV

Contains the version number without the revision.

Example:

        x11-base/xorg-server-1.20.5-r2 --> '1.20.5'

PR

Contains the revision number or 'r0' if no revision number exists.

Example:

        x11-base/xorg-server-1.20.5-r2 --> 'r2'

PVR

Contains the version number with the revision (if any).

Example:

        x11-base/xorg-server-1.20.5 --> '1.20.5'
        x11-base/xorg-server-1.20.5-r2 --> '1.20.5-r2'

PF

Contains the full package name PN-PVR

Examples:

        x11-base/xorg-server-1.20.5 --> 'xorg-server-1.20.5'
        x11-base/xorg-server-1.20.5-r2 --> 'xorg-server-1.20.5-r2'

CATEGORY

Contains the package category name.

Example:

        x11-base/xorg-server-1.20.5-r2 --> 'x11-base'

A

Contains all source files required for the package. This variable must not be defined. It is autogenerated from the SRC_URI variable.

WORKDIR = ${PORTAGE_TMPDIR}/portage/${CATEGORY}/${PF}/work

Contains the path to the package build root. Do not modify this variable.

FILESDIR = ${PORTAGE_TMPDIR}/${CATEGORY}/${PF}/files

Contains the path to the directory in which package-specific auxiliary files are located. Do not modify this variable.

EBUILD_PHASE

Contains the abbreviated name of the phase function that is currently executing, such as "setup", "unpack", "compile", or "preinst".

EBUILD_PHASE_FUNC

Beginning with EAPI 5, contains the full name of the phase function that is currently executing, such as "pkg_setup", "src_unpack", "src_compile", or "pkg_preinst".

EPREFIX

Beginning with EAPI 3, contains the offset that this Portage was configured for during installation. The offset is sometimes necessary in an ebuild or eclass, and is available in such cases as ${EPREFIX}. EPREFIX does not contain a trailing slash, therefore an absent offset is represented by the empty string. Do not modify this variable.

S = ${WORKDIR}/${P}

Contains the path to the temporary build directory. This variable is used by the functions src_compile and src_install. Both are executed with S as the current directory. This variable may be modified to match the extraction directory of a tarball for the package.

T = ${PORTAGE_TMPDIR}/portage/${CATEGORY}/${PF}/temp

Contains the path to a temporary directory. You may use this for whatever you like.

D = ${PORTAGE_TMPDIR}/portage/${CATEGORY}/${PF}/image/

Contains the path to the temporary install directory. Every write operation that does not involve the helper tools and functions (found below) should be prefixed with ${D}. Beginning with EAPI 3, the offset prefix often needs to be taken into account here, for which the variable ${ED} is provided (see below). Note that with EAPI 7, any trailing slash contained in this path will be automatically removed for ease of concatenating paths within ebuilds. Do not modify this variable.

ED = ${PORTAGE_TMPDIR}/portage/${CATEGORY}/${PF}/image/${EPREFIX}/

Beginning with EAPI 3, contains the path "${D%/}${EPREFIX}/" for convenience purposes. For EAPI values prior to EAPI 3 which do not support ED, helpers use D where they would otherwise use ED. Note that with EAPI 7, any trailing slash contained in this path will be automatically removed for ease of concatenating paths within ebuilds. Do not modify this variable.

MERGE_TYPE

Beginning with EAPI 4, the MERGE_TYPE variable can be used to query the current merge type. This variable will contain one of the following possible values:

Value	Meaning

buildonly	source-build which is not scheduled for merge
source	source-build which is scheduled for merge

PROVIDES_EXCLUDE = [space delimited list of fnmatch patterns]

Sonames and file paths matched by these fnmatch patterns will be excluded during generation of PROVIDES metadata (see portage(5)). Patterns are delimited by whitespace, and it is possible to create patterns containing quoted whitespace.

PORTAGE_LOG_FILE

Contains the path of the build log. If PORTAGE_LOGDIR variable is unset then PORTAGE_LOG_FILE="${T}/build.log".

PORTAGE_SOCKS5_PROXY

Contains the UNIX socket path to SOCKSv5 proxy providing host network access. Available only when running inside network-sandbox and a proxy is available (see network-sandbox in make.conf(5)).

REPLACED_BY_VERSION

Beginning with EAPI 4, the REPLACED_BY_VERSION variable can be used in pkg_prerm and pkg_postrm to query the package version that is replacing the current package. If there is no replacement package, the variable will be empty, otherwise it will contain a single version number.

REPLACING_VERSIONS

Beginning with EAPI 4, the REPLACING_VERSIONS variable can be used in pkg_pretend, pkg_setup, pkg_preinst and pkg_postinst to query the package version(s) that the current package is replacing. If there are no packages to replace, the variable will be empty, otherwise it will contain a space-separated list of version numbers corresponding to the package version(s) being replaced. Typically, this variable will not contain more than one version, but according to PMS it can contain more.

REQUIRES_EXCLUDE = [space delimited list of fnmatch patterns]

Sonames and file paths matched by these fnmatch patterns will be excluded during generation of REQUIRES metadata (see portage(5)). Patterns are delimited by whitespace, and it is possible to create patterns containing quoted whitespace.

ROOT = /

Please note an important recent change regarding the ROOT variable -- in EAPI 7 ebuilds, this variable will default to "" rather than the traditional "/" within ebuilds when pointing to the root filesystem, and when set to a non-root path this variable will never contain a trailing slash. This has the added convenience of eliminating the need to specify "${ROOT%/}" when concatenating paths, making the use of ROOT more elegant. This applies to the variables EROOT, D and ED as well. Please make note that this will mean that ebuilds must use different logic in conditionals to determine if they are installing to the root filesystem -- use [[ "$ROOT" == "" ]] instead of [[ "$ROOT" == "/" ]].

Contains the path that portage should use as the root of the live filesystem. When packages wish to make changes to the live filesystem, they should do so in the tree prefixed by ${ROOT}. Often the offset prefix needs to be taken into account here, for which the variable ${EROOT} is provided (see below). Do not modify this variable.

EROOT = ${ROOT%/}${EPREFIX}/

Beginning with EAPI 3, contains "${ROOT%/}${EPREFIX}/" for convenience purposes. Do not modify this variable. Also see the important note regarding ROOT with EAPI 7, above. As with ROOT, EROOT will be defined as "" when set to the root filesystem and never have a trailing slash within an ebuild.

BROOT = ${EPREFIX}

Beginning with EAPI 7, the absolute path to the root directory containing build dependencies satisfied by BDEPEND, typically executable build tools. This includes any applicable offset prefix. Do not modify this variable.

DESCRIPTION = A happy little package

Should contain a short description of the package.

EAPI = 0

Defines the ebuild API version to which this package conforms. If not defined then it defaults to "0". If portage does not recognize the EAPI value then it will mask the package and refuse to perform any operations with it since this means that a newer version of portage needs to be installed first. For maximum backward compatibility, a package should conform to the lowest possible EAPI. Note that anyone who uses the ebuild(1) command with this package will be required to have a version of portage that recognizes the EAPI to which this package conforms.

SRC_URI = https://example.com/path/${P}.tar.gz

Contains a list of URIs for the required source files. It can contain multiple URIs for a single source file. The list is processed in order if the file was not found on any of the GENTOO_MIRRORS. Beginning with EAPI 2, the output file name of a given URI may be customized with a "->" operator on the right hand side, followed by the desired output file name. All tokens, including the operator and output file name, should be separated by whitespace.

HOMEPAGE = https://example.com/

Should contain a list of URIs for the sources main sites and other further package dependent information.

KEYWORDS = [-ti][x86,ppc,sparc,mips,alpha,arm,hppa,...]

KEYWORDS works in conjunction with ACCEPT_KEYWORDS (see make.conf(5)) to implement a system of creating sets of different types of packages which can then be masked or unmasked en masse. In the Gentoo Linux project, they are used by the Gentoo arch teams to define what ebuilds are included in a particular CPU architecture's set of stable and unstable unmasked packages.

Here's how they work. For purposes of explanation, let's assume you have a stable x86-64bit system, typically referred to as "amd64". ARCH would be defined as "amd64". If you were using the stable build of Gentoo Linux, then ACCEPT_KEYWORDS would be set to "amd64" via profiles. Any ebuild that then has "amd64" in KEYWORDS will be unmasked by default.

On an "unstable" amd64 system, ACCEPT_KEYWORDS will be set to "amd64 tiamd64", with the tilde denoting "unstable." Then, if an ebuild has either "amd64" or "tiamd64" in KEYWORDS, it will be keyword unmasked by default on that system. Similarly, if an ebuild is known to not be compatible with a particular architecture, the "-" prefix ( i.e. "-amd64") setting can be specified to mask it only on that arch. If you are developing ebuilds for Gentoo Linux, there are certain policies regarding KEYWORDS that you are expected to follow in order to align with Gentoo's arch team workflow. The most important policies are listed below:

*: If you do not know if an ebuild runs under a particular arch, then do not specify it in KEYWORDS. It will then be masked by default on that architecture.
*: If the ebuild is known not to work on an arch, disable that arch in KEYWORDS. This would be done by specifying "-ppc", for example. This will ensure that it is explicitly keyword-masked for that architecture.
*: When submitting an ebuild to Gentoo Linux, it is the project policy to only have "tiarch" set in KEYWORDS for the architecture for which it has been successfully tested, and no more. As the ebuild receives more testing, Gentoo arch teams will gradually expand the KEYWORDS settings to "bump" the package to unstable, and possibly stable.
It is possible to customize the behavior of ACCEPT_KEYWORDS and KEYWORDS on a per-package basis using package.accept_keywords and package.keywords files in profiles. See portage(5) for more information on using these files.

Note that while other Gentoo-based projects have KEYWORDS and ACCEPT_KEYWORDS, they likely will not have exactly the same policies regarding their use. Therefore, it is necessary that you research their specific policies and how they differ from Gentoo.

SLOT

This sets the SLOT for packages that may need to have multiple versions co-exist. By default you should set SLOT="0". If you are unsure, then do not fiddle with this until you seek some guidance from some guru. This value should NEVER be left undefined.

Beginning with EAPI 5, the SLOT variable may contain an optional sub-slot part that follows the regular slot and is delimited by a / character. The sub-slot must be a valid slot name. The sub-slot is used to represent cases in which an upgrade to a new version of a package with a different sub-slot may require dependent packages to be rebuilt. When the sub-slot part is omitted from the SLOT definition, the package is considered to have an implicit sub-slot which is equal to the regular slot. Refer to the Atom Slot Operators section for more information about sub-slot usage.

LICENSE

This should be a space delimited list of licenses that the package falls under. This _must_ be set to a matching license in /var/db/repos/gentoo/licenses/. If the license does not exist in the repository yet, you must add it first.

IUSE

This should be a list of any and all USE flags that are leveraged within your build script. The only USE flags that should not be listed here are arch related flags (see KEYWORDS). Beginning with EAPI 1, it is possible to prefix flags with + or - in order to create default settings that respectively enable or disable the corresponding USE flags. For details about USE flag stacking order, refer to the USE_ORDER variable in make.conf(5). Given the default USE_ORDER setting, negative IUSE default settings are effective only for negation of repo-level USE settings, since profile and user configuration settings override them.

DEPEND

This should contain a list of all packages that are required for the program to compile (aka buildtime dependencies). These are usually libraries and headers.

Starting from EAPI 7, tools should go into the BDEPEND variable instead, as DEPEND will only be installed into the system being built and hence cannot be executed when cross-compiling.