EAPI 3 has pkg_pretend.

1 files changed, 56 insertions, 1 deletions

diff --git a/ebuild-functions.tex b/ebuild-functions.tex
index ee84f2c..0dfeaa4 100644
--- a/ebuild-functions.tex
+++ b/ebuild-functions.tex
@@ -25,6 +25,54 @@ package, not the current configuration.
 
 Ebuilds must not call nor assume the existence of any phase functions.
 
+\subsection{pkg\_pretend}
+\label{sec:pkg-pretend-function}
+
+The \t{pkg\_pretend} function is only called for EAPIs listed in table~\ref{tab:pkg-pretend-table} as
+supporting it.
+
+The \t{pkg\_pretend} function may be used to carry out sanity checks early on in the install
+process. For example, if an ebuild requires a particular kernel configuration, it may perform that
+check in \t{pkg\_pretend} and call \t{eerror} and then \t{die} with appropriate messages if the
+requirement is not met.
+
+\t{pkg\_pretend} is run separately from the main phase function sequence, and does not participate
+in any kind of environment saving. There is no guarantee that any of an ebuild's dependencies will
+be met at this stage, and no guarantee that the system state will not have changed substantially
+before the next phase is executed.
+
+\t{pkg\_pretend} must not write to the filesystem.
+
+\begin{centertable}{EAPIs supporting \t{pkg\_pretend}} \label{tab:pkg-pretend-table}
+\IFKDEBUILDELSE
+{
+    \begin{tabular}{ l l }
+        \toprule
+        \multicolumn{1}{c}{\textbf{EAPI}} &
+        \multicolumn{1}{c}{\textbf{Supports \t{pkg\_pretend}?}} \\
+        \midrule
+    \t{0} & No \\
+    \t{1} & No \\
+    \t{kdebuild-1} & No \\
+    \t{2} & No \\
+    \t{3} & Yes \\
+    \bottomrule
+    \end{tabular}
+}{
+    \begin{tabular}{ l l }
+        \toprule
+        \multicolumn{1}{c}{\textbf{EAPI}} &
+        \multicolumn{1}{c}{\textbf{Supports \t{pkg\_pretend}?}} \\
+        \midrule
+    \t{0} & No \\
+    \t{1} & No \\
+    \t{2} & No \\
+    \t{3} & Yes \\
+    \bottomrule
+    \end{tabular}
+}
+\end{centertable}
+
 \subsection{pkg\_setup}
 \label{sec:pkg-setup-function}
 The \t{pkg\_setup} function sets up the ebuild's environment for all following functions, before
@@ -405,6 +453,8 @@ must not call these functions except when in the phase in question.
 The call order for installing a package is:
 
 \begin{compactitem}
+\item \t{pkg\_pretend} (only for EAPIs listed in table~\ref{tab:pkg-pretend-table}), which is called
+    outside of the normal call order process.
 \item \t{pkg\_setup}
 \item \t{src\_unpack}
 \item \t{src\_prepare} (only for EAPIs listed in table~\ref{tab:src-prepare-table})
@@ -426,6 +476,8 @@ The call order for uninstalling a package is:
 The call order for reinstalling a package is:
 
 \begin{compactitem}
+\item \t{pkg\_pretend} (only for EAPIs listed in table~\ref{tab:pkg-pretend-table}), which is called
+    outside of the normal call order process.
 \item \t{pkg\_setup}
 \item \t{src\_unpack}
 \item \t{src\_prepare} (only for EAPIs listed in table~\ref{tab:src-prepare-table})
@@ -442,6 +494,8 @@ The call order for reinstalling a package is:
 The call order for upgrading or downgrading a package is:
 
 \begin{compactitem}
+\item \t{pkg\_pretend} (only for EAPIs listed in table~\ref{tab:pkg-pretend-table}), which is called
+    outside of the normal call order process.
 \item \t{pkg\_setup}
 \item \t{src\_unpack}
 \item \t{src\_prepare} (only for EAPIs listed in table~\ref{tab:src-prepare-table})
@@ -456,7 +510,8 @@ The call order for upgrading or downgrading a package is:
 \end{compactitem}
 
 The \t{pkg\_config}, \t{pkg\_info} and \t{pkg\_nofetch} functions are not called in a normal
-sequence.
+sequence. The \t{pkg\_pretend} function is called some unspecified time before a (possibly
+hypothetical) normal sequence.
 
 For installing binary packages, the \t{src} phases are not called.