diff options
| -rw-r--r-- | dependencies.tex | 19 | ||||
| -rw-r--r-- | eapi-differences.tex | 179 | ||||
| -rw-r--r-- | ebuild-env-vars.tex | 4 | ||||
| -rw-r--r-- | ebuild-functions.tex | 14 | ||||
| -rw-r--r-- | ebuild-vars.tex | 10 | ||||
| -rw-r--r-- | eclasses.tex | 1 | ||||
| -rw-r--r-- | names.tex | 1 | ||||
| -rw-r--r-- | pkg-mgr-commands.tex | 43 | ||||
| -rw-r--r-- | pms.tex | 5 | ||||
| -rw-r--r-- | tree-layout.tex | 3 |
10 files changed, 168 insertions, 111 deletions
diff --git a/dependencies.tex b/dependencies.tex index 8da2c86..bcd8e50 100644 --- a/dependencies.tex +++ b/dependencies.tex @@ -25,10 +25,10 @@ be surrounded on both sides by whitespace, except at the start and end of the st \item A package dependency specification. Permitted in \t{DEPEND}, \t{RDEPEND}, \t{PDEPEND}. \item A simple qualified package name. Permitted in \t{PROVIDE} (and inside \t{DEPEND} etc via the previous item). -\item A URI, in the form \t{proto://host/path}. Permitted in \t{SRC\_URI} and \t{HOMEPAGE}. -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 URI, in the form \t{proto://host/path}. Permitted in \t{SRC\_URI} and \t{HOMEPAGE}. 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 simple string. Permitted in \t{RESTRICT} and \t{PROPERTIES}. @@ -187,15 +187,15 @@ EAPI not supporting \t{SLOT} dependencies. }{ } +\featurelabel{use-deps} \IFKDEBUILDELSE { In EAPIs shown in table~\ref{tab:use-deps-table} as supporting kdebuild-style \t{USE} dependencies, a specification may additionally be suffixed by one or more kdebuild-style \t{[use]} restrictions, as described in section~\ref{sec:kdebuild-use-dep}. A package manager must warn or error if this feature is used with an EAPI not supporting use dependencies. -}{ -} +}{} In EAPIs shown in table~\ref{tab:use-deps-table} as supporting 2-style or 3-style \t{USE} dependencies, a specification may additionally be suffixed by at most one 2-style or 3-style \t{[use]} restriction, as described in section~\ref{sec:use-dep}. A package manager must warn or @@ -320,6 +320,7 @@ following exceptions: \item Blocks on the ebuild itself do not count. \end{compactitem} +\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 @@ -360,11 +361,13 @@ table~\ref{tab:bang-strength-table}. \subsubsection{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 \t{EAPI}), the match is treated as unsuccessful. +\featurelabel{slot-operator-deps} An operator slot dependency consists of a colon followed by one of the following operators: \begin{description} @@ -386,6 +389,7 @@ is only for package manager use and must not be used by ebuilds. \subsubsection{Ranged Dependencies} \label{sec:range-dep} + \featurelabel{ranged-deps} A ranged dependency consists of an open square bracket, followed by zero or more of (a depend operator followed by a version spec followed by a logical operator) followed by a depend operator followed by a version spec followed by a close equare bracket. More formally: @@ -456,6 +460,7 @@ 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 3-style use dependency, the flag name may immediately be followed by a \e{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 @@ -542,6 +547,7 @@ download the file. section~\ref{sec:restrict} for details. } +\featurelabel{src-uri-arrows} In EAPIs supporting arrows, if an arrow is used, the filename used when saving to \t{DISTDIR} shall instead be the name on the right of the arrow. When consulting mirrors (except for those explicitly listed on the left of the arrow, if \t{mirror://} is used), the filename to the right of the arrow @@ -549,6 +555,7 @@ shall be requested instead of the filename in the URI. \IFKDEBUILDELSE { + \featurelabel{src-uri-labels} In EAPIs supporting labels, the following labels are legal. See section~\ref{sec:labels} for label behaviour in general. diff --git a/eapi-differences.tex b/eapi-differences.tex index 68a8ac0..a4179c1 100644 --- a/eapi-differences.tex +++ b/eapi-differences.tex @@ -38,7 +38,7 @@ \IFANYKDEBUILDELSE{ \IFKDEBUILDCOLOUR{\t{scm} support} & - \IFKDEBUILDCOLOUR{table~\ref{tab:scm-table}} & + \IFKDEBUILDCOLOUR{\compactfeatureref{scm}} & \IFKDEBUILDCOLOUR{Optional} & \IFKDEBUILDCOLOUR{Optional} & \IFKDEBUILDCOLOUR{Required} & @@ -48,7 +48,7 @@ \IFANYKDEBUILDELSE{ \IFKDEBUILDCOLOUR{File extension} & - \IFKDEBUILDCOLOUR{section~\ref{file-extension}} & + \IFKDEBUILDCOLOUR{\compactfeatureref{file-extension}} & \IFKDEBUILDCOLOUR{\t{.ebuild}} & \IFKDEBUILDCOLOUR{\t{.ebuild}} & \IFKDEBUILDCOLOUR{\t{.kdebuild-1}} & @@ -56,15 +56,15 @@ \IFKDEBUILDCOLOUR{\t{.ebuild}} \\ }{} -Profile \t{USE} injection & table~\ref{tab:profile-iuse-injection-table} & No & No & +Profile \t{IUSE} injection & \compactfeatureref{profile-iuse-injection} & No & No & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{No} &}{} No & Yes \\ -\t{IUSE} defaults & table~\ref{tab:iuse-defaults-table} & No & Yes & +\t{IUSE} defaults & \compactfeatureref{iuse-defaults} & No & Yes & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{Yes} &}{} Yes & Yes \\ \IFANYKDEBUILDELSE{ \IFKDEBUILDCOLOUR{\t{PROVIDE} support} & - \IFKDEBUILDCOLOUR{table~\ref{tab:provide-table}} & + \IFKDEBUILDCOLOUR{\compactfeatureref{provide}} & \IFKDEBUILDCOLOUR{Yes} & \IFKDEBUILDCOLOUR{Yes} & \IFKDEBUILDCOLOUR{No} & @@ -72,18 +72,18 @@ Profile \t{USE} injection & table~\ref{tab:profile-iuse-injection-table} & No & \IFKDEBUILDCOLOUR{Yes} \\ }{} -\t{PROPERTIES} & table~\ref{tab:properties-table} & Optionally & Optionally & +\t{PROPERTIES} & \compactfeatureref{properties} & Optionally & Optionally & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{Optionally} &}{} Optionally & Yes \\ -\t{RDEPEND=DEPEND} & table~\ref{tab:defined-phases-table} & Yes & Yes & +\t{RDEPEND=DEPEND} & \compactfeatureref{rdepend-depend} & Yes & Yes & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{Yes} &}{} Yes & No \\ -\t{DEFINED\_PHASES} & table~\ref{tab:defined-phases-table} & Optionally & Optionally & +\t{DEFINED\_PHASES} & \compactfeatureref{defined-phases} & Optionally & Optionally & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{Optionally} &}{} Optionally & Yes \\ \IFANYKDEBUILDELSE{ \IFKDEBUILDCOLOUR{Pre-source \t{EAPI}} & - \IFKDEBUILDCOLOUR{section~\ref{sec:pre-source-eapi}} & + \IFKDEBUILDCOLOUR{\compactfeatureref{pre-source-eapi}} & \IFKDEBUILDCOLOUR{0 or unset} & \IFKDEBUILDCOLOUR{0 or unset} & \IFKDEBUILDCOLOUR{kdebuild-1} & @@ -91,12 +91,12 @@ Profile \t{USE} injection & table~\ref{tab:profile-iuse-injection-table} & No & \IFKDEBUILDCOLOUR{0 or unset} \\ }{} -\t{SRC\_URI} arrows & table~\ref{tab:uri-arrows-table} & No & No & +\t{SRC\_URI} arrows & \compactfeatureref{src-uri-arrows} & No & No & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{Yes} &}{} Yes & Yes \\ \IFANYKDEBUILDELSE{ \IFKDEBUILDCOLOUR{\t{SRC\_URI} labels} & - \IFKDEBUILDCOLOUR{table~\ref{tab:uri-labels-table}} & + \IFKDEBUILDCOLOUR{\compactfeatureref{src-uri-labels}} & \IFKDEBUILDCOLOUR{No} & \IFKDEBUILDCOLOUR{No} & \IFKDEBUILDCOLOUR{Yes} & @@ -106,7 +106,7 @@ Profile \t{USE} injection & table~\ref{tab:profile-iuse-injection-table} & No & \IFANYKDEBUILDELSE{ \IFKDEBUILDCOLOUR{\t{PDEPEND} labels} & - \IFKDEBUILDCOLOUR{table~\ref{tab:pdepend-labels-table}} & + \IFKDEBUILDCOLOUR{\compactfeatureref{pdepend-labels}} & \IFKDEBUILDCOLOUR{No} & \IFKDEBUILDCOLOUR{No} & \IFKDEBUILDCOLOUR{Yes} & @@ -116,7 +116,7 @@ Profile \t{USE} injection & table~\ref{tab:profile-iuse-injection-table} & No & \IFANYKDEBUILDELSE{ \IFKDEBUILDCOLOUR{Ranged Dependencies} & - \IFKDEBUILDCOLOUR{table~\ref{tab:range-deps-table}} & + \IFKDEBUILDCOLOUR{\compactfeatureref{ranged-deps}} & \IFKDEBUILDCOLOUR{No} & \IFKDEBUILDCOLOUR{No} & \IFKDEBUILDCOLOUR{Yes} & @@ -125,43 +125,43 @@ Profile \t{USE} injection & table~\ref{tab:profile-iuse-injection-table} & No & }{} Slot dependencies & - table~\ref{tab:slot-deps-table} & + \compactfeatureref{slot-deps} & No & Named & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{Named and Operator} &}{} Named & Named and Operator \\ -Use dependencies & table~\ref{tab:use-deps-table} & No & No & +Use dependencies & \compactfeatureref{use-deps} & No & No & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{kdebuild-style} &}{} 2-style & 3-style \\ -\t{!} blockers & table~\ref{tab:bang-strength-table} & Unspecified & Unspecified & +\t{!} blockers & \compactfeatureref{bang-strength} & Unspecified & Unspecified & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{Unspecified} &}{} Weak & Weak \\ -\t{!!} blockers & table~\ref{tab:bang-strength-table} & Forbidden & Forbidden & +\t{!!} blockers & \compactfeatureref{bang-strength} & Forbidden & Forbidden & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{Forbidden} &}{} Strong & Strong \\ -\t{S} to \t{WORKDIR} fallback & table~\ref{tab:s-fallback-table} & Always & Always & +\t{S} to \t{WORKDIR} fallback & \compactfeatureref{s-workdir-fallback} & Always & Always & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{Always} &}{} Always & Conditional \\ -\t{pkg\_pretend} & table~\ref{tab:pkg-pretend-table} & No & No & +\t{pkg\_pretend} & \compactfeatureref{pkg-pretend} & No & No & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{No} &}{} No & Yes \\ -\t{src\_prepare} & table~\ref{tab:src-prepare-table} & No & No & +\t{src\_prepare} & \compactfeatureref{src-prepare} & No & No & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{No} &}{} Yes & Yes \\ -\t{src\_configure} & table~\ref{tab:src-configure-table} & No & No & +\t{src\_configure} & \compactfeatureref{src-configure} & No & No & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{No} &}{} Yes & Yes \\ -\t{src\_compile} style & table~\ref{tab:src-compile-table} & 0 & 1 & +\t{src\_compile} style & \compactfeatureref{src-compile} & 0 & 1 & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{1} &}{} 2 & 2 \\ -\t{src\_install} style & table~\ref{tab:src-install-table} & no-op & no-op & +\t{src\_install} style & \compactfeatureref{src-install} & no-op & no-op & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{no-op} &}{} no-op & 3 \\ \IFANYKDEBUILDELSE{ \IFKDEBUILDCOLOUR{\t{src\_test}} & - \IFKDEBUILDCOLOUR{table~\ref{tab:test-required-table}} & + \IFKDEBUILDCOLOUR{\compactfeatureref{src-test-required}} & \IFKDEBUILDCOLOUR{User option} & \IFKDEBUILDCOLOUR{User option} & \IFKDEBUILDCOLOUR{Required} & @@ -169,39 +169,39 @@ Use dependencies & table~\ref{tab:use-deps-table} & No & No & \IFKDEBUILDCOLOUR{User option} \\ }{} -\t{pkg\_info} & table~\ref{tab:pkg-info-table} & Installed & Installed & +\t{pkg\_info} & \compactfeatureref{pkg-info} & Installed & Installed & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{Both} &}{} Installed & Both \\ -\t{default\_} phase functions & table~\ref{tab:default-phase-function-table} & None & None & +\t{default\_} phase functions & \compactfeatureref{default-phase-functions} & None & None & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{None} &}{} \parbox[t]{1in}{\t{pkg\_nofetch}, \t{src\_unpack}, \t{src\_prepare}, \t{src\_configure}, \t{src\_compile}, \t{src\_test}} & \parbox[t]{1in}{\t{pkg\_nofetch}, \t{src\_unpack}, \t{src\_prepare}, \t{src\_configure}, \t{src\_compile}, \t{src\_install}, \t{src\_test}} \\ -\t{AA} & table~\ref{tab:env-vars-table} & Yes & Yes & +\t{AA} & \compactfeatureref{aa} & Yes & Yes & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{Yes} &}{} Yes & No \\ -\t{KV} & table~\ref{tab:env-vars-table} & Yes & Yes & +\t{KV} & \compactfeatureref{kv} & Yes & Yes & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{Yes} &}{} Yes & No \\ -\t{REPLACING\_VERSIONS} & table~\ref{tab:env-vars-table} & No & No & +\t{REPLACING\_VERSIONS} & \compactfeatureref{replace-version-vars} & No & No & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{No} &}{} No & Yes \\ -\t{REPLACED\_BY\_VERSION} & table~\ref{tab:env-vars-table} & No & No & +\t{REPLACED\_BY\_VERSION} & \compactfeatureref{replace-version-vars} & No & No & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{No} &}{} No & Yes \\ -Most utilities die & table~\ref{tab:commands-die-table} & No & No & +Most utilities die & \compactfeatureref{die-on-failure} & No & No & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{No} &}{} No & Yes \\ -\t{nonfatal} & table~\ref{tab:commands-die-table} & No & No & +\t{nonfatal} & \compactfeatureref{nonfatal} & No & No & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{No} &}{} No & Yes \\ -\t{dohard} & table~\ref{tab:banned-commands-table} & Yes & Yes & +\t{dohard} & \compactfeatureref{banned-commands} & Yes & Yes & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{Banned} &}{} Yes & Banned \\ \IFANYKDEBUILDELSE{ \IFKDEBUILDCOLOUR{\t{dohtml}} & - \IFKDEBUILDCOLOUR{table~\ref{tab:banned-commands-table}} & + \IFKDEBUILDCOLOUR{\compactfeatureref{banned-commands}} & \IFKDEBUILDCOLOUR{Yes} & \IFKDEBUILDCOLOUR{Yes} & \IFKDEBUILDCOLOUR{Banned} & @@ -209,25 +209,25 @@ Most utilities die & table~\ref{tab:commands-die-table} & No & No & \IFKDEBUILDCOLOUR{Yes} \\ }{} -\t{dosed} & table~\ref{tab:banned-commands-table} & Yes & Yes & +\t{dosed} & \compactfeatureref{banned-commands} & Yes & Yes & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{Banned} &}{} Yes & Banned \\ -\t{econf} arguments & table~\ref{tab:econf-options-table} & & & +\t{econf} arguments & \compactfeatureref{econf-options} & & & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{} &}{} & \parbox[t]{1in}{disable dependency tracking} \\ -\t{dodoc -r} & table~\ref{tab:dodoc-table} & No & No & +\t{dodoc -r} & \compactfeatureref{dodoc} & No & No & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{No} &}{} No & Yes \\ -\t{doins} handles symlinks & table~\ref{tab:doins-table} & No & No & +\t{doins} handles symlinks & \compactfeatureref{doins} & No & No & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{No} &}{} No & Yes \\ -\t{doman} languages & table~\ref{tab:doman-table} & No & No & +\t{doman} languages & \compactfeatureref{doman-langs} & No & No & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{No} &}{} Yes & Yes \\ \IFANYKDEBUILDELSE{ \IFKDEBUILDCOLOUR{\t{dosym} does \t{dodir}} & - \IFKDEBUILDCOLOUR{table~\ref{tab:dosym-table}} & + \IFKDEBUILDCOLOUR{\compactfeatureref{dosym-dodir}} & \IFKDEBUILDCOLOUR{Yes} & \IFKDEBUILDCOLOUR{Yes} & \IFKDEBUILDCOLOUR{No} & @@ -235,16 +235,16 @@ Most utilities die & table~\ref{tab:commands-die-table} & No & No & \IFKDEBUILDCOLOUR{Yes} \\ }{} -Controllable compression & table~\ref{tab:compression-table} & No & No & +Controllable compression & \compactfeatureref{controllable-compression} & No & No & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{No} &}{} No & Yes \\ -\t{docompress} & table~\ref{tab:compression-table} & No & No & +\t{docompress} & \compactfeatureref{controllable-compression} & No & No & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{No} &}{} No & Yes \\ -\t{unpack} support for \t{xz}? & table~\ref{tab:unpack-extensions-table} & No & No & +\t{unpack} support for \t{xz}? & \compactfeatureref{unpack-extensions} & No & No & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{No} &}{} No & Yes \\ -\t{default} function & table~\ref{tab:default-function-table} & No & No & +\t{default} function & \compactfeatureref{default-func} & No & No & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{No} &}{} Yes & Yes \\ \end{longtable} @@ -263,9 +263,9 @@ EAPI 0 is the base EAPI. EAPI 1 is EAPI 0 with the following changes: \begin{compactitem} -\item \t{IUSE} defaults, table~\ref{tab:iuse-defaults-table}. -\item Slot dependencies, table~\ref{tab:slot-deps-table}. -\item Different \t{src\_compile} implementation, table~\ref{tab:src-compile-table}. +\item \t{IUSE} defaults, \featureref{iuse-defaults}. +\item Slot dependencies, \featureref{slot-deps}. +\item Different \t{src\_compile} implementation, \featureref{src-compile-1}. \end{compactitem} \IFKDEBUILDELSE @@ -275,19 +275,19 @@ EAPI 1 is EAPI 0 with the following changes: EAPI kdebuild-1 is EAPI 1 with the following changes: \begin{compactitem} - \item \t{scm} support, table~\ref{tab:scm-table}. - \item \t{kdebuild-1} file extension, section~\ref{file-extension}. - \item \t{PROVIDE} banned, table~\ref{tab:provide-table}. - \item Pre-source EAPI is \t{kdebuild-1}, section~\ref{sec:pre-source-eapi}. - \item \t{SRC\_URI} arrows, table~\ref{tab:uri-arrows-table}. - \item \t{SRC\_URI} labels, table~\ref{tab:uri-labels-table}. - \item \t{PDEPEND} labels, table~\ref{tab:pdepend-labels-table}. - \item Ranged dependencies, table~\ref{tab:range-deps-table}. - \item Use dependencies, table~\ref{tab:use-deps-table}. - \item \t{src\_test} mandatory, table~\ref{tab:test-required-table}. - \item \t{pkg\_info} can run on non-installed packages, table~\ref{tab:pkg-info-table}. - \item \t{dohard}, \t{dohtml}, \t{dosed} banned, table~\ref{tab:banned-commands-table}. - \item \t{dosym} will not do \t{dodir}, table~\ref{tab:dosym-table}. + \item \t{scm} support, \featureref{scm}. + \item \t{kdebuild-1} file extension, \featureref{file-extension}. + \item \t{PROVIDE} banned, \featureref{provide}. + \item Pre-source EAPI is \t{kdebuild-1}, \featureref{pre-source-eapi}. + \item \t{SRC\_URI} arrows, \featureref{src-uri-arrows}. + \item \t{SRC\_URI} labels, \featureref{src-uri-labels}. + \item \t{PDEPEND} labels, \featureref{pdepend-labels}. + \item Ranged dependencies, \featureref{ranged-deps}. + \item Use dependencies, \featureref{use-deps}. + \item \t{src\_test} mandatory, \featureref{src-test-required}. + \item \t{pkg\_info} can run on non-installed packages, \featureref{pkg-info}. + \item \t{dohard}, \t{dohtml}, \t{dosed} banned, \featureref{banned-commands}. + \item \t{dosym} will not do \t{dodir}, \featureref{dosym-dodir}. \end{compactitem} }{ } @@ -297,16 +297,16 @@ EAPI 1 is EAPI 0 with the following changes: EAPI 2 is EAPI 1 with the following changes: \begin{compactitem} -\item \t{SRC\_URI} arrows, table~\ref{tab:uri-arrows-table}. -\item Use dependencies, table~\ref{tab:use-deps-table}. -\item \t{!} and \t{!!} blockers, table~\ref{tab:bang-strength-table}. -\item \t{src\_prepare}, table~\ref{tab:src-prepare-table}. -\item \t{src\_configure}, table~\ref{tab:src-configure-table}. -\item Different \t{src\_compile} implementation, table~\ref{tab:src-compile-table}. +\item \t{SRC\_URI} arrows, \featureref{src-uri-arrows}. +\item Use dependencies, \featureref{use-deps}. +\item \t{!} and \t{!!} blockers, \featureref{bang-strength}. +\item \t{src\_prepare}, \featureref{src-prepare}. +\item \t{src\_configure}, \featureref{src-configure}. +\item Different \t{src\_compile} implementation, \featureref{src-compile-2}. \item \t{default\_} phase functions for phases \t{pkg\_nofetch}, \t{src\_unpack}, \t{src\_prepare}, - \t{src\_configure}, \t{src\_compile} and \t{src\_test}; table~\ref{tab:default-phase-function-table}. -\item \t{doman} languages support, table~\ref{tab:doman-table}. -\item \t{default} function, table~\ref{tab:default-function-table}. + \t{src\_configure}, \t{src\_compile} and \t{src\_test}; \featureref{default-phase-functions}. +\item \t{doman} languages support, \featureref{doman-langs}. +\item \t{default} function, \featureref{default-func}. \end{compactitem} \section*{EAPI 3} @@ -314,26 +314,27 @@ EAPI 2 is EAPI 1 with the following changes: EAPI 3 is EAPI 2 with the following changes: \begin{compactitem} -\item \t{pkg\_pretend}, table~\ref{tab:pkg-pretend-table}. -\item Slot operator dependencies, table~\ref{tab:slot-deps-table}. -\item Use dependency defaults, table~\ref{tab:use-deps-table}. -\item \t{DEFINED\_PHASES} support is mandatory, table~\ref{tab:defined-phases-table}. -\item \t{PROPERTIES} support is mandatory, table~\ref{tab:properties-table}. -\item Default \t{src\_install} no longer a no-op, table~\ref{tab:src-install-table}. -\item Controllable compression and \t{docompress}, table~\ref{tab:compression-table}. -\item \t{dodoc -r} support, table~\ref{tab:dodoc-table}. -\item \t{doins} supports symlinks, table~\ref{tab:doins-table}. -\item \t{dohard}, \t{dosed} banned, table~\ref{tab:banned-commands-table}. -\item \t{unpack} supports \t{.xz} and \t{.tar.xz}, table~\ref{tab:unpack-extensions-table}. -\item \t{econf} adds \t{-{}-disable-dependency-tracking}, table~\ref{tab:econf-options-table}. -\item \t{pkg\_info} can run on non-installed packages, table~\ref{tab:pkg-info-table}. -\item \t{USE} is calculated differently, table~\ref{tab:profile-iuse-injection-table}. -\item \t{AA} and \t{KV} are gone, table~\ref{tab:env-vars-table}. -\item \t{REPLACING\_VERSIONS} and \t{REPLACED\_BY\_VERSION}, table~\ref{tab:env-vars-table}. -\item \t{S} to \t{WORKDIR} fallback restricted, table~\ref{tab:s-fallback-table}. -\item \t{RDEPEND=DEPEND} no longer done, table~\ref{tab:rdepend-depend-table}. -\item Utilities now die on failure unless called under \t{nonfatal}, - table~\ref{tab:commands-die-table}. +\item \t{pkg\_pretend}, \featureref{pkg-pretend}. +\item Slot operator dependencies, \featureref{slot-operator-deps}. +\item Use dependency defaults, \featureref{use-dep-defaults}. +\item \t{DEFINED\_PHASES} support is mandatory, \featureref{defined-phases}. +\item \t{PROPERTIES} support is mandatory, \featureref{properties}. +\item Default \t{src\_install} no longer a no-op, \featureref{src-install-3}. +\item Controllable compression and \t{docompress}, \featureref{controllable-compression}. +\item \t{dodoc -r} support, \featureref{dodoc}. +\item \t{doins} supports symlinks, \featureref{doins}. +\item \t{dohard}, \t{dosed} banned, \featureref{banned-commands}. +\item \t{unpack} supports \t{.xz} and \t{.tar.xz}, \featureref{unpack-extensions}. +\item \t{econf} adds \t{-{}-disable-dependency-tracking}, \featureref{econf-options}. +\item \t{pkg\_info} can run on non-installed packages, \featureref{pkg-info}. +\item \t{USE} is calculated differently, \featureref{profile-iuse-injection}. +\item \t{AA} is gone, \featureref{aa}. +\item \t{KV} is gone, \featureref{kv}. +\item \t{REPLACING\_VERSIONS} and \t{REPLACED\_BY\_VERSION}, \featureref{replace-version-vars}. +\item \t{S} to \t{WORKDIR} fallback restricted, \featureref{s-workdir-fallback}. +\item \t{RDEPEND=DEPEND} no longer done, \featureref{rdepend-depend}. +\item Utilities now die on failure, \featureref{die-on-failure}, unless called under \t{nonfatal}, + \featureref{nonfatal} \end{compactitem} % vim: set filetype=tex fileencoding=utf8 et tw=100 spell spelllang=en : diff --git a/ebuild-env-vars.tex b/ebuild-env-vars.tex index c8f9759..01a7de5 100644 --- a/ebuild-env-vars.tex +++ b/ebuild-env-vars.tex @@ -72,6 +72,7 @@ variable. this.} & \t{src\_*} & Yes & + \featurelabel{aa} All source files that could be available for the package, including any that are disabled in \t{A} because of USE conditionals. The value is calculated from the base names of each element of the \t{SRC\_URI} ebuild metadata variable. Only for EAPIs listed in table~\ref{tab:env-vars-table} as @@ -158,6 +159,7 @@ variable. \t{KV} & All & Yes & + \featurelabel{kv} The version of the running kernel at the time the ebuild was first executed, as returned by the \t{uname~-r} command or equivalent. May be modified by ebuilds. Only for EAPIs listed in table~\ref{tab:env-vars-table} as supporting \t{KV}. \\ @@ -258,6 +260,7 @@ For EAPIs listed in table~\ref{tab:profile-iuse-injection-table} as not supporti the profile \t{USE\_EXPAND} variable followed by an underscore. \end{compactitem} +\featurelabel{profile-iuse-injection} For EAPIs listed in table~\ref{tab:profile-iuse-injection-table} as supporting profile defined \t{IUSE} injection, \t{IUSE\_EFFECTIVE} contains the following values: @@ -291,6 +294,7 @@ installing a package. Details are beyond the scope of this specification. \subsection{\t{REPLACING\_VERSIONS} and \t{REPLACED\_BY\_VERSION}} \label{sec:replacing-versions} +\featurelabel{replace-version-vars} In EAPIs listed in table~\ref{tab:env-vars-table} as supporting it, the \t{REPLACING\_VERSIONS} variable shall be defined in \t{pkg\_preinst} and \t{pkg\_postinst}. In addition, it \e{may} be defined in \t{pkg\_pretend} and \t{pkg\_setup}, although ebuild authors should take care to handle diff --git a/ebuild-functions.tex b/ebuild-functions.tex index bd19ad3..2cfa7c7 100644 --- a/ebuild-functions.tex +++ b/ebuild-functions.tex @@ -28,6 +28,7 @@ the ebuild must not rely upon a particular location for it. The ebuild \e{may} a initial working directory for any phase is a trusted location that may only be written to by a privileged user and group. +\featurelabel{s-workdir-fallback} Some functions are described as having an initial working directory of \t{S} with an error or fallback to \t{WORKDIR}. For EAPIs listed in table~\ref{tab:s-fallback-table} as having the fallback, this means that if \t{S} is not a directory before the start of the phase function, the @@ -76,6 +77,7 @@ of the following conditions are true, in which case the fallback to \t{WORKDIR} \subsection{pkg\_pretend} \label{sec:pkg-pretend-function} +\featurelabel{pkg-pretend} The \t{pkg\_pretend} function is only called for EAPIs listed in table~\ref{tab:pkg-pretend-table} as supporting it. @@ -133,6 +135,7 @@ and/or groups to the system. \subsection{src\_unpack} \label{sec:src-unpack-function} +\featurelabel{src-unpack} The \t{src\_unpack} function extracts all of the package's sources, applies patches and sets up the package's build system for further use. @@ -150,6 +153,7 @@ src_unpack() { \subsection{src\_prepare} \label{sec:src-prepare-function} +\featurelabel{src-prepare} The \t{src\_prepare} function is only called for EAPIs listed in table~\ref{tab:src-prepare-table} as supporting it. @@ -192,6 +196,7 @@ section~\ref{sec:s-to-workdir-fallback}. \subsection{src\_configure} \label{sec:src-configure-function} +\featurelabel{src-configure} The \t{src\_configure} function is only called for EAPIs listed in table~\ref{tab:src-configure-table} as supporting it. @@ -242,12 +247,14 @@ src_configure() { \subsection{src\_compile} \label{sec:src-compile-function} +\featurelabel{src-compile} The \t{src\_compile} function configures the package's build environment in EAPIs lacking \t{src\_configure}, and builds the package in all EAPIs. The initial working directory is \t{S}, with an error or fallback to \t{WORKDIR} as discussed in section~\ref{sec:s-to-workdir-fallback}. +\featurelabel{src-compile-0} For EAPIs listed in table~\ref{tab:src-compile-table} as using format 0, the default implementation used when the ebuild lacks the \t{src\_compile} function shall behave as: @@ -262,6 +269,7 @@ src_compile() { } \end{verbatim} +\featurelabel{src-compile-1} For EAPIs listed in table~\ref{tab:src-compile-table} as using format 1, the default implementation used when the ebuild lacks the \t{src\_compile} function shall behave as: @@ -276,6 +284,7 @@ src_compile() { } \end{verbatim} +\featurelabel{src-compile-2} For EAPIs listed in table~\ref{tab:src-compile-table} as using format 2, the default implementation used when the ebuild lacks the \t{src\_compile} function shall behave as: @@ -333,6 +342,7 @@ The \t{src\_test} function may be disabled by \t{RESTRICT}. See section~\ref{sec \IFKDEBUILDELSE { + \featurelabel{src-test-required} In some EAPIs, \t{src\_test} should only be run at user option (and never if restrictions are in place). In others, it must always be run (excepting restrictions). See table~\ref{tab:test-required-table} for which EAPIs fit into which category. @@ -358,12 +368,14 @@ The \t{src\_test} function may be disabled by \t{RESTRICT}. See section~\ref{sec \subsection{src\_install} \label{sec:src-install-function} +\featurelabel{src-install} The \t{src\_install} function installs the package's content to a directory specified in \t{D}. The initial working directory is \t{S}, with an error or fallback to \t{WORKDIR} as discussed in section~\ref{sec:s-to-workdir-fallback}. +\featurelabel{src-install-3} For EAPIs listed in table~\ref{tab:src-install-table} as using format 3, the default implementation used when the ebuild lacks the \t{src\_install} function shall behave as: @@ -471,6 +483,7 @@ fully installed. It is the only ebuild function which may be interactive and pro \subsection{pkg\_info} \label{sec:pkg-info-function} +\featurelabel{pkg-info} The \t{pkg\_info} function may be called by the package manager when displaying information about an installed package. In EAPIs listed in table~\ref{tab:pkg-info-table} as supporting \t{pkg\_info} on non-installed packages, it may also be called by the package manager when displaying information @@ -521,6 +534,7 @@ source files from their respective locations, with notes concerning licensing if \subsection{\t{default\_} Phase Functions} \label{sec:default-phase-functions} +\featurelabel{default-phase-functions} In EAPIs listed in table~\ref{tab:default-phase-function-table} as supporting \t{default\_} phase functions, a function named \t{default\_}(phase) that behaves as the default implementation for that EAPI shall be defined when executing any ebuild phase listed in the table. Ebuilds diff --git a/ebuild-vars.tex b/ebuild-vars.tex index 3c86422..cb0a266 100644 --- a/ebuild-vars.tex +++ b/ebuild-vars.tex @@ -30,6 +30,7 @@ All ebuilds must define at least the following variables: responsible for merging these values. See section~\ref{sec:use-iuse-handling} for discussion on which values must be listed this variable. + \featurelabel{iuse-defaults} In EAPIs shown in table~\ref{tab:iuse-defaults-table} as supporting \t{IUSE} defaults, any use flag name in \t{IUSE} may be prefixed by at most one of a plus or a minus sign. If such a prefix is present, the package manager may use it as a suggestion as to the default value of the use flag @@ -95,6 +96,7 @@ Ebuilds may define any of the following variables: \item[PDEPEND] See section~\ref{sec:dependencies}. \IFKDEBUILDELSE { + \featurelabel{provide} \item[PROVIDE] Zero or more qualified package names of any \e{old style} virtuals provided by this package. See section~\ref{sec:dependencies} for full syntax. In EAPIs listed in table~\ref{tab:provide-table} as not supporting \t{PROVIDE}, ebuilds must not set this @@ -110,7 +112,8 @@ Ebuilds may define any of the following variables: details. \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] Zero or more properties for this package. See section~\ref{sec:properties} +\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:properties-table} as having optional support, ebuilds must not rely upon the package manager recognising or understanding this variable in any way. @@ -181,6 +184,7 @@ ensure that it is unset. \IFKDEBUILDELSE { + \featurelabel{pre-source-eapi} When sourcing an ebuild with file extension \t{kdebuild-1}, the package manager must pre-set the \t{EAPI} variable to \t{kdebuild-1}; leaving it empty is not allowed. Ebuilds with this extension must not modify the \t{EAPI} variable. @@ -193,6 +197,7 @@ ideally, an error in one ebuild should not prevent operations upon other ebuilds \subsection{\t{RDEPEND} value} \label{sec:rdepend-depend} +\featurelabel{rdepend-depend} In EAPIs listed in table~\ref{tab:rdepend-depend-table} as having \t{RDEPEND=DEPEND}, if \t{RDEPEND} is unset (but not if it is set to an empty string) in an ebuild, the package manager must set its value to be equal to the value of \t{DEPEND}. @@ -250,7 +255,8 @@ The following are special variables defined by the package manager for internal not be exported to the ebuild environment: \begin{description} -\item[DEFINED\_PHASES] A space separated arbitrarily ordered list of phase names (e.g. \t{configure +\item[DEFINED\_PHASES] \featurelabel{defined-phases} +A space separated arbitrarily ordered list of phase names (e.g. \t{configure setup unpack}) whose phase functions are defined by the ebuild or an eclass inherited by the ebuild. If no phase functions are defined, a single hyphen is used instead of an empty string. For EAPIs listed in table~\ref{tab:defined-phases-table} as having optional \t{DEFINED\_PHASES} support, diff --git a/eclasses.tex b/eclasses.tex index 1eb5274..4835063 100644 --- a/eclasses.tex +++ b/eclasses.tex @@ -41,6 +41,7 @@ appended to that defined by the ebuild. In the case of \t{RDEPEND}, this is done implicit \t{RDEPEND} rules in section~\ref{sec:rdepend-depend} are applied. \IFKDEBUILDELSE { + \featurelabel{pdepend-labels} In EAPIs shown in table~\ref{tab:pdepend-labels-table} as supporting \t{PDEPEND} labels, the values of \t{PDEPEND} from the ebuild and each eclass must be wrapped in parentheses, so that the labels only apply within the ebuild/eclass in which @@ -61,6 +61,7 @@ This may be followed by zero or more of the suffixes \t{\_alpha}, \t{\_beta}, \t \IFKDEBUILDELSE { + \featurelabel{scm} \label{scm-versions} In ebuilds using EAPIs listed in table~\ref{tab:scm-table} as requiring support for the \t{-scm} suffix, the preceding version syntax may be either replaced or suffixed by a \t{scm} part. If both a ``normal'' version and a \t{scm} part are present, they must be diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex index 3e127b4..c574337 100644 --- a/pkg-mgr-commands.tex +++ b/pkg-mgr-commands.tex @@ -8,16 +8,17 @@ behaviour. \subsubsection{Failure behaviour and related commands} \label{sec:failure-behaviour} +\featurelabel{die-on-failure} Where a command is listed as having EAPI dependent failure behaviour, a failure shall either result in a non-zero exit status or abort the build process, as determined by table~\ref{tab:commands-die-table}. The following commands affect this behaviour: \begin{description} -\item[nonfatal] Executes the remainder of its arguments as a command, preserving the exit status. If -this results in a command being called that would normally abort the build process due to a failure, -instead a non-zero exit status shall be returned. Only in EAPIs listed in -table~\ref{tab:commands-die-table} as supporting \t{nonfatal}. +\item[nonfatal] \featurelabel{nonfatal} Executes the remainder of its arguments as a command, + preserving the exit status. If this results in a command being called that would normally abort + the build process due to a failure, instead a non-zero exit status shall be returned. Only in + EAPIs listed in table~\ref{tab:commands-die-table} as supporting \t{nonfatal}. \end{description} \begin{centertable}{EAPI Command Failure Behaviour} \label{tab:commands-die-table} @@ -55,6 +56,7 @@ table~\ref{tab:commands-die-table} as supporting \t{nonfatal}. \subsubsection{Banned commands} \label{sec:banned-commands} +\featurelabel{banned-commands} Some commands are banned in some EAPIs. If a banned command is called, the package manager must abort the build process indicating an error. @@ -163,6 +165,8 @@ has returned. to \t{./configure}. \t{econf} will look in the current working directory for a configure script unless the \t{ECONF\_SOURCE} environment variable is set, in which case it is taken to be the directory containing it. \t{econf} must pass the following options to the configure script: + + \featurelabel{econf-options} \begin{itemize} \item -{}-prefix must default to \t{/usr} unless overridden by \t{econf}'s caller. \item -{}-mandir must be \t{/usr/share/man} @@ -276,7 +280,8 @@ has returned. by setting \t{DIROPTIONS} with the \t{diropts} function. Failure behaviour is EAPI dependent as per section~\ref{sec:failure-behaviour}. -\item[dodoc] Installs the given files into a subdirectory under \t{/usr/share/doc/\$\{PF\}/} with +\item[dodoc] \featurelabel{dodoc} + Installs the given files into a subdirectory under \t{/usr/share/doc/\$\{PF\}/} with file mode \t{0644}. The subdirectory is set by the most recent call to \t{docinto}. If \t{docinto} has not yet been called, instead installs to the directory \t{/usr/share/doc/\$\{PF\}/}. For EAPIs @@ -332,7 +337,8 @@ that can be passed to \t{dohtml} are as follows: \t{0755}. This can be overridden by setting \t{EXEOPTIONS} with the \t{exeopts} function. Failure behaviour is EAPI dependent as per section~\ref{sec:failure-behaviour}. -\item[doins] Takes any number of files as arguments and installs them into \t{INSDESTTREE}, by +\item[doins] \featurelabel{doins} + Takes any number of files as arguments and installs them into \t{INSDESTTREE}, by default with file mode \t{0644}. This can be overridden by setting \t{INSOPTIONS} with the \t{insopts} function. If the first argument is \t{-r}, then operates recursively, descending into any directories given. For EAPIs listed in table~\ref{tab:doins-table}, \t{doins} must @@ -374,7 +380,10 @@ that can be passed to \t{dohtml} are as follows: \item[doman] Installs a man page into the appropriate subdirectory of \t{/usr/share/man} depending upon its apparent section suffix (e.g. \t{foo.1} goes to \t{/usr/share/man/man1/foo.1} with file - mode \t{0644}. In EAPIs listed in table~\ref{tab:doman-table} as supporting language codes, a + mode \t{0644}. + + \featurelabel{doman-langs} + In EAPIs listed in table~\ref{tab:doman-table} as supporting language codes, a man page with name of the form\t{foo.lang.1} shall go to \t{/usr/share/man/lang/man1/foo.1}, where \t{lang} refers to a pair of lower-case ASCII letters optionally followed by an underscore and a pair of upper-case ASCII letters. Failure behaviour is EAPI dependent as per @@ -389,10 +398,12 @@ that can be passed to \t{dohtml} are as follows: \IFKDEBUILDELSE { - \item[dosym] Creates a symbolic link named as for its second parameter, pointing to the first. If - the directory containing the new link does not exist, creates it if EAPI is listed in - table~\ref{tab:dosym-table} as making the directory, or aborts the build process otherwise. - Failure behaviour is EAPI dependent as per section~\ref{sec:failure-behaviour}. + \item[dosym] Creates a symbolic link named as for its second parameter, pointing to the first. + + \featurelabel{dosym-dodir} If the directory containing the new link does not exist, creates + it if EAPI is listed in table~\ref{tab:dosym-table} as making the directory, or aborts the + build process otherwise. Failure behaviour is EAPI dependent as per + section~\ref{sec:failure-behaviour}. }{ \item[dosym] Creates a symbolic link named as for its second parameter, pointing to the first. If the directory containing the new link does not exist, creates it. Failure behaviour is EAPI @@ -576,6 +587,8 @@ already exist. Failure behaviour is EAPI dependent as per section~\ref{sec:failu \end{description} \subsubsection{Commands affecting install compression} + +\featurelabel{controllable-compression} In EAPIs listed in table~\ref{tab:compression-table} as supporting controllable compression, the package manager may optionally compress a subset of the files under the \t{D} directory. To control which directories may or may not be compressed, the package manager shall maintain two lists: @@ -738,8 +751,10 @@ has returned. looks in \t{DISTDIR} for the file, or start with the string \t{./}, in which case \t{unpack} uses the argument as a path relative to the working directory. - If unpacking a supported file format fails, \t{unpack} shall abort the build process. + Any unrecognised file format shall be skipped silently. If unpacking a supported file format + fails, \t{unpack} shall abort the build process. + \featurelabel{unpack-extensions} Must be able to unpack the following file formats, if the relevant binaries are available: \begin{itemize} \item tar files (\t{*.tar}). Ebuilds must ensure that GNU tar installed. @@ -796,7 +811,9 @@ has returned. \item[inherit] See section~\ref{sec:inherit}. -\item[default] Calls the \t{default\_} function for the current phase (see section~\ref{sec:default-phase-functions}). +\item[default] + \featurelabel{default-func} + Calls the \t{default\_} function for the current phase (see section~\ref{sec:default-phase-functions}). Must not be called if the \t{default\_} function does not exist for the current phase in the current EAPI. Only available in EAPIs listed in table~\ref{tab:default-function-table}. \end{description} @@ -50,6 +50,11 @@ \renewcommand{\b}[1]{\textbf{#1}} \newcommand{\note}[1]{\paragraph{Note:} #1} +\newcommand{\featureref}[1]{\b{feat:#1} on page~\pageref{feat:#1}} +\newcommand{\compactfeatureref}[1]{#1~p\pageref{feat:#1}} +\newcommand{\featurelabel}[1]{\label{feat:#1} \visiblelabel{feat:#1} } +\newcommand{\visiblelabel}[1]{\b{[#1]}} + \definecolor{deepblue}{rgb}{0.0, 0.2, 0.7} \definecolor{deeppurple}{rgb}{0.7, 0.0, 0.8} diff --git a/tree-layout.tex b/tree-layout.tex index 1542f0f..7c1059f 100644 --- a/tree-layout.tex +++ b/tree-layout.tex @@ -64,7 +64,8 @@ Any ebuild in a package directory must be named \t{name-ver.suffix}, where: \item \t{ver} is the package's version. \IFKDEBUILDELSE { - \item \label{file-extension} \t{suffix} is \t{ebuild} or \t{kdebuild-1}. + \item \label{file-extension} \featurelabel{file-extension} \t{suffix} is \t{ebuild} or + \t{kdebuild-1}. }{ \item \label{file-extension} \t{suffix} is \t{ebuild}. } |