Ebuild phase functions

When installing packages from source, the phase function call order is pkg_pretend, pkg_setup, src_unpack, src_prepare, src_configure, src_compile, src_test (optional, FEATURES="test"), src_install, pkg_preinst, pkg_postinst. When installing packages from a binary, the phase function call order is pkg_pretend, pkg_setup, pkg_preinst, pkg_postinst. As some phases haven't been introduced from the beginning, you can have a look at EAPI usage and description for an overview, what have been introduced in which EAPI.

Ebuilds should usually define phases in the order they are called, as set out above, for readability.

How the ebuild phase functions are processed

The pkg_pretend function is to be used for performing various early sanity checks, such as ensuring that certain kernel options are enabled. It is important to keep in mind that pkg_pretend runs separately from the rest of the phase function sequence. Consequently, there is no environment saving or propagation to the next phase. Moreover, ebuild dependencies are not guaranteed to be satisfied at this phase.

The pkg_prerm and pkg_postrm functions are called when uninstalling a package. The pkg_config function is used for any special package configuration — it is only run when explicitly requested by the user. The pkg_nofetch function is used when a RESTRICT="fetch" package needs to obtain some SRC_URI components.

Between the transition from pkg_preinst to pkg_postinst, files are copied over to the live filesystem from the sandboxed temporary installation location, and Portage records digests of the files installed.

When testing or debugging, you can instruct Portage to execute a specific phase function of an ebuild by using the ebuild command, see the ebuild(1) manual page for further information.

Downloading a package's source happens before any of these phases, so emerge --fetchonly should perform all the network access you need (unless you're using live ebuilds). Network access outside of this would not be cached locally (e.g. in ${DISTDIR}, see Predefined read-only variables), which makes it hard to have reproducible builds (see Disadvantages of vcs sources). Avoid network access in any phase by using local files, extending SRC_URI (see Ebuild-defined variables), etc.

Default phase functions

The default pkg_nofetch and src_* phase functions are accessible via a function having a name that begins with default_ and ends with the respective phase function name. For example, a call to a function with the name default_src_compile is equivalent to a call to the default src_compile implementation.

The default phase functions are:

  • default_pkg_nofetch
  • default_src_unpack
  • default_src_prepare
  • default_src_configure
  • default_src_compile
  • default_src_test
  • default_src_install

A function named default is redefined for each of the above phases, so that it will call the default_* function corresponding to the current phase. For example, a call to the default function during the src_compile phase is equivalent to a call to the default_src_compile function.