Attachment #256799 for bug #347353




\item Post dependencies (\t{PDEPEND}). These must be installed at some point.
\end{compactitem}

In addition, \t{SRC\_URI}, \t{HOMEPAGE}, \t{PROVIDE}, \t{RESTRICT}, \t{PROPERTIES}, \t{LICENSE} and
\t{REQUIRED\_USE} use dependency-style specifications to specify their values.

\section{Dependency Specification Format}


    \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{RESTRICT} and \t{PROPERTIES}.
\item An all-of group, which consists of an open parenthesis, followed by whitespace,
    followed by zero or more of (a dependency item of any kind followed by whitespace), followed

    followed by an open parenthesis, followed by whitespace, followed by zero or more
    of (a dependency item of any kind followed by whitespace), followed by a close parenthesis.
    More formally: \t{any-of ::= '||' whitespace '(' whitespace (item whitespace)* ')'}.
    Permitted in \t{DEPEND}, \t{RDEPEND}, \t{PDEPEND}, \t{LICENSE}, \t{REQUIRED\_USE}.
\item An only-one-of group, which consists of the string \t{\textasciicircum\textasciicircum},
    followed by whitespace, followed by an open parenthesis, followed by whitespace, followed by
    zero or more of (a dependency item of any kind followed by whitespace), followed by a close
    parenthesis. More formally: \t{only-one-of ::= '\textasciicircum\textasciicircum' whitespace
    '(' whitespace (item whitespace)* ')'}.
    Permitted in \t{REQUIRED\_USE}.
\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 zero or more of (a dependency item


An empty any-of group counts as being matched.

\subsection{Only-one-of Dependency Specifications}

Any use-conditional group that is an immediate child of an only-one-of group, if not enabled
(disabled for an exclamation mark prefixed use flag name), is not considered a member of the
only-one-of group for match purposes.

In an only-one-of group, exactly one immediate child element must be matched.

An empty only-one-of group counts as being matched.

\subsection{Package Dependency Specifications}

A package dependency can be in one of the following base formats. A package manager must warn or

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}.

\subsection{Use State Constraints}
\label{sec:required-use}
\t{REQUIRED\_USE} contains a list of assertions that must be met by the configuration of \t{USE}
flags to be valid for this ebuild. In order to be matched, a \t{USE} flag in a terminal element
must be enabled (or disabled if it has an exclamation mark prefix).

If the package manager encounters a package version where \t{REQUIRED\_USE} assertions are not met,
it must treat this package version as if it was masked. No phase functions must be called.

It is an error for a flag to be used if it is not included in \t{IUSE\_EFFECTIVE}.

\subsection{Restrict}
\label{sec:restrict}


Lines 42-47 Profile \t{IUSE} injection & \compactfeatureref{profile-iuse-injection} & Link Here

(-)a/eapi-differences.tex (+4 lines)
42	\t{IUSE} defaults & \compactfeatureref{iuse-defaults} &	42	\t{IUSE} defaults & \compactfeatureref{iuse-defaults} &
43	No & Yes & Yes & Yes & Yes \\	43	No & Yes & Yes & Yes & Yes \\
44		44
		45	\t{REQUIRED\_USE} & \compactfeatureref{required-use} &
		46	No & No & No & No & Yes \\
		47
45	\t{PROPERTIES} & \compactfeatureref{properties} &	48	\t{PROPERTIES} & \compactfeatureref{properties} &
46	Optionally & Optionally & Optionally & Optionally & Yes \\	49	Optionally & Optionally & Optionally & Optionally & Yes \\
47		50
Lines 208-213 EAPI 4 is EAPI 3 with the following changes: Link Here
208		211
209	\begin{compactitem}	212	\begin{compactitem}
210	\item \t{PROPERTIES} support is mandatory, \featureref{properties}.	213	\item \t{PROPERTIES} support is mandatory, \featureref{properties}.
		214	\item \t{REQUIRED\_USE}, \featureref{required-use}.
211	\item \t{RDEPEND=DEPEND} no longer done, \featureref{rdepend-depend}.	215	\item \t{RDEPEND=DEPEND} no longer done, \featureref{rdepend-depend}.
212	\item \t{DEFINED\_PHASES} support is mandatory, \featureref{defined-phases}.	216	\item \t{DEFINED\_PHASES} support is mandatory, \featureref{defined-phases}.
213	\item Slot operator dependencies, \featureref{slot-operator-deps}.	217	\item Slot operator dependencies, \featureref{slot-operator-deps}.




\item[RESTRICT] Zero or more behaviour restrictions for this package. See section~\ref{sec:restrict}
    for value meanings and section~\ref{sec:dependencies} for full syntax.
\item[PROPERTIES] \featurelabel{properties} Zero or more properties for this package. See
    section~\ref{sec:properties} for value meanings and section~\ref{sec:dependencies} for full
    syntax. For EAPIs listed in table~\ref{tab:optional-vars-table} as having optional support,
    ebuilds must not rely upon the package manager recognising or understanding this variable in
    any way.
\item[REQUIRED\_USE] \featurelabel{required-use} Zero or more assertions that must be met by the
    configuration of \t{USE} flags to be valid for this ebuild. See section~\ref{sec:required-use}
    for description and section~\ref{sec:dependencies} for full syntax. Only in EAPIs listed in
    table~\ref{tab:optional-vars-table} as supporting \t{REQUIRED\_USE}.
\item[S] The path to the temporary build directory, used by \t{src\_compile}, \t{src\_install}
    etc. Defaults to \t{\$\{WORKDIR\}/\$\{P\}}.
\end{description}

\begin{centertable}{EAPIs supporting various ebuild-defined variables}
\label{tab:optional-vars-table}
    \begin{tabular}{ l l l }
        \toprule
        \multicolumn{1}{c}{\textbf{EAPI}} &
        \multicolumn{1}{c}{\textbf{Supports \t{PROPERTIES}?}} \\
        \multicolumn{1}{c}{\textbf{Supports \t{REQUIRED\_USE}?}} \\
        \midrule
    \t{0} & Optionally & No \\
    \t{1} & Optionally & No \\
    \t{2} & Optionally & No \\
    \t{3} & Optionally & No \\
    \t{4} & Yes & Yes \\
    \bottomrule
    \end{tabular}
\end{centertable}

Lines 34-43 The \t{inherit} command must also ensure that: Link Here

(-)a/eclasses.tex (-4 / +4 lines)
34		34
35	\section{Eclass-defined Metadata Keys}	35	\section{Eclass-defined Metadata Keys}
36		36
37	The \t{IUSE}, \t{DEPEND}, \t{RDEPEND} and \t{PDEPEND} variables are handled specially	37	The \t{IUSE}, \t{REQUIRED\_USE}, \t{DEPEND}, \t{RDEPEND} and \t{PDEPEND} variables are handled
38	when set by an eclass. They must be accumulated across eclasses, appending the value set by each	38	specially when set by an eclass. They must be accumulated across eclasses, appending the value set
39	eclass to the resulting value after the previous one is loaded. Then the eclass-defined value is	39	by each eclass to the resulting value after the previous one is loaded. Then the eclass-defined
40	appended to that defined by the ebuild. In the case of \t{RDEPEND}, this is done after the	40	value is appended to that defined by the ebuild. In the case of \t{RDEPEND}, this is done after the
41	implicit \t{RDEPEND} rules in section~\ref{sec:rdepend-depend} are applied.	41	implicit \t{RDEPEND} rules in section~\ref{sec:rdepend-depend} are applied.
42		42
43	\section{EXPORT\_FUNCTIONS}	43	\section{EXPORT\_FUNCTIONS}




\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 Old-style virtuals provided by this package (\t{PROVIDE})
\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 Blank lines to pad the file to 22 lines long
- 

Return to bug 347353

Lines 86-109 Ebuilds may define any of the following variables: Link Here

(-)a/ebuild-vars.tex (-10 / +17 lines)
86	\item[RESTRICT] Zero or more behaviour restrictions for this package. See section~\ref{sec:restrict}	86	\item[RESTRICT] Zero or more behaviour restrictions for this package. See section~\ref{sec:restrict}
87	for value meanings and section~\ref{sec:dependencies} for full syntax.	87	for value meanings and section~\ref{sec:dependencies} for full syntax.
88	\item[PROPERTIES] \featurelabel{properties} Zero or more properties for this package. See	88	\item[PROPERTIES] \featurelabel{properties} Zero or more properties for this package. See
89	section~\ref{sec:properties} for value meanings and section~\ref{sec:dependencies} for full syntax.	89	section~\ref{sec:properties} for value meanings and section~\ref{sec:dependencies} for full
90	For EAPIs listed in table~\ref{tab:properties-table} as having optional support, ebuilds must not	90	syntax. For EAPIs listed in table~\ref{tab:optional-vars-table} as having optional support,
91	rely upon the package manager recognising or understanding this variable in any way.	91	ebuilds must not rely upon the package manager recognising or understanding this variable in
		92	any way.
		93	\item[REQUIRED\_USE] \featurelabel{required-use} Zero or more assertions that must be met by the
		94	configuration of \t{USE} flags to be valid for this ebuild. See section~\ref{sec:required-use}
		95	for description and section~\ref{sec:dependencies} for full syntax. Only in EAPIs listed in
		96	table~\ref{tab:optional-vars-table} as supporting \t{REQUIRED\_USE}.
92	\item[S] The path to the temporary build directory, used by \t{src\_compile}, \t{src\_install}	97	\item[S] The path to the temporary build directory, used by \t{src\_compile}, \t{src\_install}
93	etc. Defaults to \t{\$\{WORKDIR\}/\$\{P\}}.	98	etc. Defaults to \t{\$\{WORKDIR\}/\$\{P\}}.
94	\end{description}	99	\end{description}
95		100
96	\begin{centertable}{EAPIs supporting \t{PROPERTIES}} \label{tab:properties-table}	101	\begin{centertable}{EAPIs supporting various ebuild-defined variables}
97	\begin{tabular}{ l l }	102	\label{tab:optional-vars-table}
		103	\begin{tabular}{ l l l }
98	\toprule	104	\toprule
99	\multicolumn{1}{c}{\textbf{EAPI}} &	105	\multicolumn{1}{c}{\textbf{EAPI}} &
100	\multicolumn{1}{c}{\textbf{Supports \t{PROPERTIES}?}} \\	106	\multicolumn{1}{c}{\textbf{Supports \t{PROPERTIES}?}} \\
		107	\multicolumn{1}{c}{\textbf{Supports \t{REQUIRED\_USE}?}} \\
101	\midrule	108	\midrule
102	\t{0} & Optionally \\	109	\t{0} & Optionally & No \\
103	\t{1} & Optionally \\	110	\t{1} & Optionally & No \\
104	\t{2} & Optionally \\	111	\t{2} & Optionally & No \\
105	\t{3} & Optionally \\	112	\t{3} & Optionally & No \\
106	\t{4} & Yes \\	113	\t{4} & Yes & Yes \\
107	\bottomrule	114	\bottomrule
108	\end{tabular}	115	\end{tabular}
109	\end{centertable}	116	\end{centertable}

Lines 13-20 There are three classes of dependencies supported by ebuilds: Link Here

(-)a/dependencies.tex (-3 / +31 lines)
13	\item Post dependencies (\t{PDEPEND}). These must be installed at some point.	13	\item Post dependencies (\t{PDEPEND}). These must be installed at some point.
14	\end{compactitem}	14	\end{compactitem}
15		15
16	In addition, \t{SRC\_URI}, \t{HOMEPAGE}, \t{PROVIDE}, \t{RESTRICT}, \t{PROPERTIES} and \t{LICENSE}	16	In addition, \t{SRC\_URI}, \t{HOMEPAGE}, \t{PROVIDE}, \t{RESTRICT}, \t{PROPERTIES}, \t{LICENSE} and
17	use dependency-style specifications to specify their values.	17	\t{REQUIRED\_USE} use dependency-style specifications to specify their values.
18		18
19	\section{Dependency Specification Format}	19	\section{Dependency Specification Format}
20		20
Lines 31-36 be surrounded on both sides by whitespace, except at the start and end of the st Link Here
31	\t{SRC\_URI}. For \t{SRC\_URI} behaviour, see section~\ref{sec:src-uri-behaviour}.	31	\t{SRC\_URI}. For \t{SRC\_URI} behaviour, see section~\ref{sec:src-uri-behaviour}.
32	\item A flat filename. Permitted in \t{SRC\_URI}.	32	\item A flat filename. Permitted in \t{SRC\_URI}.
33	\item A license name (e.\,g.\ \t{GPL-2}). Permitted in \t{LICENSE}.	33	\item A license name (e.\,g.\ \t{GPL-2}). Permitted in \t{LICENSE}.
		34	\item A use flag name, optionally preceded by an exclamation mark. Permitted in \t{REQUIRED\_USE}.
34	\item A simple string. Permitted in \t{RESTRICT} and \t{PROPERTIES}.	35	\item A simple string. Permitted in \t{RESTRICT} and \t{PROPERTIES}.
35	\item An all-of group, which consists of an open parenthesis, followed by whitespace,	36	\item An all-of group, which consists of an open parenthesis, followed by whitespace,
36	followed by zero or more of (a dependency item of any kind followed by whitespace), followed	37	followed by zero or more of (a dependency item of any kind followed by whitespace), followed
Lines 41-47 be surrounded on both sides by whitespace, except at the start and end of the st Link Here
41	followed by an open parenthesis, followed by whitespace, followed by zero or more	42	followed by an open parenthesis, followed by whitespace, followed by zero or more
42	of (a dependency item of any kind followed by whitespace), followed by a close parenthesis.	43	of (a dependency item of any kind followed by whitespace), followed by a close parenthesis.
43	More formally: \t{any-of ::= '\|\|' whitespace '(' whitespace (item whitespace)* ')'}.	44	More formally: \t{any-of ::= '\|\|' whitespace '(' whitespace (item whitespace)* ')'}.
44	Permitted in \t{DEPEND}, \t{RDEPEND}, \t{PDEPEND}, \t{LICENSE}.	45	Permitted in \t{DEPEND}, \t{RDEPEND}, \t{PDEPEND}, \t{LICENSE}, \t{REQUIRED\_USE}.
		46	\item An only-one-of group, which consists of the string \t{\textasciicircum\textasciicircum},
		47	followed by whitespace, followed by an open parenthesis, followed by whitespace, followed by
		48	zero or more of (a dependency item of any kind followed by whitespace), followed by a close
		49	parenthesis. More formally: \t{only-one-of ::= '\textasciicircum\textasciicircum' whitespace
		50	'(' whitespace (item whitespace)* ')'}.
		51	Permitted in \t{REQUIRED\_USE}.
45	\item A use-conditional group, which consists of an optional exclamation mark, followed by	52	\item A use-conditional group, which consists of an optional exclamation mark, followed by
46	a use flag name, followed by a question mark, followed by whitespace, followed by	53	a use flag name, followed by a question mark, followed by whitespace, followed by
47	an open parenthesis, followed by whitespace, followed by zero or more of (a dependency item	54	an open parenthesis, followed by whitespace, followed by zero or more of (a dependency item
Lines 90-95 considered to be matched if its associated package dependency specification is n Link Here
90		97
91	An empty any-of group counts as being matched.	98	An empty any-of group counts as being matched.
92		99
		100	\subsection{Only-one-of Dependency Specifications}
		101
		102	Any use-conditional group that is an immediate child of an only-one-of group, if not enabled
		103	(disabled for an exclamation mark prefixed use flag name), is not considered a member of the
		104	only-one-of group for match purposes.
		105
		106	In an only-one-of group, exactly one immediate child element must be matched.
		107
		108	An empty only-one-of group counts as being matched.
		109
93	\subsection{Package Dependency Specifications}	110	\subsection{Package Dependency Specifications}
94		111
95	A package dependency can be in one of the following base formats. A package manager must warn or	112	A package dependency can be in one of the following base formats. A package manager must warn or
Lines 257-262 would not have to be part of \t{IUSE}. Link Here
257	It is an error for an ebuild to use a conditional use dependency when that ebuild does not have the	274	It is an error for an ebuild to use a conditional use dependency when that ebuild does not have the
258	flag in \t{IUSE\_EFFECTIVE}.	275	flag in \t{IUSE\_EFFECTIVE}.
259		276
		277	\subsection{Use State Constraints}
		278	\label{sec:required-use}
		279	\t{REQUIRED\_USE} contains a list of assertions that must be met by the configuration of \t{USE}
		280	flags to be valid for this ebuild. In order to be matched, a \t{USE} flag in a terminal element
		281	must be enabled (or disabled if it has an exclamation mark prefix).
		282
		283	If the package manager encounters a package version where \t{REQUIRED\_USE} assertions are not met,
		284	it must treat this package version as if it was masked. No phase functions must be called.
		285
		286	It is an error for a flag to be used if it is not included in \t{IUSE\_EFFECTIVE}.
		287
260	\subsection{Restrict}	288	\subsection{Restrict}
261	\label{sec:restrict}	289	\label{sec:restrict}
262		290

Lines 26-37 order. Other lines may be present following these; their meanings are not define Link Here

(-)a/metadata-cache.tex (-3 / +3 lines)
26	\item Package keywords (\t{KEYWORDS})	26	\item Package keywords (\t{KEYWORDS})
27	\item Inherited eclasses (\t{INHERITED})	27	\item Inherited eclasses (\t{INHERITED})
28	\item Use flags that this package respects (\t{IUSE})	28	\item Use flags that this package respects (\t{IUSE})
29	\item No longer used; this line is to be ignored.	29	\item Use flags that this package requires (\t{REQUIRED\_USE}).
		30	Blank in some EAPIs; see table~\ref{tab:optional-vars-table}.
30	\item Post dependencies (\t{PDEPEND})	31	\item Post dependencies (\t{PDEPEND})
31	\item Old-style virtuals provided by this package (\t{PROVIDE})	32	\item Old-style virtuals provided by this package (\t{PROVIDE})
32	\item The ebuild API version to which this package conforms (\t{EAPI})	33	\item The ebuild API version to which this package conforms (\t{EAPI})
33	\item Properties (\t{PROPERTIES}). In some EAPIs, may optionally be blank, regardless of ebuild	34	\item Properties (\t{PROPERTIES}). In some EAPIs, may optionally be blank, regardless of ebuild
34	metadata; see table~\ref{tab:properties-table}.	35	metadata; see table~\ref{tab:optional-vars-table}.
35	\item Defined phases (\t{DEFINED\_PHASES}). In some EAPIs, may optionally be blank, regardless of	36	\item Defined phases (\t{DEFINED\_PHASES}). In some EAPIs, may optionally be blank, regardless of
36	ebuild metadata; see table~\ref{tab:defined-phases-table}.	37	ebuild metadata; see table~\ref{tab:defined-phases-table}.
37	\item Blank lines to pad the file to 22 lines long	38	\item Blank lines to pad the file to 22 lines long
38	-