path: root/ebuild-functions.tex

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

\section{List of Functions}
\label{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. Most functions must assume only that they have write access to the package's working
directory (the \t{WORKDIR} environment variable; see section~\ref{env-var-WORKDIR}), and the
temporary directory \t{T}; exceptions are noted below. All functions may assume that they have read
access to all system libraries, binaries and configuration files that are accessible to normal
users.

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, it may be set to anything and
the ebuild must not rely upon a particular location for it.

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{pkg\_setup}
\label{pkg-setup-function}
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}
\label{src-unpack-function}

The \t{src\_unpack} function extracts all of the package's sources, applies patches and sets 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:

\begin{verbatim}
src_unpack() {
    if [[ -n ${A} ]]; then
        unpack ${A}
    fi
}
\end{verbatim}

\subsection{src\_prepare}
\label{src-prepare-function}

The \t{src\_prepare} function is only called for EAPIs listed in table~\ref{src-prepare-table} as
supporting it.

The \t{src\_prepare} function can be used for post-unpack source preparation. The default
implementation does nothing.

The initial working directory must be \t{S} if that exists, falling back to \t{WORKDIR} otherwise.

\begin{centertable}{EAPIs supporting \t{src\_prepare}} \label{src-prepare-table}
\IFKDEBUILDELSE
{
    \begin{tabular}{ l l }
        \toprule
        \multicolumn{1}{c}{\textbf{EAPI}} &
        \multicolumn{1}{c}{\textbf{Supports \t{src\_prepare}?}} \\
        \midrule
    \t{0} & No \\
    \t{1} & No \\
    \t{kdebuild-1} & No \\
    \t{2} & Yes \\
    \bottomrule
    \end{tabular}
}{
    \begin{tabular}{ l l }
        \toprule
        \multicolumn{1}{c}{\textbf{EAPI}} &
        \multicolumn{1}{c}{\textbf{Supports \t{src\_prepare}?}} \\
        \midrule
    \t{0} & No \\
    \t{1} & No \\
    \t{2} & Yes \\
    \bottomrule
    \end{tabular}
}
\end{centertable}

\subsection{src\_configure}
\label{src-configure-function}

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

The initial working directory must be \t{S} if that exists, falling back to \t{WORKDIR} otherwise.

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:

\begin{verbatim}
src_configure() {
    if [[ -x ${ECONF_SOURCE:-.}/configure ]]; then
        econf
    fi
}
\end{verbatim}

\begin{centertable}{EAPIs supporting \t{src\_configure}} \label{src-configure-table}
\IFKDEBUILDELSE
{
    \begin{tabular}{ l l }
        \toprule
        \multicolumn{1}{c}{\textbf{EAPI}} &
        \multicolumn{1}{c}{\textbf{Supports \t{src\_configure}?}} \\
        \midrule
    \t{0} & No \\
    \t{1} & No \\
    \t{kdebuild-1} & No \\
    \t{2} & Yes \\
    \bottomrule
    \end{tabular}
}{
    \begin{tabular}{ l l }
        \toprule
        \multicolumn{1}{c}{\textbf{EAPI}} &
        \multicolumn{1}{c}{\textbf{Supports \t{src\_configure}?}} \\
        \midrule
    \t{0} & No \\
    \t{1} & No \\
    \t{2} & Yes \\
    \bottomrule
    \end{tabular}
}
\end{centertable}

\subsection{src\_compile}
\label{src-compile-function}

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 must be \t{S} if that exists, falling back to \t{WORKDIR} otherwise.

For EAPIs listed in table~\ref{src-compile-table} as using format 0, the default implementation used
when the ebuild lacks the \t{src\_compile} function shall behave as:

\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}

For EAPIs listed in table~\ref{src-compile-table} as using format 1, the default implementation used
when the ebuild lacks the \t{src\_compile} function shall behave as:

\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}

For EAPIs listed in table~\ref{src-compile-table} as using format 2, the default implementation used
when the ebuild lacks the \t{src\_compile} function shall behave as:

\begin{verbatim}
src_compile() {
    if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]]; then
        emake || die "emake failed"
    fi
}
\end{verbatim}

\begin{centertable}{\t{src\_compile} behaviour for EAPIs} \label{src-compile-table}
\IFKDEBUILDELSE
{
    \begin{tabular}{ l l }
        \toprule
        \multicolumn{1}{c}{\textbf{EAPI}} &
        \multicolumn{1}{c}{\textbf{Format}} \\
        \midrule
    \t{0} & 0 \\
    \t{1} & 1 \\
    \t{kdebuild-1} & 1 \\
    \t{2} & 2 \\
    \bottomrule
    \end{tabular}
}{
    \begin{tabular}{ l l }
        \toprule
        \multicolumn{1}{c}{\textbf{EAPI}} &
        \multicolumn{1}{c}{\textbf{Format}} \\
        \midrule
    \t{0} & 0 \\
    \t{1} & 1 \\
    \t{2} & 2 \\
    \bottomrule
    \end{tabular}
}
\end{centertable}

\subsection{src\_test}
\label{src-test-function}

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

The initial working directory must be \t{S} if that exists, falling back to \t{WORKDIR} otherwise.
The default implementation used when the ebuild lacks the \t{src\_test} function must, if tests are
enabled, run \t{make check} if and only if such a target is available, or if not run \t{make test},
if and only such a target is available. In both cases, if make returns non-zero the build must be
aborted.

The \t{src\_test} function may be disabled by \t{RESTRICT}. See section~\ref{restrict}.

\IFKDEBUILDELSE
{
    In some EAPIs, \t{src\_test} should only be run at user option (and never if restrictions are in
    place). In others, it must always be run (excepting restrictions). See table~\ref{test-required-table}
    for which EAPIs fit into which category.

    \begin{centertable}{EAPIs requiring \t{src\_test}} \label{test-required-table}
    \begin{tabular}{ l l }
        \toprule
        \multicolumn{1}{c}{\textbf{EAPI}} &
        \multicolumn{1}{c}{\textbf{Requires \t{src\_test}?}} \\
        \midrule
    \t{0} & At user option \\
    \t{1} & At user option \\
    \t{2} & At user option \\
    \t{kdebuild-1} & Required \\
    \bottomrule
    \end{tabular}

    \end{centertable}
}{
}

\subsection{src\_install}
\label{src-install-function}

The \t{src\_install} function installs the package's content to a directory specified in
\t{\${D}}.

The initial working directory must be \t{S} if that exists, falling back to \t{WORKDIR} otherwise.
The default implementation used when the ebuild lacks the \t{src\_install} function is a no-op.

\subsection{pkg\_preinst}
\label{pkg-preinst-function}

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}
\label{pkg-postinst-function}

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}
\label{pkg-prerm-function}

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}
\label{pkg-postrm-function}

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}
\label{pkg-config-function}

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}
\label{pkg-info-function}

\IFKDEBUILDELSE
{
    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{pkg-info-table} as supporting \t{pkg\_info} on
    uninstalled packages, it may also be called by the package manager when displaying information
    about an uninstalled package. In this case, ebuild authors should note that dependencies may not be
    installed.
}{
    The \t{pkg\_info} function may be called by the package manager when displaying information about an
    installed package.
}

\t{pkg\_info} must not write to the filesystem.

\IFKDEBUILDELSE
{
    \begin{centertable}{EAPIs supporting \t{pkg\_info} on uninstalled packages} \label{pkg-info-table}
    \begin{tabular}{ l l }
        \toprule
        \multicolumn{1}{c}{\textbf{EAPI}} &
        \multicolumn{1}{c}{\textbf{Supports \t{pkg\_info} on uninstalled packages?}} \\
        \midrule
    \t{0} & No \\
    \t{1} & No \\
    \t{2} & No \\
    \t{kdebuild-1} & Yes \\
    \bottomrule
    \end{tabular}
    \end{centertable}
}{
}

\subsection{pkg\_nofetch}
\label{pkg-nofetch-function}

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{\t{default\_} Phase Functions}

In EAPIs listed in table~\ref{default-phase-function-table} as supporting \t{default\_} phase
functions, a function named \t{default\_\$\{EBUILD\_PHASE\}} that behaves as the default
implementation for that EAPI shall be defined when executing any given \t{EBUILD\_PHASE}. Ebuilds
must not call these functions except when in the phase in question.

\begin{centertable}{EAPIs supporting \t{default\_} phase functions} \label{default-phase-function-table}
\IFKDEBUILDELSE
{
    \begin{tabular}{ l l }
        \toprule
            \multicolumn{1}{c}{\textbf{EAPI}} &
            \multicolumn{1}{c}{\textbf{Supports \t{default\_} phase functions?}} \\
            \midrule
    \t{0} & No \\
    \t{1} & No \\
    \t{kdebuild-1} & No \\
    \t{2} & Yes \\
    \bottomrule
    \end{tabular}
}{
    \begin{tabular}{ l l }
        \toprule
            \multicolumn{1}{c}{\textbf{EAPI}} &
            \multicolumn{1}{c}{\textbf{Supports \t{default\_} phase functions?}} \\
            \midrule
    \t{0} & No \\
    \t{1} & No \\
    \t{2} & Yes \\
    \bottomrule
    \end{tabular}
}
\end{centertable}

\section{Call Order}

The call order for installing a package is:

\begin{compactitem}
\item \t{pkg\_setup}
\item \t{src\_unpack}
\item \t{src\_prepare} (only for EAPIs listed in table~\ref{src-prepare-table})
\item \t{src\_configure} (only for EAPIs listed in table~\ref{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\_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 reinstalling a package is:

\begin{compactitem}
\item \t{pkg\_setup}
\item \t{src\_unpack}
\item \t{src\_prepare} (only for EAPIs listed in table~\ref{src-prepare-table})
\item \t{src\_configure} (only for EAPIs listed in table~\ref{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}

The call order for upgrading or downgrading a package is:

\begin{compactitem}
\item \t{pkg\_setup}
\item \t{src\_unpack}
\item \t{src\_prepare} (only for EAPIs listed in table~\ref{src-prepare-table})
\item \t{src\_configure} (only for EAPIs listed in table~\ref{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\_postinst}
\item \t{pkg\_prerm} for the package being replaced
\item \t{pkg\_postrm} for the package being replaced
\end{compactitem}

The \t{pkg\_config}, \t{pkg\_info} and \t{pkg\_nofetch} functions are not called in a 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"
%%% End: