\chapter{metadata.xml}
\label{sec:metadata-xml}

The \t{metadata.xml} file is used to contain extra package- or category-level information beyond
what is stored in ebuild metadata. Its exact format is strictly beyond the scope of this document,
and is described in the DTD file located at \url{https://www.gentoo.org/dtd/metadata.dtd}.

\chapter{Unspecified Items}

The following items are not specified by this document, and must not be relied upon by ebuilds.
This is, of course, an incomplete list---it covers only the things that the authors know have
been abused in the past.

\begin{compactitem}
\item The \t{FEATURES} variable. This is Portage specific.
\item Similarly, any \t{EMERGE\_} variable and any \t{PORTAGE\_} variable not explicitly listed.
\item Any Portage configuration file.
\item The VDB (\t{/var/db/pkg}). Ebuilds must not access this or rely upon it existing or being
    in any particular format.
\item The \t{portageq} command. The \t{has\_version} and \t{best\_version} commands are
    available as functions.
\item The \t{emerge} command.
\item Binary packages.
\item The \t{PORTDIR\_OVERLAY} variable, and overlay behaviour in general.
\end{compactitem}

\chapter{Historical Curiosities}

The items described in this chapter are included for information only. They were deprecated or
abandoned long before \t{EAPI} was introduced. Ebuilds must not use these features, and package
managers should not be changed to support them.

\section{If-else use blocks}

Historically, Portage supported if-else use conditionals, as shown by
listing~\ref{lst:if-else-use-listing}. The block before the colon would be taken if the condition
was met, and the block after the colon would be taken if the condition was not met.

This feature was deprecated and removed from the tree long before the introduction of \t{EAPI}.

\begin{listing}
\caption{If-else use blocks} \label{lst:if-else-use-listing}
\begin{verbatim}
DEPEND="
    flag? (
        taken/if-true
    ) : (
        taken/if-false
    )
    "
\end{verbatim}
\end{listing}

\section{cvs Versions}

Portage has very crude support for CVS packages. The package \t{foo} could contain a file named
\t{foo-cvs.1.2.3.ebuild}. This version would order \e{higher} than any non-CVS version (including
\t{foo-2.ebuild}). This feature has not seen real world use and breaks versioned dependencies, so
it must not be used.

\section{use.defaults}

The \t{use.defaults} file in the profile directory was used to implement `autouse'---switching USE
flags on or off depending upon which packages are installed. It was deprecated long ago and finally
removed in 2009.

\section{Old-style Virtuals}

Historically, virtuals were special packages rather than regular ebuilds. An ebuild could specify in
the \t{PROVIDE} metadata that it supplied certain virtuals, and the package manager had to bear this
in mind when handling dependencies.

Old-style virtuals were supported by EAPIs \t{0}, \t{1}, \t{2}, \t{3} and \t{4}, and were phased out
via GLEP 37~\cite{Glep37}.

% 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:
