From bc35add47d38f60824491c5ef1ced7dbdab3dd33 Mon Sep 17 00:00:00 2001
From: Ulrich Müller <ulm@gentoo.org>
Date: Fri, 29 Sep 2017 17:16:48 +0200
Subject: Promote "Available commands" from section to chapter.

"The ebuild environment" is the largest chapter by far with 23 pages,
mainly due to section "Available commands" which alone has 15 pages.
Therefore, promote this section to a chapter of its own (which will
still be the largest chapter of the document).
---
 commands.tex | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100644 commands.tex

(limited to 'commands.tex')

diff --git a/commands.tex b/commands.tex
new file mode 100644
index 0000000..5f6fe7a
--- /dev/null
+++ b/commands.tex
@@ -0,0 +1,66 @@
+\chapter{Available Commands}
+
+This chapter documents the commands available to an ebuild. Unless otherwise specified, they may be
+aliases, shell functions, or executables in the ebuild's \t{PATH}.
+
+When an ebuild is being sourced for metadata querying rather than for a build (that is to say,
+when none of the \t{src_} or \t{pkg_} functions are to be called), no external command may
+be executed. The package manager may take steps to enforce this.
+
+\section{System Commands}
+
+Any ebuild not listed in the system set for the active profile(s) may assume the presence of every
+command that is always provided by the system set for that profile. However, it must target the
+lowest common denominator of all systems on which it might be installed---in most cases this means
+that the only packages that can be assumed to be present are those listed in the \t{base} profile or
+equivalent, which is inherited by all available profiles. If an ebuild requires any applications not
+provided by the system profile, or that are provided conditionally based on USE flags, appropriate
+dependencies must be used to ensure their presence.
+
+\subsection{Guaranteed system commands}
+\label{sec:guaranteed-system-commands}
+
+The following commands must always be available in the ebuild environment:
+\begin{compactitem}
+\item All builtin commands in GNU bash, version as listed in table~\ref{tab:bash-version} on
+    page~\pageref{tab:bash-version}.
+\item \t{sed} must be available, and must support all forms of invocations valid for GNU sed
+    version 4 or later.
+\item \t{patch} must be available, and must support all inputs valid for GNU patch.
+\item \featurelabel{gnu-find} \t{find} and \t{xargs} must be available, and must support all forms
+    of invocations valid for GNU findutils version 4.4 or later. Only for EAPIs listed in
+    table~\ref{tab:system-commands-table} as requiring GNU find.
+\end{compactitem}
+
+\ChangeWhenAddingAnEAPI{6}
+\begin{centertable}{System commands for EAPIs}
+    \label{tab:system-commands-table}
+    \begin{tabular}{ll}
+      \toprule
+      \multicolumn{1}{c}{\textbf{EAPI}} &
+      \multicolumn{1}{c}{\textbf{GNU \t{find}?}} \\
+      \midrule
+      0, 1, 2, 3, 4     & Undefined \\
+      5, 6              & Yes       \\
+      \bottomrule
+    \end{tabular}
+\end{centertable}
+
+\section{Commands Provided by Package Dependencies}
+
+In some cases a package's build process will require the availability of executables not provided by
+the core system, a common example being autotools. The availability of commands provided by the
+particular types of dependencies is explained in section~\ref{sec:dependency-classes}.
+
+\input{pkg-mgr-commands.tex}
+
+% vim: set filetype=tex fileencoding=utf8 et tw=100 spell spelllang=en :
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: "pms"
+%%% LaTeX-indent-level: 4
+%%% LaTeX-item-indent: 0
+%%% TeX-brace-indent-level: 4
+%%% fill-column: 100
+%%% End:
-- 
cgit v1.2.3-65-gdbad