Re: [gentoo-dev] Gentoo Prefix: on EPREFIX, ED and EROOT inside ebuilds

[Fabian Groffen <grobian@gentoo.org>]

[-- Attachment #1: Type: text/plain, Size: 580 bytes --]

On 25-11-2009 16:43:32 -0700, Denis Dupeyron wrote:
> > Yes, I agreed coming up with some patch.  I admit I haven't yet even
> > looked into it.
> 
> Great, thanks. If you can have it ready some time before the meeting
> so that all devs can get a chance to review it before the council
> members vote on it that will be even better. If you need help don't
> hesitate to contact me. I'll try and look for the right people to help
> you depending on what you need.

Here is the patch.  I tried to cover all places.


-- 
Fabian Groffen
Gentoo on a different level

[-- Attachment #2: prefix-r0.patch --]
[-- Type: text/plain, Size: 14760 bytes --]

diff --git a/eapi-differences.tex b/eapi-differences.tex
index 7e792b8..2fdf763 100644
--- a/eapi-differences.tex
+++ b/eapi-differences.tex
@@ -176,7 +176,8 @@ Use dependencies & \compactfeatureref{use-deps} & No & No &
     \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{None} &}{}
     \parbox[t]{1in}{\t{pkg\_nofetch}, \t{src\_unpack}, \t{src\_prepare}, \t{src\_configure}, \t{src\_compile}, \t{src\_test}} &
     \parbox[t]{1in}{\t{pkg\_nofetch}, \t{src\_unpack}, \t{src\_prepare}, \t{src\_configure},
-        \t{src\_compile}, \t{src\_install}, \t{src\_test}} \\
+        \t{src\_compile}, \t{src\_install}, \t{src\_test},
+        \t{EPREFIX}, \t{ED}, \t{EROOT}} \\
 
 \t{AA} & \compactfeatureref{aa} & Yes & Yes &
     \IFANYKDEBUILDELSE{\IFKDEBUILDCOLOUR{Yes} &}{} Yes & No \\
@@ -335,6 +336,8 @@ EAPI 3 is EAPI 2 with the following changes:
 \item \t{RDEPEND=DEPEND} no longer done, \featureref{rdepend-depend}.
 \item Utilities now die on failure, \featureref{die-on-failure}, unless called under \t{nonfatal},
     \featureref{nonfatal}
+\item offset-prefix support by definition of \t{EPREFIX}, \t{ED} and
+\t{EROOT}, \featureref{offset-prefix-vars}
 \end{compactitem}
 
 % vim: set filetype=tex fileencoding=utf8 et tw=100 spell spelllang=en :
diff --git a/ebuild-env-vars.tex b/ebuild-env-vars.tex
index e093218..3f9d25c 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,17 @@ 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 environment, a
+	cross-prefix build is performed where using the existing utilities,
+	a package is build for the given \t{EPREFIX}, akin to \t{ROOT}.  See
+	also~\ref{sec:offset-vars}. \\
 \t{D} &
     \t{src\_install} &
     No &
@@ -130,6 +146,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 &
@@ -216,6 +237,22 @@ variable.
 }
 \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 \\
+\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
@@ -309,6 +346,18 @@ 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}
+
+\featurelabel{offset-prefix-vars} In EAPI 3, three variables related to
+offset-prefix installations were added.  Two of these, \t{EROOT} and
+\t{ED}, are convenience variables using the variable \t{EPREFIX}.  In
+EAPIs prior to 3, the installation offset is hardwired to \t{/usr}.
+Using the variable \t{EPREFIX}, in EAPI 3 this installation offset can
+be set as \t{\$\{EPREFIX\}/usr}.  This way, \t{EPREFIX} set to the empty
+string makes the behaviour identical to EAPIs prior to 3, but adds two
+extra variables.
+
 % 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 4b88b20..de2f325 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -169,12 +169,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
@@ -211,6 +211,13 @@ has returned.
     }
     \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 for which support was added
+	in EAPI 3.  When no offset-prefix installation is in effect,
+	\t{EPREFIX} becomes the empty string, making the behaviour of econf
+	equal to EAPIs prior to EAPI 3.
+
     \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.
@@ -218,7 +225,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
@@ -245,14 +252,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} was introduced in
+	EAPI 3, hence in prior EAPIs, \t{D} should be used 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}
@@ -263,7 +275,8 @@ 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
+all filenames created or modified are relative to the staging directory,
+given by \t{ED} for EAPI 3, and \t{D} for EAPIs prior to EAPI 3.  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.
@@ -272,6 +285,9 @@ has returned.
 \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}.
+% todo: Portage does not behave like this, and Prefix relies on that
+%       root:root -> 0:0 (for systems where root name/group are different)
+%       PORTAGE_INST_UID:PORTAGE_INST_GID <- Prefix sets that to user ids
 
 \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.
@@ -317,7 +333,8 @@ 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.
+    \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}.
@@ -556,7 +573,9 @@ that can be passed to \t{dohtml} are as follows:
 }
 
 \subsubsection{Commands affecting install destinations}
-The following commands are used to set the various destination trees, all relative to \t{\$\{D\}},
+The following commands are used to set the various destination trees,
+all relative to \t{\$\{ED\}} in EAPI 3 and relative to \t{\$\{D\}} in
+prior 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.
@@ -564,7 +583,8 @@ 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
+the directory under \t{\$\{ED\}} for EAPI 3 or \t{\$\{D\}} for prior
+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
@@ -590,7 +610,7 @@ already exist. Failure behaviour is EAPI dependent as per section~\ref{sec:failu
 
 \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
+files under the \t{ED} for EAPI 3 and \t{D} for prior EAPIs directory. To control which directories may or may not be compressed, the
 package manager shall maintain two lists:
 
 \begin{compactitem}
@@ -601,7 +621,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 EAPI 3 or the \t{D} variable in prior
+EAPIs prepended, then:
 
 \begin{compactitem}
 \item If it is a directory, act as if every file or directory immediately under this directory
@@ -611,7 +632,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 EAPI 3 or the \t{D}
+variable in prior EAPIs prepended, then:
 
 \begin{compactitem}
 \item If it is a directory, act as if every file or directory immediately under this directory
@@ -736,9 +758,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
+    argument, if it names, relative to \t{ED} (EAPI 3) or \t{D} (EAPIs
+	prior to 3) 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
+    argument. The initial value of the expression is \t{s:\$\{ED\}::g}
+	in EAPI 3 and \t{s:\$\{D\}::g} in prior 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}.
@@ -771,6 +795,9 @@ has returned.
     \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.
+% todo: Portage's implementation is different and required for Prefix
+%       these files are unpacked with deb2targz if available, else it
+%       falls back to "ar", which cannot be required to be GNU binutils
     \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.