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.

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.
The pkg_* phases are started in a dedicated empty directory, which
keeps tools from interacting with whatever files happen to be in the current
working directory. In EAPI 7, no particular directory is guaranteed for these
phases, so an ebuild must not rely on one.
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.
Phase order on upgrade
When a package is upgraded, downgraded or reinstalled, the phases of the new version and the uninstall phases of the version being replaced are interleaved:
-
pkg_pretend,pkg_setupand thesrc_*phases of the new version, as for a new install -
pkg_preinstof the new version - The new version's files are merged to the live filesystem
-
pkg_prermof the old version - The old version's files are removed, except for those that have been overwritten by the new version
-
pkg_postrmof the old version -
pkg_postinstof the new version
Consequently:
-
The old version's
pkg_prermandpkg_postrmrun after the new version's files are already in place. They must not remove or modify files that the new version may also install. -
The new version's
pkg_postinstruns last, so it sees the final state of the filesystem. Tasks like updating caches or printing upgrade notes belong there.
To tell whether a phase is running during an upgrade, use
REPLACING_VERSIONS in pkg_preinst and pkg_postinst, and
REPLACED_BY_VERSION in pkg_prerm and pkg_postrm. See
Predefined read-only variables.
When a binary package is built without being installed
(MERGE_TYPE=buildonly), pkg_preinst and pkg_postinst are
not called.
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_nofetchdefault_src_unpackdefault_src_preparedefault_src_configuredefault_src_compiledefault_src_testdefault_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.