[patch] PMS offset-prefix patch (r6)

0001-Offset-prefix-EPREFIX-ED-and-EROOT.patch (text/plain), 17.91 KB, created by Ulrich Müller on 2010-01-16 19:59:57 UTC

From 5bb79b303e15cacb48190345c56b1f3cdc028d21 Mon Sep 17 00:00:00 2001
From: Ulrich Mueller <[e-mail]>
Date: Mon, 11 Jan 2010 22:53:14 +0100
Subject: [PATCH] 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.
---
 eapi-differences.tex |    6 ++-
 ebuild-env-vars.tex  |   73 ++++++++++++++++++++++++++++++++-
 pkg-mgr-commands.tex |  111 +++++++++++++++++++++++++++++++++++---------------
 3 files changed, 155 insertions(+), 35 deletions(-)

diff --git a/eapi-differences.tex b/eapi-differences.tex
index 179d9f7..87f69b1 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..fd3d460 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 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 +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 &
@@ -197,6 +218,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 +329,38 @@ 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..d9faef5 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -132,12 +132,13 @@ 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 +160,14 @@ 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 +175,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 +202,21 @@ 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 +227,22 @@ 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
+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.
@@ -265,7 +288,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}.
@@ -423,16 +447,21 @@ 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\}},
+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}.
@@ -455,10 +484,13 @@ 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:
+\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{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 +500,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 +511,9 @@ 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
@@ -571,13 +606,17 @@ of the above categories. Ebuilds must not run any of these commands once the cur
 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
+\item[dosed] Takes any number of arguments, which can be files or
+    \t{sed} expressions. For each 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}.
+    section~\ref{sec:banned-commands}. Failure behaviour is EAPI
+    dependent as per section~\ref{sec:failure-behaviour}.
 
 \item[unpack] Unpacks one or more source archives, in order, into the current directory. After
     unpacking, must ensure that all filesystem objects inside the current working directory (but not
@@ -606,7 +645,13 @@ 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.
-- 
1.6.6