\chapter{Metadata Cache}
\label{ch:metadata-cache}

\section{Directory Contents}

The \t{metadata/cache} or \t{metadata/md5-cache} directories, if either of them exists, contain
directories whose names are the same as categories in the repository. Each subdirectory may
optionally contain one file per package version in that category, named \t{<package>-<version>},
in one of the formats described below.

The metadata cache may be incomplete or non-existent, and may contain additional bogus entries.

\section{Legacy Cache File Format}
\label{sec:legacy-cache}

The legacy cache file format is used in the \t{metadata/cache} directory. Each cache file contains
the textual values of various metadata keys, one per line, in the following order. Other lines may
be present following these; their meanings are not defined here.

\begin{compactenum}
\item Build-time dependencies (\t{DEPEND})
\item Run-time dependencies (\t{RDEPEND})
\item Slot (\t{SLOT})
\item Source tarball URIs (\t{SRC_URI})
\item \t{RESTRICT}
\item Package homepage (\t{HOMEPAGE})
\item Package license (\t{LICENSE})
\item Package description (\t{DESCRIPTION})
\item Package keywords (\t{KEYWORDS})
\item Inherited eclasses (\t{INHERITED})
\item Use flags that this package respects (\t{IUSE})
\item Use flags that this package requires (\t{REQUIRED_USE}).
    Blank in some EAPIs; see table~\ref{tab:optional-vars-table}.
\item Post dependencies (\t{PDEPEND})
\item Build-time dependencies for \t{CBUILD} host (\t{BDEPEND}).
    Blank in some EAPIs; see table~\ref{tab:depend-table}.
\item The ebuild API version to which this package conforms (\t{EAPI})
\item Properties (\t{PROPERTIES}). In some EAPIs, may optionally be blank, regardless of ebuild
    metadata; see table~\ref{tab:optional-vars-table}.
\item Defined phases (\t{DEFINED_PHASES}). In some EAPIs, may optionally be blank, regardless of
    ebuild metadata; see table~\ref{tab:defined-phases-table}.
\item Install-time dependencies (\t{IDEPEND}).
    Blank in some EAPIs; see table~\ref{tab:depend-table}.
\item Blank lines to pad the file to 22 lines long
\end{compactenum}

Future EAPIs may define new variables, remove existing variables, change the line number or
format used for a particular variable, add or reduce the total length of the file and so on.
Any future EAPI that uses this cache format will continue to place the EAPI value on line~15 if
such a concept makes sense for that EAPI, and will place a value that is clearly not a supported
EAPI on line~15 if it does~not.

\section{md5-dict Cache File Format}

The ``md5-dict'' cache file format is used in the \t{metadata/md5-cache} directory. Each cache file
contains \t{<key>=<value>} pairs, one per line, in arbitrary order. The keys are the same as those
listed in section~\ref{sec:legacy-cache} except the \t{INHERITED} key. In addition, keys \t{_md5_}
and \t{_eclasses_} contain values as defined below.

\begin{description}
\item[_md5_] The MD5 checksum of the ebuild for the package version.

\item[_eclasses_] A list of \i{name-checksum} pairs for all eclasses directly or indirectly
inherited by the ebuild, in arbitrary order, where \i{name} is the eclass name and \i{checksum}
is the MD5 checksum of the eclass. Pairs are separated from each other by single tab characters,
as are \i{name} and \i{checksum} in each pair.
\end{description}

All MD5 checksums are computed and formatted as described in RFC~1321~\cite{rfc1321}.

Other keys may be present; their meanings are not defined here. Lines with an empty value can be
omitted.

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