path: root/tree-layout.tex

\chapter{Tree Layout}

This chapter defines the layout on-disk of an ebuild repository. In all cases below where a file or
directory is specified, a symlink to a file or directory is also valid. In this case, the package
manager must follow the operating system's semantics for symbolic links and must not behave
differently from normal.

\section{Top Level}

An ebuild repository shall occupy one directory on disk, with the following subdirectories:
\begin{bulletlist}
\item One directory per category, whose name shall be the name of the category. The layout of
    these directories shall be as described in section \ref{category-dirs}.
\item A \t{profiles} directory, described in section \ref{profiles-dir}.
\item A \t{licenses} directory (optional), described in section \ref{licenses-dir}.
\item An \t{eclass} directory (optional), described in section \ref{eclass-dir}.
\item A \t{metadata} directory (optional), described in section \ref{metadata-dir}.
\item Other optional support files and directories (skeleton ebuilds or ChangeLogs,
    for example) may exist but are not covered by this specification. The package manager must
    ignore any of these files or directories that it does not recognise.

\end{bulletlist}

\section{Category Directories}
\label{category-dirs}

Each category provided by the repository (see also: the \t{profiles/categories} file, section
\ref{profiles-categories}) shall be contained in one directory, whose name shall be that of the
category. Each category directory shall contain:
\begin{bulletlist}
\item A \t{metadata.xml} file, as described in appendix \ref{metadata-xml}\@. Optional.
\item Zero or more package directories, one for each package in the category, as described in section
    \ref{package-dirs}. The name of the package directory shall be the corresponding package name.
\end{bulletlist}

Category directories may contain additional files, whose purpose is not covered by this
specification. Additional directories that are not for a package may \i{not} be present, to avoid
conflicts with package name directories; an exception is made for filesystem components whose name
starts with a dot, which the package manager must ignore, and for any directory named \t{CVS}.

A category directory may not exist. A category directory that does not exist shall be considered
equivalent to an empty category (and by extension, a package manager may treat an empty category as
a category that does not exist).

\section{Package Directories}
\label{package-dirs}

A package directory contains the following:
\begin{bulletlist}
\item One or more ebuilds. These are as described in section \ref{ebuild-format} and others.
\item A \t{metadata.xml} file, as described in appendix \ref{metadata-xml}\@. Optional only for
    legacy support.
\item A \t{ChangeLog}, in a format determined by the provider of the respository. Optional.
\item A \t{Manifest} file, whose format is described in \cite{Glep44}.
\item A \t{files} directory, containing any support files needed by the ebuilds. Optional.
\end{bulletlist}

Any ebuild in a package directory must be named \t{name-ver.ebuild}, where \t{name} is the
(unqualified) package name, and \t{ver} is the package's version. Package managers must ignore
any ebuild file that does not match these rules.

A package directory that contains no correctly named ebuilds shall be considered a package with no
versions. A package with no versions shall be considered equivalent to a package that does not
exist (and by extension, a package manager may treat a package that does not exist as a package
with no versions).

A package directory may contain other files or directories, whose purpose is not covered by
this specification.

\section{The Profiles Directory}
\label{profiles-dir}

The profiles directory shall contain zero or more profile directories as described in section
\ref{profiles}, as well as the following files and directories. In any line-based file, lines
beginning with a \# character are treated as comments, whilst blank lines are ignored. All contents
of this directory, with the exception of \t{repo\_name}, are optional.

If the repository is not intended to be stand-alone, the contents of these files are to be taken
from or merged with the master repository as necessary.

Other files not described by this specification may exist, but may not be relied upon. The package
manager must ignore any files in this directory that it does not recognise.

\begin{description}
\item[arch.list] \label{arch.list} Contains a list, one entry per line, of permissible values for
    the \t{ARCH} variable, and hence permissible keywords for packages in this repository.
\item[categories] \label{profiles-categories} Contains a list, one entry per line, of categories
    provided by this repository.
\item[info\_pkgs] Contains a list, one entry per line, of qualified package names. Any package
    matching one of these is to be listed when a package manager displays a `system information'
    listing.
\item[info\_vars] Contains a list, one entry per line, of profile, configuration, and environment
    variables which are considered to be of interest. The value of each of these variables may be
    shown when the package manager displays a `system information' listing.
\item[package.mask] \label{profiles-package.mask}
    Contains a list, one entry per line, of (EAPI-0) package dependency specifications. Any package
    version matching one of these is considered to be masked, and will not be installed regardless
    of profile unless it is unmasked by the user configuration.
\item[profiles.desc] Described below in section \ref{profiles.desc}.
\item[repo\_name] Contains, on a single line, the name of this repository. The repository name must
    conform to section \ref{repository-names}.
\item[thirdpartymirrors] Described below in section \ref{thirdpartymirrors}.
\item[use.desc] Contains descriptions of valid global USE flags for this repository. The format is
    described in section \ref{use.desc}.
\item[use.local.desc] Contains descriptions of valid local USE flags for this repository, along with
    the packages to which they apply. The format is as described in section \ref{use.desc}.
\item[desc/] This directory contains files analogous to \t{use.desc} for the various \t{USE\_EXPAND}
    variables. Each file in it is named \t{<varname>.desc}, where \t{<varname>} is the variable
    name, in lowercase, whose possible values the file describes. The format of each file is as for
    \t{use.desc}, described in section \ref{use.desc}. The \t{USE\_EXPAND} name is \i{not}
    included as a prefix here.
\item[updates/] This directory is described in section \ref{updates-dir}.
\end{description}

\subsection{The profiles.desc file}
\label{profiles.desc}
\t{profiles.desc} is a line-based file, with the standard commenting rules from section
\ref{profiles-dir}, containing a list of profiles that are valid for use, along with their
associated architecture and status. Each line has the format:
\begin{verbatim}
<keyword> <profile path> stable|dev
\end{verbatim}
Where \t{<keyword>} is the default keyword for the profile and the \t{ARCH} for which the profile is
valid, \t{<profile path>} is the (relative) path from the \t{profiles} directory to the profile in
question, and the third field is either \t{stable} or \t{dev}, depending upon whether the profile is
reckoned to be `stable' for normal use. Fields are whitespace-delimited. The last field is of most
use to QA scanning tools, which may display certain errors with reduced severity should they appear
in a `dev' profile.

\subsection{The thirdpartymirrors file}
\label{thirdpartymirrors}
\t{thirdpartymirrors} is another simple line-based file, describing the valid mirrors for use with
\t{mirror://} URIs in this repository, and the associated download locations. The format of each
line is:
\begin{verbatim}
<mirror name> <mirror 1> <mirror 2> ... <mirror n>
\end{verbatim}
Fields are whitespace-delimited. When parsing a URI of the form \t{mirror://name/path/filename},
where the \t{path/} part is optional, the \t{thirdpartymirrors} file is searched for a line whose
first field is \t{name}. Then the download URIs in the subsequent fields have \t{path/filename}
appended to them to generate the URIs from which a download is attempted.

Each mirror name may appear at most once in a file. Behaviour when a mirror name appears multiple
times is undefined. Behaviour when a mirror is defined in terms of another mirror is undefined. A
package manager may choose to fetch from all of or a subset of the listed mirrors, and may use an
order other than the one described.

The mirror with the name equal to the repository's name (and if the repository has a master,
the master's name) may be consulted for all downloads.

\subsection{use.desc and related files}
\label{use.desc}
\t{use.desc} contains descriptions of every valid global USE flag for this repository. It is a
line-based file with the standard rules for comments and blank lines. The format of each line is:
\begin{verbatim}
<flagname> - <description>
\end{verbatim}

\t{use.local.desc} contains descriptions of every valid local USE flag---those that apply only to a
small number of packages, or that have different meanings for different packages. Its format is:
\begin{verbatim}
<category/package>:<flagname> - <description>
\end{verbatim}
Flags must be listed once for each package to which they apply, or if a flag is listed in both
\t{use.desc} and \t{use.local.desc}, it must be listed once for each package for which its meaning
differs from that described in \t{use.desc}.

\subsection{The updates directory}
\label{updates-dir}
The \t{updates} directory is used to inform the package manager that a package has moved categories,
names, or that a version has changed SLOT. It contains one file per quarter year, named
\t{[1-4]Q-[YYYY]} for the first to fourth quarter of a given year, for example \t{1Q-2004} or
\t{3Q-2006}. The format of each file is again line-based, with each line having one of the following
formats:
\begin{verbatim}
move <qpn1> <qpn2>
slotmove <spec> <slot1> <slot2>
\end{verbatim}
The first form, where \t{qpn1} and \t{qpn2} are \i{qualified package names}, instructs the package
manager that the package \t{qpn1} has changed name, category, or both, and is now called \t{qpn2}.

The second form instructs the package manager that any currently installed package version matching
package dependency specification \t{spec} whose \t{SLOT} is set to \t{slot1} should have it updated
to \t{slot2}.

Any name that has appeared as the origin of a move must not be reused in the future. Any slot
that has appeared as the origin of a slot move may not be used by packages matching the spec of
that slot move in the future.

\section{The Licenses Directory}
\label{licenses-dir}

The \t{licenses} directory shall contain copies of the licenses used by packages in the
repository. Each file will be named according to the name used in the \t{LICENSE} variable as
described in section \ref{ebuild-var-LICENSE}, and will contain the complete text of the license in
human-readable form. Plain text format is strongly preferred but not required.

\section{The Eclass Directory}
\label{eclass-dir}

The \t{eclass} directory shall contain copies of the eclasses provided by this repository. The
format of these files is described in section \ref{eclasses}. It may also contain, in their own
directory, support files needed by these eclasses.

\section{The Metadata Directory}
\label{metadata-dir}

The \t{metadata} directory contains various repository-level metadata that is not contained in
\t{profiles/}. All contents are optional. In this standard only the \t{cache} subdirectory is
described; other contents are optional but may include security advisories, DTD files for the
various XML files used in the repository, and repository timestamps.

\subsection{The metadata cache}

The \t{metadata/cache} directory contains a cached form of all important ebuild metadata variables.
The cache directory, if it exists, contains directories whose names are the same as categories in
the repository---not all categories and packages must be contained in it. Each subdirectory may
optionally contain one file per package version in that category, named \t{<package>-<version>},
in the following format:

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{enumerate}
\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 No longer used; this line is to be ignored.
\item Post dependencies (\t{PDEPEND})
\item Old-style virtuals provided by this package (\t{PROVIDE})
\item The ebuild API version to which this package conforms (\t{EAPI})
\item Blank lines to pad the file to 22 lines long
\end{enumerate}

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 14, if such a concept makes sense for that EAPI, and will place a value that is clearly
not a supported EAPI on line 14 if it does not.

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