diff options
| -rw-r--r-- | dependencies.tex | 154 | ||||
| -rw-r--r-- | eapi-differences.tex | 254 | ||||
| -rw-r--r-- | ebuild-env-vars.tex | 10 | ||||
| -rw-r--r-- | ebuild-functions.tex | 169 | ||||
| -rw-r--r-- | ebuild-vars.tex | 6 | ||||
| -rw-r--r-- | eclasses.tex | 1 | ||||
| -rw-r--r-- | introduction.tex | 2 | ||||
| -rw-r--r-- | names.tex | 1 | ||||
| -rw-r--r-- | pkg-mgr-commands.tex | 69 | ||||
| -rw-r--r-- | pms.tex | 8 | ||||
| -rw-r--r-- | tree-layout.tex | 4 |
11 files changed, 635 insertions, 43 deletions
diff --git a/dependencies.tex b/dependencies.tex index de29703..bd62649 100644 --- a/dependencies.tex +++ b/dependencies.tex @@ -25,16 +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). -\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 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 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}. @@ -66,9 +60,9 @@ be surrounded on both sides by whitespace, except at the start and end of the st In particular, note that whitespace is not optional. +\begin{centertable}{EAPIs supporting \t{SRC\_URI} arrows} \label{uri-arrows-table} \IFKDEBUILDELSE { - \begin{centertable}{EAPIs supporting \t{SRC\_URI} arrows} \label{uri-arrows-table} \begin{tabular}{ l l } \toprule \multicolumn{1}{c}{\textbf{EAPI}} & @@ -77,10 +71,25 @@ In particular, note that whitespace is not optional. \t{0} & No \\ \t{1} & No \\ \t{kdebuild-1} & Yes \\ + \t{2} & Yes \\ \bottomrule \end{tabular} - \end{centertable} +}{ + \begin{tabular}{ l l } + \toprule + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Supports \t{SRC\_URI} arrows?}} \\ + \midrule + \t{0} & No \\ + \t{1} & No \\ + \t{2} & Yes \\ + \bottomrule + \end{tabular} +} +\end{centertable} +\IFKDEBUILDELSE +{ \begin{centertable}{EAPIs supporting \t{SRC\_URI} labels} \label{uri-labels-table} \begin{tabular}{ l l } \toprule @@ -90,6 +99,7 @@ In particular, note that whitespace is not optional. \t{0} & No \\ \t{1} & No \\ \t{kdebuild-1} & Yes \\ + \t{2} & No \\ \bottomrule \end{tabular} \end{centertable} @@ -103,6 +113,7 @@ In particular, note that whitespace is not optional. \t{0} & No \\ \t{1} & No \\ \t{kdebuild-1} & Yes \\ + \t{2} & No \\ \bottomrule \end{tabular} \end{centertable} @@ -166,15 +177,29 @@ EAPI not supporting \t{SLOT} dependencies. 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. +\IFKDEBUILDELSE +{ + In EAPIs shown in table~\ref{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{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{use-deps-table} as supporting 2-style \t{USE} dependencies, a specification +may additionally be suffixed by at most one 2-style \t{[use]} restriction, 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. + +\IFKDEBUILDELSE +{ \note Order is important. The slot restriction must come before the range restriction, which must come before use dependencies. }{ + \note Order is important. The slot restriction must come before use dependencies. } \begin{centertable}{EAPIs supporting \t{SLOT} dependencies} \label{slot-deps-table} @@ -188,6 +213,7 @@ EAPI not supporting \t{SLOT} dependencies. \t{0} & No \\ \t{1} & Named only \\ \t{kdebuild-1} & Named and operator \\ + \t{2} & Named only \\ \bottomrule \end{tabular} }{ @@ -198,6 +224,7 @@ EAPI not supporting \t{SLOT} dependencies. \midrule \t{0} & No \\ \t{1} & Yes \\ + \t{2} & Yes \\ \bottomrule \end{tabular} } @@ -214,10 +241,15 @@ EAPI not supporting \t{SLOT} dependencies. \t{0} & No \\ \t{1} & No \\ \t{kdebuild-1} & Yes \\ + \t{2} & No \\ \bottomrule \end{tabular} \end{centertable} +}{ +} +\IFKDEBUILDELSE +{ \begin{centertable}{EAPIs supporting \t{USE} dependencies} \label{use-deps-table} \begin{tabular}{ l l } \toprule @@ -226,11 +258,24 @@ EAPI not supporting \t{SLOT} dependencies. \midrule \t{0} & No \\ \t{1} & No \\ - \t{kdebuild-1} & Yes \\ + \t{kdebuild-1} & kdebuild-style \\ + \t{2} & 2-style \\ \bottomrule \end{tabular} \end{centertable} }{ + \begin{centertable}{EAPIs supporting \t{USE} dependencies} \label{use-deps-table} + \begin{tabular}{ l l } + \toprule + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Supports \t{USE} dependencies?}} \\ + \midrule + \t{0} & No \\ + \t{1} & No \\ + \t{2} & 2-style \\ + \bottomrule + \end{tabular} + \end{centertable} } \subsubsection{Operators} @@ -254,8 +299,8 @@ The following operators are available: \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, with the +If the specification is prefixed with one or two exclamation marks, the named dependency is a block +rather than a requirement---that is to say, the specified package must not be installed, with the following exceptions: \begin{compactitem} @@ -263,6 +308,41 @@ following exceptions: \item Blocks on the ebuild itself do not count. \end{compactitem} +There are two strengths of block: weak and strong. A weak block may be ignored by the package +manager, so long as any blocked package will be uninstalled later on. A strong block must not be +ignored. The mapping from one or two exclamation marks to strength is described in +table~\ref{bang-strength-table}. + +\begin{centertable}{Exclamation mark strengths for EAPIs} \label{bang-strength-table} +\IFKDEBUILDELSE +{ + \begin{tabular}{ l l l } + \toprule + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{\t{!}}} & + \multicolumn{1}{c}{\textbf{\t{!!}}} \\ + \midrule + \t{0} & Unspecified & Forbidden \\ + \t{1} & Unspecified & Forbidden \\ + \t{kdebuild-1} & Unspecified & Forbidden \\ + \t{2} & Weak & Strong \\ + \bottomrule + \end{tabular} +}{ + \begin{tabular}{ l l l } + \toprule + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{\t{!}}} & + \multicolumn{1}{c}{\textbf{\t{!!}}} \\ + \midrule + \t{0} & Unspecified & Forbidden \\ + \t{1} & Unspecified & Forbidden \\ + \t{2} & Weak & Strong \\ + \bottomrule + \end{tabular} +} +\end{centertable} + \subsubsection{Slot Dependencies} \label{slot-dep} @@ -314,10 +394,10 @@ the match is treated as unsuccessful. \IFKDEBUILDELSE { - \subsubsection{Use Dependencies} - \label{use-dep} + \subsubsection{kdebuild Style Use Dependencies} + \label{kdebuild-use-dep} - A use dependency consists of one of the following: + A kdebuild-style use dependency consists of one of the following: \begin{description} \item{[opt]} The flag must be enabled. @@ -337,9 +417,39 @@ the match is treated as unsuccessful. \end{description} When multiple use dependencies are specified, all must match for a successful match. + + It is an error for a use dependency to be applied to an ebuild which does not have the flag in + question in \t{IUSE}, or for an ebuild to use a conditional use dependency when that ebuild does + not have the flag in \t{IUSE}. }{ } +\subsubsection{2-Style Use Dependencies} +\label{use-dep} + +A 2-style 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 disabled if the use flag is disabled for the package with the + dependency. +\item{[-opt]} The flag must be disabled. +\end{description} + +Multiple requirements may be combined using commas, e.g. \t{[first,-second,third?]}. + +When multiple requirements are specified, all must match for a successful match. + +It is an error for a use dependency to be applied to an ebuild which does not have the flag in +question in \t{IUSE}, or for an ebuild to use a conditional use dependency when that ebuild does +not have the flag in \t{IUSE}. + \IFKDEBUILDELSE { \subsection{Package Dependency Labels} diff --git a/eapi-differences.tex b/eapi-differences.tex new file mode 100644 index 0000000..6772198 --- /dev/null +++ b/eapi-differences.tex @@ -0,0 +1,254 @@ +\chapter{Feature Availability by EAPI} + +\note This chapter is informative and for convenience only. Refer to the main text for specifics. + +\begin{longtable}{\IFANYKDEBUILDELSE{llllll}{lllll}} +\caption{Features in EAPIs}\\ +\toprule +\multicolumn{1}{c}{\b{Feature}} & +\multicolumn{1}{c}{\b{Reference}} & +\IFANYKDEBUILDELSE{\multicolumn{4}{c}{\b{EAPIs}} \\}{\multicolumn{3}{c}{\b{EAPIs}} \\} +\multicolumn{1}{c}{} & +\multicolumn{1}{c}{} & +\multicolumn{1}{c}{0} & +\multicolumn{1}{c}{1} & +\IFANYKDEBUILDELSE{\multicolumn{1}{c}{\IFKDEBUILDCOLOUR{kdebuild-1}} &}{} +\multicolumn{1}{c}{2} \\ +\midrule +\endfirsthead +\midrule +\multicolumn{1}{c}{\b{Feature}} & +\multicolumn{1}{c}{\b{Reference}} & +\IFANYKDEBUILDELSE{\multicolumn{4}{c}{\b{EAPIs}} \\}{\multicolumn{3}{c}{\b{EAPIs}} \\} +\multicolumn{1}{c}{} & +\multicolumn{1}{c}{} & +\multicolumn{1}{c}{0} & +\multicolumn{1}{c}{1} & +\IFANYKDEBUILDELSE{\multicolumn{1}{c}{\IFKDEBUILDCOLOUR{kdebuild-1}} &}{} +\multicolumn{1}{c}{2} \\ +\midrule +\endhead +\midrule +\endfoot +\bottomrule +\endlastfoot + +\IFANYKDEBUILDELSE{ + \IFKDEBUILDCOLOUR{\t{scm} support} & + \IFKDEBUILDCOLOUR{table~\ref{scm-table}} & + \IFKDEBUILDCOLOUR{Optional} & + \IFKDEBUILDCOLOUR{Optional} & + \IFKDEBUILDCOLOUR{Required} & + \IFKDEBUILDCOLOUR{Optional} \\ +}{} + +\IFANYKDEBUILDELSE{ + \IFKDEBUILDCOLOUR{File extension} & + \IFKDEBUILDCOLOUR{section~\ref{file-extension}} & + \IFKDEBUILDCOLOUR{\t{.ebuild}} & + \IFKDEBUILDCOLOUR{\t{.ebuild}} & + \IFKDEBUILDCOLOUR{\t{.kdebuild-1}} & + \IFKDEBUILDCOLOUR{\t{.ebuild}} \\ +}{} + +\t{IUSE} defaults & table~\ref{iuse-defaults-table} & No & Yes & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{Yes} &}{} Yes \\ + +\IFANYKDEBUILDELSE{ + \IFKDEBUILDCOLOUR{\t{PROVIDE} support} & + \IFKDEBUILDCOLOUR{table~\ref{provide-table}} & + \IFKDEBUILDCOLOUR{Yes} & + \IFKDEBUILDCOLOUR{Yes} & + \IFKDEBUILDCOLOUR{No} & + \IFKDEBUILDCOLOUR{Yes} \\ +}{} + +\IFANYKDEBUILDELSE{ + \IFKDEBUILDCOLOUR{Pre-source \t{EAPI}} & + \IFKDEBUILDCOLOUR{section~\ref{pre-source-eapi}} & + \IFKDEBUILDCOLOUR{0 or unset} & + \IFKDEBUILDCOLOUR{0 or unset} & + \IFKDEBUILDCOLOUR{kdebuild-1} & + \IFKDEBUILDCOLOUR{0 or unset} \\ +}{} + +\t{SRC\_URI} arrows & table~\ref{uri-arrows-table} & No & No & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{Yes} &}{} Yes \\ + +\IFANYKDEBUILDELSE{ + \IFKDEBUILDCOLOUR{\t{SRC\_URI} labels} & + \IFKDEBUILDCOLOUR{table~\ref{uri-labels-table}} & + \IFKDEBUILDCOLOUR{No} & + \IFKDEBUILDCOLOUR{No} & + \IFKDEBUILDCOLOUR{Yes} & + \IFKDEBUILDCOLOUR{No} \\ +}{} + +\IFANYKDEBUILDELSE{ + \IFKDEBUILDCOLOUR{\t{PDEPEND} labels} & + \IFKDEBUILDCOLOUR{table~\ref{pdepend-labels-table}} & + \IFKDEBUILDCOLOUR{No} & + \IFKDEBUILDCOLOUR{No} & + \IFKDEBUILDCOLOUR{Yes} & + \IFKDEBUILDCOLOUR{No} \\ +}{} + +\IFANYKDEBUILDELSE{ + \IFKDEBUILDCOLOUR{Ranged Dependencies} & + \IFKDEBUILDCOLOUR{table~\ref{range-deps-table}} & + \IFKDEBUILDCOLOUR{No} & + \IFKDEBUILDCOLOUR{No} & + \IFKDEBUILDCOLOUR{Yes} & + \IFKDEBUILDCOLOUR{No} \\ +}{} + +Slot dependencies & + table~\ref{slot-deps-table} & + No & + \IFKDEBUILDELSE{Named}{Yes} & + \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{Named and Operator} &}{} + \IFKDEBUILDELSE{Named}{Yes} \\ + +Use dependencies & table~\ref{use-deps-table} & No & No & + \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{kdebuild-style} &}{} 2-style \\ + +\t{!} blockers & table~\ref{bang-strength-table} & Unspecified & Unspecified & + \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{Unspecified} &}{} Weak \\ + +\t{!!} blockers & table~\ref{bang-strength-table} & Forbidden & Forbidden & + \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{Forbidden} &}{} Strong \\ + +\t{src\_prepare} & table~\ref{src-prepare-table} & No & No & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{No} &}{} Yes \\ + +\t{src\_configure} & table~\ref{src-configure-table} & No & No & \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{No} &}{} Yes \\ + +\t{src\_compile} style & table~\ref{src-compile-table} & 0 & 1 & + \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{1} &}{} 2 \\ + +\IFANYKDEBUILDELSE{ + \IFKDEBUILDCOLOUR{\t{src\_test}} & + \IFKDEBUILDCOLOUR{table~\ref{test-required-table}} & + \IFKDEBUILDCOLOUR{User option} & + \IFKDEBUILDCOLOUR{User option} & + \IFKDEBUILDCOLOUR{Required} & + \IFKDEBUILDCOLOUR{User option} \\ +}{} + +\IFANYKDEBUILDELSE{ + \IFKDEBUILDCOLOUR{\t{pkg\_info}} & + \IFKDEBUILDCOLOUR{table~\ref{pkg-info-table}} & + \IFKDEBUILDCOLOUR{Installed} & + \IFKDEBUILDCOLOUR{Installed} & + \IFKDEBUILDCOLOUR{Both} & + \IFKDEBUILDCOLOUR{Installed} \\ +}{} + +\t{default\_} phase functions & table~\ref{default-phase-function-table} & No & No & + \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{No} &}{} Yes \\ + +\IFANYKDEBUILDELSE{ + \IFKDEBUILDCOLOUR{\t{dohard}} & + \IFKDEBUILDCOLOUR{table~\ref{banned-commands-table}} & + \IFKDEBUILDCOLOUR{Yes} & + \IFKDEBUILDCOLOUR{Yes} & + \IFKDEBUILDCOLOUR{Banned} & + \IFKDEBUILDCOLOUR{Yes} \\ +}{} + +\IFANYKDEBUILDELSE{ + \IFKDEBUILDCOLOUR{\t{dohtml}} & + \IFKDEBUILDCOLOUR{table~\ref{banned-commands-table}} & + \IFKDEBUILDCOLOUR{Yes} & + \IFKDEBUILDCOLOUR{Yes} & + \IFKDEBUILDCOLOUR{Banned} & + \IFKDEBUILDCOLOUR{Yes} \\ +}{} + +\IFANYKDEBUILDELSE{ + \IFKDEBUILDCOLOUR{\t{dosed}} & + \IFKDEBUILDCOLOUR{table~\ref{banned-commands-table}} & + \IFKDEBUILDCOLOUR{Yes} & + \IFKDEBUILDCOLOUR{Yes} & + \IFKDEBUILDCOLOUR{Banned} & + \IFKDEBUILDCOLOUR{Yes} \\ +}{} + +\t{doman} languages & table~\ref{doman-table} & No & No & + \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{No} &}{} Yes \\ + +\IFANYKDEBUILDELSE{ + \IFKDEBUILDCOLOUR{\t{dosym} does \t{dodir}} & + \IFKDEBUILDCOLOUR{table~\ref{dosym-table}} & + \IFKDEBUILDCOLOUR{Yes} & + \IFKDEBUILDCOLOUR{Yes} & + \IFKDEBUILDCOLOUR{No} & + \IFKDEBUILDCOLOUR{Yes} \\ +}{} + +\t{default} function & table~\ref{default-function-table} & No & No & + \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{No} &}{} Yes \\ + +\end{longtable} + +\chapter{Differences Between EAPIs} + +\note This chapter is informative and for convenience only. Refer to the main text for specifics. + +\section*{EAPI 0} + +EAPI 0 is the base EAPI. + +\section*{EAPI 1} + +EAPI 1 is EAPI 0 with the following changes: + +\begin{compactitem} +\item \t{IUSE} defaults, table~\ref{iuse-defaults-table}. +\item Slot dependencies, table~\ref{slot-deps-table}. +\item Different \t{src\_compile} implementation, table~\ref{src-compile-table}. +\end{compactitem} + +\IFKDEBUILDELSE +{ + \section*{EAPI kdebuild-1} + + EAPI kdebuild-1 is EAPI 1 with the following changes: + + \begin{compactitem} + \item \t{scm} support, table~\ref{scm-table}. + \item \t{kdebuild-1} file extension, section~\ref{file-extension}. + \item \t{PROVIDE} banned, table~\ref{provide-table}. + \item Pre-source EAPI is \t{kdebuild-1}, section~\ref{pre-source-eapi}. + \item \t{SRC\_URI} arrows, table~\ref{uri-arrows-table}. + \item \t{SRC\_URI} labels, table~\ref{uri-labels-table}. + \item \t{PDEPEND} labels, table~\ref{pdepend-labels-table}. + \item Ranged dependencies, table~\ref{range-deps-table}. + \item Use dependencies, table~\ref{use-deps-table}. + \item \t{src\_test} mandatory, table~\ref{test-required-table}. + \item \t{pkg\_info} can run on uninstalled packages, table~\ref{pkg-info-table}. + \item \t{dohard}, \t{dohtml}, \t{dosed} banned, table~\ref{banned-commands-table}. + \item \t{dosym} will not do \t{dodir}, table~\ref{dosym-table}. + \end{compactitem} +}{ +} + +\section*{EAPI 2} + +EAPI 2 is EAPI 1 with the following changes: + +\begin{compactitem} +\item \t{SRC\_URI} arrows, table~\ref{uri-arrows-table}. +\item Use dependencies, table~\ref{use-deps-table}. +\item \t{!} and \t{!!} blockers, table~\ref{bang-strength-table}. +\item \t{src\_prepare}, table~\ref{src-prepare-table}. +\item \t{src\_configure}, table~\ref{src-configure-table}. +\item Different \t{src\_compile} implementation, table~\ref{src-compile-table}. +\item \t{default\_} phase functions, table~\ref{default-phase-function-table}. +\item \t{doman} languages support, table~\ref{doman-table}. +\item \t{default} function, table~\ref{default-function-table}. +\end{compactitem} + +% vim: set filetype=tex fileencoding=utf8 et tw=100 spell spelllang=en : + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "pms" +%%% End: diff --git a/ebuild-env-vars.tex b/ebuild-env-vars.tex index 2f06370..f6a16bd 100644 --- a/ebuild-env-vars.tex +++ b/ebuild-env-vars.tex @@ -144,11 +144,11 @@ variable. \t{EBUILD\_PHASE} & All & No & - Takes one of the values \t{config}, \t{setup}, \t{nofetch}, \t{unpack}, - \t{compile}, \t{test}, \t{install}, \t{preinst}, \t{postinst}, \t{prerm}, \t{postrm}, \t{info} - according to the top level ebuild function that was executed by the package manager. May be - unset or any single word that is not any of the above when the ebuild is being sourced for - other (e.g. metadata or QA) purposes. \\ + Takes one of the values \t{config}, \t{setup}, \t{nofetch}, \t{unpack}, \t{prepare}, + \t{configure}, \t{compile}, \t{test}, \t{install}, \t{preinst}, \t{postinst}, \t{prerm}, + \t{postrm}, \t{info} according to the top level ebuild function that was executed by the package + manager. May be unset or any single word that is not any of the above when the ebuild is being + sourced for other (e.g. metadata or QA) purposes. \\ \t{WORKDIR} & \t{src\_*} & Yes & diff --git a/ebuild-functions.tex b/ebuild-functions.tex index 8e1918d..bc654ad 100644 --- a/ebuild-functions.tex +++ b/ebuild-functions.tex @@ -49,15 +49,102 @@ src_unpack() { } \end{verbatim} +\subsection{src\_prepare} +\label{src-prepare-function} + +The \t{src\_prepare} function is only called for EAPIs listed in table~\ref{src-prepare-table} as +supporting it. + +The \t{src\_prepare} function can be used for post-unpack source preparation. The default +implementation does nothing. + +The initial working directory must be \t{S} if that exists, falling back to \t{WORKDIR} otherwise. + +\begin{centertable}{EAPIs supporting \t{src\_prepare}} \label{src-prepare-table} +\IFKDEBUILDELSE +{ + \begin{tabular}{ l l } + \toprule + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Supports \t{src\_prepare}?}} \\ + \midrule + \t{0} & No \\ + \t{1} & No \\ + \t{kdebuild-1} & No \\ + \t{2} & Yes \\ + \bottomrule + \end{tabular} +}{ + \begin{tabular}{ l l } + \toprule + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Supports \t{src\_prepare}?}} \\ + \midrule + \t{0} & No \\ + \t{1} & No \\ + \t{2} & Yes \\ + \bottomrule + \end{tabular} +} +\end{centertable} + +\subsection{src\_configure} +\label{src-configure-function} + +The \t{src\_configure} function is only called for EAPIs listed in table~\ref{src-configure-table} as +supporting it. + +The initial working directory must be \t{S} if that exists, falling back to \t{WORKDIR} otherwise. + +The \t{src\_configure} function configures the package's build environment. The default +implementation used when the ebuild lacks the \t{src\_configure} function shall behave as: + +\begin{verbatim} +src_configure() { + if [[ -x ${ECONF_SOURCE:-.}/configure ]]; then + econf + fi +} +\end{verbatim} + +\begin{centertable}{EAPIs supporting \t{src\_configure}} \label{src-configure-table} +\IFKDEBUILDELSE +{ + \begin{tabular}{ l l } + \toprule + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Supports \t{src\_configure}?}} \\ + \midrule + \t{0} & No \\ + \t{1} & No \\ + \t{kdebuild-1} & No \\ + \t{2} & Yes \\ + \bottomrule + \end{tabular} +}{ + \begin{tabular}{ l l } + \toprule + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Supports \t{src\_configure}?}} \\ + \midrule + \t{0} & No \\ + \t{1} & No \\ + \t{2} & Yes \\ + \bottomrule + \end{tabular} +} +\end{centertable} + \subsection{src\_compile} \label{src-compile-function} -The \t{src\_compile} function configures the package's build environment and builds the package. +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 must be \t{S} if that exists, falling back to \t{WORKDIR} otherwise. -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: +For EAPIs listed in table~\ref{src-compile-table} as using format 0, the default implementation used +when the ebuild lacks the \t{src\_compile} function shall behave as: \begin{verbatim} src_compile() { @@ -70,8 +157,8 @@ src_compile() { } \end{verbatim} -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: +For EAPIs listed in table~\ref{src-compile-table} as using format 1, the default implementation used +when the ebuild lacks the \t{src\_compile} function shall behave as: \begin{verbatim} src_compile() { @@ -84,27 +171,40 @@ src_compile() { } \end{verbatim} -\begin{centertable}{EAPIs supporting \t{ECONF\_SOURCE} in \t{src\_compile}} \label{src-compile-table} +For EAPIs listed in table~\ref{src-compile-table} as using format 2, the default implementation used +when the ebuild lacks the \t{src\_compile} function shall behave as: + +\begin{verbatim} +src_compile() { + if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]]; then + emake || die "emake failed" + fi +} +\end{verbatim} + +\begin{centertable}{\t{src\_compile} behaviour for EAPIs} \label{src-compile-table} \IFKDEBUILDELSE { \begin{tabular}{ l l } \toprule \multicolumn{1}{c}{\textbf{EAPI}} & - \multicolumn{1}{c}{\textbf{Supports \t{ECONF\_SOURCE}?}} \\ + \multicolumn{1}{c}{\textbf{Format}} \\ \midrule - \t{0} & No \\ - \t{1} & Yes \\ - \t{kdebuild-1} & Yes \\ + \t{0} & 0 \\ + \t{1} & 1 \\ + \t{kdebuild-1} & 1 \\ + \t{2} & 2 \\ \bottomrule \end{tabular} }{ \begin{tabular}{ l l } \toprule \multicolumn{1}{c}{\textbf{EAPI}} & - \multicolumn{1}{c}{\textbf{Supports \t{ECONF\_SOURCE}?}} \\ + \multicolumn{1}{c}{\textbf{Format}} \\ \midrule - \t{0} & No \\ - \t{1} & Yes \\ + \t{0} & 0 \\ + \t{1} & 1 \\ + \t{2} & 2 \\ \bottomrule \end{tabular} } @@ -138,6 +238,7 @@ The \t{src\_test} function may be disabled by \t{RESTRICT}. See section~\ref{res \midrule \t{0} & At user option \\ \t{1} & At user option \\ + \t{2} & At user option \\ \t{kdebuild-1} & Required \\ \bottomrule \end{tabular} @@ -230,6 +331,7 @@ fully installed. It is the only ebuild function which may be interactive and pro \midrule \t{0} & No \\ \t{1} & No \\ + \t{2} & No \\ \t{kdebuild-1} & Yes \\ \bottomrule \end{tabular} @@ -246,6 +348,41 @@ source files from their respective locations, with notes concerning licensing if \t{pkg\_nofetch} must require no write access to any part of the filesystem. +\subsection{\t{default\_} Phase Functions} + +In EAPIs listed in table~\ref{default-phase-function-table} as supporting \t{default\_} phase +functions, a function named \t{default\_\$\{EBUILD\_PHASE\}} that behaves as the default +implementation for that EAPI shall be defined when executing any given \t{EBUILD\_PHASE}. Ebuilds +must not call these functions except when in the phase in question. + +\begin{centertable}{EAPIs supporting \t{default\_} phase functions} \label{default-phase-function-table} +\IFKDEBUILDELSE +{ + \begin{tabular}{ l l } + \toprule + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Supports \t{default\_} phase functions?}} \\ + \midrule + \t{0} & No \\ + \t{1} & No \\ + \t{kdebuild-1} & No \\ + \t{2} & Yes \\ + \bottomrule + \end{tabular} +}{ + \begin{tabular}{ l l } + \toprule + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Supports \t{default\_} phase functions?}} \\ + \midrule + \t{0} & No \\ + \t{1} & No \\ + \t{2} & Yes \\ + \bottomrule + \end{tabular} +} +\end{centertable} + \section{Call Order} The call order for installing a package is: @@ -253,6 +390,8 @@ The call order for installing a package is: \begin{compactitem} \item \t{pkg\_setup} \item \t{src\_unpack} +\item \t{src\_prepare} (only for EAPIs listed in table~\ref{src-prepare-table}) +\item \t{src\_configure} (only for EAPIs listed in table~\ref{src-configure-table}) \item \t{src\_compile} \item \t{src\_test} (except if \t{RESTRICT=test}) \item \t{src\_install} @@ -272,6 +411,8 @@ The call order for reinstalling a package is: \begin{compactitem} \item \t{pkg\_setup} \item \t{src\_unpack} +\item \t{src\_prepare} (only for EAPIs listed in table~\ref{src-prepare-table}) +\item \t{src\_configure} (only for EAPIs listed in table~\ref{src-configure-table}) \item \t{src\_compile} \item \t{src\_test} (except if \t{RESTRICT=test}) \item \t{src\_install} @@ -286,6 +427,8 @@ The call order for upgrading or downgrading a package is: \begin{compactitem} \item \t{pkg\_setup} \item \t{src\_unpack} +\item \t{src\_prepare} (only for EAPIs listed in table~\ref{src-prepare-table}) +\item \t{src\_configure} (only for EAPIs listed in table~\ref{src-configure-table}) \item \t{src\_compile} \item \t{src\_test} (except if \t{RESTRICT=test}) \item \t{src\_install} diff --git a/ebuild-vars.tex b/ebuild-vars.tex index 052dde4..262dfad 100644 --- a/ebuild-vars.tex +++ b/ebuild-vars.tex @@ -66,6 +66,7 @@ operations upon other ebuilds or packages. \t{0} & No \\ \t{1} & Yes \\ \t{kdebuild-1} & Yes \\ + \t{2} & Yes \\ \bottomrule \end{tabular} } @@ -77,6 +78,7 @@ operations upon other ebuilds or packages. \midrule \t{0} & No \\ \t{1} & Yes \\ + \t{2} & Yes \\ \bottomrule \end{tabular} } @@ -121,12 +123,16 @@ Ebuilds may define any of the following variables: \t{0} & Yes \\ \t{1} & Yes \\ \t{kdebuild-1} & No \\ + \t{2} & Yes \\ \bottomrule \end{tabular} \end{centertable} }{ } +\subsection{EAPI} +\label{pre-source-eapi} + 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. diff --git a/eclasses.tex b/eclasses.tex index dffc7a0..d60d739 100644 --- a/eclasses.tex +++ b/eclasses.tex @@ -12,6 +12,7 @@ section~\ref{eclass-dir}. Each eclass is a single file named \t{<name>.eclass}, the name of this eclass, used by \t{inherit} and \t{EXPORT\_FUNCTIONS} among other places. \section{The inherit command} +\label{inherit} An ebuild wishing to make use of an eclass does so by using the \t{inherit} command in global scope. This will cause the eclass to be sourced as part of the ebuild---any function or variable diff --git a/introduction.tex b/introduction.tex index a9ed5f9..58b6415 100644 --- a/introduction.tex +++ b/introduction.tex @@ -49,6 +49,8 @@ value is a string. The following EAPIs are defined by this specification: explicitly noted, it is in all other ways identical to EAPI `1'. }{ } +\item[2] EAPI `2' contains a number of extensions to EAPI `1'. Except where explicitly noted, it is + in all other ways identical to EAPI `1'. \end{description} \ifthenelse{\boolean{ENABLE-ALL-OPTIONS}\and\not\boolean{TEX4HT-HACKS}} @@ -82,6 +82,7 @@ This may optionally be followed by the suffix \t{-r} followed immediately by an \t{0} & No \\ \t{1} & No \\ \t{kdebuild-1} & Yes \\ + \t{2} & No \\ \bottomrule \end{tabular} \end{centertable} diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex index ac6106c..875bddb 100644 --- a/pkg-mgr-commands.tex +++ b/pkg-mgr-commands.tex @@ -26,6 +26,7 @@ behaviour. \t{0} & No & No & No \\ \t{1} & No & No & No \\ \t{kdebuild-1} & Yes & Yes & Yes \\ + \t{2} & No & No & No \\ \bottomrule \end{tabular} \end{centertable} @@ -250,7 +251,11 @@ are as follows: \end{algorithm} \item[doman] Installs a man page into the appropriate subdirectory of \t{/usr/share/man} depending - upon its apparent section suffix. + upon its apparent section suffix (e.g. \t{foo.1} goes to \t{/usr/share/man/man1/foo.1}. + In EAPIs listed in table~\ref{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. \item[domo] Installs a \t{.mo} file into the appropriate subdirectory of \t{DESTTREE/share/locale}, generated by taking the basename of the file, removing the \t{.*} suffix, and appending @@ -297,6 +302,34 @@ are as follows: \end{description} +\begin{centertable}{EAPIs supporting \t{doman} languages} \label{doman-table} +\IFKDEBUILDELSE +{ + \begin{tabular}{ l l } + \toprule + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Supports \t{doman} languages?}} \\ + \midrule + \t{0} & No \\ + \t{1} & No \\ + \t{kdebuild-1} & No \\ + \t{2} & Yes \\ + \bottomrule + \end{tabular} +}{ + \begin{tabular}{ l l } + \toprule + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Supports \t{doman} languages?}} \\ + \midrule + \t{0} & No \\ + \t{1} & No \\ + \t{2} & Yes \\ + \bottomrule + \end{tabular} +} +\end{centertable} + \IFKDEBUILDELSE { \begin{centertable}{EAPIs where \t{dosym} makes the directory} \label{dosym-table} @@ -308,6 +341,7 @@ are as follows: \t{0} & Yes \\ \t{1} & Yes \\ \t{kdebuild-1} & No \\ + \t{2} & Yes \\ \bottomrule \end{tabular} \end{centertable} @@ -423,8 +457,41 @@ has returned. \end{itemize} It is up to the ebuild to ensure that the relevant external utilities are available, whether by being in the system set or via dependencies. + +\item[inherit] See section~\ref{inherit}. + +\item[default] Calls the \t{default\_\$\{EBUILD\_PHASE\}} function. Only available in EAPIs listed in + table~\ref{default-function-table}. \end{description} +\begin{centertable}{EAPIs supporting the \t{default} function} \label{default-function-table} +\IFKDEBUILDELSE +{ + \begin{tabular}{ l l } + \toprule + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Supports \t{default} function?}} \\ + \midrule + \t{0} & No \\ + \t{1} & No \\ + \t{kdebuild-1} & No \\ + \t{2} & Yes \\ + \bottomrule + \end{tabular} +}{ + \begin{tabular}{ l l } + \toprule + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Supports \t{default} function?}} \\ + \midrule + \t{0} & No \\ + \t{1} & No \\ + \t{2} & Yes \\ + \bottomrule + \end{tabular} +} +\end{centertable} + \subsubsection{Debug Commands} The following commands are available for debugging. Normally all of these commands should be no ops; a package manager may provide a special debug mode where these commands instead do something. @@ -67,12 +67,18 @@ \ifthenelse{\boolean{ENABLE-ALL-OPTIONS}\and\not\boolean{TEX4HT-HACKS}} { \newcommand{\IFKDEBUILDELSE}[2]{{\def\mycolour{\color{deepblue}}\mycolour #1}{\def\mycolour{\color{deeppurple}}\mycolour #2}} + \newcommand{\IFANYKDEBUILDELSE}[2]{#1} + \newcommand{\IFKDEBUILDCOLOUR}[1]{{\def\mycolour{\color{deepblue}}\mycolour #1}} }{ \ifthenelse{\boolean{ENABLE-KDEBUILD}} { \newcommand{\IFKDEBUILDELSE}[2]{#1} + \newcommand{\IFANYKDEBUILDELSE}[2]{#1} + \newcommand{\IFKDEBUILDCOLOUR}[1]{#1} }{ \newcommand{\IFKDEBUILDELSE}[2]{#2} + \newcommand{\IFANYKDEBUILDELSE}[2]{#2} + \newcommand{\IFKDEBUILDCOLOUR}[1]{#1} } } @@ -144,6 +150,8 @@ \include{appendices} +\include{eapi-differences} + \bibliography{pms} \end{document} diff --git a/tree-layout.tex b/tree-layout.tex index ea74a0b..0dd030a 100644 --- a/tree-layout.tex +++ b/tree-layout.tex @@ -64,9 +64,9 @@ Any ebuild in a package directory must be named \t{name-ver.suffix}, where: \item \t{ver} is the package's version. \IFKDEBUILDELSE { - \item \t{suffix} is \t{ebuild} or \t{kdebuild-1}. + \item \label{file-extension} \t{suffix} is \t{ebuild} or \t{kdebuild-1}. }{ - \item \t{suffix} is \t{ebuild}. + \item \label{file-extension} \t{suffix} is \t{ebuild}. } \end{compactitem} |