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
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{roo...@. 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.
