From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by finch.gentoo.org (Postfix) with ESMTPS id 10347139694 for ; Mon, 15 May 2017 23:02:50 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 4F689E0DD7; Mon, 15 May 2017 23:02:29 +0000 (UTC) Received: from smtp.gentoo.org (smtp.gentoo.org [140.211.166.183]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id 069D4E0DD7 for ; Mon, 15 May 2017 23:02:29 +0000 (UTC) Received: from oystercatcher.gentoo.org (oystercatcher.gentoo.org [148.251.78.52]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.gentoo.org (Postfix) with ESMTPS id ECD843416D7 for ; Mon, 15 May 2017 23:02:27 +0000 (UTC) Received: from localhost.localdomain (localhost [IPv6:::1]) by oystercatcher.gentoo.org (Postfix) with ESMTP id 68C89745B for ; Mon, 15 May 2017 23:02:26 +0000 (UTC) From: "Ulrich Müller" To: gentoo-commits@lists.gentoo.org Content-Transfer-Encoding: 8bit Content-type: text/plain; charset=UTF-8 Reply-To: gentoo-dev@lists.gentoo.org, "Ulrich Müller" Message-ID: <1494882102.40612826e416cd4cd96d2dbdae7904ed4ee25833.ulm@gentoo> Subject: [gentoo-commits] proj/pms:master commit in: / X-VCS-Repository: proj/pms X-VCS-Files: appendices.tex dependencies.tex eapi-cheatsheet.tex eapi-differences.tex ebuild-env-commands.tex ebuild-env-invariancy.tex ebuild-env-state.tex ebuild-env-vars.tex ebuild-format.tex ebuild-functions.tex ebuild-vars.tex eclasses.tex merge.tex metadata-cache.tex names.tex pkg-mgr-commands.tex profile-variables.tex profiles.tex tree-layout.tex X-VCS-Directories: / X-VCS-Committer: ulm X-VCS-Committer-Name: Ulrich Müller X-VCS-Revision: 40612826e416cd4cd96d2dbdae7904ed4ee25833 X-VCS-Branch: master Date: Mon, 15 May 2017 23:02:26 +0000 (UTC) Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-commits@lists.gentoo.org X-Archives-Salt: 3e5aab68-e82e-4236-81b6-d6dcf72fb3b5 X-Archives-Hash: 04e1a900bd98e5fe8983675ca08bfa3a commit: 40612826e416cd4cd96d2dbdae7904ed4ee25833 Author: Ulrich Müller gentoo org> AuthorDate: Sat May 13 09:34:44 2017 +0000 Commit: Ulrich Müller gentoo org> CommitDate: Mon May 15 21:01:42 2017 +0000 URL: https://gitweb.gentoo.org/proj/pms.git/commit/?id=40612826 Use simple underscores throughout. Replacement was done using "sed -i 's/\\_/_/g' *.tex". This does not change the resulting PDF and HTML output. appendices.tex | 6 +- dependencies.tex | 68 ++++++------- eapi-cheatsheet.tex | 78 +++++++-------- eapi-differences.tex | 104 ++++++++++---------- ebuild-env-commands.tex | 2 +- ebuild-env-invariancy.tex | 10 +- ebuild-env-state.tex | 2 +- ebuild-env-vars.tex | 138 +++++++++++++------------- ebuild-format.tex | 2 +- ebuild-functions.tex | 242 +++++++++++++++++++++++----------------------- ebuild-vars.tex | 16 +-- eclasses.tex | 20 ++-- merge.tex | 16 +-- metadata-cache.tex | 6 +- names.tex | 30 +++--- pkg-mgr-commands.tex | 92 +++++++++--------- profile-variables.tex | 30 +++--- profiles.tex | 4 +- tree-layout.tex | 12 +-- 19 files changed, 439 insertions(+), 439 deletions(-) diff --git a/appendices.tex b/appendices.tex index 1b70568..8c97734 100644 --- a/appendices.tex +++ b/appendices.tex @@ -13,15 +13,15 @@ been abused in the past. \begin{compactitem} \item The \t{FEATURES} variable. This is Portage specific. -\item Similarly, any \t{EMERGE\_} variable and any \t{PORTAGE\_} variable not explicitly listed. +\item Similarly, any \t{EMERGE_} variable and any \t{PORTAGE_} variable not explicitly listed. \item Any Portage configuration file. \item The VDB (\t{/var/db/pkg}). Ebuilds must not access this or rely upon it existing or being in any particular format. -\item The \t{portageq} command. The \t{has\_version} and \t{best\_version} commands are +\item The \t{portageq} command. The \t{has_version} and \t{best_version} commands are available as functions. \item The \t{emerge} command. \item Binary packages. -\item The \t{PORTDIR\_OVERLAY} variable, and overlay behaviour in general. +\item The \t{PORTDIR_OVERLAY} variable, and overlay behaviour in general. \end{compactitem} \chapter{Historical Curiosities} diff --git a/dependencies.tex b/dependencies.tex index ee4339b..d9a6f1a 100644 --- a/dependencies.tex +++ b/dependencies.tex @@ -11,14 +11,14 @@ \multicolumn{1}{c}{\textbf{Phase function}} & \multicolumn{1}{c}{\textbf{Satisfied dependency classes}} \\ \midrule - \t{pkg\_pretend}, \t{pkg\_setup}, \t{pkg\_info}, \t{pkg\_nofetch} & + \t{pkg_pretend}, \t{pkg_setup}, \t{pkg_info}, \t{pkg_nofetch} & None (ebuilds can rely only on the packages in the system set) \\ - \t{src\_unpack}, \t{src\_prepare}, \t{src\_configure}, \t{src\_compile}, \t{src\_test}, - \t{src\_install} & \t{DEPEND} \\ - \t{pkg\_preinst}, \t{pkg\_postinst}, \t{pkg\_prerm}, \t{pkg\_postrm} & + \t{src_unpack}, \t{src_prepare}, \t{src_configure}, \t{src_compile}, \t{src_test}, + \t{src_install} & \t{DEPEND} \\ + \t{pkg_preinst}, \t{pkg_postinst}, \t{pkg_prerm}, \t{pkg_postrm} & \t{RDEPEND} (unless the particular dependency results in a circular dependency, in which case it may be installed later) \\ - \t{pkg\_config} & \t{RDEPEND}, \t{PDEPEND} \\ + \t{pkg_config} & \t{RDEPEND}, \t{PDEPEND} \\ \bottomrule \end{tabular} \end{centertable} @@ -27,7 +27,7 @@ There are three classes of dependencies supported by ebuilds: \begin{compactitem} \item Build dependencies (\t{DEPEND}). These must be installed and usable before any of - the ebuild \t{src\_*} phase functions is executed. These may not be installed at all + the ebuild \t{src_*} phase functions is executed. These may not be installed at all if a binary package is being merged. \item Runtime dependencies (\t{RDEPEND}). These must be installed and usable before the results of an ebuild merging are treated as usable. @@ -38,8 +38,8 @@ There are three classes of dependencies supported by ebuilds: Table~\ref{tab:phase-function-dependency-classes} lists dependencies which must be satisfied before a particular phase function is executed. -In addition, \t{SRC\_URI}, \t{HOMEPAGE}, \t{RESTRICT}, \t{PROPERTIES}, \t{LICENSE} and -\t{REQUIRED\_USE} use dependency-style specifications to specify their values. +In addition, \t{SRC_URI}, \t{HOMEPAGE}, \t{RESTRICT}, \t{PROPERTIES}, \t{LICENSE} and +\t{REQUIRED_USE} use dependency-style specifications to specify their values. \section{Dependency Specification Format} @@ -48,13 +48,13 @@ be surrounded on both sides by whitespace, except at the start and end of the st \begin{compactitem} \item A package dependency specification. Permitted in \t{DEPEND}, \t{RDEPEND}, \t{PDEPEND}. -\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 +\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}. + in \t{SRC_URI}\@. For \t{SRC_URI} behaviour, see section~\ref{sec:src-uri-behaviour}. +\item A flat filename. Permitted in \t{SRC_URI}. \item A license name (e.\,g.\ \t{GPL-2}). Permitted in \t{LICENSE}. -\item A use flag name, optionally preceded by an exclamation mark. Permitted in \t{REQUIRED\_USE}. +\item A use flag name, optionally preceded by an exclamation mark. Permitted in \t{REQUIRED_USE}. \item A simple string. Permitted in \t{RESTRICT} and \t{PROPERTIES}. \item An all-of group, which consists of an open parenthesis, followed by whitespace, followed by zero or more of (a dependency item of any kind followed by whitespace), followed @@ -65,19 +65,19 @@ be surrounded on both sides by whitespace, except at the start and end of the st followed by an open parenthesis, followed by whitespace, followed by zero or more of (a dependency item of any kind followed by whitespace), followed by a close parenthesis. More formally: \t{any-of} \t{::=} \t{'||' whitespace '(' whitespace (item whitespace)* ')'}. - Permitted in \t{DEPEND}, \t{RDEPEND}, \t{PDEPEND}, \t{LICENSE}, \t{REQUIRED\_USE}. + Permitted in \t{DEPEND}, \t{RDEPEND}, \t{PDEPEND}, \t{LICENSE}, \t{REQUIRED_USE}. \item An exactly-one-of group, which consists of the string \t{\textasciicircum\textasciicircum}, followed by whitespace, followed by an open parenthesis, followed by whitespace, followed by zero or more of (a dependency item of any kind followed by whitespace), followed by a close parenthesis. More formally: \t{exactly-one-of} \t{::=} \t{'\textasciicircum\textasciicircum' whitespace '(' whitespace (item whitespace)* ')'}. - Permitted in \t{REQUIRED\_USE}. + Permitted in \t{REQUIRED_USE}. \item \featurelabel{at-most-one-of} An at-most-one-of group, which consists of the string \t{??}, followed by whitespace, followed by an open parenthesis, followed by whitespace, followed by zero or more of (a dependency item of any kind followed by whitespace), followed by a close parenthesis. More formally: \t{at-most-one-of} \t{::=} \t{'??'\ whitespace '(' whitespace - (item whitespace)* ')'}. Permitted in \t{REQUIRED\_USE} in EAPIs listed in - table~\ref{tab:at-most-one-of-table} as supporting \t{REQUIRED\_USE ??}\ groups. + (item whitespace)* ')'}. Permitted in \t{REQUIRED_USE} in EAPIs listed in + table~\ref{tab:at-most-one-of-table} as supporting \t{REQUIRED_USE ??}\ groups. \item A use-conditional group, which consists of an optional exclamation mark, followed by a use flag name, followed by a question mark, followed by whitespace, followed by an open parenthesis, followed by whitespace, followed by zero or more of (a dependency item @@ -90,12 +90,12 @@ be surrounded on both sides by whitespace, except at the start and end of the st In particular, note that whitespace is not optional. \ChangeWhenAddingAnEAPI{6} -\begin{centertable}{EAPIs supporting \t{SRC\_URI} arrows} +\begin{centertable}{EAPIs supporting \t{SRC_URI} arrows} \label{tab:uri-arrows-table} \begin{tabular}{ll} \toprule \multicolumn{1}{c}{\textbf{EAPI}} & - \multicolumn{1}{c}{\textbf{Supports \t{SRC\_URI} arrows?}} \\ + \multicolumn{1}{c}{\textbf{Supports \t{SRC_URI} arrows?}} \\ \midrule 0, 1 & No \\ 2, 3, 4, 5, 6 & Yes \\ @@ -104,12 +104,12 @@ In particular, note that whitespace is not optional. \end{centertable} \ChangeWhenAddingAnEAPI{6} -\begin{centertable}{EAPIs supporting \t{REQUIRED\_USE ??}\ groups} +\begin{centertable}{EAPIs supporting \t{REQUIRED_USE ??}\ groups} \label{tab:at-most-one-of-table} \begin{tabular}{ll} \toprule \multicolumn{1}{c}{\textbf{EAPI}} & - \multicolumn{1}{c}{\textbf{Supports \t{REQUIRED\_USE ??}\ groups?}} \\ + \multicolumn{1}{c}{\textbf{Supports \t{REQUIRED_USE ??}\ groups?}} \\ \midrule 0, 1, 2, 3, 4 & No \\ 5, 6 & Yes \\ @@ -126,7 +126,7 @@ In an all-of group, all of the child elements must be matched. In a use-conditional group, if the associated use flag is enabled (or disabled if it has an exclamation mark prefix), all of the child elements must be matched. -It is an error for a flag to be used if it is not included in \t{IUSE\_EFFECTIVE} as described in +It is an error for a flag to be used if it is not included in \t{IUSE_EFFECTIVE} as described in section~\ref{sec:use-iuse-handling}. \subsection{Any-of dependency specifications} @@ -325,29 +325,29 @@ When multiple requirements are specified, all must match for a successful match. \featurelabel{use-dep-defaults} In a 4-style use dependency, the flag name may immediately be followed by a \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 as if the flag were present and enabled; +\t{IUSE_REFERENCEABLE}, the package manager shall behave as if the flag were present and enabled; the latter, present and disabled. Unless a 4-style default is specified, it is an error for a use dependency to be applied to an -ebuild which does not have the flag in question in \t{IUSE\_REFERENCEABLE}. +ebuild which does not have the flag in question in \t{IUSE_REFERENCEABLE}. \note By extension of the above, a default that could reference an ebuild using an EAPI not supporting profile \t{IUSE} injections cannot rely upon any particular behaviour for flags that would not have to be part of \t{IUSE}. It is an error for an ebuild to use a conditional use dependency when that ebuild does not have the -flag in \t{IUSE\_EFFECTIVE}. +flag in \t{IUSE_EFFECTIVE}. \subsection{USE state constraints} \label{sec:required-use} -\t{REQUIRED\_USE} contains a list of assertions that must be met by the configuration of \t{USE} +\t{REQUIRED_USE} contains a list of assertions that must be met by the configuration of \t{USE} flags to be valid for this ebuild. In order to be matched, a \t{USE} flag in a terminal element must be enabled (or disabled if it has an exclamation mark prefix). -If the package manager encounters a package version where \t{REQUIRED\_USE} assertions are not met, +If the package manager encounters a package version where \t{REQUIRED_USE} assertions are not met, it must treat this package version as if it was masked. No phase functions must be called. -It is an error for a flag to be used if it is not included in \t{IUSE\_EFFECTIVE}. +It is an error for a flag to be used if it is not included in \t{IUSE_EFFECTIVE}. \subsection{Restrict} \label{sec:restrict} @@ -355,13 +355,13 @@ It is an error for a flag to be used if it is not included in \t{IUSE\_EFFECTIVE 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 +\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. Implies \t{mirror}. +\item[fetch] The package's \t{SRC_URI} entries may not be downloaded automatically. If + entries are not available, \t{pkg_nofetch} is called. Implies \t{mirror}. \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[test] The \t{src_test} phase must not be run. \end{description} Package managers may recognise other tokens, but ebuilds may not rely upon them being supported. @@ -377,11 +377,11 @@ The following tokens are permitted inside \t{PROPERTIES}: Ebuilds may not rely upon any token being supported. -\subsection{SRC\_URI} +\subsection{SRC_URI} \label{sec: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 +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 diff --git a/eapi-cheatsheet.tex b/eapi-cheatsheet.tex index 6ac72b9..c14701f 100644 --- a/eapi-cheatsheet.tex +++ b/eapi-cheatsheet.tex @@ -94,7 +94,7 @@ differences between these previous EAPIs. % sign in front. See \featureref{iuse-defaults}. % \item[Named slot dependencies] Dependencies can explicitly request % a specific slot by using the -% \code{dev-libs/foo:}\allowbreak\emph{SLOT\_name} syntax. +% \code{dev-libs/foo:}\allowbreak\emph{SLOT_name} syntax. % See \featureref{slot-deps}. % \end{description} @@ -103,14 +103,14 @@ differences between these previous EAPIs. % \subsection{Additions/Changes} % \label{sec:cs:eapi2-additions} % \begin{description} -% \item[\code{SRC\_URI} arrows] Allows redirection of upstream file +% \item[\code{SRC_URI} arrows] Allows redirection of upstream file % naming scheme. By using -% \code{SRC\_URI="http:/\slash some\slash url -> foo"} the file is +% \code{SRC_URI="http:/\slash some\slash url -> foo"} the file is % saved as \code{foo} in DISTDIR\@. % See \featureref{src-uri-arrows}. % \item[USE dependencies] Dependencies can specify USE flag % requirements on their target, removing the need for -% \code{built\_with\_use} checks. +% \code{built_with_use} checks. % \begin{description} % \item[{[opt]}] The flag must be enabled. % \item[{[opt=]}] The flag must be enabled if it is @@ -130,20 +130,20 @@ differences between these previous EAPIs. % be ignored by the package manager as long as the stated package is % uninstalled later on. Two exclamation marks are a strong blocker % and will always be respected. See \featureref{bang-strength}. -% \item[\code{src\_configure, src\_prepare}] Both new phases provide +% \item[\code{src_configure, src_prepare}] Both new phases provide % finer granularity in the ebuild's structure. Configure calls -% should be moved from \code{src\_compile} to \code{src\_configure}. +% should be moved from \code{src_compile} to \code{src_configure}. % Patching and similar preparation must now be done in -% \code{src\_prepare}, not \code{src\_unpack}. See +% \code{src_prepare}, not \code{src_unpack}. See % \featureref{src-prepare} and \featureref{src-configure}. % \item[Default phase functions] The default functions for -% phases \code{pkg\_nofetch}, \code{src\_unpack}, -% \code{src\_prepare}, \code{src\_configure}, \code{src\_compile} -% and \code{src\_test} can be called via -% \code{default\_}\emph{phasename}, so duplicating the standard +% phases \code{pkg_nofetch}, \code{src_unpack}, +% \code{src_prepare}, \code{src_configure}, \code{src_compile} +% and \code{src_test} can be called via +% \code{default_}\emph{phasename}, so duplicating the standard % implementation is no longer necessary for small additions. The % short-hand \code{default} function calls the current phase's -% \code{default\_} function automatically, so any small additions +% \code{default_} function automatically, so any small additions % you need will not be accompanied by a complete reimplementation of % the phase. See \featureref{default-phase-funcs} and % \featureref{default-func}. @@ -160,7 +160,7 @@ differences between these previous EAPIs. \begin{description} \item[Support for \code{.xz}] Unpack of \code{.xz} and \code{.tar.xz} files is possible without any custom - \code{src\_unpack} functions. See \featureref{unpack-extensions}. + \code{src_unpack} functions. See \featureref{unpack-extensions}. \item[Offset prefix] Supporting installation on Prefix-enabled systems will be easier with this EAPI. \end{description} @@ -170,17 +170,17 @@ differences between these previous EAPIs. \subsection{Additions/Changes} \label{sec:cs:eapi4-additions} \begin{description} - \item[\code{pkg\_pretend}] Some useful checks (kernel options for + \item[\code{pkg_pretend}] Some useful checks (kernel options for example) can be placed in this new phase to inform the user early (when just pretending to emerge the package). Most checks should - usually be repeated in \code{pkg\_setup}. + usually be repeated in \code{pkg_setup}. See \featureref{pkg-pretend}. - \item[\code{src\_install}] The \code{src\_install} phase is no + \item[\code{src_install}] The \code{src_install} phase is no longer empty but has a default now. This comes along with an accompanying \code{default} function. See \featureref{src-install-4}. - \item[\code{pkg\_info} on non-installed packages] The - \code{pkg\_info} phase can be called even for non-installed + \item[\code{pkg_info} on non-installed packages] The + \code{pkg_info} phase can be called even for non-installed packages. Be warned that dependencies might not have been installed at execution time. See \featureref{pkg-info}. \item[\code{econf} changes] The helper function now always @@ -190,12 +190,12 @@ differences between these previous EAPIs. in EAPI 2 for USE dependencies, a \code{(+)} or \code{(-)} can be added after a USE flag (mind the parentheses). The former specifies that flags not in IUSE should be treated as enabled; the - latter, disabled. Cannot be used with USE\_EXPAND flags. This + latter, disabled. Cannot be used with USE_EXPAND flags. This mimics parts of the behaviour of \code{-{}-missing} in - \code{built\_with\_use}. See \featureref{use-dep-defaults}. + \code{built_with_use}. See \featureref{use-dep-defaults}. \item[Controllable compression] All items in the \code{doc}, \code{info}, \code{man} subdirectories of \code{/usr/share/} may - be compressed on-disk after \code{src\_install}, except for + be compressed on-disk after \code{src_install}, except for \code{/usr/share/doc/\$\{PF\}/html}. \code{docompress path \dots} adds paths to the inclusion list for compression. \code{docompress -x path \dots} adds paths to the exclusion list. @@ -213,7 +213,7 @@ differences between these previous EAPIs. See \featureref{doins}. \item[\code{PROPERTIES}] Is mandatory for all package managers now to support interactive installs. - \item[\code{REQUIRED\_USE}] This variable can be used similar to + \item[\code{REQUIRED_USE}] This variable can be used similar to the \code{(R|P)DEPEND} variables and define sets of USE flag combinations that are not allowed. All elements can be further nested to achieve more functionality. @@ -228,13 +228,13 @@ differences between these previous EAPIs. "\code{\textasciicircum\textasciicircum ( flag1 flag2 \dots\ )}". \end{description} See \featureref{required-use}. - \item[\code{MERGE\_TYPE}] This variable contains one of three + \item[\code{MERGE_TYPE}] This variable contains one of three possible values to allow checks if it is normal merge with compilation and installation (\code{source}), installation of a binary package (\code{binary}), or a compilation without installation (\code{buildonly}). See \featureref{merge-type}. - \item[\code{REPLACING\_VERSIONS}, \code{REPLACED\_BY\_VERSION}] - These variables, valid in \code{pkg\_*}, contain a list of all + \item[\code{REPLACING_VERSIONS}, \code{REPLACED_BY_VERSION}] + These variables, valid in \code{pkg_*}, contain a list of all versions (\code{PVR}) of this package that we are replacing, and the version that is replacing the current one, respectively. See \featureref{replace-version-vars}. @@ -283,17 +283,17 @@ differences between these previous EAPIs. explicitly listed in \code{IUSE}, additional flags can be implicitly provided by profiles. See \featureref{profile-iuse-inject}. - \item[At-most-one-of groups] In \code{REQUIRED\_USE} you can use + \item[At-most-one-of groups] In \code{REQUIRED_USE} you can use "\code{??\ ( flag1 flag2 \dots\ )}" to allow zero or one USE flag out of many. See \featureref{at-most-one-of}. - \item[Parallel tests] The default for \code{src\_test} runs + \item[Parallel tests] The default for \code{src_test} runs \code{emake} without \code{-j1} now. See \featureref{parallel-tests}. \item[\code{econf} changes] The \code{econf} function now always passes \code{-{}-disable-silent-rules} to \code{configure}. See \featureref{econf-options}. - \item[\code{has\_version} and \code{best\_version} changes] + \item[\code{has_version} and \code{best_version} changes] The two helpers support a \code{-{}-host-root} option that causes the query to apply to the host root instead of \code{ROOT}. See~\featureref{host-root-option}. @@ -312,8 +312,8 @@ differences between these previous EAPIs. read from standard input if the first argument is \code{-} (a hyphen). See \featureref{newfoo-stdin}. - \item[\code{EBUILD\_PHASE\_FUNC}] This variable is very similar to - \code{EBUILD\_PHASE}, but contains the name of the current ebuild + \item[\code{EBUILD_PHASE_FUNC}] This variable is very similar to + \code{EBUILD_PHASE}, but contains the name of the current ebuild function. See \featureref{ebuild-phase-func}. \item[Stable use masking/forcing] New files @@ -339,15 +339,15 @@ differences between these previous EAPIs. See \featureref{failglob}. \item[Locale settings] It is ensured that the behaviour of case modification and collation order for ASCII characters - (\code{LC\_CTYPE} and \code{LC\_COLLATE}) are the same as in the + (\code{LC_CTYPE} and \code{LC_COLLATE}) are the same as in the POSIX locale. See \featureref{locale-settings}. - \item[\code{src\_prepare}] This phase function has a default now, + \item[\code{src_prepare}] This phase function has a default now, which applies patches from the \code{PATCHES} variable with the new \code{eapply} command, and user-provided patches with - \code{eapply\_user}. + \code{eapply_user}. See \featureref{src-prepare-6}. - \item[\code{src\_install}] The default implementation uses the new + \item[\code{src_install}] The default implementation uses the new \code{einstalldocs} function for installing documentation. See \featureref{src-install-6}. \item[\code{nonfatal die}] When \code{die} or \code{assert} are @@ -376,20 +376,20 @@ differences between these previous EAPIs. The patches from its file or directory arguments are applied using \code{patch -p1}. See \featureref{eapply}. - \item[\code{eapply\_user}] The \code{eapply\_user} command permits + \item[\code{eapply_user}] The \code{eapply_user} command permits the package manager to apply user-provided patches. It must be - called from every \code{src\_prepare} function. + called from every \code{src_prepare} function. See \featureref{eapply-user}. \item[\code{einstalldocs}] The \code{einstalldocs} function will install the files specified by the \code{DOCS} variable (or a default set of files if \code{DOCS} is unset) and by the - \code{HTML\_DOCS} variable. + \code{HTML_DOCS} variable. See \featureref{einstalldocs}. - \item[\code{in\_iuse}] The \code{in\_iuse} function returns + \item[\code{in_iuse}] The \code{in_iuse} function returns true if the USE flag given as its argument is available in the ebuild for USE queries. See \featureref{in-iuse}. - \item[\code{get\_libdir}] The \code{get\_libdir} command outputs + \item[\code{get_libdir}] The \code{get_libdir} command outputs the \code{lib*} directory basename suitable for the current ABI. See \featureref{get-libdir}. \end{description} diff --git a/eapi-differences.tex b/eapi-differences.tex index c552497..8f8bf72 100644 --- a/eapi-differences.tex +++ b/eapi-differences.tex @@ -49,7 +49,7 @@ Bash version & \compactfeatureref{bash-version} & \t{IUSE} defaults & \compactfeatureref{iuse-defaults} & * & Yes & Yes & Yes & Yes \\ -\t{REQUIRED\_USE} & \compactfeatureref{required-use} & +\t{REQUIRED_USE} & \compactfeatureref{required-use} & No & No & Yes & Yes & Yes \\ \t{PROPERTIES} & \compactfeatureref{properties} & @@ -58,13 +58,13 @@ Bash version & \compactfeatureref{bash-version} & \t{RDEPEND=DEPEND} & \compactfeatureref{rdepend-depend} & Yes & Yes & No & No & No \\ -\t{DEFINED\_PHASES} & \compactfeatureref{defined-phases} & +\t{DEFINED_PHASES} & \compactfeatureref{defined-phases} & Optionally & Optionally & Yes & Yes & Yes \\ \t{??\ ( )} groups & \compactfeatureref{at-most-one-of} & No & No & No & Yes & Yes \\ -\t{SRC\_URI} arrows & \compactfeatureref{src-uri-arrows} & +\t{SRC_URI} arrows & \compactfeatureref{src-uri-arrows} & * & Yes & Yes & Yes & Yes \\ Slot dependencies & \compactfeatureref{slot-deps} & @@ -85,40 +85,40 @@ Use dependencies & \compactfeatureref{use-deps} & \t{S} to \t{WORKDIR} fallback & \compactfeatureref{s-workdir-fallback} & Always & Always & Conditional & Conditional & Conditional \\ -\t{pkg\_pretend} & \compactfeatureref{pkg-pretend} & +\t{pkg_pretend} & \compactfeatureref{pkg-pretend} & No & No & Yes & Yes & Yes \\ -\t{src\_prepare} & \compactfeatureref{src-prepare} & +\t{src_prepare} & \compactfeatureref{src-prepare} & * & Yes & Yes & Yes & Yes \\ -\t{src\_prepare} style & \compactfeatureref{src-prepare} & +\t{src_prepare} style & \compactfeatureref{src-prepare} & * & no-op & no-op & no-op & 6 \\ -\t{src\_configure} & \compactfeatureref{src-configure} & +\t{src_configure} & \compactfeatureref{src-configure} & * & Yes & Yes & Yes & Yes \\ -\t{src\_compile} style & \compactfeatureref{src-compile} & +\t{src_compile} style & \compactfeatureref{src-compile} & * & 2 & 2 & 2 & 2 \\ Parallel tests & \compactfeatureref{parallel-tests} & No & No & No & Yes & Yes \\ -\t{src\_install} style & \compactfeatureref{src-install} & +\t{src_install} style & \compactfeatureref{src-install} & no-op & no-op & 4 & 4 & 6 \\ -\t{pkg\_info} & \compactfeatureref{pkg-info} & +\t{pkg_info} & \compactfeatureref{pkg-info} & Installed & Installed & Both & Both & Both \\ -\t{default\_} phase functions & \compactfeatureref{default-phase-funcs} & +\t{default_} phase functions & \compactfeatureref{default-phase-funcs} & * & - \t{pkg\_nofetch}, \t{src\_unpack}, \t{src\_prepare}, \t{src\_configure}, - \t{src\_compile}, \t{src\_test} & - \t{pkg\_nofetch}, \t{src\_unpack}, \t{src\_prepare}, \t{src\_configure}, - \t{src\_compile}, \t{src\_install}, \t{src\_test} & - \t{pkg\_nofetch}, \t{src\_unpack}, \t{src\_prepare}, \t{src\_configure}, - \t{src\_compile}, \t{src\_install}, \t{src\_test} & - \t{pkg\_nofetch}, \t{src\_unpack}, \t{src\_prepare}, \t{src\_configure}, - \t{src\_compile}, \t{src\_install}, \t{src\_test} \\ + \t{pkg_nofetch}, \t{src_unpack}, \t{src_prepare}, \t{src_configure}, + \t{src_compile}, \t{src_test} & + \t{pkg_nofetch}, \t{src_unpack}, \t{src_prepare}, \t{src_configure}, + \t{src_compile}, \t{src_install}, \t{src_test} & + \t{pkg_nofetch}, \t{src_unpack}, \t{src_prepare}, \t{src_configure}, + \t{src_compile}, \t{src_install}, \t{src_test} & + \t{pkg_nofetch}, \t{src_unpack}, \t{src_prepare}, \t{src_configure}, + \t{src_compile}, \t{src_install}, \t{src_test} \\ \t{AA} & \compactfeatureref{aa} & Yes & Yes & No & No & No \\ @@ -126,10 +126,10 @@ Parallel tests & \compactfeatureref{parallel-tests} & \t{KV} & \compactfeatureref{kv} & Yes & Yes & No & No & No \\ -\t{EBUILD\_PHASE\_FUNC} & \compactfeatureref{ebuild-phase-func} & +\t{EBUILD_PHASE_FUNC} & \compactfeatureref{ebuild-phase-func} & No & No & No & Yes & Yes \\ -\t{MERGE\_TYPE} & \compactfeatureref{merge-type} & +\t{MERGE_TYPE} & \compactfeatureref{merge-type} & No & No & Yes & Yes & Yes \\ Sane locale settings & \compactfeatureref{locale-settings} & @@ -138,10 +138,10 @@ Sane locale settings & \compactfeatureref{locale-settings} & Profile \t{IUSE} injection & \compactfeatureref{profile-iuse-inject} & No & No & No & Yes & Yes \\ -\t{REPLACING\_VERSIONS} & \compactfeatureref{replace-version-vars} & +\t{REPLACING_VERSIONS} & \compactfeatureref{replace-version-vars} & No & No & Yes & Yes & Yes \\ -\t{REPLACED\_BY\_VERSION} & \compactfeatureref{replace-version-vars} & +\t{REPLACED_BY_VERSION} & \compactfeatureref{replace-version-vars} & No & No & Yes & Yes & Yes \\ \t{EPREFIX}, \t{ED}, \t{EROOT} & \compactfeatureref{offset-prefix-vars} & @@ -177,7 +177,7 @@ Option \t{-{}-host-root} & \compactfeatureref{host-root-option} & \t{eapply} & \compactfeatureref{eapply} & No & No & No & No & Yes \\ -\t{eapply\_user} & \compactfeatureref{eapply-user} & +\t{eapply_user} & \compactfeatureref{eapply-user} & No & No & No & No & Yes \\ \t{econf} arguments & \compactfeatureref{econf-options} & @@ -209,13 +209,13 @@ Controllable compression & \compactfeatureref{docompress} & \t{docompress} & \compactfeatureref{docompress} & No & No & Yes & Yes & Yes \\ -\t{use\_with} empty third arg & \compactfeatureref{use-with} & +\t{use_with} empty third arg & \compactfeatureref{use-with} & No & No & Yes & Yes & Yes \\ \t{usex} & \compactfeatureref{usex} & No & No & No & Yes & Yes \\ -\t{in\_iuse} & \compactfeatureref{in-iuse} & +\t{in_iuse} & \compactfeatureref{in-iuse} & No & No & No & No & Yes \\ \t{unpack} absolute paths & \compactfeatureref{unpack-absolute} & @@ -236,7 +236,7 @@ Controllable compression & \compactfeatureref{docompress} & \t{einstalldocs} & \compactfeatureref{einstalldocs} & No & No & No & No & Yes \\ -\t{get\_libdir} & \compactfeatureref{get-libdir} & +\t{get_libdir} & \compactfeatureref{get-libdir} & No & No & No & No & Yes \\ File mtimes preserved & \compactfeatureref{mtime-preserve} & @@ -260,7 +260,7 @@ EAPI 1 is EAPI 0 with the following changes: \begin{compactitem} \item \t{IUSE} defaults, \featureref{iuse-defaults}. \item Slot dependencies, \featureref{slot-deps}. -\item Different \t{src\_compile} implementation, \featureref{src-compile-1}. +\item Different \t{src_compile} implementation, \featureref{src-compile-1}. \end{compactitem} \section{EAPI 2} @@ -270,12 +270,12 @@ EAPI 2 is EAPI 1 with the following changes: \begin{compactitem} \item Use dependencies, \featureref{use-deps}. \item \t{!}\ and \t{!!}\ blockers, \featureref{bang-strength}. -\item \t{SRC\_URI} arrows, \featureref{src-uri-arrows}. -\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}; \featureref{default-phase-funcs}. +\item \t{SRC_URI} arrows, \featureref{src-uri-arrows}. +\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}; \featureref{default-phase-funcs}. \item \t{doman} language detection by filename, \featureref{doman-langs}. \item \t{default} function, \featureref{default-func}. \end{compactitem} @@ -296,18 +296,18 @@ EAPI 4 is EAPI 3 with the following changes: \begin{compactitem} \item \t{PROPERTIES} support is mandatory, \featureref{properties}. -\item \t{REQUIRED\_USE}, \featureref{required-use}. +\item \t{REQUIRED_USE}, \featureref{required-use}. \item \t{RDEPEND=DEPEND} no longer done, \featureref{rdepend-depend}. -\item \t{DEFINED\_PHASES} support is mandatory, \featureref{defined-phases}. +\item \t{DEFINED_PHASES} support is mandatory, \featureref{defined-phases}. \item Use dependency defaults, \featureref{use-dep-defaults}. \item \t{S} to \t{WORKDIR} fallback restricted, \featureref{s-workdir-fallback}. -\item \t{pkg\_pretend}, \featureref{pkg-pretend}. -\item Default \t{src\_install} no longer a no-op, \featureref{src-install-4}. -\item \t{pkg\_info} can run on non-installed packages, \featureref{pkg-info}. +\item \t{pkg_pretend}, \featureref{pkg-pretend}. +\item Default \t{src_install} no longer a no-op, \featureref{src-install-4}. +\item \t{pkg_info} can run on non-installed packages, \featureref{pkg-info}. \item \t{AA} is gone, \featureref{aa}. \item \t{KV} is gone, \featureref{kv}. -\item \t{MERGE\_TYPE}, \featureref{merge-type}. -\item \t{REPLACING\_VERSIONS} and \t{REPLACED\_BY\_VERSION}, \featureref{replace-version-vars}. +\item \t{MERGE_TYPE}, \featureref{merge-type}. +\item \t{REPLACING_VERSIONS} and \t{REPLACED_BY_VERSION}, \featureref{replace-version-vars}. \item Utilities now die on failure, \featureref{die-on-failure}, unless called under \t{nonfatal}, \featureref{nonfatal} \item \t{dohard}, \t{dosed} banned, \featureref{banned-commands}. @@ -316,7 +316,7 @@ EAPI 4 is EAPI 3 with the following changes: \item \t{doins} supports symlinks, \featureref{doins}. \item \t{doman -i18n} option takes precedence, \featureref{doman-langs}. \item Controllable compression and \t{docompress}, \featureref{docompress}. -\item \t{use\_with} and \t{use\_enable} support empty third argument, \featureref{use-with}. +\item \t{use_with} and \t{use_enable} support empty third argument, \featureref{use-with}. \end{compactitem} \section{EAPI 5} @@ -325,14 +325,14 @@ EAPI 5 is EAPI 4 with the following changes: \begin{compactitem} \item Stable use masking and forcing, \featureref{stablemask}. -\item \t{REQUIRED\_USE} now supports \t{??}\ groups, \featureref{at-most-one-of}. +\item \t{REQUIRED_USE} now supports \t{??}\ groups, \featureref{at-most-one-of}. \item Slot operator dependencies, \featureref{slot-operator-deps}. \item \t{SLOT} now supports an optional sub-slot part, \featureref{sub-slot}. -\item \t{src\_test} supports parallel tests, \featureref{parallel-tests}. -\item \t{EBUILD\_PHASE\_FUNC}, \featureref{ebuild-phase-func}. +\item \t{src_test} supports parallel tests, \featureref{parallel-tests}. +\item \t{EBUILD_PHASE_FUNC}, \featureref{ebuild-phase-func}. \item \t{USE} is calculated differently, \featureref{profile-iuse-inject}. \item \t{find} is guaranteed to be GNU, \featureref{gnu-find}. -\item \t{best\_version} and \t{has\_version} support the \t{-{}-host-root} option, +\item \t{best_version} and \t{has_version} support the \t{-{}-host-root} option, \featureref{host-root-option}. \item \t{econf} adds \t{-{}-disable-silent-rules}, \featureref{econf-options}. \item \t{doheader} and \t{newheader} support, \featureref{doheader}. @@ -346,21 +346,21 @@ EAPI 6 is EAPI 5 with the following changes: \begin{compactitem} \item Bash version is 4.2, \featureref{bash-version}. -\item Default \t{src\_prepare} no longer a no-op, \featureref{src-prepare-6}. -\item Different \t{src\_install} implementation, \featureref{src-install-6}. -\item \t{LC\_CTYPE} and \t{LC\_COLLATE} compatible with POSIX locale, \featureref{locale-settings}. +\item Default \t{src_prepare} no longer a no-op, \featureref{src-prepare-6}. +\item Different \t{src_install} implementation, \featureref{src-install-6}. +\item \t{LC_CTYPE} and \t{LC_COLLATE} compatible with POSIX locale, \featureref{locale-settings}. \item \t{failglob} is enabled in global scope, \featureref{failglob}. \item \t{einstall} banned, \featureref{banned-commands}. \item \t{die} and \t{assert} called with \t{-n} respect \t{nonfatal}, \featureref{nonfatal-die}. \item \t{eapply} support, \featureref{eapply}. -\item \t{eapply\_user} support, \featureref{eapply-user}. +\item \t{eapply_user} support, \featureref{eapply-user}. \item \t{econf} adds \t{-{}-docdir} and \t{-{}-htmldir}, \featureref{econf-options}. -\item \t{in\_iuse} support, \featureref{in-iuse}. +\item \t{in_iuse} support, \featureref{in-iuse}. \item \t{unpack} supports absolute and relative paths, \featureref{unpack-absolute}. \item \t{unpack} supports \t{.txz}, \featureref{unpack-extensions}. \item \t{unpack} matches filename extensions case-insensitively, \featureref{unpack-ignore-case}. \item \t{einstalldocs} support, \featureref{einstalldocs}. -\item \t{get\_libdir} support, \featureref{get-libdir}. +\item \t{get_libdir} support, \featureref{get-libdir}. \end{compactitem} \ChangeWhenAddingAnEAPI{6} diff --git a/ebuild-env-commands.tex b/ebuild-env-commands.tex index 921a664..d1773f5 100644 --- a/ebuild-env-commands.tex +++ b/ebuild-env-commands.tex @@ -4,7 +4,7 @@ This section documents the commands available to an ebuild. Unless otherwise spe aliases, shell functions, or executables in the ebuild's \t{PATH}. When an ebuild is being sourced for metadata querying rather than for a build (that is to say, -when none of the \t{src\_} or \t{pkg\_} functions are to be called), no external command may +when none of the \t{src_} or \t{pkg_} functions are to be called), no external command may be executed. The package manager may take steps to enforce this. \subsection{System commands} diff --git a/ebuild-env-invariancy.tex b/ebuild-env-invariancy.tex index 861e6b9..cc95a2b 100644 --- a/ebuild-env-invariancy.tex +++ b/ebuild-env-invariancy.tex @@ -6,10 +6,10 @@ For the sake of this section: \item Variancy is any package manager action that modifies either \t{ROOT} or \t{/} in any way that isn't merely a simple addition of something that doesn't alter other packages. This includes any - non-default call to any \t{pkg} phase function except \t{pkg\_setup}, + non-default call to any \t{pkg} phase function except \t{pkg_setup}, a merge of any package or an unmerge of any package. \item As an exception, changes to \t{DISTDIR} do not count as variancy. -\item The \t{pkg\_setup} function may be assumed not to introduce variancy. +\item The \t{pkg_setup} function may be assumed not to introduce variancy. Thus, ebuilds must not perform variant actions in this phase. \end{compactitem} @@ -17,10 +17,10 @@ The following exclusivity and invariancy requirements are mandated: \begin{compactitem} \item No variancy shall be introduced at any point between a package's - \t{pkg\_setup} being started up to the point that that package is + \t{pkg_setup} being started up to the point that that package is merged, except for any variancy introduced by that package. -\item There must be no variancy between a package's \t{pkg\_setup} and - a package's \t{pkg\_postinst}, except for any variancy introduced +\item There must be no variancy between a package's \t{pkg_setup} and + a package's \t{pkg_postinst}, except for any variancy introduced by that package. \item Any non-default \t{pkg} phase function must be run exclusively. \item Each phase function must be called at most once during the build diff --git a/ebuild-env-state.tex b/ebuild-env-state.tex index d2cf7b4..2333b01 100644 --- a/ebuild-env-state.tex +++ b/ebuild-env-state.tex @@ -5,7 +5,7 @@ Exported and default scope variables are saved between functions. A non-local va function earlier in the call sequence must have its value preserved for later functions, including functions executed as part of a later uninstall. -\note \t{pkg\_pretend} is \e{not} part of the normal call sequence, and does not take part in +\note \t{pkg_pretend} is \e{not} part of the normal call sequence, and does not take part in environment saving. Variables that were exported must remain exported in later functions; variables with default diff --git a/ebuild-env-vars.tex b/ebuild-env-vars.tex index 82ab4cf..8b43b09 100644 --- a/ebuild-env-vars.tex +++ b/ebuild-env-vars.tex @@ -7,8 +7,8 @@ any value. Ebuilds must not attempt to modify any of these variables, unless oth Because of their special meanings, these variables may not be preserved consistently across all phases as would normally happen due to environment saving (see~\ref{sec:ebuild-env-state}). For example, -\t{EBUILD\_PHASE} is different for every phase, and \t{ROOT} may have changed between the various -different \t{pkg\_*} phases. Ebuilds must recalculate any variable they derive from an inconsistent +\t{EBUILD_PHASE} is different for every phase, and \t{ROOT} may have changed between the various +different \t{pkg_*} phases. Ebuilds must recalculate any variable they derive from an inconsistent variable. \begin{landscape} @@ -67,12 +67,12 @@ variable. Yes & Package version and revision (if any), for example \t{7.0.174} or \t{7.0.174-r1}. \\ \t{A} & - \t{src\_*}, \t{pkg\_nofetch} & + \t{src_*}, \t{pkg_nofetch} & Yes & All source files available for the package, whitespace separated with no leading or trailing whitespace, and in the order in which the item first appears in a matched component of - \t{SRC\_URI}\@. Does not include any that are disabled because of USE conditionals. The value is - calculated from the base names of each element of the \t{SRC\_URI} ebuild metadata variable. \\ + \t{SRC_URI}\@. Does not include any that are disabled because of USE conditionals. The value is + calculated from the base names of each element of the \t{SRC_URI} ebuild metadata variable. \\ \t{AA}\footnote{This variable is generally considered deprecated. However, ebuilds must still assume that the package manager sets it in the EAPIs supporting it. For example, a few configure scripts use this variable to find the \t{aalib} package; ebuilds calling such @@ -81,10 +81,10 @@ variable. 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 + of each element of the \t{SRC_URI} ebuild metadata variable. Only for EAPIs listed in table~\ref{tab:removed-env-vars-table} as supporting \t{AA}. \\ \t{FILESDIR} & - \t{src\_*}, global~scope\footnote{Not necessarily present when installing from a binary package. + \t{src_*}, global~scope\footnote{Not necessarily present when installing from a binary package. Ebuilds must not access the directory in global scope.} & Yes & The full path to a directory where the files from the package's files directory (used for @@ -101,22 +101,22 @@ variable. The full path to the ebuild's working directory, where all build data should be contained.% \label{env-var-WORKDIR} \\ \t{S} & - \t{src\_*} & + \t{src_*} & Yes & - The full path to the temporary build directory, used by \t{src\_compile}, \t{src\_install} etc. + The full path to the temporary build directory, used by \t{src_compile}, \t{src_install} etc. Defaults to \t{\$\{WORKDIR\}/\$\{P\}}. May be modified by ebuilds. If \t{S} is assigned in the global scope of an ebuild, then the restrictions of section~\ref{sec:ebuild-env-state} for global variables apply. \\ \t{PORTDIR} & - \t{src\_*} & + \t{src_*} & No & The full path to the master repository's base directory. \\ \t{ECLASSDIR} & - \t{src\_*} & + \t{src_*} & No & The full path to the master repository's eclass directory. \\ \t{ROOT} & - \t{pkg\_*} & + \t{pkg_*} & No & The absolute path to the root directory into which the package is to be merged. Phases which run with full filesystem access must not touch any files outside of the directory given in @@ -124,7 +124,7 @@ variable. will not be executable on the build machine, so ebuilds must not call them. \t{ROOT} must be non-empty and end in a trailing slash. \\ \t{EROOT} & - \t{pkg\_*} & + \t{pkg_*} & No & Contains the path \t{\$\{ROOT\%/\}\$\{EPREFIX\}/} for convenience. See also the \t{EPREFIX} variable. Only for EAPIs listed in table~\ref{tab:offset-env-vars-table} as @@ -156,27 +156,27 @@ variable. See also~\ref{sec:offset-vars}. Only for EAPIs listed in table~\ref{tab:offset-env-vars-table} as supporting \t{EPREFIX}. \\ \t{D} & - \t{src\_install} & + \t{src_install} & No & Contains the full path to the image directory into which the package should be installed. Must be non-empty and end in a trailing slash. \\ \t{D} (continued) & - \t{pkg\_preinst}, \t{pkg\_postinst} & + \t{pkg_preinst}, \t{pkg_postinst} & Yes & Contains the full path to the image that is about to be or has just been merged. Must be non-empty and end in a trailing slash. \\ \t{ED} & - \t{src\_install}, \t{pkg\_preinst}, \t{pkg\_postinst} & + \t{src_install}, \t{pkg_preinst}, \t{pkg_postinst} & See \t{D} & Contains the path \t{\$\{D\%/\}\$\{EPREFIX\}/} for convenience. See also the \t{EPREFIX} variable. Only for EAPIs listed in table~\ref{tab:offset-env-vars-table} as supporting \t{ED}. \\ \t{DESTTREE} & - \t{src\_install} & + \t{src_install} & No & Controls the location where \t{dobin}, \t{dolib}, \t{domo}, and \t{dosbin} install things. \\ \t{INSDESTTREE} & - \t{src\_install} & + \t{src_install} & No & Controls the location where \t{doins} installs things. \\ \t{USE} & @@ -184,7 +184,7 @@ variable. Yes & A whitespace-delimited list of all active USE flags for this ebuild. See section~\ref{sec:use-iuse-handling} for details. \\ -\t{EBUILD\_PHASE} & +\t{EBUILD_PHASE} & All & No & Takes one of the values \t{config}, \t{setup}, \t{nofetch}, \t{unpack}, \t{prepare}, @@ -192,43 +192,43 @@ variable. \t{postrm}, \t{info}, \t{pretend} 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{EBUILD\_PHASE\_FUNC} & +\t{EBUILD_PHASE_FUNC} & All & No & - \featurelabel{ebuild-phase-func} Takes one of the values \t{pkg\_config}, \t{pkg\_setup}, - \t{pkg\_nofetch}, \t{src\_unpack}, \t{src\_prepare}, \t{src\_configure}, \t{src\_compile}, - \t{src\_test}, \t{src\_install}, \t{pkg\_preinst}, \t{pkg\_postinst}, \t{pkg\_prerm}, - \t{pkg\_postrm}, \t{pkg\_info}, \t{pkg\_pretend} according to the top level ebuild function that + \featurelabel{ebuild-phase-func} Takes one of the values \t{pkg_config}, \t{pkg_setup}, + \t{pkg_nofetch}, \t{src_unpack}, \t{src_prepare}, \t{src_configure}, \t{src_compile}, + \t{src_test}, \t{src_install}, \t{pkg_preinst}, \t{pkg_postinst}, \t{pkg_prerm}, + \t{pkg_postrm}, \t{pkg_info}, \t{pkg_pretend} 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. Only for - EAPIs listed in table~\ref{tab:added-env-vars-table} as supporting \t{EBUILD\_PHASE\_FUNC}. \\ + EAPIs listed in table~\ref{tab:added-env-vars-table} as supporting \t{EBUILD_PHASE_FUNC}. \\ \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:removed-env-vars-table} as supporting \t{KV}. \\ -\t{MERGE\_TYPE} & - \t{pkg\_*} & +\t{MERGE_TYPE} & + \t{pkg_*} & No & \featurelabel{merge-type} The type of package that is being merged. Possible values are: \t{source} if building and installing a package from source, \t{binary} if installing a binary package, and \t{buildonly} if building a binary package without installing it. Only for EAPIs - listed in table~\ref{tab:added-env-vars-table} as supporting \t{MERGE\_TYPE}. \\ -\t{REPLACING\_VERSIONS} & - \t{pkg\_*} (see text) & + listed in table~\ref{tab:added-env-vars-table} as supporting \t{MERGE_TYPE}. \\ +\t{REPLACING_VERSIONS} & + \t{pkg_*} (see text) & Yes & A list of all versions of this package (including revision, if specified), whitespace separated with no leading or trailing whitespace, that are being replaced (uninstalled or overwritten) as a result of this install. See section~\ref{sec:replacing-versions}. Only for EAPIs listed - in table~\ref{tab:added-env-vars-table} as supporting \t{REPLACING\_VERSIONS}. \\ -\t{REPLACED\_BY\_VERSION} & - \t{pkg\_prerm}, \t{pkg\_postrm} & + in table~\ref{tab:added-env-vars-table} as supporting \t{REPLACING_VERSIONS}. \\ +\t{REPLACED_BY_VERSION} & + \t{pkg_prerm}, \t{pkg_postrm} & Yes & The single version of this package (including revision, if specified) that is replacing us, if we are being uninstalled as part of an install, or an empty string otherwise. See section~\ref{sec:replacing-versions}. Only for EAPIs listed in table~\ref{tab:added-env-vars-table} - as supporting \t{REPLACED\_BY\_VERSION}. + as supporting \t{REPLACED_BY_VERSION}. \end{longtable} \end{landscape} @@ -238,10 +238,10 @@ variable. \begin{tabular}{lllll} \toprule \multicolumn{1}{c}{\textbf{EAPI}} & - \multicolumn{1}{c}{\textbf{\t{MERGE\_TYPE}?}} & - \multicolumn{1}{c}{\textbf{\t{REPLACING\_VERSIONS}?}} & - \multicolumn{1}{c}{\textbf{\t{REPLACED\_BY\_VERSION}?}} & - \multicolumn{1}{c}{\textbf{\t{EBUILD\_PHASE\_FUNC}?}} \\ + \multicolumn{1}{c}{\textbf{\t{MERGE_TYPE}?}} & + \multicolumn{1}{c}{\textbf{\t{REPLACING_VERSIONS}?}} & + \multicolumn{1}{c}{\textbf{\t{REPLACED_BY_VERSION}?}} & + \multicolumn{1}{c}{\textbf{\t{EBUILD_PHASE_FUNC}?}} \\ \midrule 0, 1, 2, 3 & No & No & No & No \\ 4 & Yes & Yes & Yes & No \\ @@ -290,11 +290,11 @@ the scope of this specification) or be unset. is left up to interpretation, but it should include the equivalent ``sbin'' and ``bin'' and any package manager specific directories. -\t{GZIP}, \t{BZIP}, \t{BZIP2}, \t{CDPATH}, \t{GREP\_OPTIONS}, \t{GREP\_COLOR} and \t{GLOBIGNORE} +\t{GZIP}, \t{BZIP}, \t{BZIP2}, \t{CDPATH}, \t{GREP_OPTIONS}, \t{GREP_COLOR} and \t{GLOBIGNORE} must not be set. -\featurelabel{locale-settings} The package manager must ensure that the \t{LC\_CTYPE} and -\t{LC\_COLLATE} locale categories are equivalent to the POSIX locale, as far as characters in the +\featurelabel{locale-settings} The package manager must ensure that the \t{LC_CTYPE} and +\t{LC_COLLATE} locale categories are equivalent to the POSIX locale, as far as characters in the ASCII range (U+0000 to U+007F) are concerned. Only for EAPIs listed in such a manner in table~\ref{tab:locale-settings}. @@ -304,7 +304,7 @@ table~\ref{tab:locale-settings}. \begin{tabular}{ll} \toprule \multicolumn{1}{c}{\textbf{EAPI}} & - \multicolumn{1}{c}{\textbf{Sane \t{LC\_CTYPE} and \t{LC\_COLLATE}?}} \\ + \multicolumn{1}{c}{\textbf{Sane \t{LC_CTYPE} and \t{LC_COLLATE}?}} \\ \midrule 0, 1, 2, 3, 4, 5 & Undefined \\ 6 & Yes \\ @@ -319,78 +319,78 @@ This section discusses the handling of four variables: \begin{description} \item[IUSE] is the variable calculated from the \t{IUSE} values defined in ebuilds and eclasses. -\item[IUSE\_REFERENCEABLE] is a variable calculated from \t{IUSE} and a variety of other sources +\item[IUSE_REFERENCEABLE] is a variable calculated from \t{IUSE} and a variety of other sources described below. It is purely a conceptual variable; it is not exported to the ebuild - environment. Values in \t{IUSE\_REFERENCEABLE} may legally be used in queries from other + environment. Values in \t{IUSE_REFERENCEABLE} may legally be used in queries from other packages about an ebuild's state (for example, for use dependencies). -\item[IUSE\_EFFECTIVE] is another conceptual, unexported variable. Values in \t{IUSE\_EFFECTIVE} are +\item[IUSE_EFFECTIVE] is another conceptual, unexported variable. Values in \t{IUSE_EFFECTIVE} are those which an ebuild may legally use in queries about itself (for example, for the \t{use} function, and for use in dependency specification conditional blocks). \item[USE] is a variable calculated by the package manager and exported to the ebuild environment. \end{description} -In all cases, the values of \t{IUSE\_REFERENCEABLE} and \t{IUSE\_EFFECTIVE} are undefined during +In all cases, the values of \t{IUSE_REFERENCEABLE} and \t{IUSE_EFFECTIVE} are undefined during metadata generation. For EAPIs listed in table~\ref{tab:profile-iuse-injection-table} as not supporting profile defined -\t{IUSE} injection, \t{IUSE\_REFERENCEABLE} is equal to the calculated \t{IUSE} value. For EAPIs -where profile defined \t{IUSE} injection is supported, \t{IUSE\_REFERENCEABLE} is equal to -\t{IUSE\_EFFECTIVE}. +\t{IUSE} injection, \t{IUSE_REFERENCEABLE} is equal to the calculated \t{IUSE} value. For EAPIs +where profile defined \t{IUSE} injection is supported, \t{IUSE_REFERENCEABLE} is equal to +\t{IUSE_EFFECTIVE}. For EAPIs listed in table~\ref{tab:profile-iuse-injection-table} as not supporting profile defined -\t{IUSE} injection, \t{IUSE\_EFFECTIVE} contains the following values: +\t{IUSE} injection, \t{IUSE_EFFECTIVE} contains the following values: \begin{compactitem} \item All values in the calculated \t{IUSE} value. \item All possible values for the \t{ARCH} variable. \item All legal use flag names whose name starts with the lowercase equivalent of any value in - the profile \t{USE\_EXPAND} variable followed by an underscore. + the profile \t{USE_EXPAND} variable followed by an underscore. \end{compactitem} \featurelabel{profile-iuse-inject} 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: +as supporting profile defined \t{IUSE} injection, \t{IUSE_EFFECTIVE} contains the following values: \begin{compactitem} \item All values in the calculated \t{IUSE} value. -\item All values in the profile \t{IUSE\_IMPLICIT} variable. -\item All values in the profile variable named \t{USE\_EXPAND\_VALUES\_\$\{v\}}, where \t{\$\{v\}} - is any value in the intersection of the profile \t{USE\_EXPAND\_UNPREFIXED} and - \t{USE\_EXPAND\_IMPLICIT} variables. -\item All values for \t{\$\{lower\_v\}\_\$\{x\}}, where \t{\$\{x\}} is all values in the profile - variable named \t{USE\_EXPAND\_VALUES\_\$\{v\}}, where \t{\$\{v\}} is any value in the - intersection of the profile \t{USE\_EXPAND} and \t{USE\_EXPAND\_IMPLICIT} variables and - \t{\$\{lower\_v\}} is the lowercase equivalent of \t{\$\{v\}}. +\item All values in the profile \t{IUSE_IMPLICIT} variable. +\item All values in the profile variable named \t{USE_EXPAND_VALUES_\$\{v\}}, where \t{\$\{v\}} + is any value in the intersection of the profile \t{USE_EXPAND_UNPREFIXED} and + \t{USE_EXPAND_IMPLICIT} variables. +\item All values for \t{\$\{lower_v\}_\$\{x\}}, where \t{\$\{x\}} is all values in the profile + variable named \t{USE_EXPAND_VALUES_\$\{v\}}, where \t{\$\{v\}} is any value in the + intersection of the profile \t{USE_EXPAND} and \t{USE_EXPAND_IMPLICIT} variables and + \t{\$\{lower_v\}} is the lowercase equivalent of \t{\$\{v\}}. \end{compactitem} -The \t{USE} variable is set by the package manager. For each value in \t{IUSE\_EFFECTIVE}, \t{USE} +The \t{USE} variable is set by the package manager. For each value in \t{IUSE_EFFECTIVE}, \t{USE} shall contain that value if the flag is to be enabled for the ebuild in question, and shall not contain that value if it is to be disabled. In EAPIs listed in table~\ref{tab:profile-iuse-injection-table} as not supporting profile defined \t{IUSE} injection, \t{USE} may contain other flag names that are not relevant for the ebuild. For EAPIs listed in table~\ref{tab:profile-iuse-injection-table} as supporting profile defined -\t{IUSE} injection, the variables named in \t{USE\_EXPAND} and \t{USE\_EXPAND\_UNPREFIXED} shall +\t{IUSE} injection, the variables named in \t{USE_EXPAND} and \t{USE_EXPAND_UNPREFIXED} shall have their profile-provided values reduced to contain only those values that are present in -\t{IUSE\_EFFECTIVE}. +\t{IUSE_EFFECTIVE}. For EAPIs listed in table~\ref{tab:profile-iuse-injection-table} as supporting profile defined -\t{IUSE} injection, the package manager must save the calculated value of \t{IUSE\_EFFECTIVE} when +\t{IUSE} injection, the package manager must save the calculated value of \t{IUSE_EFFECTIVE} when installing a package. Details are beyond the scope of this specification. -\subsection{REPLACING\_VERSIONS and REPLACED\_BY\_VERSION} +\subsection{REPLACING_VERSIONS and REPLACED_BY_VERSION} \label{sec:replacing-versions} \featurelabel{replace-version-vars} In EAPIs listed in table~\ref{tab:added-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}, +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 binary package creation and installation correctly when using it in these phases. -\t{REPLACING\_VERSIONS} is a list, not a single optional value, to handle pathological cases such as +\t{REPLACING_VERSIONS} is a list, not a single optional value, to handle pathological cases such as installing \t{foo-2:2} to replace \t{foo-2:1} and \t{foo-3:2}. In EAPIs listed in table~\ref{tab:added-env-vars-table} as supporting it, the -\t{REPLACED\_BY\_VERSION} variable shall be defined in \t{pkg\_prerm} and \t{pkg\_postrm}. It shall +\t{REPLACED_BY_VERSION} variable shall be defined in \t{pkg_prerm} and \t{pkg_postrm}. It shall contain at most one value. \subsection{Offset-prefix variables} diff --git a/ebuild-format.tex b/ebuild-format.tex index db6d7a1..fa49e8f 100644 --- a/ebuild-format.tex +++ b/ebuild-format.tex @@ -5,7 +5,7 @@ a bash script. The interpreter is assumed to be GNU bash, version as listed in table~\ref{tab:bash-version}, or any later version. If possible, the package manager should set the shell's compatibility level to the exact version specified. It must ensure that any such -compatibility settings (e.g. the \t{BASH\_COMPAT} variable) are not exported to external programs. +compatibility settings (e.g. the \t{BASH_COMPAT} variable) are not exported to external programs. The file encoding must be UTF-8 with Unix-style newlines. When sourced, the ebuild must define certain variables and functions (see sections~\ref{sec:ebuild-vars} and~\ref{sec:ebuild-functions} diff --git a/ebuild-functions.tex b/ebuild-functions.tex index 045b207..e90c050 100644 --- a/ebuild-functions.tex +++ b/ebuild-functions.tex @@ -12,8 +12,8 @@ temporary directory \t{T}; exceptions are noted below. All functions may assume access to all system libraries, binaries and configuration files that are accessible to normal users. -The environment for functions run outside of the build sequence (that is, \t{pkg\_config}, -\t{pkg\_info}, \t{pkg\_prerm} and \t{pkg\_postrm}) must be the environment used for the build of the +The environment for functions run outside of the build sequence (that is, \t{pkg_config}, +\t{pkg_info}, \t{pkg_prerm} and \t{pkg_postrm}) must be the environment used for the build of the package, not the current configuration. Ebuilds must not call nor assume the existence of any phase functions. @@ -37,10 +37,10 @@ fallback to \t{WORKDIR} is used: \begin{compactitem} \item The \t{A} variable contains no items. -\item The phase function in question is not in \t{DEFINED\_PHASES}. +\item The phase function in question is not in \t{DEFINED_PHASES}. \item None of the phase functions \t{unpack}, \t{prepare}, \t{configure}, \t{compile} or \t{install}, if supported by the EAPI in question and occurring prior to the phase about to be executed, are - in \t{DEFINED\_PHASES}. + in \t{DEFINED_PHASES}. \end{compactitem} \ChangeWhenAddingAnEAPI{6} @@ -57,30 +57,30 @@ fallback to \t{WORKDIR} is used: \end{tabular} \end{centertable} -\subsection{pkg\_pretend} +\subsection{pkg_pretend} -\featurelabel{pkg-pretend} The \t{pkg\_pretend} function is only called for EAPIs listed in +\featurelabel{pkg-pretend} The \t{pkg_pretend} function is only called for EAPIs listed in table~\ref{tab:pkg-pretend-table} as supporting it. -The \t{pkg\_pretend} function may be used to carry out sanity checks early on in the install +The \t{pkg_pretend} function may be used to carry out sanity checks early on in the install process. For example, if an ebuild requires a particular kernel configuration, it may perform that -check in \t{pkg\_pretend} and call \t{eerror} and then \t{die} with appropriate messages if the +check in \t{pkg_pretend} and call \t{eerror} and then \t{die} with appropriate messages if the requirement is not met. -\t{pkg\_pretend} is run separately from the main phase function sequence, and does not participate +\t{pkg_pretend} is run separately from the main phase function sequence, and does not participate in any kind of environment saving. There is no guarantee that any of an ebuild's dependencies will be met at this stage, and no guarantee that the system state will not have changed substantially before the next phase is executed. -\t{pkg\_pretend} must not write to the filesystem. +\t{pkg_pretend} must not write to the filesystem. \ChangeWhenAddingAnEAPI{6} -\begin{centertable}{EAPIs supporting \t{pkg\_pretend}} +\begin{centertable}{EAPIs supporting \t{pkg_pretend}} \label{tab:pkg-pretend-table} \begin{tabular}{ll} \toprule \multicolumn{1}{c}{\textbf{EAPI}} & - \multicolumn{1}{c}{\textbf{Supports \t{pkg\_pretend}?}} \\ + \multicolumn{1}{c}{\textbf{Supports \t{pkg_pretend}?}} \\ \midrule 0, 1, 2, 3 & No \\ 4, 5, 6 & Yes \\ @@ -88,25 +88,25 @@ before the next phase is executed. \end{tabular} \end{centertable} -\subsection{pkg\_setup} +\subsection{pkg_setup} -The \t{pkg\_setup} function sets up the ebuild's environment for all following functions, before +The \t{pkg_setup} function sets up the ebuild's environment for all following functions, before the build process starts. Further, it checks whether any necessary prerequisites not covered by the package manager, e.\,g.\ that certain kernel configuration options are fulfilled. -\t{pkg\_setup} must be run with full filesystem permissions, including the ability to add new users +\t{pkg_setup} must be run with full filesystem permissions, including the ability to add new users and/or groups to the system. -\subsection{src\_unpack} +\subsection{src_unpack} -The \t{src\_unpack} function extracts all of the package's sources. In EAPIs lacking -\t{src\_prepare}, it may also apply patches and set up the package's build system for further use. +The \t{src_unpack} function extracts all of the package's sources. In EAPIs lacking +\t{src_prepare}, it may also apply patches and set up the package's build system for further use. The initial working directory must be \t{WORKDIR}, and the default implementation used when -the ebuild lacks the \t{src\_unpack} function shall behave as: +the ebuild lacks the \t{src_unpack} function shall behave as: \begin{listing}[H] -\caption{\t{src\_unpack}} +\caption{\t{src_unpack}} \begin{verbatim} src_unpack() { if [[ -n ${A} ]]; then @@ -116,21 +116,21 @@ src_unpack() { \end{verbatim} \end{listing} -\subsection{src\_prepare} +\subsection{src_prepare} -\featurelabel{src-prepare} The \t{src\_prepare} function is only called for EAPIs listed in -table~\ref{tab:src-prepare-table} as supporting it. The \t{src\_prepare} function can be used for +\featurelabel{src-prepare} The \t{src_prepare} function is only called for EAPIs listed in +table~\ref{tab:src-prepare-table} as supporting it. The \t{src_prepare} function can be used for post-unpack source preparation. 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-prepare-6} For EAPIs listed in table~\ref{tab:src-prepare-table} as using format -6, the default implementation used when the ebuild lacks the \t{src\_prepare} function shall behave +6, the default implementation used when the ebuild lacks the \t{src_prepare} function shall behave as: \begin{listing}[H] -\caption{\t{src\_prepare}, format~6} +\caption{\t{src_prepare}, format~6} \begin{verbatim} src_prepare() { if declare -p PATCHES | grep -q "^declare -a "; then @@ -143,16 +143,16 @@ src_prepare() { \end{verbatim} \end{listing} -For other EAPIs supporting \t{src\_prepare}, the default implementation used when the ebuild lacks -the \t{src\_prepare} function is a no-op. +For other EAPIs supporting \t{src_prepare}, the default implementation used when the ebuild lacks +the \t{src_prepare} function is a no-op. \ChangeWhenAddingAnEAPI{6} -\begin{centertable}{\t{src\_prepare} support and behaviour for EAPIs} +\begin{centertable}{\t{src_prepare} support and behaviour for EAPIs} \label{tab:src-prepare-table} \begin{tabular}{lll} \toprule \multicolumn{1}{c}{\textbf{EAPI}} & - \multicolumn{1}{c}{\textbf{Supports \t{src\_prepare}?}} & + \multicolumn{1}{c}{\textbf{Supports \t{src_prepare}?}} & \multicolumn{1}{c}{\textbf{Format}} \\ \midrule 0, 1 & No & Not applicable \\ @@ -162,19 +162,19 @@ the \t{src\_prepare} function is a no-op. \end{tabular} \end{centertable} -\subsection{src\_configure} +\subsection{src_configure} -\featurelabel{src-configure} The \t{src\_configure} function is only called for EAPIs listed in +\featurelabel{src-configure} The \t{src_configure} function is only called for EAPIs listed in table~\ref{tab:src-configure-table} as supporting it. 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}. -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: +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{listing}[H] -\caption{\t{src\_configure}} +\caption{\t{src_configure}} \begin{verbatim} src_configure() { if [[ -x ${ECONF_SOURCE:-.}/configure ]]; then @@ -185,12 +185,12 @@ src_configure() { \end{listing} \ChangeWhenAddingAnEAPI{6} -\begin{centertable}{EAPIs supporting \t{src\_configure}} +\begin{centertable}{EAPIs supporting \t{src_configure}} \label{tab:src-configure-table} \begin{tabular}{ll} \toprule \multicolumn{1}{c}{\textbf{EAPI}} & - \multicolumn{1}{c}{\textbf{Supports \t{src\_configure}?}} \\ + \multicolumn{1}{c}{\textbf{Supports \t{src_configure}?}} \\ \midrule 0, 1 & No \\ 2, 3, 4, 5, 6 & Yes \\ @@ -198,20 +198,20 @@ src_configure() { \end{tabular} \end{centertable} -\subsection{src\_compile} +\subsection{src_compile} -\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. +\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 +0, the default implementation used when the ebuild lacks the \t{src_compile} function shall behave as: \begin{listing}[H] -\caption{\t{src\_compile}, format~0} +\caption{\t{src_compile}, format~0} \begin{verbatim} src_compile() { if [[ -x ./configure ]]; then @@ -225,11 +225,11 @@ src_compile() { \end{listing} \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 +1, the default implementation used when the ebuild lacks the \t{src_compile} function shall behave as: \begin{listing}[H] -\caption{\t{src\_compile}, format~1} +\caption{\t{src_compile}, format~1} \begin{verbatim} src_compile() { if [[ -x ${ECONF_SOURCE:-.}/configure ]]; then @@ -243,11 +243,11 @@ src_compile() { \end{listing} \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 +2, the default implementation used when the ebuild lacks the \t{src_compile} function shall behave as: \begin{listing}[H] -\caption{\t{src\_compile}, format~2} +\caption{\t{src_compile}, format~2} \begin{verbatim} src_compile() { if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]]; then @@ -258,7 +258,7 @@ src_compile() { \end{listing} \ChangeWhenAddingAnEAPI{6} -\begin{centertable}{\t{src\_compile} behaviour for EAPIs} +\begin{centertable}{\t{src_compile} behaviour for EAPIs} \label{tab:src-compile-table} \begin{tabular}{ll} \toprule @@ -272,13 +272,13 @@ src_compile() { \end{tabular} \end{centertable} -\subsection{src\_test} +\subsection{src_test} -The \t{src\_test} function runs unit tests for the newly built but not yet installed package as +The \t{src_test} function runs unit tests for the newly built but not yet installed package as provided. The initial working directory must be \t{S} if that exists, falling back to \t{WORKDIR} otherwise. -The default implementation used when the ebuild lacks the \t{src\_test} function must, if tests are +The default implementation used when the ebuild lacks the \t{src_test} function must, if tests are enabled, run \t{emake check} if and only if such a target is available, or if not run \t{emake test} if and only if such a target is available. In both cases, if \t{emake} returns non-zero the build must be aborted. @@ -286,11 +286,11 @@ non-zero the build must be aborted. \featurelabel{parallel-tests} For EAPIs listed in table~\ref{tab:src-test-table} as not supporting parallel tests, the \t{emake} command must be called with option \t{-j1}. -The \t{src\_test} function may be disabled by \t{RESTRICT}\@. See section~\ref{sec:restrict}. It may +The \t{src_test} function may be disabled by \t{RESTRICT}\@. See section~\ref{sec:restrict}. It may be disabled by user too, using a PM-specific mechanism. \ChangeWhenAddingAnEAPI{6} -\begin{centertable}{\t{src\_test} behaviour for EAPIs} +\begin{centertable}{\t{src_test} behaviour for EAPIs} \label{tab:src-test-table} \begin{tabular}{ll} \toprule @@ -303,20 +303,20 @@ be disabled by user too, using a PM-specific mechanism. \end{tabular} \end{centertable} -\subsection{src\_install} +\subsection{src_install} -\featurelabel{src-install} The \t{src\_install} function installs the package's content to a +\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-4} For EAPIs listed in table~\ref{tab:src-install-table} as using format -4, the default implementation used when the ebuild lacks the \t{src\_install} function shall behave +4, the default implementation used when the ebuild lacks the \t{src_install} function shall behave as: \begin{listing}[H] -\caption{\t{src\_install}, format~4} +\caption{\t{src_install}, format~4} \begin{verbatim} src_install() { if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]]; then @@ -339,11 +339,11 @@ src_install() { \end{listing} \featurelabel{src-install-6} For EAPIs listed in table~\ref{tab:src-install-table} as using format -6, the default implementation used when the ebuild lacks the \t{src\_install} function shall behave +6, the default implementation used when the ebuild lacks the \t{src_install} function shall behave as: \begin{listing}[H] -\caption{\t{src\_install}, format~6} +\caption{\t{src_install}, format~6} \begin{verbatim} src_install() { if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]]; then @@ -354,11 +354,11 @@ src_install() { \end{verbatim} \end{listing} -For other EAPIs, the default implementation used when the ebuild lacks the \t{src\_install} function +For other EAPIs, the default implementation used when the ebuild lacks the \t{src_install} function is a no-op. \ChangeWhenAddingAnEAPI{6} -\begin{centertable}{\t{src\_install} behaviour for EAPIs} +\begin{centertable}{\t{src_install} behaviour for EAPIs} \label{tab:src-install-table} \begin{tabular}{ll} \toprule @@ -372,66 +372,66 @@ is a no-op. \end{tabular} \end{centertable} -\subsection{pkg\_preinst} +\subsection{pkg_preinst} -The \t{pkg\_preinst} function performs any special tasks that are required immediately before +The \t{pkg_preinst} function performs any special tasks that are required immediately before merging the package to the live filesystem. It must not write outside of the directories specified by the \t{ROOT} and \t{D} environment variables. -\t{pkg\_preinst} must be run with full access to all files and directories below that specified by +\t{pkg_preinst} must be run with full access to all files and directories below that specified by the \t{ROOT} and \t{D} environment variables. -\subsection{pkg\_postinst} +\subsection{pkg_postinst} -The \t{pkg\_postinst} function performs any special tasks that are required immediately after +The \t{pkg_postinst} function performs any special tasks that are required immediately after merging the package to the live filesystem. It must not write outside of the directory specified in the \t{ROOT} environment variable. -\t{pkg\_postinst}, like, \t{pkg\_preinst}, must be run with full access to all files and directories +\t{pkg_postinst}, like, \t{pkg_preinst}, must be run with full access to all files and directories below that specified by the \t{ROOT} environment variable. -\subsection{pkg\_prerm} +\subsection{pkg_prerm} -The \t{pkg\_prerm} function performs any special tasks that are required immediately before +The \t{pkg_prerm} function performs any special tasks that are required immediately before unmerging the package from the live filesystem. It must not write outside of the directory specified by the \t{ROOT} environment variable. -\t{pkg\_prerm} must be run with full access to all files and directories below that specified by +\t{pkg_prerm} must be run with full access to all files and directories below that specified by the \t{ROOT} environment variable. -\subsection{pkg\_postrm} +\subsection{pkg_postrm} -The \t{pkg\_postrm} function performs any special tasks that are required immediately after +The \t{pkg_postrm} function performs any special tasks that are required immediately after unmerging the package from the live filesystem. It must not write outside of the directory specified by the \t{ROOT} environment variable. -\t{pkg\_postrm} must be run with full access to all files and directories below that specified by +\t{pkg_postrm} must be run with full access to all files and directories below that specified by the \t{ROOT} environment variable. -\subsection{pkg\_config} +\subsection{pkg_config} -The \t{pkg\_config} function performs any custom steps required to configure a package after it has been +The \t{pkg_config} function performs any custom steps required to configure a package after it has been fully installed. It is the only ebuild function which may be interactive and prompt for user input. -\t{pkg\_config} must be run with full access to all files and directories inside of \t{ROOT}. +\t{pkg_config} must be run with full access to all files and directories inside of \t{ROOT}. -\subsection{pkg\_info} +\subsection{pkg_info} -\featurelabel{pkg-info} The \t{pkg\_info} function may be called by the package manager when +\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 +as supporting \t{pkg_info} on non-installed packages, it may also be called by the package manager when displaying information about a non-installed package. In this case, ebuild authors should note that dependencies may not be installed. -\t{pkg\_info} must not write to the filesystem. +\t{pkg_info} must not write to the filesystem. \ChangeWhenAddingAnEAPI{6} -\begin{centertable}{EAPIs supporting \t{pkg\_info} on non-installed packages} +\begin{centertable}{EAPIs supporting \t{pkg_info} on non-installed packages} \label{tab:pkg-info-table} \begin{tabular}{ll} \toprule \multicolumn{1}{c}{\textbf{EAPI}} & - \multicolumn{1}{c}{\textbf{Supports \t{pkg\_info} on non-installed packages?}} \\ + \multicolumn{1}{c}{\textbf{Supports \t{pkg_info} on non-installed packages?}} \\ \midrule 0, 1, 2, 3 & No \\ 4, 5, 6 & Yes \\ @@ -439,36 +439,36 @@ that dependencies may not be installed. \end{tabular} \end{centertable} -\subsection{pkg\_nofetch} +\subsection{pkg_nofetch} -The \t{pkg\_nofetch} function is run when the fetch phase of an fetch-restricted ebuild is run, and +The \t{pkg_nofetch} function is run when the fetch phase of an fetch-restricted ebuild is run, and the relevant source files are not available. It should direct the user to download all relevant source files from their respective locations, with notes concerning licensing if applicable. -\t{pkg\_nofetch} must require no write access to any part of the filesystem. +\t{pkg_nofetch} must require no write access to any part of the filesystem. \subsection{Default phase functions} \label{sec:default-phase-funcs} \featurelabel{default-phase-funcs} 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 +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 must not call these functions except when in the phase in question. \ChangeWhenAddingAnEAPI{6} -\begin{centertable}{EAPIs supporting \t{default\_} phase functions} +\begin{centertable}{EAPIs supporting \t{default_} phase functions} \label{tab:default-phase-function-table} \begin{tabular}{l P{26em}} \toprule \multicolumn{1}{c}{\textbf{EAPI}} & - \multicolumn{1}{c}{\textbf{Supports \t{default\_} functions in phases}} \\ + \multicolumn{1}{c}{\textbf{Supports \t{default_} functions in phases}} \\ \midrule 0, 1 & None \\ - 2, 3 & \t{pkg\_nofetch}, \t{src\_unpack}, \t{src\_prepare}, \t{src\_configure}, - \t{src\_compile}, \t{src\_test} \\ - 4, 5, 6 & \t{pkg\_nofetch}, \t{src\_unpack}, \t{src\_prepare}, \t{src\_configure}, - \t{src\_compile}, \t{src\_install}, \t{src\_test} \\ + 2, 3 & \t{pkg_nofetch}, \t{src_unpack}, \t{src_prepare}, \t{src_configure}, + \t{src_compile}, \t{src_test} \\ + 4, 5, 6 & \t{pkg_nofetch}, \t{src_unpack}, \t{src_prepare}, \t{src_configure}, + \t{src_compile}, \t{src_install}, \t{src_test} \\ \bottomrule \end{tabular} \end{centertable} @@ -478,56 +478,56 @@ when in the phase in question. The call order for installing a package is: \begin{compactitem} -\item \t{pkg\_pretend} (only for EAPIs listed in table~\ref{tab:pkg-pretend-table}), which is called +\item \t{pkg_pretend} (only for EAPIs listed in table~\ref{tab:pkg-pretend-table}), which is called outside of the normal call order process. -\item \t{pkg\_setup} -\item \t{src\_unpack} -\item \t{src\_prepare} (only for EAPIs listed in table~\ref{tab:src-prepare-table}) -\item \t{src\_configure} (only for EAPIs listed in table~\ref{tab:src-configure-table}) -\item \t{src\_compile} -\item \t{src\_test} (except if \t{RESTRICT=test} or disabled by user) -\item \t{src\_install} -\item \t{pkg\_preinst} -\item \t{pkg\_postinst} +\item \t{pkg_setup} +\item \t{src_unpack} +\item \t{src_prepare} (only for EAPIs listed in table~\ref{tab:src-prepare-table}) +\item \t{src_configure} (only for EAPIs listed in table~\ref{tab:src-configure-table}) +\item \t{src_compile} +\item \t{src_test} (except if \t{RESTRICT=test} or disabled by user) +\item \t{src_install} +\item \t{pkg_preinst} +\item \t{pkg_postinst} \end{compactitem} The call order for uninstalling a package is: \begin{compactitem} -\item \t{pkg\_prerm} -\item \t{pkg\_postrm} +\item \t{pkg_prerm} +\item \t{pkg_postrm} \end{compactitem} The call order for upgrading, downgrading or reinstalling a package is: \begin{compactitem} -\item \t{pkg\_pretend} (only for EAPIs listed in table~\ref{tab:pkg-pretend-table}), which is called +\item \t{pkg_pretend} (only for EAPIs listed in table~\ref{tab:pkg-pretend-table}), which is called outside of the normal call order process. -\item \t{pkg\_setup} -\item \t{src\_unpack} -\item \t{src\_prepare} (only for EAPIs listed in table~\ref{tab:src-prepare-table}) -\item \t{src\_configure} (only for EAPIs listed in table~\ref{tab:src-configure-table}) -\item \t{src\_compile} -\item \t{src\_test} (except if \t{RESTRICT=test}) -\item \t{src\_install} -\item \t{pkg\_preinst} -\item \t{pkg\_prerm} for the package being replaced -\item \t{pkg\_postrm} for the package being replaced -\item \t{pkg\_postinst} +\item \t{pkg_setup} +\item \t{src_unpack} +\item \t{src_prepare} (only for EAPIs listed in table~\ref{tab:src-prepare-table}) +\item \t{src_configure} (only for EAPIs listed in table~\ref{tab:src-configure-table}) +\item \t{src_compile} +\item \t{src_test} (except if \t{RESTRICT=test}) +\item \t{src_install} +\item \t{pkg_preinst} +\item \t{pkg_prerm} for the package being replaced +\item \t{pkg_postrm} for the package being replaced +\item \t{pkg_postinst} \end{compactitem} Note: When up- or downgrading a package in EAPI 0 or 1, the last four phase functions can -alternatively be called in the order \t{pkg\_preinst}, \t{pkg\_postinst}, \t{pkg\_prerm}, -\t{pkg\_postrm}. This behaviour is deprecated. +alternatively be called in the order \t{pkg_preinst}, \t{pkg_postinst}, \t{pkg_prerm}, +\t{pkg_postrm}. This behaviour is deprecated. -The \t{pkg\_config}, \t{pkg\_info} and \t{pkg\_nofetch} functions are not called in a normal -sequence. The \t{pkg\_pretend} function is called some unspecified time before a (possibly +The \t{pkg_config}, \t{pkg_info} and \t{pkg_nofetch} functions are not called in a normal +sequence. The \t{pkg_pretend} function is called some unspecified time before a (possibly hypothetical) normal sequence. For installing binary packages, the \t{src} phases are not called. -When building binary packages that are not to be installed locally, the \t{pkg\_preinst} -and \t{pkg\_postinst} functions are not called. +When building binary packages that are not to be installed locally, the \t{pkg_preinst} +and \t{pkg_postinst} functions are not called. % vim: set filetype=tex fileencoding=utf8 et tw=100 spell spelllang=en : diff --git a/ebuild-vars.tex b/ebuild-vars.tex index 9a9502e..b910f25 100644 --- a/ebuild-vars.tex +++ b/ebuild-vars.tex @@ -47,7 +47,7 @@ Ebuilds may define any of the following variables: \item[EAPI] The EAPI\@. See below. \item[HOMEPAGE] The URI or URIs for a package's homepage, including protocols. See section~\ref{sec:dependencies} for full syntax. -\item[SRC\_URI] A list of source URIs for the package. Valid protocols are \t{http://}, +\item[SRC_URI] A list of source URIs for the package. Valid protocols are \t{http://}, \t{https://}, \t{ftp://} and \t{mirror://} (see section~\ref{sec:thirdpartymirrors} for mirror behaviour). Fetch restricted packages may include URL parts consisting of just a filename. See section~\ref{sec:dependencies} for full syntax. @@ -67,10 +67,10 @@ Ebuilds may define any of the following variables: \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[REQUIRED\_USE] \featurelabel{required-use} Zero or more assertions that must be met by the +\item[REQUIRED_USE] \featurelabel{required-use} Zero or more assertions that must be met by the configuration of \t{USE} flags to be valid for this ebuild. See section~\ref{sec:required-use} for description and section~\ref{sec:dependencies} for full syntax. Only in EAPIs listed in - table~\ref{tab:optional-vars-table} as supporting \t{REQUIRED\_USE}. + table~\ref{tab:optional-vars-table} as supporting \t{REQUIRED_USE}. \item[PROPERTIES] \featurelabel{properties} Zero or more properties for this package. See section~\ref{sec:properties} for value meanings and section~\ref{sec:dependencies} for full syntax. For EAPIs listed in table~\ref{tab:optional-vars-table} as having optional support, @@ -106,7 +106,7 @@ Ebuilds may define any of the following variables: \toprule \multicolumn{1}{c}{\textbf{EAPI}} & \multicolumn{1}{c}{\textbf{Supports \t{PROPERTIES}?}} & - \multicolumn{1}{c}{\textbf{Supports \t{REQUIRED\_USE}?}} \\ + \multicolumn{1}{c}{\textbf{Supports \t{REQUIRED_USE}?}} \\ \midrule 0, 1, 2, 3 & Optionally & No \\ 4, 5, 6 & Yes & Yes \\ @@ -208,11 +208,11 @@ The following are special variables defined by the package manager for internal not be exported to the ebuild environment: \begin{description} -\item[DEFINED\_PHASES] \featurelabel{defined-phases} A space separated arbitrarily ordered list of +\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, package managers may not rely upon the metadata cache having +optional \t{DEFINED_PHASES} support, package managers may not rely upon the metadata cache having this variable defined, and must treat an empty string as ``this information is not available''. \end{description} @@ -220,12 +220,12 @@ this variable defined, and must treat an empty string as ``this information is n based upon any variant condition. \ChangeWhenAddingAnEAPI{6} -\begin{centertable}{EAPIs supporting \t{DEFINED\_PHASES}} +\begin{centertable}{EAPIs supporting \t{DEFINED_PHASES}} \label{tab:defined-phases-table} \begin{tabular}{ll} \toprule \multicolumn{1}{c}{\textbf{EAPI}} & - \multicolumn{1}{c}{\textbf{Supports \t{DEFINED\_PHASES}?}} \\ + \multicolumn{1}{c}{\textbf{Supports \t{DEFINED_PHASES}?}} \\ \midrule 0, 1, 2, 3 & Optionally \\ 4, 5, 6 & Yes \\ diff --git a/eclasses.tex b/eclasses.tex index 7569caf..49c6c4e 100644 --- a/eclasses.tex +++ b/eclasses.tex @@ -9,7 +9,7 @@ hold. Eclasses must be located in the \t{eclass} directory in the top level of the repository---see section~\ref{sec:eclass-dir}. Each eclass is a single file named \t{.eclass}, where \t{} is -the name of this eclass, used by \t{inherit} and \t{EXPORT\_FUNCTIONS} among other places. +the name of this eclass, used by \t{inherit} and \t{EXPORT_FUNCTIONS} among other places. \section{The inherit Command} \label{sec:inherit} @@ -34,22 +34,22 @@ The \t{inherit} command must also ensure that: \section{Eclass-defined Metadata Keys} -The \t{IUSE}, \t{REQUIRED\_USE}, \t{DEPEND}, \t{RDEPEND} and \t{PDEPEND} variables are handled +The \t{IUSE}, \t{REQUIRED_USE}, \t{DEPEND}, \t{RDEPEND} and \t{PDEPEND} variables are handled specially when set by an eclass. They must be accumulated across eclasses, appending the value set by each eclass to the resulting value after the previous one is loaded. Then the eclass-defined value is appended to that defined by the ebuild. In the case of \t{RDEPEND}, this is done after the implicit \t{RDEPEND} rules in section~\ref{sec:rdepend-depend} are applied. -\section{EXPORT\_FUNCTIONS} +\section{EXPORT_FUNCTIONS} There is one command available in the eclass environment that is neither available nor meaningful -in ebuilds---\t{EXPORT\_FUNCTIONS}\@. This can be used to alias ebuild phase functions from the +in ebuilds---\t{EXPORT_FUNCTIONS}\@. This can be used to alias ebuild phase functions from the eclass so that an ebuild inherits a default definition whilst retaining the ability to override and call the eclass-defined version from it. The use of it is best illustrated by an example; this is given in listing~\ref{lst:export-functions} and is a snippet from a hypothetical \t{foo.eclass}. \begin{listing} -\caption{\t{EXPORT\_FUNCTIONS} example: \t{foo.eclass}} \label{lst:export-functions} +\caption{\t{EXPORT_FUNCTIONS} example: \t{foo.eclass}} \label{lst:export-functions} \begin{verbatim} foo_src_compile() { @@ -63,13 +63,13 @@ EXPORT_FUNCTIONS src_compile \end{verbatim} \end{listing} -This example defines an eclass \t{src\_compile} function and uses \t{EXPORT\_FUNCTIONS} to alias -it. Then any ebuild that inherits \t{foo.eclass} will have a default \t{src\_compile} defined, but +This example defines an eclass \t{src_compile} function and uses \t{EXPORT_FUNCTIONS} to alias +it. Then any ebuild that inherits \t{foo.eclass} will have a default \t{src_compile} defined, but should the author wish to override it he can access the function in \t{foo.eclass} by calling -\t{foo\_src\_compile}. +\t{foo_src_compile}. -\t{EXPORT\_FUNCTIONS} must only be used on ebuild phase functions. The function that is aliased -must be named \t{eclassname\_phasefunctionname}, where \t{eclassname} is the name of the eclass. +\t{EXPORT_FUNCTIONS} must only be used on ebuild phase functions. The function that is aliased +must be named \t{eclassname_phasefunctionname}, where \t{eclassname} is the name of the eclass. % vim: set filetype=tex fileencoding=utf8 et tw=100 spell spelllang=en : diff --git a/merge.tex b/merge.tex index 0077837..ee40947 100644 --- a/merge.tex +++ b/merge.tex @@ -104,25 +104,25 @@ is undefined. \label{sec:config-protect} The package manager must provide a means to prevent user configuration files from being -overwritten by any package updates. The profile variables \t{CONFIG\_PROTECT} and -\t{CONFIG\_PROTECT\_MASK} (section~\ref{sec:profile-variables}) control the paths for which this +overwritten by any package updates. The profile variables \t{CONFIG_PROTECT} and +\t{CONFIG_PROTECT_MASK} (section~\ref{sec:profile-variables}) control the paths for which this must be enforced. In order to ensure interoperability with configuration update tools, the following scheme must be used by all package managers when merging any regular file: \begin{compactenum} -\item If the directory containing the file to be merged is not listed in \t{CONFIG\_PROTECT}, and - is not a subdirectory of any such directory, and if the file is not listed in \t{CONFIG\_PROTECT}, +\item If the directory containing the file to be merged is not listed in \t{CONFIG_PROTECT}, and + is not a subdirectory of any such directory, and if the file is not listed in \t{CONFIG_PROTECT}, the file is merged normally. -\item If the directory containing the file to be merged is listed in \t{CONFIG\_PROTECT\_MASK}, or - is a subdirectory of such a directory, or if the file is listed in \t{CONFIG\_PROTECT\_MASK}, +\item If the directory containing the file to be merged is listed in \t{CONFIG_PROTECT_MASK}, or + is a subdirectory of such a directory, or if the file is listed in \t{CONFIG_PROTECT_MASK}, the file is merged normally. \item If no existing file with the intended filename exists, or the existing file has identical content to the one being merged, the file is installed normally. -\item Otherwise, prepend the filename with \t{.\_cfg0000\_}. If no file with the new name exists, +\item Otherwise, prepend the filename with \t{._cfg0000_}. If no file with the new name exists, then the file is merged with this name. -\item Otherwise, increment the number portion (to form \t{.\_cfg0001\_}) and repeat step 4. +\item Otherwise, increment the number portion (to form \t{._cfg0001_}) and repeat step 4. Continue this process until a usable filename is found. \item If 9999 is reached in this way, behaviour is undefined. \end{compactenum} diff --git a/metadata-cache.tex b/metadata-cache.tex index ed58317..80018e4 100644 --- a/metadata-cache.tex +++ b/metadata-cache.tex @@ -18,7 +18,7 @@ order. Other lines may be present following these; their meanings are not define \item Build-time dependencies (\t{DEPEND}) \item Run-time dependencies (\t{RDEPEND}) \item Slot (\t{SLOT}) -\item Source tarball URIs (\t{SRC\_URI}) +\item Source tarball URIs (\t{SRC_URI}) \item \t{RESTRICT} \item Package homepage (\t{HOMEPAGE}) \item Package license (\t{LICENSE}) @@ -26,14 +26,14 @@ order. Other lines may be present following these; their meanings are not define \item Package keywords (\t{KEYWORDS}) \item Inherited eclasses (\t{INHERITED}) \item Use flags that this package respects (\t{IUSE}) -\item Use flags that this package requires (\t{REQUIRED\_USE}). +\item Use flags that this package requires (\t{REQUIRED_USE}). Blank in some EAPIs; see table~\ref{tab:optional-vars-table}. \item Post dependencies (\t{PDEPEND}) \item Unused; previously used for old-style virtual \t{PROVIDE}. \item The ebuild API version to which this package conforms (\t{EAPI}) \item Properties (\t{PROPERTIES}). In some EAPIs, may optionally be blank, regardless of ebuild metadata; see table~\ref{tab:optional-vars-table}. -\item Defined phases (\t{DEFINED\_PHASES}). In some EAPIs, may optionally be blank, regardless of +\item Defined phases (\t{DEFINED_PHASES}). In some EAPIs, may optionally be blank, regardless of ebuild metadata; see table~\ref{tab:defined-phases-table}. \item Blank lines to pad the file to 22 lines long \end{compactenum} diff --git a/names.tex b/names.tex index a348c0f..6767c55 100644 --- a/names.tex +++ b/names.tex @@ -6,14 +6,14 @@ No name may be empty. Package managers must not impose fixed upper boundaries up name. A package manager should indicate or reject any name that is invalid according to these rules. \subsection{Category names} -A category name may contain any of the characters [\t{A-Za-z0-9+\_.-}]. It must not begin with +A category name may contain any of the characters [\t{A-Za-z0-9+_.-}]. It must not begin with a hyphen, a dot or a plus sign. \note A hyphen is \e{not} required because of the \t{virtual} category. Usually, however, category names will contain a hyphen. \subsection{Package names} -A package name may contain any of the characters [\t{A-Za-z0-9+\_-}]. It must not begin with a +A package name may contain any of the characters [\t{A-Za-z0-9+_-}]. It must not begin with a hyphen or a plus sign, and must not end in a hyphen followed by anything matching the version syntax described in section~\ref{sec:version-spec}. @@ -22,35 +22,35 @@ where a \t{category/package} pair is meant. \subsection{Slot names} \label{sec:slot-names} -A slot name may contain any of the characters [\t{A-Za-z0-9+\_.-}]. It must not begin with a +A slot name may contain any of the characters [\t{A-Za-z0-9+_.-}]. It must not begin with a hyphen, a dot or a plus sign. \subsection{USE flag names} -A USE flag name may contain any of the characters [\t{A-Za-z0-9+\_@-}]. It must begin with an -alphanumeric character. Underscores should be considered reserved for \t{USE\_EXPAND}, as +A USE flag name may contain any of the characters [\t{A-Za-z0-9+_@-}]. It must begin with an +alphanumeric character. Underscores should be considered reserved for \t{USE_EXPAND}, as described in section~\ref{sec:use-iuse-handling}. \note The at-sign is required for \t{LINGUAS}. \subsection{Repository names} \label{sec:repository-names} -A repository name may contain any of the characters [\t{A-Za-z0-9\_-}]. It must not begin with a +A repository name may contain any of the characters [\t{A-Za-z0-9_-}]. It must not begin with a hyphen. In addition, every repository name must also be a valid package name. \subsection{License names} \label{sec:license-names} -A license name may contain any of the characters [\t{A-Za-z0-9+\_.-}]. It must not begin with a +A license name may contain any of the characters [\t{A-Za-z0-9+_.-}]. It must not begin with a hyphen, a dot or a plus sign. \subsection{Keyword names} \label{sec:keyword-names} -A keyword name may contain any of the characters [\t{A-Za-z0-9\_-}]. It must not begin with a +A keyword name may contain any of the characters [\t{A-Za-z0-9_-}]. It must not begin with a hyphen. In contexts where it makes sense to do so, a keyword name may be prefixed by a tilde or a hyphen. In \t{KEYWORDS}, \t{-*} is also acceptable as a keyword. \subsection{EAPI names} \label{sec:eapi-names} -An EAPI name may contain any of the characters [\t{A-Za-z0-9+\_.-}]. It must not begin with a +An EAPI name may contain any of the characters [\t{A-Za-z0-9+_.-}]. It must not begin with a hyphen, a dot or a plus sign. \section{Version Specifications} @@ -63,8 +63,8 @@ A version starts with the number part, which is in the form \t{[0-9]+(\textbacks 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 followed by an optional integer. Suffix and integer +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 followed by an optional integer. Suffix and integer count as separate version components. This may optionally be followed by the suffix \t{-r} followed immediately by an integer (the @@ -159,13 +159,13 @@ from which it was invoked. \STATE compare $As_i$ and $Bs_i$ using Algorithm~\ref{alg:version-comparison-suffix-each} \ENDFOR \IF{$Asn>Bsn$} - \IF{$As_{Bsn}$ is of type \t{\_p}} + \IF{$As_{Bsn}$ is of type \t{_p}} \RETURN $A>B$ \ELSE \RETURN $AB$ @@ -177,7 +177,7 @@ from which it was invoked. \begin{algorithm}[p] \caption{Version comparison logic for each suffix} \label{alg:version-comparison-suffix-each} \begin{algorithmic}[1] - \IF{$As_i$ and $Bs_i$ are of the same type (\t{\_alpha} vs \t{\_beta} etc)} + \IF{$As_i$ and $Bs_i$ are of the same type (\t{_alpha} vs \t{_beta} etc)} \STATE let $As'_i$ be the integer part of $As_i$ if any, otherwise \t{0} \STATE let $Bs'_i$ be the integer part of $Bs_i$ if any, otherwise \t{0} \IF{$As'_i>Bs'_i$, using integer comparison} @@ -186,7 +186,7 @@ from which it was invoked. \RETURN $AB$ \ELSE \RETURN $A.desc}, where \t{} is the variable name, in lowercase, whose possible values the file describes. The format of each file is as for - \t{use.desc}, described in section~\ref{sec:use.desc}. The \t{USE\_EXPAND} name is \e{not} + \t{use.desc}, described in section~\ref{sec:use.desc}. The \t{USE_EXPAND} name is \e{not} included as a prefix here. \item[updates/] This directory is described in section~\ref{sec:updates-dir}. \end{description}