diff options
| -rw-r--r-- | dependencies.tex | 373 | ||||
| -rw-r--r-- | ebuild-functions.tex | 101 | ||||
| -rw-r--r-- | ebuild-vars.tex | 106 | ||||
| -rw-r--r-- | introduction.tex | 43 | ||||
| -rw-r--r-- | labels.listing | 14 | ||||
| -rw-r--r-- | names.tex | 61 | ||||
| -rw-r--r-- | pkg-mgr-commands.tex | 110 | ||||
| -rw-r--r-- | pms.tex | 26 | ||||
| -rw-r--r-- | tree-layout.tex | 17 |
9 files changed, 769 insertions, 82 deletions
diff --git a/dependencies.tex b/dependencies.tex index de85eae..a47f3f3 100644 --- a/dependencies.tex +++ b/dependencies.tex @@ -13,8 +13,8 @@ There are three classes of dependencies supported by ebuilds: the ebuild if they are not already installed. \end{compactitem} -In addition, \t{SRC\_URI}, \t{HOMEPAGE}, \t{PROVIDE} and \t{LICENSE} use dependency-style -specifications to specify their values. +In addition, \t{SRC\_URI}, \t{HOMEPAGE}, \t{PROVIDE}, \t{RESTRICT} and \t{LICENSE} use +dependency-style specifications to specify their values. \section{Dependency Specification Format} @@ -25,7 +25,16 @@ 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}. +\IFKDEBUILDELSE +{ + \item A URI, in the form \t{proto://host/path}. Permitted in \t{SRC\_URI} and \t{HOMEPAGE}. + In EAPIs listed in table~\ref{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{src-uri-behaviour}. +}{ + \item A URI, in the form \t{proto://host/path}. Permitted in \t{SRC\_URI} and \t{HOMEPAGE}. + For \t{SRC\_URI} behaviour, see section~\ref{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}. @@ -45,10 +54,102 @@ be surrounded on both sides by whitespace, except at the start and end of the st of any kind followed by whitespace), followed by a close parenthesis. More formally: \t{use-conditional ::= '!'? flag-name '?' whitespace '(' whitespace (item whitespace)* ')'}. Permitted in all specification style variables. +\IFKDEBUILDELSE +{ + \item A label, which is a string without whitespace followed by a colon. Permitted in + \t{SRC\_URI} in EAPIs shown in table~\ref{uri-labels-table} as supporting \t{SRC\_URI} labels, + and in \t{PDEPEND} in EAPIs shown in table~\ref{pdepend-labels-table} as supporting \t{PDEPEND} + labels. +}{ +} \end{compactitem} In particular, note that whitespace is not optional. +\IFKDEBUILDELSE +{ + \begin{center} + \topcaption{EAPIs supporting \t{SRC\_URI} arrows} + \tablehead{ + \hline + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Supports \t{SRC\_URI} arrows?}} \\ + \hline + } + \begin{mpxtabular}{ l l } \label{uri-arrows-table} + \t{0} & No \\ + \t{1} & No \\ + \t{kdebuild-1} & Yes \\ + \hline + \end{mpxtabular} + \end{center} + + \begin{center} + \topcaption{EAPIs supporting \t{SRC\_URI} labels} + \tablehead{ + \hline + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Supports \t{SRC\_URI} labels?}} \\ + \hline + } + \begin{mpxtabular}{ l l } \label{uri-labels-table} + \t{0} & No \\ + \t{1} & No \\ + \t{kdebuild-1} & Yes \\ + \hline + \end{mpxtabular} + \end{center} + + \begin{center} + \topcaption{EAPIs supporting \t{PDEPEND} labels} + \tablehead{ + \hline + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Supports \t{PDEPEND} labels?}} \\ + \hline + } + \begin{mpxtabular}{ l l } \label{pdepend-labels-table} + \t{0} & No \\ + \t{1} & No \\ + \t{kdebuild-1} & Yes \\ + \hline + \end{mpxtabular} + \end{center} +}{ +} + +\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. + +\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. + +An empty any-of group counts as being matched. + +\IFKDEBUILDELSE +{ + \subsection{Labels} + \label{labels} + + A label alters the behaviour of any subsequent items (including those inside subgroups) in the + current group. This is demonstrated by code listing~\ref{lst:labels-listing}. + +\lstinputlisting[float,caption=How labels are applied,label=lst:labels-listing]{labels.listing} +}{ +} + \subsection{Package Dependency Specifications} A package dependency can be in one of the following base formats. A package manager must warn or @@ -56,12 +157,104 @@ error on non-compliant input. \begin{compactitem} \item A simple \t{category/package} name. -\item An operator, followed immediately by \t{category/package}, followed by a hyphen, - followed by a version specification. +\item An operator, as described in section~\ref{dep-operator}, followed immediately by + \t{category/package}, followed by a hyphen, followed by a version specification. \end{compactitem} -In EAPI 1, either of the above formats may additionally be suffixed by a \t{:slot} -restriction. A package manager must warn or error if slot dependencies are used with EAPI 0. +In EAPIs shown in table~\ref{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{slot-dep}. A package manager must warn or error if slot dependencies are used with an +EAPI not supporting \t{SLOT} dependencies. + +\IFKDEBUILDELSE +{ + In EAPIs shown in table~\ref{range-deps-table} as supporting ranged dependencies, a + specification that does not use an operator at the start may additionally be suffixed by one + \t{[range]} restriction, as described in section~\ref{range-dep}. A package manager must warn or + error if this feature is used with an EAPI not supporting ranged dependencies. + + In EAPIs shown in table~\ref{use-deps-table} as supporting \t{USE} dependencies, a specification + may additionally be suffixed by one or more \t{[use]} restrictions, as described in + section~\ref{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 the range restriction, which + must come before use dependencies. +}{ +} + +\IFKDEBUILDELSE +{ + \begin{center} + \topcaption{EAPIs supporting \t{SLOT} dependencies} + \tablehead{ + \hline + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Supports \t{SLOT} dependencies?}} \\ + \hline + } + \begin{mpxtabular}{ l l } \label{slot-deps-table} + \t{0} & No \\ + \t{1} & Named only \\ + \t{kdebuild-1} & Named and operator \\ + \hline + \end{mpxtabular} + \end{center} +}{ + \begin{center} + \topcaption{EAPIs supporting \t{SLOT} dependencies} + \tablehead{ + \hline + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Supports \t{SLOT} dependencies?}} \\ + \hline + } + \begin{mpxtabular}{ l l } \label{slot-deps-table} + \t{0} & No \\ + \t{1} & Yes \\ + \hline + \end{mpxtabular} + \end{center} +} + +\IFKDEBUILDELSE +{ + \begin{center} + \topcaption{EAPIs supporting ranged dependencies} + \tablehead{ + \hline + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Supports ranged dependencies?}} \\ + \hline + } + \begin{mpxtabular}{ l l } \label{range-deps-table} + \t{0} & No \\ + \t{1} & No \\ + \t{kdebuild-1} & Yes \\ + \hline + \end{mpxtabular} + \end{center} + + \begin{center} + \topcaption{EAPIs supporting \t{USE} dependencies} + \tablehead{ + \hline + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Supports \t{USE} dependencies?}} \\ + \hline + } + \begin{mpxtabular}{ l l } \label{use-deps-table} + \t{0} & No \\ + \t{1} & No \\ + \t{kdebuild-1} & Yes \\ + \hline + \end{mpxtabular} + \end{center} +}{ +} + +\subsubsection{Operators} +\label{dep-operator} The following operators are available: @@ -79,6 +272,8 @@ The following operators are available: \item[\t{>}] Strictly greater than the specified version. \end{description} +\subsubsection{Block Operator} + If the specification is prefixed with an exclamation mark, the named dependency is a block rather than a requirement---that is to say, the specified package must not be installed, except with the following exceptions: @@ -88,25 +283,165 @@ following exceptions: \item Blocks on the ebuild itself do not count. \end{compactitem} -\subsection{All-of Dependency Specifications} +\subsubsection{Slot Dependencies} +\label{slot-dep} -In an all-of group, all of the child elements must be matched. +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. -\subsection{Use-conditional Dependency Specifications} +\IFKDEBUILDELSE +{ + An operator slot dependency consists of a colon followed by one of the following operators: -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. + \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 equal to the slot of + the best installed version at the time the package was installed is available. + \end{description} -\subsection{Any-of Dependency Specifications} + To implement the equals slot operator, the package manager will need to store the slot of the + best installed version of the matching package. The package manager may do this by appending + the appropriate slot after the equals sign when saving the package's dependencies. This syntax + is only for package manager use and must not be used by ebuilds. +}{ +} -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. +\IFKDEBUILDELSE +{ + \subsubsection{Ranged Dependencies} + \label{range-dep} -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. + 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: + \t{ranged-dep ::= '[' (op ver logical-op)* op ver ']' }. -An empty any-of group counts as being matched. + The following logical operators are supported: + + \begin{description} + \item[\&] An 'and' match. All op-ver pairs must match for a successful match. + \item[|] An 'or' match. At least one op-ver pair must match for a successful match. + \end{description} + + A ranged dependency must not mix logical operators. +}{ +} + +\IFKDEBUILDELSE +{ + \subsubsection{Use Dependencies} + \label{use-dep} + + A use dependency consists of one of the following: + + \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 enabled if the use flag is disabled for the package with the + dependency. + \item{[-opt]} The flag must be disabled. + \item{[-opt?]} The flag must be disabled if the flag is enabled for the package with the + dependency. + \item{[-opt!?]} The flag must be disabled if the flag is disabled for the package with the + dependency. + \end{description} + + When multiple use dependencies are specified, all must match for a successful match. +}{ +} + +\IFKDEBUILDELSE +{ + \subsection{Package Dependency Labels} + + In EAPIs supporting \t{PDEPEND} labels, the following labels are legal. See + section~\ref{labels} for label behaviour in general. + + \begin{description} + \item[required] Indicates a required post dependency. + \item[suggested] Indicates a suggested post dependency. The package manager may ignore the + suggestion or install it at user option. + \end{description} + + The default label is \t{required}. +}{ +} + +\subsection{Restrict} +\label{restrict} + +The following tokens are permitted inside \t{RESTRICT}: + +\begin{description} +\item[mirror] The package's \t{SRC\_URI} entries may not be mirrored, and mirrors should not + be checked when fetching. +\item[fetch] The package's \t{SRC\_URI} entries may not be downloaded automatically. If + entries are not available, \t{pkg\_nofetch} is called. +\item[strip] No stripping of debug symbols from files to be installed may be performed. +\item[userpriv] The package manager may not drop root privileges when building the package. +\item[test] The \t{src\_test} phase must not be run. +\item[sandbox] The \t{sandbox} tool must not be used when building the package. +\end{description} + +Package managers may recognise other tokens, but ebuilds may not rely upon them being supported. + +\subsection{SRC\_URI} +\label{src-uri-behaviour} + +All filename components that are enabled (i.e. not inside a use-conditional block that is not +matched) in \t{SRC\_URI} must be available in the \t{DISTDIR} directory. In addition, these +components are used to make the \t{A} and \t{AA} variables. + +If a component contains a full URI with protocol, that download location must be used. Package +managers may also consult mirrors for their files. + +The special \t{mirror://} protocol must be supported. See section~\ref{thirdpartymirrors} for mirror +details. + +If a simple filename rather than a full URI is provided, the package manager can only use mirrors to +download the file. + +\IFKDEBUILDELSE +{ + The \t{RESTRICT} metadata key can be used to impose additional restrictions upon downloading---see + section~\ref{restrict} for details. Labels also alter behaviour---see below for details. +}{ + The \t{RESTRICT} metadata key can be used to impose additional restrictions upon downloading---see + section~\ref{restrict} for details. +} + +\IFKDEBUILDELSE +{ +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 +shall be requested instead of the filename in the URI. + +In EAPIs supporting labels, the following labels are legal. See section~\ref{labels} for label +behaviour in general. + +\begin{description} +\item[mirrors-first] Mirrors shall be consulted before the listed URI. +\item[mirrors-only] Only mirrors shall be consulted, and the listed URI shall be ignored. +\item[listed-first] The listed URI shall be consulted before mirrors. +\item[listed-only] Only the listed URI shall be consulted. +\item[manual] No URI shall be consulted. A manual download is required. +\end{description} + +The default label is \t{mirrors-first}, unless \t{RESTRICT} contains \t{mirror}, in which case it is +\t{listed-only}, unless \t{RESTRICT} contains \t{fetch}, in which case it is \t{manual}. +}{ +} % vim: set filetype=tex fileencoding=utf8 et tw=100 spell spelllang=en : diff --git a/ebuild-functions.tex b/ebuild-functions.tex index 3ace8e9..92dbfb2 100644 --- a/ebuild-functions.tex +++ b/ebuild-functions.tex @@ -56,8 +56,8 @@ The \t{src\_compile} function configures the package's build environment and bui The initial working directory must be \t{S} if that exists, falling back to \t{WORKDIR} otherwise. -For EAPI 0, the default implementation used when the ebuild lacks the \t{src\_compile} function -shall behave as: +For EAPIs not listed in table~\ref{src-compile-table} as being \t{ECONF\_SOURCE} aware, the default +implementation used when the ebuild lacks the \t{src\_compile} function shall behave as: \begin{lstlisting} src_compile() { @@ -70,8 +70,8 @@ src_compile() { } \end{lstlisting} -For EAPI 1, the default implementation used when the ebuild lacks the \t{src\_compile} function -shall behave as: +For EAPIs listed in table~\ref{src-compile-table} as being \t{ECONF\_SOURCE} aware, the default +implementation used when the ebuild lacks the \t{src\_compile} function shall behave as: \begin{lstlisting} src_compile() { @@ -84,6 +84,40 @@ src_compile() { } \end{lstlisting} +\IFKDEBUILDELSE +{ + \begin{center} + \topcaption{EAPIs supporting \t{ECONF\_SOURCE} in \t{src\_compile}} + \tablehead{ + \hline + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Supports \t{ECONF\_SOURCE}?}} \\ + \hline + } + \begin{mpxtabular}{ l l } \label{src-compile-table} + \t{0} & No \\ + \t{1} & Yes \\ + \t{kdebuild-1} & Yes \\ + \hline + \end{mpxtabular} + \end{center} +}{ + \begin{center} + \topcaption{EAPIs supporting \t{ECONF\_SOURCE} in \t{src\_compile}} + \tablehead{ + \hline + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Supports \t{ECONF\_SOURCE}?}} \\ + \hline + } + \begin{mpxtabular}{ l l } \label{src-compile-table} + \t{0} & No \\ + \t{1} & Yes \\ + \hline + \end{mpxtabular} + \end{center} +} + \subsection{src\_test} \label{src-test-function} @@ -96,6 +130,32 @@ enabled, run \t{make check} if and only if such a target is available, or if not if and only such a target is available. In both cases, if make returns non-zero the build must be aborted. +The \t{src\_test} function may be disabled by \t{RESTRICT}. See section~\ref{restrict}. + +\IFKDEBUILDELSE +{ + 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{test-required-table} + for which EAPIs fit into which category. + + \begin{center} + \topcaption{EAPIs requiring \t{src\_test}} + \tablehead{ + \hline + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Requires \t{src\_test}?}} \\ + \hline + } + \begin{mpxtabular}{ l l } \label{test-required-table} + \t{0} & At user option \\ + \t{1} & At user option \\ + \t{kdebuild-1} & Required \\ + \hline + \end{mpxtabular} + \end{center} +}{ +} + \subsection{src\_install} \label{src-install-function} @@ -156,11 +216,40 @@ fully installed. It is the only ebuild function which may be interactive and pro \subsection{pkg\_info} \label{pkg-info-function} -The \t{pkg\_info} function may be called by the package manager when displaying information about an -installed package. +\IFKDEBUILDELSE +{ + 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{pkg-info-table} as supporting \t{pkg\_info} on + uninstalled packages, it may also be called by the package manager when displaying information + about an uninstalled package. In this case, ebuild authors should note that dependencies may not be + installed. +}{ + The \t{pkg\_info} function may be called by the package manager when displaying information about an + installed package. +} \t{pkg\_info} must not write to the filesystem. +\IFKDEBUILDELSE +{ + \begin{center} + \topcaption{EAPIs supporting \t{pkg\_info} on uninstalled packages} + \tablehead{ + \hline + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Supports \t{pkg\_info} on uninstalled packages?}} \\ + \hline + } + \begin{mpxtabular}{ l l } \label{pkg-info-table} + \t{0} & No \\ + \t{1} & No \\ + \t{kdebuild-1} & Yes \\ + \hline + \end{mpxtabular} + \end{center} +}{ +} + \subsection{pkg\_nofetch} \label{pkg-nofetch-function} diff --git a/ebuild-vars.tex b/ebuild-vars.tex index fa41b52..664d1d3 100644 --- a/ebuild-vars.tex +++ b/ebuild-vars.tex @@ -40,9 +40,10 @@ All ebuilds must define at least the following variables: must also set \t{IUSE}, listing only the variables used by that eclass. The package manager is responsible for merging these values. - In EAPI 1, 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 if no other configuration overrides it. + In EAPIs shown in table~\ref{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 + if no other configuration overrides it. \item[KEYWORDS] A whitespace separated list of keywords for the ebuild. Each token must be a valid keyword name, as per section~\ref{keyword-names}. May include \t{-*}, which indicates that the package will only work on explicitly listed archs. May include \t{-arch}, @@ -54,6 +55,41 @@ If any of these variables are undefined, or if any of these variables are set to the package manager's behaviour is undefined; ideally, an error in one ebuild should not prevent operations upon other ebuilds or packages. +\IFKDEBUILDELSE +{ + \begin{center} + \topcaption{EAPIs supporting \t{IUSE} defaults} + \tablehead{ + \hline + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Supports \t{IUSE} defaults?}} \\ + \hline + } + \begin{mpxtabular}{ l l } \label{iuse-defaults-table} + \t{0} & No \\ + \t{1} & Yes \\ + \t{kdebuild-1} & Yes \\ + \hline + \end{mpxtabular} + \end{center} +} +{ + \begin{center} + \topcaption{EAPIs supporting \t{IUSE} defaults} + \tablehead{ + \hline + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Supports \t{IUSE} defaults?}} \\ + \hline + } + \begin{mpxtabular}{ l l } \label{iuse-defaults-table} + \t{0} & No \\ + \t{1} & Yes \\ + \hline + \end{mpxtabular} + \end{center} +} + \section{Optional Ebuild-defined Variables} Ebuilds may define any of the following variables: @@ -64,14 +100,43 @@ Ebuilds may define any of the following variables: \item[DEPEND] See section~\ref{dependencies}. \item[RDEPEND] See section~\ref{dependencies}. \item[PDEPEND] See section~\ref{dependencies}. -\item[PROVIDE] Zero or more qualified package names of any \e{old style} - virtuals provided by this package. See section~\ref{dependencies} for full syntax. - \label{ebuild-var-provide} -\item[EAPI] The EAPI, by default \t{0} or an empty string. +\IFKDEBUILDELSE +{ + \item[PROVIDE] Zero or more qualified package names of any \e{old style} + virtuals provided by this package. See section~\ref{dependencies} for full syntax. In EAPIs + listed in table~\ref{provide-table} as not supporting \t{PROVIDE}, ebuilds must not set this + variable and the package manager must reject any ebuild that does so. + \label{ebuild-var-provide} +}{ + \item[PROVIDE] Zero or more qualified package names of any \e{old style} + virtuals provided by this package. See section~\ref{dependencies} for full syntax. + \label{ebuild-var-provide} +} +\item[EAPI] The EAPI. See below for defaults. \item[RESTRICT] Zero or more behaviour restrictions for this package. See section~\ref{restrict} for value meanings and section~\ref{dependencies} for full syntax. \end{description} +\IFKDEBUILDELSE +{ + \begin{center} + \topcaption{EAPIs supporting \t{PROVIDE}} + \tablehead{ + \hline + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Supports \t{PROVIDE}?}} \\ + \hline + } + \begin{mpxtabular}{ l l } \label{provide-table} + \t{0} & Yes \\ + \t{1} & Yes \\ + \t{kdebuild-1} & No \\ + \hline + \end{mpxtabular} + \end{center} +}{ +} + An empty \t{EAPI} value is equal to \t{0}. Ebuilds must not assume that they will get a particular one of these two values if they are expecting one of these two values. @@ -80,28 +145,17 @@ before sourcing the ebuild for metadata generation. When using the ebuild for ot package manager must either pre-set \t{EAPI} to the value specified by the ebuild's metadata or ensure that it is unset. +\IFKDEBUILDELSE +{ + 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. +}{ +} + If any of these variables are set to invalid values, the package manager's behaviour is undefined; ideally, an error in one ebuild should not prevent operations upon other ebuilds or packages. -\subsection{Restrict} -\label{restrict} - -The \t{RESTRICT} variable is a dependency-type variable as described in section~\ref{dependencies}, -with the following tokens as values: - -\begin{description} -\item[mirror] The package's \t{SRC\_URI} entries may not be mirrored, and mirrors should not - be checked when fetching. -\item[fetch] The package's \t{SRC\_URI} entries may not be downloaded automatically. If - entries are not available, \t{pkg\_nofetch} is called. -\item[strip] No stripping of debug symbols from files to be installed may be performed. -\item[userpriv] The package manager may not drop root privileges when building the package. -\item[test] The \t{src\_test} phase must not be run. -\item[sandbox] The \t{sandbox} tool must not be used when building the package. -\end{description} - -Package managers may recognise other tokens, but ebuilds may not rely upon them being supported. - \section{Magic Ebuild-defined Variables} The following variables must be defined by \t{inherit}, and may be considered to be part diff --git a/introduction.tex b/introduction.tex index 5206768..b0d678b 100644 --- a/introduction.tex +++ b/introduction.tex @@ -37,27 +37,54 @@ applicable to tools or other applications that interact with ebuilds or ebuild r \section{EAPIs} An EAPI can be thought of as a `version' of this specification to which a package conforms. An EAPI -value is a string (all EAPIs defined by this specification currently use an integer, but package -managers must not assume that this will hold in the future, and package managers must not assume -that any kind of comparison other than equality between EAPI values makes sense). There are two -EAPIs defined by this specification: +value is a string. The following EAPIs are defined by this specification: \begin{description} \item[0] The `original' base EAPI. \item[1] EAPI `1' contains a number of extensions to EAPI `0'. Except where explicitly noted, it is in all other ways identical to EAPI `0'. +\IFKDEBUILDELSE +{ + \item[kdebuild-1] A series of extensions to EAPI `1' used by the Gentoo KDE project. Except where + explicitly noted, it is in all other ways identical to EAPI `1'. +}{ +} \end{description} -Except where explicitly noted, everything in this specification applies to both EAPIs. +\ifthenelse{\boolean{ENABLE-ALL-OPTIONS}} +{ + \note We're not sure whether \t{kdebuild-1} will end up in the final version of this + specification. For now, it's included but can easily be hidden using a switch in the master + \t{pms.tex} file. To make editing easier, we also have a mode that shows the document both with + and without the \t{kdebuild-1} stuff enabled. You currently have that mode enabled--- + \IFKDEBUILDELSE{ + text only shown when \t{kdebuild-1} is enabled looks like this, + }{ + and text only shown when it is disabled looks like this. + } +}{ +} + +Except where explicitly noted, everything in this specification applies to all EAPIs. If a package manager encounters a package version with an unrecognised EAPI, it must not attempt to perform any operations upon it. It could, for example, ignore the package version entirely (although this can lead to user confusion), or it could mark the package version as masked. A package manager must not use any metadata generated from a package with an unrecognised EAPI. -EAPIs whose value consists purely of an integer are reserved for future versions of this -specification. EAPIs whose value starts with the string \t{paludis-} are reserved for experimental -use by the Paludis package manager. +The package manager must not attempt to perform any kind of comparison test other than equality upon +EAPIs. + +\subsection{Reserved EAPIs} + +\begin{compactitem} +\item EAPIs whose value consists purely of an integer are reserved for future versions of this + specification. +\item EAPIs whose value starts with the string \t{paludis-} are reserved for experimental + use by the Paludis package manager. +\item EAPIs whose value starts iwth the string \t{kdebuild-} are reserved for the Gentoo KDE + project. +\end{compactitem} % vim: set filetype=tex fileencoding=utf8 et tw=100 spell spelllang=en : diff --git a/labels.listing b/labels.listing new file mode 100644 index 0000000..109e843 --- /dev/null +++ b/labels.listing @@ -0,0 +1,14 @@ +SOME_VALUE=" + label-is-default + foo: + label-is-foo + label-is-still-foo + flag? ( + label-is-still-foo + bar: + label-is-now-bar + baz: + label-is-now-baz + ) + label-is-back-to-foo + " @@ -59,8 +59,15 @@ integer, followed by zero or more dot-prefixed positive integers). This may optionally be followed by one of \t{[a-z]} (a lowercase letter). This may be followed by zero or more of the suffixes \t{\_alpha}, \t{\_beta}, \t{\_pre}, -\t{\_rc} or \t{\_p}, which themselves may be suffixed by an optional integer (if not present, -this integer is assumed to be zero). +\t{\_rc} or \t{\_p}, which themselves may be suffixed by an optional integer. + +\IFKDEBUILDELSE +{ + In ebuilds using EAPIs listed in table~\ref{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 separated by a hyphen. +}{ +} This may optionally be followed by the suffix \t{-r} followed immediately by an integer (the ``revision number''). If this suffix is not present, it is assumed to be \t{-r0}. @@ -69,11 +76,38 @@ This may optionally be followed by the suffix \t{-r} followed immediately by an ability to ignore versions it doesn't recognise. This should probably remain excluded and replaced by a proper solution in future EAPIs.} +\IFKDEBUILDELSE +{ + \begin{center} + \topcaption{EAPIs requiring \t{scm} support} + \tablehead{ + \hline + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Requires \t{scm} support?}} \\ + \hline + } + \begin{mpxtabular}{ l l } \label{scm-table} + \t{0} & No \\ + \t{1} & No \\ + \t{kdebuild-1} & Yes \\ + \hline + \end{mpxtabular} + \end{center} +}{ +} + \section{Version Comparison} Version specifications are compared component by component, moving from left to right. -The first component of the number part is compared using strict integer comparison. +\IFKDEBUILDELSE +{ + If a version starts with \t{scm}, it orders higher than any version that does not + start with \t{scm}. Otherwise, if neither version starts with \t{scm}, the +}{ + The +} +first component of the number part is compared using strict integer comparison. Any subsequent components of the number part are compared as follows: @@ -91,8 +125,25 @@ Letter suffixes are compared alphabetically, with any letter being newer than no If the letters are equal, suffixes are compared. The ordering is \t{\_alpha} is less than \t{\_beta} is less than \t{\_pre} is less than \t{\_rc} is less than no suffix is less than -\t{\_p}. If a suffix string is equal, the associated integer parts (which default to zero) -are compared using strict integer comparison. +\IFKDEBUILDELSE +{ + \t{\_p} is less than \t{-scm}. +}{ + \t{\_p}. +} +If a suffix string is equal, the associated integer parts +\IFKDEBUILDELSE +{ + (except for \t{scm} parts) +}{} +are compared using strict integer comparison. A missing integer part is treated as +\IFKDEBUILDELSE +{ + zero, unless the suffix is directly followed by \t{-scm}, in which case it is treated as being + higher than any integer. +}{ + zero. +} If at this point the two versions are still equal, the revision number is compared. The revision number has an optional integer suffix and is compared using strict integer comparison as per the diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex index c362eb2..1e75023 100644 --- a/pkg-mgr-commands.tex +++ b/pkg-mgr-commands.tex @@ -5,6 +5,36 @@ manager. Except where otherwise noted, they may be internal (shell functions or commands available in \t{PATH}; where this is not specified, ebuilds may not rely upon either behaviour. +\IFKDEBUILDELSE +{ + \subsubsection{Banned commands} + \label{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. + + \begin{center} + \topcaption{Banned commands} + \tablehead{ + \hline + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{3}{c}{\textbf{Command banned?}} \\ + \multicolumn{1}{c}{} & + \multicolumn{1}{c}{\textbf{\t{dohard}}} & + \multicolumn{1}{c}{\textbf{\t{dohtml}}} & + \multicolumn{1}{c}{\textbf{\t{dosed}}} \\ + \hline + } + \begin{mpxtabular}{ l l l l } \label{banned-commands-table} + \t{0} & No & No & No \\ + \t{1} & No & No & No \\ + \t{kdebuild-1} & Yes & Yes & Yes \\ + \hline + \end{mpxtabular} + \end{center} +}{ +} + \subsubsection{Sandbox commands} These commands affect the behaviour of the sandbox. Each command takes a single directory as argument. Ebuilds must not run any of these commands once the current phase function has returned. @@ -149,9 +179,21 @@ has returned. \item[doexe] Installs the given files into the directory specified by the most recent \t{exedesttree} call. If \t{exedesttree} has not yet been called, behaviour is undefined. -\item[dohard] Takes two parameters. Creates a hardlink from the second to the first. - -\item[dohtml] \TODO{Write dohtml.} +\IFKDEBUILDELSE +{ + \item[dohard] Takes two parameters. Creates a hardlink from the second to the first. In EAPIs + listed in table~\ref{banned-commands-table}, this command is banned as per + section~\ref{banned-commands}. +}{ + \item[dohard] Takes two parameters. Creates a hardlink from the second to the first. +} + +\IFKDEBUILDELSE +{ + \item[dohtml] \TODO{Write dohtml. It's banned in kdebuild-1.} +}{ + \item[dohtml] \TODO{Write dohtml.} +} \item[doinfo] Installs a GNU Info file into the \t{/usr/share/info} area. @@ -199,8 +241,15 @@ has returned. \item[dosbin] As \t{dobin}, but installs to \t{DESTTREE/sbin}. -\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. +\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{dosym-table} as making the directory, or aborts the build process otherwise. +}{ + \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. +} \item[fowners] Acts as for \t{chown}, but takes paths relative to the image directory. @@ -231,6 +280,26 @@ has returned. \end{description} +\IFKDEBUILDELSE +{ + \begin{center} + \topcaption{EAPIs where \t{dosym} makes the directory} + \tablehead{ + \hline + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{\t{dosym} makes the directory?}} \\ + \hline + } + \begin{mpxtabular}{ l l } \label{dosym-table} + \t{0} & Yes \\ + \t{1} & Yes \\ + \t{kdebuild-1} & No \\ + \hline + \end{mpxtabular} + \end{center} +}{ +} + \subsubsection{Commands affecting install destinations} The following commands are used to set the various destination trees, all relative to \t{\$\{D\}}, used by the above installation commands. They must be shell functions or aliases, due to the need to @@ -240,16 +309,16 @@ current phase function has returned. \begin{description} \item[into] Sets the value of \t{DESTTREE} for future invocations of the above utilities. Creates - the directory under \t{\$\{D\}}, using \t{install -d} with no additional options, if it does not - already exist. +the directory under \t{\$\{D\}}, using \t{install -d} with no additional options, if it does not +already exist. -\item[insinto] Sets the value of \t{INSDESTTREE} for future invocations of the above utilities. Creates - the directory, as specified for \t{into}. +\item[insinto] Sets the value of \t{INSDESTTREE} for future invocations of the above utilities. May + create the directory, as specified for \t{into}. -\item[exeinto] Sets the install path for \t{doexe} and \t{newexe}. Creates the directory, as specified +\item[exeinto] Sets the install path for \t{doexe} and \t{newexe}. May create the directory, as specified for \t{into}. -\item[docinto] Sets the install subdirectory for \t{dodoc} et al. Creates the directory, as specified +\item[docinto] Sets the install subdirectory for \t{dodoc} et al. May creates the directory, as specified for \t{into}. \item[insopts] Sets the options passed by \t{doins} et al. to the \t{install} command. @@ -297,10 +366,21 @@ of the above categories. Ebuilds must not run any of these commands once the cur has returned. \begin{description} -\item[dosed] Takes any number of arguments, which can be files or \t{sed} expressions. For each - argument, if it names, relative to \t{D} a file which exists, then \t{sed} is run with the - current expression on that file. Otherwise, the current expression is set to the text of the - argument. The initial value of the expression is \t{s:\$\{D\}::g}. +\IFKDEBUILDELSE +{ + \item[dosed] Takes any number of arguments, which can be files or \t{sed} expressions. For each + argument, if it names, relative to \t{D} a file which exists, then \t{sed} is run with the + current expression on that file. Otherwise, the current expression is set to the text of the + argument. The initial value of the expression is \t{s:\$\{D\}::g}. In EAPIs listed in + table~\ref{banned-commands-table}, this command is banned as per + section~\ref{banned-commands}. +}{ + \item[dosed] Takes any number of arguments, which can be files or \t{sed} expressions. For each + argument, if it names, relative to \t{D} a file which exists, then \t{sed} is run with the + current expression on that file. Otherwise, the current expression is set to the text of the + argument. The initial value of the expression is \t{s:\$\{D\}::g}. +} + \item[unpack] Unpacks a source archive into the current directory. Must be able to unpack the following file formats, if the relevant binaries are available: \begin{itemize} @@ -36,6 +36,32 @@ \newcommand{\TODOBUG}[2]{\fixme[inline]{(discussion on bug \##1) #2}} \newcommand{\TODO}[1]{\fixme[inline]{#1}} +\usepackage{ifthen} +\newboolean{ENABLE-ALL-OPTIONS} +\newboolean{ENABLE-KDEBUILD} + +%%% Enable the below option if you'd like to see both sides of KDEBUILD conditionals shown in +%%% different colours. Disable it to either fully enable or fully disable KDEBUILD. +\setboolean{ENABLE-ALL-OPTIONS}{true} + +%%% Enable the below if you'd like to see KDEBUILD things. +\setboolean{ENABLE-KDEBUILD}{true} + +\usepackage{color} +\ifthenelse{\boolean{ENABLE-ALL-OPTIONS}} +{ + \definecolor{deepblue}{rgb}{0.0, 0.2, 0.7} + \definecolor{deeppurple}{rgb}{0.7, 0.0, 0.8} + \newcommand{\IFKDEBUILDELSE}[2]{{\color{deepblue} #1}{\color{deeppurple} #2}} +}{ + \ifthenelse{\boolean{ENABLE-KDEBUILD}} + { + \newcommand{\IFKDEBUILDELSE}[2]{ #1 } + }{ + \newcommand{\IFKDEBUILDELSE}[2]{ #2 } + } +} + \hypersetup{% urlcolor=black, colorlinks=true, diff --git a/tree-layout.tex b/tree-layout.tex index 99d21d5..ea74a0b 100644 --- a/tree-layout.tex +++ b/tree-layout.tex @@ -57,9 +57,20 @@ A package directory contains the following: \item A \t{files} directory, containing any support files needed by the ebuilds. Optional. \end{compactitem} -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. +Any ebuild in a package directory must be named \t{name-ver.suffix}, where: + +\begin{compactitem} +\item \t{name} is the (unqualified) package name. +\item \t{ver} is the package's version. +\IFKDEBUILDELSE +{ + \item \t{suffix} is \t{ebuild} or \t{kdebuild-1}. +}{ + \item \t{suffix} is \t{ebuild}. +} +\end{compactitem} + +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 |