diff --git a/eapi-differences.tex b/eapi-differences.tex index e73f96d..784c4a8 100644 --- a/eapi-differences.tex +++ b/eapi-differences.tex @@ -188,7 +188,8 @@ Use dependencies & \compactfeatureref{use-deps} & No & No & \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\_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 & Yes & No \\ @@ -327,7 +328,8 @@ EAPI 2 is EAPI 1 with the following changes: EAPI 3 is EAPI 2 with the following changes: \begin{compactitem} -\item (to be completed) +\item offset-prefix support by definition of \t{EPREFIX}, \t{ED} and +\t{EROOT}, \featureref{offset-prefix-vars} \end{compactitem} \section*{EAPI 4} diff --git a/ebuild-env-vars.tex b/ebuild-env-vars.tex index 30ae534..4d914ce 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 & @@ -218,6 +239,23 @@ 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 \\ +\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 @@ -311,6 +349,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 and later 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 f694f72..bb5facb 100644 --- a/pkg-mgr-commands.tex +++ b/pkg-mgr-commands.tex @@ -173,12 +173,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 @@ -217,6 +217,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 and later. + \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. @@ -224,7 +231,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 @@ -251,14 +258,20 @@ 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 and is available in later EAPIs, 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} @@ -269,7 +282,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 later, 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. @@ -278,6 +292,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. @@ -323,7 +340,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}. @@ -569,7 +587,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\}} onward from 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. @@ -577,7 +597,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\}} in EAPI 3 and later 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 @@ -603,7 +624,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} onward from 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} @@ -614,7 +635,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 and later 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 @@ -624,7 +646,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 and later 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 @@ -753,9 +776,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 and later) 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}. @@ -788,6 +813,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.