\chapter{Ebuild-defined Functions}
\label{ch:ebuild-functions}

\section{List of Functions}

The following is a list of functions that an ebuild, or eclass, may define, and which will be called
by the package manager as part of the build and/or install process. In all cases the package manager
must provide a default implementation of these functions; unless otherwise stated this must be a
no-op. All functions may assume that they have read access to all system libraries, binaries and
configuration files that are accessible to normal users, as well as write access to the temporary
directories specified by the \t{T}, \t{TMPDIR} and \t{HOME} environment variables
(see section~\ref{sec:ebuild-env-vars}). Most functions must assume only that they have additional
write access to the package's working directory (the \t{WORKDIR} environment variable); exceptions
are noted below.

The environment for functions run outside of the build sequence (that is, \t{pkg_config},
\t{pkg_info}, \t{pkg_prerm} and \t{pkg_postrm}) must be the environment used for the build of the
package, not the current configuration.

Ebuilds must not call nor assume the existence of any phase functions.

\subsection{Initial working directories}
\label{sec:s-to-workdir-fallback}

\featurelabel{phase-function-dir} Some functions may assume that their initial working directory is
set to a particular location; these are noted below. If no initial working directory is mandated,
then for EAPIs listed in table~\ref{tab:function-dirs} as having an empty directory, it must be set
to a dedicated directory that is empty at the start of the function and may be read-only. For other
EAPIs, it may be set to anything. The ebuild must not rely upon a particular location for it.
The ebuild \emph{may} assume that the initial working directory for any phase is a trusted location
that may only be written to by a privileged user and group.

\featurelabel{s-workdir-fallback} Some functions are described as having an initial working
directory of \t{S} with an error or fallback to \t{WORKDIR}\@. For EAPIs listed in
table~\ref{tab:s-fallback-table} as having the fallback, this means that if \t{S} is not a directory
before the start of the phase function, the initial working directory shall be \t{WORKDIR} instead.
For EAPIs where it is a conditional error, if \t{S} is not a directory before the start of the phase
function, it is a fatal error, unless all of the following conditions are true, in which case the
fallback to \t{WORKDIR} is used:

\begin{compactitem}
\item The \t{A} variable contains no items.
\item The phase function in question is not in \t{DEFINED_PHASES}.
\item None of the phase functions \t{unpack}, \t{prepare}, \t{configure}, \t{compile}, \t{test} or
    \t{install}, if supported by the EAPI in question and occurring prior to the phase about to be
    executed, are in \t{DEFINED_PHASES}.
\end{compactitem}

\ChangeWhenAddingAnEAPI{8}
\begin{centertable}{Initial working directory in \t{pkg_*} phase functions for EAPIs}
    \label{tab:function-dirs}
    \begin{tabular}{ll}
      \toprule
      \multicolumn{1}{c}{\textbf{EAPI}} &
      \multicolumn{1}{c}{\textbf{Initial working directory?}} \\
      \midrule
      0, 1, 2, 3, 4, 5, 6, 7  & Any   \\
      8                       & Empty \\
      \bottomrule
    \end{tabular}
\end{centertable}

\ChangeWhenAddingAnEAPI{8}
\begin{centertable}{EAPIs with \t{S} to \t{WORKDIR} fallbacks}
    \label{tab:s-fallback-table}
    \begin{tabular}{ll}
      \toprule
      \multicolumn{1}{c}{\textbf{EAPI}} &
      \multicolumn{1}{c}{\textbf{Fallback to \t{WORKDIR} permitted?}} \\
      \midrule
      0, 1, 2, 3        & Always            \\
      4, 5, 6, 7, 8     & Conditional error \\
      \bottomrule
    \end{tabular}
\end{centertable}

\subsection{pkg_pretend}

\featurelabel{pkg-pretend} The \t{pkg_pretend} function is only called for EAPIs listed in
table~\ref{tab:pkg-pretend-table} as supporting it.

The \t{pkg_pretend} function may be used to carry out sanity checks early on in the install
process. For example, if an ebuild requires a particular kernel configuration, it may perform that
check in \t{pkg_pretend} and call \t{eerror} and then \t{die} with appropriate messages if the
requirement is not met.

\t{pkg_pretend} is run separately from the main phase function sequence, and does not participate
in any kind of environment saving. There is no guarantee that any of an ebuild's dependencies will
be met at this stage, and no guarantee that the system state will not have changed substantially
before the next phase is executed.

\t{pkg_pretend} must not write to the filesystem.

\ChangeWhenAddingAnEAPI{8}
\begin{centertable}{EAPIs supporting \t{pkg_pretend}}
    \label{tab:pkg-pretend-table}
    \begin{tabular}{ll}
      \toprule
      \multicolumn{1}{c}{\textbf{EAPI}} &
      \multicolumn{1}{c}{\textbf{Supports \t{pkg_pretend}?}} \\
      \midrule
      0, 1, 2, 3        & No  \\
      4, 5, 6, 7, 8     & Yes \\
      \bottomrule
    \end{tabular}
\end{centertable}

\subsection{pkg_setup}

The \t{pkg_setup} function sets up the ebuild's environment for all following functions, before
the build process starts. Further, it checks whether any necessary prerequisites not covered
by the package manager, e.\,g.\ that certain kernel configuration options are fulfilled.

\t{pkg_setup} must be run with full filesystem permissions, including the ability to add new users
and/or groups to the system.

\subsection{src_unpack}

The \t{src_unpack} function extracts all of the package's sources. In EAPIs lacking
\t{src_prepare}, it may also apply patches and set up the package's build system for further use.

The initial working directory must be \t{WORKDIR}, and the default implementation used when
the ebuild lacks the \t{src_unpack} function shall behave as in listing~\ref{lst:src-unpack-0}.

\begin{listing}[H]
\caption{\t{src_unpack}} \label{lst:src-unpack-0}
\begin{verbatim}
src_unpack() {
    if [[ -n ${A} ]]; then
        unpack ${A}
    fi
}
\end{verbatim}
\end{listing}

\subsection{src_prepare}

\featurelabel{src-prepare} The \t{src_prepare} function is only called for EAPIs listed in
table~\ref{tab:src-prepare-table} as supporting it. The \t{src_prepare} function can be used for
post-unpack source preparation.

The initial working directory is \t{S}, with an error or fallback to \t{WORKDIR} as discussed in
section~\ref{sec:s-to-workdir-fallback}.

For EAPIs listed in table~\ref{tab:src-prepare-table} as using format 6 or~8, the default
implementation used when the ebuild lacks the \t{src_prepare} function shall behave as in
listing~\ref{lst:src-prepare-6} or listing~\ref{lst:src-prepare-8}, respectively.

For other EAPIs supporting \t{src_prepare}, the default implementation used when the ebuild lacks
the \t{src_prepare} function is a no-op.

\ChangeWhenAddingAnEAPI{8}
\begin{centertable}{\t{src_prepare} support and behaviour for EAPIs}
    \label{tab:src-prepare-table}
    \begin{tabular}{lll}
      \toprule
      \multicolumn{1}{c}{\textbf{EAPI}} &
      \multicolumn{1}{c}{\textbf{Supports \t{src_prepare}?}} &
      \multicolumn{1}{c}{\textbf{Format}} \\
      \midrule
      0, 1              & No  & Not applicable \\
      2, 3, 4, 5        & Yes & no-op          \\
      6, 7              & Yes & 6              \\
      8                 & Yes & 8              \\
      \bottomrule
    \end{tabular}
\end{centertable}

\begin{listing}[H]
\caption{\t{src_prepare}, format~6} \label{lst:src-prepare-6}
\begin{verbatim}
src_prepare() {
    if [[ $(declare -p PATCHES 2>/dev/null) == "declare -a"* ]]; then
        [[ -n ${PATCHES[@]} ]] && eapply "${PATCHES[@]}"
    else
        [[ -n ${PATCHES} ]] && eapply ${PATCHES}
    fi
    eapply_user
}
\end{verbatim}
\end{listing}

\begin{listing}[H]
\caption{\t{src_prepare}, format~8} \label{lst:src-prepare-8}
\begin{verbatim}
src_prepare() {
    if [[ ${PATCHES@a} == *a* ]]; then
        [[ -n ${PATCHES[@]} ]] && eapply -- "${PATCHES[@]}"
    else
        [[ -n ${PATCHES} ]] && eapply -- ${PATCHES}
    fi
    eapply_user
}
\end{verbatim}
\end{listing}

\subsection{src_configure}

\featurelabel{src-configure} The \t{src_configure} function is only called for EAPIs listed in
table~\ref{tab:src-configure-table} as supporting it.

The initial working directory is \t{S}, with an error or fallback to \t{WORKDIR} as discussed in
section~\ref{sec:s-to-workdir-fallback}.

The \t{src_configure} function configures the package's build environment. The default
implementation used when the ebuild lacks the \t{src_configure} function shall behave as in
listing~\ref{lst:src-configure-2}.

\ChangeWhenAddingAnEAPI{8}
\begin{centertable}{EAPIs supporting \t{src_configure}}
    \label{tab:src-configure-table}
    \begin{tabular}{ll}
      \toprule
      \multicolumn{1}{c}{\textbf{EAPI}} &
      \multicolumn{1}{c}{\textbf{Supports \t{src_configure}?}} \\
      \midrule
      0, 1                & No  \\
      2, 3, 4, 5, 6, 7, 8 & Yes \\
      \bottomrule
    \end{tabular}
\end{centertable}

\begin{listing}[H]
\caption{\t{src_configure}} \label{lst:src-configure-2}
\begin{verbatim}
src_configure() {
    if [[ -x ${ECONF_SOURCE:-.}/configure ]]; then
        econf
    fi
}
\end{verbatim}
\end{listing}

\subsection{src_compile}

\featurelabel{src-compile} The \t{src_compile} function configures the package's build environment
in EAPIs lacking \t{src_configure}, and builds the package in all EAPIs.

The initial working directory is \t{S}, with an error or fallback to \t{WORKDIR} as discussed in
section~\ref{sec:s-to-workdir-fallback}.

For EAPIs listed in table~\ref{tab:src-compile-table} as using format 0, 1 or~2, the default
implementation used when the ebuild lacks the \t{src_prepare} function shall behave as in
listing~\ref{lst:src-compile-0}, listing~\ref{lst:src-compile-1} or listing~\ref{lst:src-compile-2},
respectively.

\ChangeWhenAddingAnEAPI{8}
\begin{centertable}{\t{src_compile} behaviour for EAPIs}
    \label{tab:src-compile-table}
    \begin{tabular}{ll}
      \toprule
      \multicolumn{1}{c}{\textbf{EAPI}} &
      \multicolumn{1}{c}{\textbf{Format}} \\
      \midrule
      0                   & 0 \\
      1                   & 1 \\
      2, 3, 4, 5, 6, 7, 8 & 2 \\
      \bottomrule
    \end{tabular}
\end{centertable}

\begin{listing}[H]
\caption{\t{src_compile}, format~0} \label{lst:src-compile-0}
\begin{verbatim}
src_compile() {
    if [[ -x ./configure ]]; then
        econf
    fi
    if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]]; then
        emake || die "emake failed"
    fi
}
\end{verbatim}
\end{listing}

\begin{listing}[H]
\caption{\t{src_compile}, format~1} \label{lst:src-compile-1}
\begin{verbatim}
src_compile() {
    if [[ -x ${ECONF_SOURCE:-.}/configure ]]; then
        econf
    fi
    if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]]; then
        emake || die "emake failed"
    fi
}
\end{verbatim}
\end{listing}

\begin{listing}[H]
\caption{\t{src_compile}, format~2} \label{lst:src-compile-2}
\begin{verbatim}
src_compile() {
    if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]]; then
        emake || die "emake failed"
    fi
}
\end{verbatim}
\end{listing}

\subsection{src_test}

The \t{src_test} function runs unit tests for the newly built but not yet installed package as
provided.

The initial working directory is \t{S}, with an error or fallback to \t{WORKDIR} as discussed in
section~\ref{sec:s-to-workdir-fallback}.

The default implementation used when the ebuild lacks the \t{src_test} function must, if tests are
enabled, run \t{emake check} if and only if such a target is available, or if not run
\t{emake test} if and only if such a target is available. In both cases, if \t{emake} returns
non-zero the build must be aborted.

\featurelabel{parallel-tests} For EAPIs listed in table~\ref{tab:src-test-table} as not supporting
parallel tests, the \t{emake} command must be called with option \t{-j1}.

The \t{src_test} function may be disabled by \t{RESTRICT}\@. See section~\ref{sec:restrict}. It may
be disabled by user too, using a PM-specific mechanism.

\ChangeWhenAddingAnEAPI{8}
\begin{centertable}{\t{src_test} behaviour for EAPIs}
    \label{tab:src-test-table}
    \begin{tabular}{ll}
      \toprule
      \multicolumn{1}{c}{\textbf{EAPI}} &
      \multicolumn{1}{c}{\textbf{Supports parallel tests?}} \\
      \midrule
      0, 1, 2, 3, 4     & No  \\
      5, 6, 7, 8        & Yes \\
      \bottomrule
    \end{tabular}
\end{centertable}

\subsection{src_install}

\featurelabel{src-install} The \t{src_install} function installs the package's content to a
directory specified in \t{D}.

The initial working directory is \t{S}, with an error or fallback to \t{WORKDIR} as discussed in
section~\ref{sec:s-to-workdir-fallback}.

For EAPIs listed in table~\ref{tab:src-install-table} as using format 4 or~6, the default
implementation used when the ebuild lacks the \t{src_prepare} function shall behave as in
listing~\ref{lst:src-install-4} or listing~\ref{lst:src-install-6}, respectively.

For other EAPIs, the default implementation used when the ebuild lacks the \t{src_install} function
is a no-op.

\ChangeWhenAddingAnEAPI{8}
\begin{centertable}{\t{src_install} behaviour for EAPIs}
    \label{tab:src-install-table}
    \begin{tabular}{ll}
      \toprule
      \multicolumn{1}{c}{\textbf{EAPI}} &
      \multicolumn{1}{c}{\textbf{Format}} \\
      \midrule
      0, 1, 2, 3        & no-op \\
      4, 5              & 4     \\
      6, 7, 8           & 6     \\
      \bottomrule
    \end{tabular}
\end{centertable}

\begin{listing}[H]
\caption{\t{src_install}, format~4} \label{lst:src-install-4}
\begin{verbatim}
src_install() {
    if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]]; then
        emake DESTDIR="${D}" install
    fi

    if ! declare -p DOCS >/dev/null 2>&1; then
        local d
        for d in README* ChangeLog AUTHORS NEWS TODO CHANGES \
                THANKS BUGS FAQ CREDITS CHANGELOG; do
            [[ -s "${d}" ]] && dodoc "${d}"
        done
    elif [[ $(declare -p DOCS) == "declare -a"* ]]; then
        dodoc "${DOCS[@]}"
    else
        dodoc ${DOCS}
    fi
}
\end{verbatim}
\end{listing}

\begin{listing}[H]
\caption{\t{src_install}, format~6} \label{lst:src-install-6}
\begin{verbatim}
src_install() {
    if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]]; then
        emake DESTDIR="${D}" install
    fi
    einstalldocs
}
\end{verbatim}
\end{listing}

\subsection{pkg_preinst}

The \t{pkg_preinst} function performs any special tasks that are required immediately before
merging the package to the live filesystem. It must not write outside of the directories specified
by the \t{ROOT} and \t{D} environment variables.

\t{pkg_preinst} must be run with full access to all files and directories below that specified by
the \t{ROOT} and \t{D} environment variables.

\subsection{pkg_postinst}

The \t{pkg_postinst} function performs any special tasks that are required immediately after
merging the package to the live filesystem. It must not write outside of the directory specified
in the \t{ROOT} environment variable.

\t{pkg_postinst}, like, \t{pkg_preinst}, must be run with full access to all files and directories
below that specified by the \t{ROOT} environment variable.

\subsection{pkg_prerm}

The \t{pkg_prerm} function performs any special tasks that are required immediately before
unmerging the package from the live filesystem. It must not write outside of the directory specified
by the \t{ROOT} environment variable.

\t{pkg_prerm} must be run with full access to all files and directories below that specified by
the \t{ROOT} environment variable.

\subsection{pkg_postrm}

The \t{pkg_postrm} function performs any special tasks that are required immediately after
unmerging the package from the live filesystem. It must not write outside of the directory specified
by the \t{ROOT} environment variable.

\t{pkg_postrm} must be run with full access to all files and directories below that specified by
the \t{ROOT} environment variable.

\subsection{pkg_config}

The \t{pkg_config} function performs any custom steps required to configure a package after it has
been fully installed. It is the only ebuild function which may be interactive and prompt for user
input.

\t{pkg_config} must be run with full access to all files and directories inside of \t{ROOT}.

\subsection{pkg_info}

\featurelabel{pkg-info} The \t{pkg_info} function may be called by the package manager when
displaying information about an installed package. In EAPIs listed in table~\ref{tab:pkg-info-table}
as supporting \t{pkg_info} on non-installed packages, it may also be called by the package manager
when displaying information about a non-installed package. In this case, ebuild authors should note
that dependencies may not be installed.

\t{pkg_info} must not write to the filesystem.

\ChangeWhenAddingAnEAPI{8}
\begin{centertable}{EAPIs supporting \t{pkg_info} on non-installed packages}
    \label{tab:pkg-info-table}
    \begin{tabular}{ll}
      \toprule
      \multicolumn{1}{c}{\textbf{EAPI}} &
      \multicolumn{1}{c}{\textbf{Supports \t{pkg_info} on non-installed packages?}} \\
      \midrule
      0, 1, 2, 3        & No  \\
      4, 5, 6, 7, 8     & Yes \\
      \bottomrule
    \end{tabular}
\end{centertable}

\subsection{pkg_nofetch}

The \t{pkg_nofetch} function is run when the fetch phase of an fetch-restricted ebuild is run, and
the relevant source files are not available. It should direct the user to download all relevant
source files from their respective locations, with notes concerning licensing if applicable.

\t{pkg_nofetch} must require no write access to any part of the filesystem.

\subsection{Default phase functions}
\label{sec:default-phase-funcs}

\featurelabel{default-phase-funcs} In EAPIs listed in
table~\ref{tab:default-phase-function-table} as supporting \t{default_} phase functions, a function
named \t{default_<phase-function>}) that behaves as the default implementation for that EAPI shall
be defined when executing any ebuild phase function listed in the table. Ebuilds must not call
these functions except when in the phase in question.

\ChangeWhenAddingAnEAPI{8}
\begin{centertable}{EAPIs supporting \t{default_} phase functions}
    \label{tab:default-phase-function-table}
    \begin{tabular}{l P{26em}}
      \toprule
      \multicolumn{1}{c}{\textbf{EAPI}} &
      \multicolumn{1}{c}{\textbf{Supports \t{default_} functions in phases}} \\
      \midrule
      0, 1              & None \\
      2, 3              & \t{pkg_nofetch}, \t{src_unpack}, \t{src_prepare}, \t{src_configure},
                          \t{src_compile}, \t{src_test} \\
      4, 5, 6, 7, 8     & \t{pkg_nofetch}, \t{src_unpack}, \t{src_prepare}, \t{src_configure},
                          \t{src_compile}, \t{src_test}, \t{src_install} \\
      \bottomrule
    \end{tabular}
\end{centertable}

\section{Call Order}

The call order for installing a package is:
\nobreakpar
\begin{compactitem}
\item \t{pkg_pretend} (only for EAPIs listed in table~\ref{tab:pkg-pretend-table}), which is called
    outside of the normal call order process.
\item \t{pkg_setup}
\item \t{src_unpack}
\item \t{src_prepare} (only for EAPIs listed in table~\ref{tab:src-prepare-table})
\item \t{src_configure} (only for EAPIs listed in table~\ref{tab:src-configure-table})
\item \t{src_compile}
\item \t{src_test} (except if \t{RESTRICT=test} or disabled by user)
\item \t{src_install}
\item \t{pkg_preinst}
\item \t{pkg_postinst}
\end{compactitem}

The call order for uninstalling a package is:

\begin{compactitem}
\item \t{pkg_prerm}
\item \t{pkg_postrm}
\end{compactitem}

The call order for upgrading, downgrading or reinstalling a package is:

\begin{compactitem}
\item \t{pkg_pretend} (only for EAPIs listed in table~\ref{tab:pkg-pretend-table}), which is called
    outside of the normal call order process.
\item \t{pkg_setup}
\item \t{src_unpack}
\item \t{src_prepare} (only for EAPIs listed in table~\ref{tab:src-prepare-table})
\item \t{src_configure} (only for EAPIs listed in table~\ref{tab:src-configure-table})
\item \t{src_compile}
\item \t{src_test} (except if \t{RESTRICT=test})
\item \t{src_install}
\item \t{pkg_preinst}
\item \t{pkg_prerm} for the package being replaced
\item \t{pkg_postrm} for the package being replaced
\item \t{pkg_postinst}
\end{compactitem}

\note{When up- or downgrading a package in EAPI 0 or 1, the last four phase functions can
alternatively be called in the order \t{pkg_preinst}, \t{pkg_postinst}, \t{pkg_prerm},
\t{pkg_postrm}. This behaviour is deprecated.}

The \t{pkg_config}, \t{pkg_info} and \t{pkg_nofetch} functions are not called in a normal
sequence. The \t{pkg_pretend} function is called some unspecified time before a (possibly
hypothetical) normal sequence.

For installing binary packages, the \t{src} phases are not called.

When building binary packages that are not to be installed locally, the \t{pkg_preinst}
and \t{pkg_postinst} functions are not called.

% vim: set filetype=tex fileencoding=utf8 et tw=100 spell spelllang=en :

%%% Local Variables:
%%% mode: latex
%%% TeX-master: "pms"
%%% LaTeX-indent-level: 4
%%% LaTeX-item-indent: 0
%%% TeX-brace-indent-level: 4
%%% fill-column: 100
%%% End: