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 <fauli@gentoo.org>

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.