\chapter{Dependencies} \label{ch:dependencies} \section{Dependency Classes} \label{sec:dependency-classes} \begin{centertable}{Dependency classes required to be satisfied for a particular phase function} \label{tab:phase-function-dependency-classes} \begin{tabular}{P{13.5em} P{0.6\textwidth}} \toprule \multicolumn{1}{c}{\textbf{Phase function}} & \multicolumn{1}{c}{\textbf{Satisfied dependency classes}} \\ \midrule \t{pkg_pretend}, \t{pkg_info}, \t{pkg_nofetch} & None (ebuilds can rely only on the packages in the system~set) \\ \addlinespace \t{pkg_setup} & Same as \t{src_unpack} if executed as part of source build, same as \t{pkg_pretend} otherwise \\ \addlinespace \t{src_unpack}, \t{src_prepare}, \t{src_configure}, \t{src_compile}, \t{src_test}, \t{src_install} & \t{DEPEND}, \t{BDEPEND} \\ \addlinespace \t{pkg_preinst}, \t{pkg_postinst}, \t{pkg_prerm}, \t{pkg_postrm} & \t{RDEPEND}, \t{IDEPEND} \\ \addlinespace \t{pkg_config} & \t{RDEPEND}, \t{PDEPEND} \\ \bottomrule \end{tabular} \end{centertable} \begin{centertable}{Summary of other interfaces related to dependency classes} \label{tab:dep-class-api} \begin{tabular}{llll} \toprule & \t{BDEPEND}, \t{IDEPEND} & \t{DEPEND} & \t{RDEPEND}, \t{PDEPEND} \\ \midrule Binary compatible with & \t{CBUILD} & \t{CHOST} & \t{CHOST} \\ Base unprefixed path & \t{/} & \t{\$\{SYSROOT\}} & \t{\$\{ROOT\}} \\ Relevant offset-prefix & \t{\$\{BROOT\}} & See table~\ref{tab:depend-prefix} & \t{\$\{EPREFIX\}} \\ Path combined with prefix & \t{\$\{BROOT\}} & \t{\$\{ESYSROOT\}} & \t{\$\{EROOT\}} \\ PM query command option & \t{-b} & \t{-d} & \t{-r} \\ \bottomrule \end{tabular} \end{centertable} \begin{centertable}{Prefix values for \t{DEPEND}} \label{tab:depend-prefix} \begin{tabular}{llll} \toprule If \t{SYSROOT} is: & \t{\$\{ROOT\}} & Empty, and \t{ROOT} is non-empty & Other \\ \midrule Then offset-prefix is: & \t{\$\{EPREFIX\}} & \t{\$\{BROOT\}} & Empty \\ And \t{ESYSROOT} is: & \t{\$\{EROOT\}} & \t{\$\{BROOT\}} & \t{\$\{SYSROOT\}} \\ \bottomrule \end{tabular} \end{centertable} There are three classes of dependencies supported by ebuilds: \begin{compactitem} \item Build dependencies (\t{DEPEND}). These must be installed and usable before the \t{pkg_setup} phase function is executed as a part of source build and throughout all \t{src_*} phase functions executed as part of that build. These may not be installed at all if a binary package is being merged. \item Runtime dependencies (\t{RDEPEND}). These must be installed and usable before the results of an ebuild merging are treated as usable. \item Post dependencies (\t{PDEPEND}). These must be installed at some point before the package manager finishes the batch of installs. \end{compactitem} \featurelabel{bdepend} Additionally, in EAPIs listed in table~\ref{tab:depend-table} as supporting \t{BDEPEND}, the build dependencies are split into two subclasses: \begin{compactitem} \item \t{BDEPEND} build dependencies that are binary compatible with the native build system (\t{CBUILD}). The ebuild is allowed to call binary executables installed by this kind of dependency. \item \t{DEPEND} build dependencies that are binary compatible with the system being built (\t{CHOST}). The ebuild must not execute binary executables installed by this kind of dependency. \end{compactitem} \featurelabel{idepend} Additionally, in EAPIs listed in table~\ref{tab:depend-table} as supporting \t{IDEPEND}, install-time dependencies can be specified. These dependencies are binary compatible with the native build system (\t{CBUILD}). Ebuilds are allowed to call them in \t{pkg_preinst} and \t{pkg_postinst}. Ebuilds may also call them in \t{pkg_prerm} and \t{pkg_postrm} but must not rely on them being available. \ChangeWhenAddingAnEAPI{8} \begin{centertable}{EAPIs supporting additional dependency types} \label{tab:depend-table} \begin{tabular}{lll} \toprule \multicolumn{1}{c}{\textbf{EAPI}} & \multicolumn{1}{c}{\textbf{Supports \t{BDEPEND}?}} & \multicolumn{1}{c}{\textbf{Supports \t{IDEPEND}?}} \\ \midrule 0, 1, 2, 3, 4, 5, 6 & No & No \\ 7 & Yes & No \\ 8 & Yes & Yes \\ \bottomrule \end{tabular} \end{centertable} Table~\ref{tab:phase-function-dependency-classes} lists dependencies which must be satisfied before a particular phase function is executed. Table~\ref{tab:dep-class-api} summarises additional interfaces related to the dependency classes. In addition, \t{HOMEPAGE}, \t{SRC_URI}, \t{LICENSE}, \t{REQUIRED_USE}, \t{PROPERTIES} and \t{RESTRICT} use dependency-style specifications to specify their values. \section{Dependency Specification Format} \label{sec:dependency-spec} The following elements are recognised in at least one class of specification. All elements must be surrounded on both sides by whitespace, except at the start and end of the string. \begin{compactitem} \item A package dependency specification. Permitted in \t{DEPEND}, \t{BDEPEND}, \t{RDEPEND}, \t{PDEPEND}, \t{IDEPEND}. \item A URI, in the form \t{proto://host/path}. Permitted in \t{HOMEPAGE} and \t{SRC_URI}\@. In EAPIs listed in table~\ref{tab:uri-arrows-table} as supporting \t{SRC_URI} arrows, may optionally be followed by whitespace, then \t{->}, then whitespace, then a simple filename when in \t{SRC_URI}\@. For \t{SRC_URI} behaviour, see section~\ref{sec:src-uri-behaviour}. \item A flat filename. Permitted in \t{SRC_URI}. \item A license name (e.\,g.\ \t{GPL-2}). Permitted in \t{LICENSE}. \item A use flag name, optionally preceded by an exclamation mark. Permitted in \t{REQUIRED_USE}. \item A simple string. Permitted in \t{PROPERTIES} and \t{RESTRICT}. \item An all-of group, which consists of an open parenthesis, followed by whitespace, followed by one or more of (a dependency item of any kind followed by whitespace), followed by a close parenthesis. More formally: \t{all-of} \t{::=} \t{'(' whitespace (item whitespace)+ ')'}. Permitted in all specification style variables. \item An any-of group, which consists of the string \t{||}, followed by whitespace, followed by an open parenthesis, followed by whitespace, followed by one or more of (a dependency item of any kind followed by whitespace), followed by a close parenthesis. More formally: \t{any-of} \t{::=} \t{'||' whitespace '(' whitespace (item whitespace)+ ')'}. Permitted in \t{DEPEND}, \t{BDEPEND}, \t{RDEPEND}, \t{PDEPEND}, \t{IDEPEND}, \t{LICENSE}, \t{REQUIRED_USE}. \item An exactly-one-of group, which has the same format as the any-of group, but begins with the string \t{\textasciicircum\textasciicircum} instead. Permitted in \t{REQUIRED_USE}. \item \featurelabel{at-most-one-of} An at-most-one-of group, which has the same format as the any-of group, but begins with the string \t{??}\ instead. Permitted in \t{REQUIRED_USE} in EAPIs listed in table~\ref{tab:at-most-one-of-table} as supporting \t{REQUIRED_USE ??}\ groups. \item A use-conditional group, which consists of an optional exclamation mark, followed by a use flag name, followed by a question mark, followed by whitespace, followed by an open parenthesis, followed by whitespace, followed by one or more of (a dependency item of any kind followed by whitespace), followed by a close parenthesis. More formally: \t{use-conditional} \t{::=} \t{'!'?\ flag-name '?'\ whitespace '(' whitespace (item whitespace)+ ')'}. Permitted in all specification style variables. \end{compactitem} In particular, note that whitespace is not optional. \ChangeWhenAddingAnEAPI{8} \begin{centertable}{EAPIs supporting \t{REQUIRED_USE ??}\ groups} \label{tab:at-most-one-of-table} \begin{tabular}{ll} \toprule \multicolumn{1}{c}{\textbf{EAPI}} & \multicolumn{1}{c}{\textbf{Supports \t{REQUIRED_USE ??}\ groups?}} \\ \midrule 0, 1, 2, 3, 4 & No \\ 5, 6, 7, 8 & Yes \\ \bottomrule \end{tabular} \end{centertable} \subsection{All-of dependency specifications} In an all-of group, all of the child elements must be matched. \subsection{USE-conditional dependency specifications} In a use-conditional group, if the associated use flag is enabled (or disabled if it has an exclamation mark prefix), all of the child elements must be matched. It is an error for a flag to be used if it is not included in \t{IUSE_EFFECTIVE} as described in section~\ref{sec:use-iuse-handling}. \subsection{Any-of dependency specifications} Any use-conditional group that is an immediate child of an any-of group, if not enabled (disabled for an exclamation mark prefixed use flag name), is not considered a member of the any-of group for match purposes. In an any-of group, at least one immediate child element must be matched. A blocker is considered to be matched if its associated package dependency specification is not matched. \featurelabel{empty-dep-groups} In EAPIs specified in table~\ref{tab:empty-dep-groups}, an empty any-of group counts as being matched. \subsection{Exactly-one-of dependency specifications} Any use-conditional group that is an immediate child of an exactly-one-of group, if not enabled (disabled for an exclamation mark prefixed use flag name), is not considered a member of the exactly-one-of group for match purposes. In an exactly-one-of group, exactly one immediate child element must be matched. In EAPIs specified in table~\ref{tab:empty-dep-groups}, an empty exactly-one-of group counts as being matched. \ChangeWhenAddingAnEAPI{8} \begin{centertable}{Matching of empty dependency groups in EAPIs} \label{tab:empty-dep-groups} \begin{tabular}{ll} \toprule \multicolumn{1}{c}{\textbf{EAPI}} & \multicolumn{1}{c}{\textbf{Empty \t{||} and \t{\textasciicircum\textasciicircum} groups are matched?}} \\ \midrule 0, 1, 2, 3, 4, 5, 6 & Yes \\ 7, 8 & No \\ \bottomrule \end{tabular} \end{centertable} \subsection{At-most-one-of dependency specifications} Any use-conditional group that is an immediate child of an at-most-one-of group, if not enabled (disabled for an exclamation mark prefixed use flag name), is not considered a member of the at-most-one-of group for match purposes. In an at-most-one-of group, at most one immediate child element must be matched. \section{Package Dependency Specifications} A package dependency can be in one of the following base formats. A package manager must warn or error on non-compliant input. \begin{compactitem} \item A simple \t{category/package} name. \item An operator, as described in section~\ref{sec:dep-operator}, followed immediately by \t{category/package}, followed by a hyphen, followed by a version specification. \end{compactitem} In EAPIs shown in table~\ref{tab:slot-deps-table} as supporting \t{SLOT} dependencies, either of the above formats may additionally be suffixed by a \t{:slot} restriction, as described in section~\ref{sec:slot-dep}. A package manager must warn or error if slot dependencies are used with an EAPI not supporting \t{SLOT} dependencies. \featurelabel{use-deps} In EAPIs shown in table~\ref{tab:use-deps-table} as supporting 2-style or 4-style \t{USE} dependencies, a specification may additionally be suffixed by at most one 2-style or 4-style \t{[use]} restriction, as described in section~\ref{sec:use-dep}. A package manager must warn or error if this feature is used with an EAPI not supporting use dependencies. \note{Order is important. The slot restriction must come before use dependencies.} \ChangeWhenAddingAnEAPI{8} \begin{centertable}{Support for \t{SLOT} dependencies and sub-slots in EAPIs} \label{tab:slot-deps-table} \begin{tabular}{lll} \toprule \multicolumn{1}{c}{\textbf{EAPI}} & \multicolumn{1}{c}{\textbf{Supports \t{SLOT} dependencies?}} & \multicolumn{1}{c}{\textbf{Supports sub-slots?}} \\ \midrule 0 & No & No \\ 1, 2, 3, 4 & Named only & No \\ 5, 6, 7, 8 & Named and operator & Yes \\ \bottomrule \end{tabular} \end{centertable} \ChangeWhenAddingAnEAPI{8} \begin{centertable}{EAPIs supporting \t{USE} dependencies} \label{tab:use-deps-table} \begin{tabular}{ll} \toprule \multicolumn{1}{c}{\textbf{EAPI}} & \multicolumn{1}{c}{\textbf{Supports \t{USE} dependencies?}} \\ \midrule 0, 1 & No \\ 2, 3 & 2-style \\ 4, 5, 6, 7, 8 & 4-style \\ \bottomrule \end{tabular} \end{centertable} \subsection{Operators} \label{sec:dep-operator} The following operators are available: \begin{description} \item[\t{<}] Strictly less than the specified version. \item[\t{<=}] Less than or equal to the specified version. \item[\t{=}] Exactly equal to the specified version. Special exception: if the version specified has an asterisk immediately following it, then only the given number of version components is used for comparison, i.\,e.\ the asterisk acts as a wildcard for any further components. When an asterisk is used, the specification must remain valid if the asterisk were removed. (An asterisk used with any other operator is illegal.) \item[\t{\textasciitilde}] Equal to the specified version when revision parts are ignored. \item[\t{>=}] Greater than or equal to the specified version. \item[\t{>}] Strictly greater than the specified version. \end{description} \subsection{Block operator} If the specification is prefixed with one or two exclamation marks, the named dependency is a block rather than a requirement---that is to say, the specified package must not be installed. As an exception, weak blocks on the package version of the ebuild itself do not count. \featurelabel{bang-strength} There are two strengths of block: weak and strong. A weak block may be ignored by the package manager, so long as any blocked package will be uninstalled later on. A strong block must not be ignored. The mapping from one or two exclamation marks to strength is described in table~\ref{tab:bang-strength-table}. \ChangeWhenAddingAnEAPI{8} \begin{centertable}{Exclamation mark strengths for EAPIs} \label{tab:bang-strength-table} \begin{tabular}{lll} \toprule \multicolumn{1}{c}{\textbf{EAPI}} & \multicolumn{1}{c}{\textbf{\t{!}}} & \multicolumn{1}{c}{\textbf{\t{!!}}} \\ \midrule 0, 1 & Unspecified & Forbidden \\ 2, 3, 4, 5, 6, 7, 8 & Weak & Strong \\ \bottomrule \end{tabular} \end{centertable} \subsection{Slot dependencies} \label{sec:slot-dep} \featurelabel{slot-deps} A named slot dependency consists of a colon followed by a slot name. A specification with a named slot dependency matches only if the slot of the matched package is equal to the slot specified. If the slot of the package to match cannot be determined (e.\,g.\ because it is not a supported EAPI, the match is treated as unsuccessful. \featurelabel{sub-slot} In EAPIs shown in table~\ref{tab:slot-deps-table} as supporting sub-slots, a slot dependency may contain an optional sub-slot part that follows the regular slot and is delimited by a \t{/} character. \featurelabel{slot-operator-deps} An operator slot dependency consists of a colon followed by one of the following operators: \nobreakpar \begin{description} \item[*] Indicates that any slot value is acceptable. In addition, for runtime dependencies, indicates that the package will not break if the matched package is uninstalled and replaced by a different matching package in a different slot. \item[=] Indicates that any slot value is acceptable. In addition, for runtime dependencies, indicates that the package will break unless a matching package with slot and sub-slot equal to the slot and sub-slot of the best version installed as a build-time (\t{DEPEND}) dependency is available. \item[slot=] Indicates that only a specific slot value is acceptable, and otherwise behaves identically to the plain equals slot operator. \end{description} To implement the equals slot operator, the package manager will need to store the slot/sub-slot pair of the best installed version of the matching package. This syntax is only for package manager use and must not be used by ebuilds. The package manager may do this by inserting the appropriate slot/sub-slot pair between the colon and equals sign when saving the package's dependencies. The sub-slot part must not be omitted here (when the SLOT variable omits the sub-slot part, the package is considered to have an implicit sub-slot which is equal to the regular slot). Whenever the equals slot operator is used in an enabled dependency group, the dependencies (\t{DEPEND}) must ensure that a matching package is installed at build time. It is invalid to use the equals slot operator inside \t{PDEPEND} or inside any-of dependency specifications. \subsection{2-style and 4-style USE dependencies} \label{sec:use-dep} A 2-style or 4-style use dependency consists of one of the following: \nobreakpar \begin{description} \item[{[opt]}] The flag must be enabled. \item[{[opt=]}] The flag must be enabled if the flag is enabled for the package with the dependency, or disabled otherwise. \item[{[!opt=]}] The flag must be disabled if the flag is enabled for the package with the dependency, or enabled otherwise. \item[{[opt?]}] The flag must be enabled if the flag is enabled for the package with the dependency. \item[{[!opt?]}] The flag must be disabled if the use flag is disabled for the package with the dependency. \item[{[-opt]}] The flag must be disabled. \end{description} Multiple requirements may be combined using commas, e.\,g.\ \t{[first,-second,third?]}. When multiple requirements are specified, all must match for a successful match. \featurelabel{use-dep-defaults} In a 4-style use dependency, the flag name may immediately be followed by a \emph{default} specified by either \t{(+)} or \t{(-)}. The former indicates that, when applying the use dependency to a package that does not have the flag in question in \t{IUSE_REFERENCEABLE}, the package manager shall behave as if the flag were present and enabled; the latter, present and disabled. Unless a 4-style default is specified, it is an error for a use dependency to be applied to an ebuild which does not have the flag in question in \t{IUSE_REFERENCEABLE}. \note{By extension of the above, a default that could reference an ebuild using an EAPI not supporting profile \t{IUSE} injections cannot rely upon any particular behaviour for flags that would not have to be part of \t{IUSE}.} It is an error for an ebuild to use a conditional use dependency when that ebuild does not have the flag in \t{IUSE_EFFECTIVE}. % 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: