Chapter 6. Ebuild

Table of Contents

Ebuild Phases
Interaction with previous installed version
Upgrade/downgrade order used by versions less than 2.1.5 (deprecated)
Upgrade/downgrade order starting with version 2.1.5
Helper Functions
Output
ebegin
eend
einfo
elog
eqawarn
ewarn
EAPI
EAPI 0
Phases
Default src_compile Phase Function
EAPI 1
IUSE defaults
Phases
Default src_compile Phase Function
SLOT Dependencies
EAPI 2
Helpers
doman
Recognition of Language Codes in File Names
Metadata
Dependencies
Blocker Atoms
New Meaning for Old Syntax
New !!atom Syntax
USE Dependencies
Unconditional USE Dependencies
Conditional USE Dependencies
SRC_URI
Customization of Output File Names
Phases
New src_prepare Phase Function
New src_configure Phase Function
Execution Order of Phase Functions
Default Phase Functions
Default Phase Function Alias
EAPI 3
Helpers
unpack
Support for the xz file extension
Support for installation prefix
Helpers
econf
einstall
Variables
EAPI 4
Helpers
Removed dohard and dosed
All helpers die on failure
Controllable Compression
docompress helper
dodoc -r
doins and newins preserve symlinks
doman -i18n option takes precedence over filename language suffix
econf adds --disable-dependency-tracking
use_with and use_enable support empty third argument
Metadata
Dependencies
unset RDEPEND no longer triggers implicit setting
USE Dependency Defaults
REQUIRED_USE
Motivation
Specification
Phases
New pkg_pretend Phase Function
Default src_install no longer a no-op
S to WORKDIR fallback restricted
Variables
AA and KV variables are no longer exported
MERGE_TYPE
REPLACING_VERSIONS and REPLACED_BY_VERSION
EAPI 4-python
Helpers
Extended default list of extensions in dohtml
Helpers Banned in Global Scope
Metadata
Support for Period Characters in Package Names
Support for Period Characters in USE Flags
Repository Dependencies
globstar shell option enabled by default
Variables
REPOSITORY Variable
Extended Repository-Level Configuration
Directories Allowed for Profile-Level and Repository-Level Configuration
USE Flag Aliases
EAPI 4-slot-abi
Metadata
SLOT Supports Optional "sub-slot" ABI part
Dependency Atom slot/sub-slot := Operator
Dependency Atom slot/sub-slot :* Operator
EAPI 5
Metadata
REQUIRED_USE supports new at-most-one-of operator
SLOT supports optional "sub-slot" part
Dependency atom slot operators
Profiles
Profile IUSE Injection
Profile stable USE forcing and masking
Helpers
econf adds --disable-silent-rules
new* commands can read from standard input
New option --host-root for {has,best}_version
New doheader helper function
New usex helper function
Phases
src_test supports parallel tests
Ebuild Environment Variables
New EBUILD_PHASE_FUNC variable
EAPI 5-progress
Helpers
master_repositories
repository_path
available_eclasses
eclass_path
license_path
package_manager_build_user
package_manager_build_group
Extended default list of extensions in dohtml
Case-insensitive matching of extensions in unpack
Helpers Banned in Global Scope
Metadata
Support for Period Characters in Package Names
Support for Period Characters in USE Flags
Repository Dependencies
Automatic Unpack Dependencies
globstar shell option enabled by default
Variables
REPOSITORY Variable
Extended Repository-Level Configuration
Directories Allowed for Profile-Level and Repository-Level Configuration
USE Flag Aliases
EAPI 5-hdepend
Metadata
Dependencies
HDEPEND
Special "targetroot" USE flag

Ebuild Phases

Ebuild execution is divided into a series of phases. In order to implement a phase, an ebuild defines a function to serve as an entry point for execution of that phase. This design is similar to the template method pattern that is commonly used in object oriented programming languages. An ebuild can inherit or override a template method from an eclass.

The function names for the ebuild phases, listed in order of execution:

  • pkg_pretend

  • pkg_setup

  • src_unpack

  • src_prepare

  • src_configure

  • src_compile

  • src_test

  • src_install

  • pkg_preinst

  • pkg_postinst

  • pkg_prerm

  • pkg_postrm

Interaction with previous installed version

The order for upgrade and downgrade operations changed in version 2.1.5, but the order for reinstall operations remained unchanged.

Upgrade/downgrade order used by versions less than 2.1.5 (deprecated)

  • pkg_preinst

  • pkg_postinst

  • pkg_prerm

  • pkg_postrm

Upgrade/downgrade order starting with version 2.1.5

The new order for upgrades and downgrades is identical to the order used for reinstall operations:

  • pkg_preinst

  • pkg_prerm

  • pkg_postrm

  • pkg_postinst

Now that pkg_postinst is called after all other phases, it's not possible to call has_version in pkg_postinst to detect whether the current install operation is an upgrade or downgrade. If this information is needed during the pkg_postinst phase, do the has_version call in an earlier phase (such as pkg_preinst) and store the result in a global variable to be accessed by pkg_postinst when it is called.