path: root/eapi-cheatsheet.tex

\documentclass[a4paper,nofoldmark]{leaflet}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{
    url,
    xr-hyper,
    hyperref,
    ifthen,
    mathptmx,
    courier
}
\usepackage[orig,english]{isodate}
\usepackage[scaled=.90]{helvet}
\usepackage[nohyphen]{underscore}
\usepackage[local]{gitinfo2}
\newcommand{\code}[1]{\texttt{#1}}
% This should reflect the latest approved EAPI version
\newcommand{\version}{7.0}
\newcommand{\featureref}[1]{\textsc{#1} on page~\pageref{feat:#1}}
\renewcommand{\familydefault}{\sfdefault}
\urlstyle{sf}
\externaldocument{pms}

\title{EAPI Cheat Sheet}
\author{%
    Christian Faulhammer \\
    \href{mailto:fauli@gentoo.org}{fauli@gentoo.org}
    \and
    Ulrich Müller \\
    \href{mailto:ulm@gentoo.org}{ulm@gentoo.org}
}
\date{%
    Version \version \\
    \ifthenelse{\equal{\gitCommitterDate}{(None)}}
    {Generated on: \today}
    {\printdate{\gitCommitterDate}}%
}
\CutLine*{1}
\CutLine*{3}
\CutLine*{4}
\CutLine*{6}
\hypersetup{%
    urlcolor=black,
    colorlinks=true,
    citecolor=black,
    linkcolor=black,
    filecolor=black,
    pdftitle={EAPI Desk Reference},
    pdfauthor={Christian Faulhammer, Ulrich Müller},
    pdfsubject={Making look-up faster for EAPI features},
    pdflang={en},
    pdfkeywords={Gentoo, package manager, reference},
    pdfcreator={pdfLaTeX and hyperref},
    pdfproducer={pdfLaTeX and hyperref},
}
\begin{document}
\maketitle
\thispagestyle{empty}
\begin{abstract}
    An overview of the main EAPI changes in Gentoo, for ebuild
    authors.  For full details, consult the Package Manager
    Specification found on the project page;\footnote{%
    \url{https://wiki.gentoo.org/wiki/Project:Package_Manager_Specification}}
    this is an incomplete summary only.

    Official Gentoo EAPIs are consecutively numbered integers (0, 1,
    2, \dots).  Except where otherwise noted, an EAPI is the same as
    the previous EAPI\@.  All labels refer to the PMS document itself,
    built from the same checkout as this overview.

    % Please report mistakes in or enhancements to this document via the
    % Gentoo bug tracking system\footnote{\url{https://bugs.gentoo.org/}}
    % to the original author or the PMS team.

    This work is released under the Creative Commons
    Attribution-ShareAlike 4.0 International Licence.%
    \footnote{\url{https://creativecommons.org/licenses/by-sa/4.0/}}
\end{abstract}

\section{EAPIs 0, 1, 2, 3, and 4}
\label{sec:cs:eapi0-2}
Omitted for lack of space. See version~5.0 of this document for
differences between these previous EAPIs.

% \section{EAPI 0}
% \label{sec:cs:eapi0}
% If there is no EAPI explicitly specified, EAPI 0 is assumed.

% \section{EAPI 1}
% \label{sec:cs:eapi1}
% \subsection{Additions/Changes}
% \label{sec:cs:eapi1-additions}
% \begin{description}
%     \item[IUSE defaults] A USE flag can be marked as mandatory (if
%     not disabled explicitly by user configuration) with a \code{+}
%     sign in front.  See \featureref{iuse-defaults}.
%     \item[Named slot dependencies] Dependencies can explicitly request
%     a specific slot by using the
%     \code{dev-libs/foo:}\allowbreak\emph{SLOT_name} syntax.
%     See \featureref{slot-deps}.
% \end{description}

% \section{EAPI 2 (2008-09-25)}
% \label{sec:cs:eapi2}
% \subsection{Additions/Changes}
% \label{sec:cs:eapi2-additions}
% \begin{description}
%     \item[\code{SRC_URI} arrows] Allows redirection of upstream file
%     naming scheme.  By using
%     \code{SRC_URI="http:/\slash some\slash url -> foo"} the file is
%     saved as \code{foo} in DISTDIR\@.
%     See \featureref{src-uri-arrows}.
%     \item[USE dependencies] Dependencies can specify USE flag
%     requirements on their target, removing the need for
%     \code{built_with_use} checks.
%     \begin{description}
%         \item[{[opt]}] The flag must be enabled.
%         \item[{[opt=]}] The flag must be enabled if it is
%         enabled for the package with the dependency, or disabled
%         otherwise.
%         \item[{[!opt=]}] The flag must be disabled if it is
%         enabled for the package with the dependency, or enabled
%         otherwise.
%         \item[{[opt?]}] The flag must be enabled if it is
%         enabled for the package with the dependency.
%         \item[{[!opt?]}] The flag must be disabled if it is
%         disabled for the package with the dependency.
%         \item[{[-opt]}] The flag must be disabled.
%     \end{description}
%     See \featureref{use-deps}.
%     \item[Blocker syntax] A single exclamation mark as a blocker may
%     be ignored by the package manager as long as the stated package is
%     uninstalled later on.  Two exclamation marks are a strong blocker
%     and will always be respected.  See \featureref{bang-strength}.
%     \item[\code{src_configure, src_prepare}] Both new phases provide
%     finer granularity in the ebuild's structure.  Configure calls
%     should be moved from \code{src_compile} to \code{src_configure}.
%     Patching and similar preparation must now be done in
%     \code{src_prepare}, not \code{src_unpack}.  See
%     \featureref{src-prepare} and \featureref{src-configure}.
%     \item[Default phase functions] The default functions for
%     phases \code{pkg_nofetch}, \code{src_unpack},
%     \code{src_prepare}, \code{src_configure}, \code{src_compile}
%     and \code{src_test} can be called via
%     \code{default_}\emph{phasename}, so duplicating the standard
%     implementation is no longer necessary for small additions.  The
%     short-hand \code{default} function calls the current phase's
%     \code{default_} function automatically, so any small additions
%     you need will not be accompanied by a complete reimplementation of
%     the phase.  See \featureref{default-phase-funcs} and
%     \featureref{default-func}.
%     \item[\code{doman} language support] The \code{doman} installation
%     function recognizes language specific man page extensions and
%     behaves accordingly.  This behaviour can be inhibited by the
%     \code{-i18n} switch with EAPI 4.  See \featureref{doman-langs}.
% \end{description}

% \section{EAPI 3 (2010-01-18)}
% \label{sec:cs:eapi3}
% \subsection{Additions/Changes}
% \label{sec:cs:eapi3-additions}
% \begin{description}
%     \item[Support for \code{.xz}] Unpack of \code{.xz} and
%     \code{.tar.xz} files is possible without any custom
%     \code{src_unpack} functions.  See \featureref{unpack-extensions}.
%     \item[Offset prefix] Supporting installation on Prefix-enabled
%     systems will be easier with this EAPI.
% \end{description}

% \section{EAPI 4 (2011-01-17)}
% \label{sec:cs:eapi4}
% \subsection{Additions/Changes}
% \label{sec:cs:eapi4-additions}
% \begin{description}
%     \item[\code{pkg_pretend}] Some useful checks (kernel options for
%     example) can be placed in this new phase to inform the user early
%     (when just pretending to emerge the package).  Most checks should
%     usually be repeated in \code{pkg_setup}.
%     See \featureref{pkg-pretend}.
%     \item[\code{src_install}] The \code{src_install} phase is no
%     longer empty but has a default now.  This comes along with an
%     accompanying \code{default} function.
%     See \featureref{src-install-4}.
%     \item[\code{pkg_info} on non-installed packages] The
%     \code{pkg_info} phase can be called even for non-installed
%     packages.  Be warned that dependencies might not have been
%     installed at execution time.  See \featureref{pkg-info}.
%     \item[\code{econf} changes] The helper function now always
%     activates \code{-{}-disable-dependency-tracking}.
%     See \featureref{econf-options}.
%     \item[USE dependency defaults] In addition to the features offered
%     in EAPI 2 for USE dependencies, a \code{(+)} or \code{(-)} can be
%     added after a USE flag (mind the parentheses).  The former
%     specifies that flags not in IUSE should be treated as enabled; the
%     latter, disabled. Cannot be used with USE_EXPAND flags.  This
%     mimics parts of the behaviour of \code{-{}-missing} in
%     \code{built_with_use}.  See \featureref{use-dep-defaults}.
%     \item[Controllable compression] All items in the \code{doc},
%     \code{info}, \code{man} subdirectories of \code{/usr/share/} may
%     be compressed on-disk after \code{src_install}, except for
%     \code{/usr/share/doc/\$\{PF\}/html}.  \code{docompress path \dots}
%     adds paths to the inclusion list for compression.
%     \code{docompress -x path \dots} adds paths to the exclusion list.
%     See \featureref{docompress}.
%     \item[\code{nonfatal} for commands] If you call \code{nonfatal}
%     the command given as argument will not abort the build process in
%     case of a failure (as is the default) but will return non-zero on
%     failure.
%     See \featureref{nonfatal}.
%     \item[\code{dodoc} recursion] If the \code{-r} switch is given as
%     first argument and followed by directories, files from there are
%     installed recursively.  See \featureref{dodoc}.
%     \item[\code{doins} symlink support] Symbolic links are now
%     properly installed when using recursion (\code{-r} switch).
%     See \featureref{doins}.
%     \item[\code{PROPERTIES}] Is mandatory for all package managers now
%     to support interactive installs.
%     \item[\code{REQUIRED_USE}] This variable can be used similar to
%     the \code{(R|P)DEPEND} variables and define sets of USE flag
%     combinations that are not allowed.  All elements can be further
%     nested to achieve more functionality.
%     \begin{description}
%         \item[Illegal combination] To prevent activation of
%         \code{flag1} if \code{flag2} is enabled use
%         "\code{flag2?\ ( !flag1 )}".
%         \item[OR] If at least one USE flag out of many must be
%         activated on \code{flag1} use
%         "\code{flag1?\ ( || ( flag2 flag3 \dots\ ) )}".
%         \item[XOR] To allow exactly one USE flag out of many use
%         "\code{\textasciicircum\textasciicircum ( flag1 flag2 \dots\ )}".
%     \end{description}
%     See \featureref{required-use}.
%     \item[\code{MERGE_TYPE}] This variable contains one of three
%     possible values to allow checks if it is normal merge with
%     compilation and installation (\code{source}), installation of a
%     binary package (\code{binary}), or a compilation without
%     installation (\code{buildonly}).  See \featureref{merge-type}.
%     \item[\code{REPLACING_VERSIONS}, \code{REPLACED_BY_VERSION}]
%     These variables, valid in \code{pkg_*}, contain a list of all
%     versions (\code{PVR}) of this package that we are replacing, and
%     the version that is replacing the current one, respectively.
%     See \featureref{replace-version-vars}.
% \end{description}
% \subsection{Removals/Bans}
% \label{sec:cs:eapi4-removalsbans}
% \begin{description}
%     \item[\code{dohard}, \code{dosed}] Both functions are not allowed
%     any more.  See \featureref{banned-commands}.
%     \item[No \code{RDEPEND} fall-back] The package manager will not
%     fall back to \code{RDEPEND=DEPEND} if \code{RDEPEND} is undefined.
%     See \featureref{rdepend-depend}.
%     \item[\code{S} fallback changes] The value of the variable
%     \code{S} will not automatically be changed to \code{WORKDIR}, if
%     \code{S} is not a directory, but abort.  Virtual packages are the
%     only exception.  See \featureref{s-workdir-fallback}.
%     \item[\code{AA}, \code{KV}] These variables are not defined
%     any more.  See \featureref{aa} and \featureref{kv}.
% \end{description}

\section{EAPI 5 (2012-09-20)}
\label{sec:cs:eapi5}
\subsection{Additions/Changes}
\label{sec:cs:eapi5-additions}
\begin{description}
    \item[Sub-slots] The \code{SLOT} variable and slot dependencies
    may contain an optional sub-slot part that follows the regular
    slot, delimited by a \code{/} character; for example
    \code{2/2.30}.  The sub-slot is used to represent cases in which
    an upgrade to a new version of a package with a different sub-slot
    may require dependent packages to be rebuilt.  If the sub-slot is
    not specified in \code{SLOT}, it defaults to the regular slot.
    See \featureref{sub-slot}.
    \item[Slot operator dependencies] Package dependencies can specify
    one of the following operators as a suffix, which will affect
    updates of runtime dependencies:
    \begin{description}
        \item[\code{:*}] Any slot value is acceptable.  The package
        will not break when its dependency is updated.
        \item[\code{:=}] Any slot value is acceptable, but the package
        can break when its dependency is updated to a different slot
        (or sub-slot).
    \end{description}
    See \featureref{slot-operator-deps}.
    \item[Profile \code{IUSE} injection] Apart from the USE flags
    explicitly listed in \code{IUSE}, additional flags can be
    implicitly provided by profiles.
    See \featureref{profile-iuse-inject}.
    \item[At-most-one-of groups] In \code{REQUIRED_USE} you can use
    "\code{??\ ( flag1 flag2 \dots\ )}" to allow zero or one USE flag
    out of many.
    See \featureref{at-most-one-of}.
    \item[Parallel tests] The default for \code{src_test} runs
    \code{emake} without \code{-j1} now.
    See \featureref{parallel-tests}.
    \item[\code{econf} changes] The \code{econf} function now always
    passes \code{-{}-disable-silent-rules} to \code{configure}.
    See \featureref{econf-options}.
    \item[\code{has_version} and \code{best_version} changes]
    The two helpers support a \code{-{}-host-root} option that causes
    the query to apply to the host root instead of \code{ROOT}.
    See~\featureref{pm-query-options}.
    \item[\code{usex}] Usage for this helper function is
    \code{usex} \emph{<USE flag> [true1] [false1] [true2] [false2]}.
    If the USE flag is set, outputs \emph{[true1][true2]}
    (defaults to \code{yes}), otherwise outputs
    \emph{[false1][false2]} (defaults to \code{no}).
    See \featureref{usex}.
    \item[\code{doheader} and \code{newheader}] These new helper
    functions install the given header file(s) into
    \code{/usr/include}. The \code{-r} option enables recursion for
    \code{doheader}, similar to \code{doins}.
    See \featureref{doheader}.
    \item[\code{new*} standard input] The \code{newins} etc.\ commands
    read from standard input if the first argument is \code{-}
    (a hyphen).
    See \featureref{newfoo-stdin}.
    \item[\code{EBUILD_PHASE_FUNC}] This variable is very similar to
    \code{EBUILD_PHASE}, but contains the name of the current ebuild
    function.
    See \featureref{ebuild-phase-func}.
    \item[Stable use masking/forcing] New files
    \code{use.stable.\allowbreak\{mask,force\}} and
    \code{package.use.stable.\allowbreak\{mask,force\}}
    are supported in profile directories.  They are similar to their
    non-\code{stable} counterparts, but act only on packages that
    would be merged due to a stable keyword.
    See \featureref{stablemask}.
\end{description}

\section{EAPI 6 (2015-11-13)}
\label{sec:cs:eapi6}
\subsection{Additions/Changes}
\label{sec:cs:eapi6-additions}
\begin{description}
    \item[Bash version] Ebuilds can use features of Bash version 4.2
    (was 3.2 before).
    See \featureref{bash-version}.
    \item[\code{failglob}] The \code{failglob} option of Bash is set
    in global scope, so that unintentional pattern expansion will be
    caught as an error.
    See \featureref{failglob}.
    \item[Locale settings] It is ensured that the behaviour of case
    modification and collation order for ASCII characters
    (\code{LC_CTYPE} and \code{LC_COLLATE}) are the same as in the
    POSIX locale.
    See \featureref{locale-settings}.
    \item[\code{src_prepare}] This phase function has a default now,
    which applies patches from the \code{PATCHES} variable with the
    new \code{eapply} command, and user-provided patches with
    \code{eapply_user}.
    See \featureref{src-prepare-6}.
    \item[\code{src_install}] The default implementation uses the new
    \code{einstalldocs} function for installing documentation.
    See \featureref{src-install-6}.
    \item[\code{nonfatal die}] When \code{die} or \code{assert} are
    called under the \code{nonfatal} command and with the \code{-n}
    option, they will not abort the build process but return with an
    error.
    See \featureref{nonfatal-die}.
    \item[\code{unpack} changes] \code{unpack} has been extended:
    \begin{description}
        \item[Pathnames] Both absolute paths and paths relative to the
        working directory are accepted as arguments.
        See \featureref{unpack-absolute}.
        \item[\code{.txz} files] Suffix \code{.txz} for xz compressed
        tarballs is recognised.
        See \featureref{unpack-extensions}.
        \item[Filename case] Character case of filename extensions is
        ignored.
        See \featureref{unpack-ignore-case}.
    \end{description}
    \item[\code{econf} changes] Options \code{-{}-docdir} and
    \code{-{}-htmldir} are passed to \code{configure}, in addition to
    the existing options.
    See \featureref{econf-options}.
    \item[\code{eapply}] The \code{eapply} command is a simplified
    substitute for \code{epatch}, implemented in the package manager.
    The patches from its file or directory arguments are applied using
    \code{patch -p1}.
    See \featureref{eapply}.
    \item[\code{eapply_user}] The \code{eapply_user} command permits
    the package manager to apply user-provided patches. It must be
    called from every \code{src_prepare} function.
    See \featureref{eapply-user}.
    \item[\code{einstalldocs}] The \code{einstalldocs} function will
    install the files specified by the \code{DOCS} variable (or a
    default set of files if \code{DOCS} is unset) and by the
    \code{HTML_DOCS} variable.
    See \featureref{einstalldocs}.
    \item[\code{in_iuse}] The \code{in_iuse} function returns
    true if the USE flag given as its argument is available in the
    ebuild for USE queries.
    See \featureref{in-iuse}.
    \item[\code{get_libdir}] The \code{get_libdir} command outputs
    the \code{lib*} directory basename suitable for the current ABI\@.
    See \featureref{get-libdir}.
\end{description}
\subsection{Removals/Bans}
\label{sec:cs:eapi6-removalsbans}
\begin{description}
    \item[\code{einstall}] No longer allowed. Use \code{emake install}
    as replacement.
    See \featureref{banned-commands}.
\end{description}

\section{EAPI 7 (2018-04-30)}
\label{sec:cs:eapi7}
\subsection{Additions/Changes}
\label{sec:cs:eapi7-additions}
\begin{description}
    \item[\code{package.*} and \code{use.*}] These profile files can
    be directories instead of regular files. This is intended to be
    used in overlays only.
    See \featureref{package-mask-dir} and \featureref{profile-file-dirs}.
    \item[\code{||} and \code{\textasciicircum\textasciicircum}
    dependency groups] These groups now evaluate to false when they
    are empty (for example, if there are only unmatched use
    dependencies inside of them).
    See \featureref{empty-dep-groups}.
    \item[No trailing slash] The paths specified by \code{ROOT},
    \code{EROOT}, \code{D}, and \code{ED} no longer end with a slash.
    Thus, default \code{ROOT} is empty now.
    See \featureref{trailing-slash}.
    \item[Cross compilation support] Several variables have been added
    and some commands have been extended for better cross compilation
    support:
    \begin{description}
        \item[\code{BDEPEND}] Build dependencies are divided into two
        classes: \code{BDEPEND} for native build tools (\code{CBUILD});
        \code{DEPEND} for dependencies compatible with the system
        being built (\code{CHOST}).
        See \featureref{bdepend}.
        \item[\code{SYSROOT}] The path to the root directory for
        \code{DEPEND} type dependencies.
        See \featureref{sysroot}.
        \item[\code{ESYSROOT}] The concatenation of \code{SYSROOT} and
        the applicable offset-prefix. See \featureref{sysroot}.
        \item[\code{BROOT}] The prefixed root directory path for
        \code{BDEPEND} type dependencies, typically executable build
        tools.
        See \featureref{broot}.
        \item[\code{econf}] If supported, configure will be called
        with the \code{-{}-with-sysroot=\$\{ESYSROOT:-/\}} option.
        See \featureref{econf-options}.
        \item[\code{has_version} and \code{best_version}] These
        helpers support \code{-b}, \code{-d} or \code{-r} options,
        causing the query to apply to \code{BDEPEND}, \code{DEPEND}
        or \code{RDEPEND} (the default). This replaces the
        \code{-{}-host-root} option.
        See \featureref{pm-query-options}.
    \end{description}
    \item[Environment blacklist] Any environment variable listed in
    the profile-defined \code{ENV_UNSET} variable will be unset by the
    package manager.
    See \featureref{env-unset}.
    \item[\code{patch}] All inputs valid for GNU patch version 2.7
    are supported. Especially, this includes support for git-formatted
    patches.
    See \featureref{gnu-patch}.
    \item[\code{nonfatal}] In addition to its definition as a shell
    function, the \code{nonfatal} wrapper has now a fallback
    implementation as an external command. Thus, it can be called
    from other commands.
    See \featureref{nonfatal}.
    \item[Output commands] \code{einfo} and friends no longer use
    stdout, so inside of command substitution their output won't be
    caught.
    See \featureref{output-no-stdout}.
    \item[\code{eqawarn}] The \code{eqawarn} output command is
    supported in the package manager itself.
    See \featureref{eqawarn}.
    \item[\code{die} in subshell] The \code{die} command is guaranteed
    to work in a subshell context.
    See \featureref{subshell-die}.
    \item[\code{domo} destination] \code{domo} installs the specified
    files under \code{/usr/share/locale} instead of
    \code{\$\{DESTTREE\}/\allowbreak share/locale}.
    See \featureref{domo-path}.
    \item[Controllable stripping] The \code{dostrip -x} command can be
    used to add paths to an exclusion list for stripping of debug
    symbols, to allow more fine-grained control than with
    \code{RESTRICT="strip"}.
    See \featureref{dostrip}.
    \item[Version manipulation and comparison commands] \mbox{}
    \begin{description}
        \item[\code{ver_cut} \emph{range} {[\emph{version}]}]
        Print the version substring specified by \emph{range}.
        \emph{version} defaults to \code{PV}.
        \item[\code{ver_rs} \emph{range repl} \dots\ {[\emph{version}]}]
        Replace all version separators in \emph{range} by string
        \emph{repl}. Multiple \emph{range repl} pairs are allowed.
        \emph{version} defaults to \code{PV}.
        \item[\code{ver_test} {[\emph{v1}]} \emph{op v2}]
        Check if the relation \emph{v1 op v2} is true.
        \emph{v1} defaults to \code{PVR}; \emph{op} can be \code{-eq},
        \code{-ne}, \code{-gt}, \code{-ge}, \code{-lt} or \code{-le}.
    \end{description}
    See \featureref{ver-commands}.
\end{description}
\subsection{Removals/Bans}
\label{sec:cs:eapi7-removalsbans}
\begin{description}
    \item[\code{package.provided}] Deprecated since a long time and
    finally dropped.
    See \featureref{package-provided}.
    \item[\code{PORTDIR} and \code{ECLASSDIR}] No longer defined,
    because ebuilds should not directly access files in the repository.
    See \featureref{portdir} and \featureref{eclassdir}.
    \item[\code{DESTTREE} and \code{INSDESTTREE}] Not defined any
    more. Use the \code{into} and \code{insinto} commands instead.
    See \featureref{desttree} and \featureref{insdesttree}.
    \item[\code{dohtml}] No longer allowed. \code{doins -r} can be
    used as a replacement.
    See \featureref{banned-commands}.
    \item[\code{dolib} and \code{libopts}] No longer allowed.
    The specific \code{dolib.a} or \code{dolib.so} commands should be
    used as replacement.
    See \featureref{banned-commands}.
\end{description}
\end{document}

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

%%% Local Variables:
%%% mode: latex
%%% LaTeX-indent-level: 4
%%% LaTeX-item-indent: 0
%%% TeX-brace-indent-level: 4
%%% fill-column: 70
%%% End: