From f49a53b3a97dbe299f1b71dad5a6bf5b9b6805ba Mon Sep 17 00:00:00 2001 From: Ulrich Mueller Date: Mon, 11 Jan 2010 22:53:14 +0100 Subject: Offset-prefix (EPREFIX, ED and EROOT). Patch prepared by Fabian Groffen, minor corrections by me. See bug 296716 and council meeting of 2009-12-07. Signed-off-by: Christian Faulhammer --- eapi-differences.tex | 6 ++- ebuild-env-vars.tex | 66 +++++++++++++++++++++++++++++++- pkg-mgr-commands.tex | 105 ++++++++++++++++++++++++++++++++------------------- 3 files changed, 137 insertions(+), 40 deletions(-) diff --git a/eapi-differences.tex b/eapi-differences.tex index 179d9f7..915c2d4 100644 --- a/eapi-differences.tex +++ b/eapi-differences.tex @@ -106,6 +106,9 @@ Use dependencies & \compactfeatureref{use-deps} & \t{REPLACED\_BY\_VERSION} & \compactfeatureref{replace-version-vars} & No & No & No & No & Yes \\ +\t{EPREFIX}, \t{ED}, \t{EROOT} & \compactfeatureref{offset-prefix-vars} & + No & No & No & Yes & Yes \\ + Most utilities die & \compactfeatureref{die-on-failure} & No & No & No & No & Yes \\ @@ -187,8 +190,9 @@ EAPI 2 is EAPI 1 with the following changes: EAPI 3 is EAPI 2 with the following changes: \begin{compactitem} +\item Offset-prefix support by definition of \t{EPREFIX}, \t{ED} and \t{EROOT}, + \featureref{offset-prefix-vars} \item File modification times are preserved, \featureref{mtime-preserve}. -\item (to be completed) \end{compactitem} \section*{EAPI 4} diff --git a/ebuild-env-vars.tex b/ebuild-env-vars.tex index 0bba364..f004d34 100644 --- a/ebuild-env-vars.tex +++ b/ebuild-env-vars.tex @@ -13,7 +13,7 @@ variable. \begin{landscape} \begin{longtable}{l p{0.15\textwidth} l p{0.5\textwidth}} -\caption{Defined variables}\\ +\caption{Defined variables\label{tab:defined_vars}}\\ \toprule \multicolumn{1}{c}{\b{Variable}} & \multicolumn{1}{c}{\b{Legal in}} & @@ -104,6 +104,11 @@ variable. \t{ROOT}\@. Also of note is that in a cross-compiling environment, binaries inside of \t{ROOT} 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\_*} & + No & + Like \t{ROOT}, but with \t{EPREFIX} appended. This is a convenience variable. See also the + \t{EPREFIX} variable. \\ \t{T} & All & Partially\footnote{Consistent and preserved across a single connected sequence of install or @@ -120,6 +125,14 @@ variable. Ditto & The full path to an appropriate temporary directory for use by any programs invoked by the ebuild that may read or modify the home directory. \\ +\t{EPREFIX} & + All & + Yes & + The normalised offset-prefix path of an offset installation. When \t{EPREFIX} is not set in the + calling environment, \t{EPREFIX} defaults to the built-in offset-prefix that was set during + installation of the package manager. When a different \t{EPREFIX} value than the built-in value is set + in the calling environment, a cross-prefix build is performed where using the existing utilities, a + package is built for the given \t{EPREFIX}, akin to \t{ROOT}. See also~\ref{sec:offset-vars}. \\ \t{D} & \t{src\_install} & No & @@ -130,6 +143,11 @@ variable. 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} & + See \t{D} & + Like \t{D}, but with \t{EPREFIX} appended. This is a convenience variable. See also the + \t{EPREFIX} variable. \\ \t{IMAGE}\footnote{Deprecated in favour of \t{D}.} & \t{pkg\_preinst}, \t{pkg\_postinst} & Yes & @@ -197,6 +215,24 @@ variable. \end{tabular} \end{centertable} +\begin{centertable}{EAPIs supporting offset-prefix env variables} + \label{tab:offset-env-vars-table} + \begin{tabular}{ l l l l } + \toprule + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{\t{EPREFIX}?}} & + \multicolumn{1}{c}{\textbf{\t{EROOT}?}} & + \multicolumn{1}{c}{\textbf{\t{ED}?}} \\ + \midrule + \t{0} & No & No & No \\ + \t{1} & No & No & No \\ + \t{2} & No & No & No \\ + \t{3} & Yes & Yes & Yes \\ + \t{4} & Yes & Yes & Yes \\ + \bottomrule + \end{tabular} +\end{centertable} + Except where otherwise noted, all variables set in the active profiles' \t{make.defaults} files must be exported to the ebuild environment. \t{CHOST}, \t{CBUILD} and \t{CTARGET}, if not set by profiles, must contain either an appropriate machine tuple (the definition of appropriate is beyond @@ -290,6 +326,34 @@ installing \t{foo-2:2} to replace \t{foo-2:1} and \t{foo-3:2}. In EAPIs listed in table~\ref{tab:env-vars-table} as supporting it, the \t{REPLACED\_BY} variable shall be defined in \t{pkg\_prerm} and \t{pkg\_postrm}. It shall contain at most one value. +\subsection{Offset-prefix variables \t{EPREFIX}, \t{EROOT} and \t{ED}} +\label{sec:offset-vars} + +\begin{centertable}{EAPIs supporting offset-prefix} + \label{tab:offset-support-table} + \begin{tabular}{ l l } + \toprule + \multicolumn{1}{c}{\textbf{EAPI}} & + \multicolumn{1}{c}{\textbf{Supports offset-prefix?}}\\ + \midrule + \t{0} & No \\ + \t{1} & No \\ + \t{2} & No \\ + \t{3} & Yes \\ + \t{4} & Yes \\ + \bottomrule + \end{tabular} +\end{centertable} + +\featurelabel{offset-prefix-vars} Table~\ref{tab:offset-support-table} lists the EAPIs which support +offset-prefix installations. This support was initially added in EAPI 3, in the form of three extra +variables. Two of these, \t{EROOT} and \t{ED}, are convenience variables using the variable +\t{EPREFIX}. In EAPIs that do not support an offset-prefix, the installation offset is hardwired to +\t{/usr}. In offset-prefix supporting EAPIs the installation offset is set as \t{\$\{EPREFIX\}/usr} +and hence can be adjusted using the variable \t{EPREFIX}. Note that the behaviour of offset-prefix +aware and agnostic is the same when \t{EPREFIX} is set to the empty string in offset-prefix aware +EAPIs. The latter do have the variables \t{ED} and \t{EROOT} properly set, though. + % vim: set filetype=tex fileencoding=utf8 et tw=100 spell spelllang=en : %%% Local Variables: diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex index 62adb09..0fc5f27 100644 --- a/pkg-mgr-commands.tex +++ b/pkg-mgr-commands.tex @@ -132,12 +132,12 @@ has returned. \featurelabel{econf-options} \begin{itemize} - \item -{}-prefix must default to \t{/usr} unless overridden by \t{econf}'s caller. - \item -{}-mandir must be \t{/usr/share/man} - \item -{}-infodir must be \t{/usr/share/info} - \item -{}-datadir must be \t{/usr/share} - \item -{}-sysconfdir must be \t{/etc} - \item -{}-localstatedir must be \t{/var/lib} + \item -{}-prefix must default to \t{\$\{EPREFIX\}/usr} unless overridden by \t{econf}'s caller. + \item -{}-mandir must be \t{\$\{EPREFIX\}/usr/share/man} + \item -{}-infodir must be \t{\$\{EPREFIX\}/usr/share/info} + \item -{}-datadir must be \t{\$\{EPREFIX\}/usr/share} + \item -{}-sysconfdir must be \t{\$\{EPREFIX\}/etc} + \item -{}-localstatedir must be \t{\$\{EPREFIX\}/var/lib} \item -{}-host must be the value of the \t{CHOST} environment variable. \item -{}-libdir must be set according to Algorithm~\ref{alg:econf-libdir}. \item -{}-disable-dependency-tracking, if the EAPI is listed in @@ -159,6 +159,12 @@ has returned. \end{tabular} \end{centertable} + Note that the \t{\$\{EPREFIX\}} component represents the same offset-prefix as described in + Table~\ref{tab:defined_vars}. It facilitates offset-prefix installations which is supported by EAPIs + listed in Table~\ref{tab:offset-prefix-table}. When no offset-prefix installation is in effect, + \t{EPREFIX} becomes the empty string, making the behaviour of \t{econf} equal for both offset-prefix + supporting and agnostic EAPIs. + \t{econf} must be implemented internally---that is, as a bash function and not an external script. Should any portion of it fail, it must abort the build using \t{die}, unless run using \t{nonfatal}, in which case it must return non-zero exit status. @@ -166,7 +172,7 @@ has returned. \begin{algorithm} \caption{econf -{}-libdir logic} \label{alg:econf-libdir} \begin{algorithmic}[1] -\STATE let prefix=/usr +\STATE let prefix=\$\{EPREFIX\}/usr \IF{the caller specified -{}-prefix=\$p} \STATE let prefix=\$p \ENDIF @@ -193,14 +199,19 @@ has returned. to \t{einstall} are passed verbatim to \t{emake}, as shown. Failure behaviour is EAPI dependent as per section~\ref{sec:failure-behaviour}. + The variable \t{ED} is defined as in Table~\ref{tab:defined_vars} and depends on the use of an + offset-prefix. When such offset-prefix is absent, \t{ED} is equivalent to \t{D}. \t{ED} is always + available in EAPIs that support offset-prefix installations as listed in + Table~\ref{tab:offset-env-vars-table}, hence EAPIs lacking offset-prefix support should use \t{D} + instead of \t{ED} in the command given in Listing~\ref{lst:einstall}. \begin{listing}[H] \caption{einstall command}\label{lst:einstall} \begin{verbatim} emake \ - prefix="${D}"/usr \ - mandir="${D}"/usr/share/man \ - infodir="${D}"/usr/share/info \ - libdir="${D}"/usr/$(get_libdir) \ + prefix="${ED}"/usr \ + mandir="${ED}"/usr/share/man \ + infodir="${ED}"/usr/share/info \ + libdir="${ED}"/usr/$(get_libdir) \ "$@" \ install \end{verbatim} @@ -211,15 +222,21 @@ emake \ \subsubsection{Installation commands} These commands are used to install files into the staging area, in cases where the package's \t{make install} target cannot be used or does not install all needed files. Except where otherwise stated, -all filenames created or modified are relative to the staging directory, given by \t{D}. These -commands must all be external programs and not bash functions or aliases---that is, they must be -callable from \t{xargs}. Ebuilds must not run any of these commands once the current phase function -has returned. +all filenames created or modified are relative to the staging directory including the offset-prefix +\t{ED} in offset-prefix aware EAPIs, or just the staging directory \t{D} in offset-prefix agnostic +EAPIs. These commands must all be external programs and not bash functions or aliases---that is, they +must be callable from \t{xargs}. Ebuilds must not run any of these commands once the current phase +function has returned. \begin{description} -\item[dobin] Installs the given files into \t{DESTTREE/bin}, where \t{DESTTREE} defaults to - \t{/usr}. Gives the files mode \t{0755} and ownership \t{root:root}. Failure behaviour is EAPI - dependent as per section~\ref{sec:failure-behaviour}. +\item[dobin] Installs the given files into \t{DESTTREE/bin}, where + \t{DESTTREE} defaults to \t{/usr}. Gives the files mode \t{0755} + and transfers file ownership to the superuser or its equivalent on + the system or installation at hand. For instance on Gentoo Linux in + a non-offset-prefix installation this ownership is \t{root:root}, + while on an offset-prefix aware installation this may be + \t{joe:users}. Failure behaviour is EAPI dependent as per + section~\ref{sec:failure-behaviour}. \item[doconfd] Installs the given config files into \t{/etc/conf.d/}, by default with file mode \t{0644}. This can be overridden by setting \t{INSOPTIONS} with the \t{insopts} function. @@ -257,7 +274,7 @@ variable with the \t{docinto} function. Files to be installed automatically are extension and the default extensions are \t{css}, \t{gif}, \t{htm}, \t{html}, \t{jpeg}, \t{jpg}, \t{js} and \t{png}. These default extensions can be extended or reduced (see below). The options that can be passed to \t{dohtml} are as follows: - \begin{description} +\begin{description} \item{\t{-r}} --- enables recursion into directories. \item{\t{-V}} --- enables verbosity. \item{\t{-A}} --- adds file type extensions to the default list. @@ -265,8 +282,9 @@ that can be passed to \t{dohtml} are as follows: \item{\t{-f}} --- list of files that are able to be installed. \item{\t{-x}} --- list of directories that files will not be installed from (only used in conjunction with \t{-r}). - \item{\t{-p}} --- sets a document prefix for installed files. - \end{description} + \item{\t{-p}} --- sets a document prefix for installed files, not to be confused with the global + offset-prefix. +\end{description} Failure behaviour is EAPI dependent as per section~\ref{sec:failure-behaviour}. @@ -423,16 +441,20 @@ that can be passed to \t{dohtml} are as follows: \end{centertable} \subsubsection{Commands affecting install destinations} -The following commands are used to set the various destination trees, all relative to \t{\$\{D\}}, -used by the above installation commands. They must be shell functions or aliases, due to the need to -set variables read by the above commands. Ebuilds must not run any of these commands once the -current phase function has returned. +The following commands are used to set the various destination trees, all relative to \t{\$\{ED\}} in +offset-prefix aware EAPIs and relative to \t{\$\{D\}} in offset-prefix agnostic EAPIs, used by the +above installation commands. They must be shell functions or aliases, due to the need to set variables +read by the above commands. Ebuilds must not run any of these commands once the current phase function +has returned. \begin{description} -\item[into] Sets the value of \t{DESTTREE} for future invocations of the above utilities. Creates -the directory under \t{\$\{D\}}, using \t{install -d} with no additional options, if it does not -already exist. Failure behaviour is EAPI dependent as per section~\ref{sec:failure-behaviour}. +\item[into] Sets the value of \t{DESTTREE} for future invocations + of the above utilities. Creates the directory under \t{\$\{ED\}} + in offset-prefix aware EAPIs or under \t{\$\{D\}} in offset-prefix + agnostic EAPIs, using \t{install -d} with no additional options, + if it does not already exist. Failure behaviour is EAPI dependent + as per section~\ref{sec:failure-behaviour}. \item[insinto] Sets the value of \t{INSDESTTREE} for future invocations of the above utilities. May create the directory, as specified for \t{into}. @@ -456,9 +478,10 @@ already exist. Failure behaviour is EAPI dependent as per section~\ref{sec:failu \subsubsection{Commands affecting install compression} \featurelabel{controllable-compress} In EAPIs listed in table~\ref{tab:compression-table} as -supporting controllable compression, the package manager may optionally compress a subset of the -files under the \t{D} directory. To control which directories may or may not be compressed, the -package manager shall maintain two lists: +supporting controllable compression, the package manager may optionally compress a subset of the files +under the \t{ED} directory in offset-prefix aware EAPIs or the \t{D} directory in offset-prefix +agnostic EAPIs. To control which directories may or may not be compressed, the package manager shall +maintain two lists: \begin{compactitem} \item An inclusion list, which initially contains \t{/usr/share/doc}, \t{/usr/share/info} and @@ -468,7 +491,8 @@ package manager shall maintain two lists: The optional compression shall be carried out after \t{src\_install} has completed, and before the execution of any subsequent phase function. For each item in the inclusion list, pretend it has the -value of the \t{D} variable prepended, then: +value of the \t{ED} variable in offset-prefix aware EAPIs or the \t{D} +variable in offset-prefix agnostic EAPIs prepended, then: \begin{compactitem} \item If it is a directory, act as if every file or directory immediately under this directory @@ -478,7 +502,8 @@ value of the \t{D} variable prepended, then: \end{compactitem} Whether an item is to be excluded is determined as follows: For each item in the exclusion list, -pretend it has the value of the \t{D} variable prepended, then: +pretend it has the value of the \t{ED} variable in offset-prefix aware EAPIs or the \t{D} variable in +offset-prefix agnostic EAPIs prepended, then: \begin{compactitem} \item If it is a directory, act as if every file or directory immediately under this directory @@ -572,10 +597,11 @@ has returned. \begin{description} \item[dosed] Takes any number of arguments, which can be files or \t{sed} expressions. For each - argument, if it names, relative to \t{D} a file which exists, then \t{sed} is run with the - current expression on that file. Otherwise, the current expression is set to the text of the - argument. The initial value of the expression is \t{s:\$\{D\}::g}. In EAPIs listed in - table~\ref{tab:banned-commands-table}, this command is banned as per + argument, if it names, relative to \t{ED} (offset-prefix aware EAPIs) or \t{D} (offset-prefix agnostic + EAPIs) a file which exists, then \t{sed} is run with the current expression on that file. Otherwise, + the current expression is set to the text of the argument. The initial value of the expression is + \t{s:\$\{ED\}::g} in offset-prefix aware EAPIs and \t{s:\$\{D\}::g} in offset-prefix agnostic + EAPIs. In EAPIs listed in table~\ref{tab:banned-commands-table}, this command is banned as per section~\ref{sec:banned-commands}. Failure behaviour is EAPI dependent as per section~\ref{sec:failure-behaviour}. @@ -606,7 +632,10 @@ has returned. \item rar files (\t{*.rar, *.RAR}). Ebuilds must ensure that RARLAB's unrar is installed. \item LHA archives (\t{*.LHA, *.LHa, *.lha, *.lhz}). Ebuilds must ensure that the lha program is installed. - \item ar archives (\t{*.a, *.deb}). Ebuilds must ensure that GNU binutils is installed. + \item ar archives (\t{*.a}). Ebuilds must ensure that GNU binutils is installed. + \item deb packages (\t{*.deb}). Ebuilds must ensure that the deb2targz program is installed on + those platforms where the GNU binutils ar program is not available and the installed ar program is + incompatible with GNU archives. Otherwise, ebuilds must ensure that GNU binutils is installed. \item lzma-compressed files (\t{*.lzma}). Ebuilds must ensure that LZMA Utils is installed. \item lzma-compressed tar files (\t{*.tar.lzma}). Ebuilds must ensure that LZMA Utils and GNU tar are installed. -- cgit v1.2.3-18-g5258