\documentclass[a4paper,nofoldmark]{leaflet}
\input{vc}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{
    url,
    xr-hyper,
    hyperref,
    ifthen,
    mathptmx,
    courier
}
\usepackage[orig,english]{isodate}
\usepackage[scaled=.90]{helvet}
\newcommand{\code}[1]{\texttt{#1}}
% This should reflect the latest approved EAPI version
\newcommand{\version}{6.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}
}
\ifthenelse{\equal{\VCDateISO}{}}
{
    \date{Version \version{}, generated on: \\\today}
}{
    \date{Version \version\\\printdate{\VCDateISO}}
}
\CutLine*{1}
\CutLine*{3}
\CutLine*{4}
\CutLine*{6}
\hypersetup{%
    urlcolor=black,
    colorlinks=true,
    citecolor=black,
    linkcolor=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},
    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-Share Alike 3.0 Licence.%
    \footnote{\url{http://creativecommons.org/licenses/by-sa/3.0/}}
\end{abstract}

\section{EAPIs 0, 1, and 2}
\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{host-root-option}.
    \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}
\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:
