\chapter{Introduction}

\section{Aims and Motivation}

This document aims to fully describe the format of an ebuild repository and the ebuilds therein, as
well as certain aspects of package manager behaviour required to support such a repository.

This document is \i{not} designed to be an introduction to ebuild development. Prior knowledge of
ebuild creation and an understanding of how the package management system works is assumed; certain
less familiar terms are explained in the Glossary in chapter~\ref{glossary}.

This document does not specify any user or package manager configuration information.

\section{Rationale}

At present the only definition of what an ebuild can assume about its environment,
and the only definition of what is valid in an ebuild, is the source code of the latest Portage release
and a general consensus about which features are too new to assume availability. This has several
drawbacks: not only is it impossible to change any aspect of Portage behaviour without verifying
that nothing in the tree relies upon it, but if a new package manager should appear it becomes
impossible to fully support such an ill-defined standard.

This document aims to address both of these concerns by defining almost all aspects of what an
ebuild repository looks like, and how an ebuild is allowed to behave. Thus, both Portage and other
package managers can change aspects of their behaviour not defined here without worry of
incompatibilities with any particular repository.

\section{Conventions}

Text in \t{teletype} is used for filenames or variable names. \i{Italic} text is used for terms
with a particular technical meaning in places where there may otherwise be ambiguity.

The term \i{package manager} is used throughout this document in a broad sense. Although some parts
of this document are only relevant to fully featured package managers, many items are equally
applicable to tools or other applications that interact with ebuilds or ebuild repositories.

\section{EAPIs}

An EAPI can be thought of as a `version' of this specification to which a package conforms. An EAPI
value is a string. The following EAPIs are defined by this specification:

\begin{description}
\item[0] The `original' base EAPI.
\item[1] EAPI `1' contains a number of extensions to EAPI `0'. Except where explicitly noted, it is
    in all other ways identical to EAPI `0'.
\IFKDEBUILDELSE
{
    \item[kdebuild-1] A series of extensions to EAPI `1' used by the Gentoo KDE project. Except where
        explicitly noted, it is in all other ways identical to EAPI `1'.
}{
}
\end{description}

\ifthenelse{\boolean{ENABLE-ALL-OPTIONS}}
{
    \note We're not sure whether \t{kdebuild-1} will end up in the final version of this
    specification. For now, it's included but can easily be hidden using a switch in the master
    \t{pms.tex} file. To make editing easier, we also have a mode that shows the document both with
    and without the \t{kdebuild-1} stuff enabled. You currently have that mode enabled---
    \IFKDEBUILDELSE{
        text only shown when \t{kdebuild-1} is enabled looks like this,
    }{
        and text only shown when it is disabled looks like this.
    }
}{
}

Except where explicitly noted, everything in this specification applies to all EAPIs.

If a package manager encounters a package version with an unrecognised EAPI, it must not attempt to
perform any operations upon it. It could, for example, ignore the package version entirely (although
this can lead to user confusion), or it could mark the package version as masked. A package manager
must not use any metadata generated from a package with an unrecognised EAPI.

The package manager must not attempt to perform any kind of comparison test other than equality upon
EAPIs.

\subsection{Reserved EAPIs}

\begin{compactitem}
\item EAPIs whose value consists purely of an integer are reserved for future versions of this
    specification.
\item EAPIs whose value starts with the string \t{paludis-} are reserved for experimental
    use by the Paludis package manager.
\item EAPIs whose value starts with the string \t{kdebuild-} are reserved for the Gentoo KDE
    project.
\end{compactitem}

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

%%% Local Variables:
%%% mode: latex
%%% TeX-master: "pms"
%%% End:
