commit: bc35add47d38f60824491c5ef1ced7dbdab3dd33
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Fri Sep 29 15:16:48 2017 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Fri Sep 29 15:16:48 2017 +0000
URL: https://gitweb.gentoo.org/proj/pms.git/commit/?id=bc35add4
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).
ebuild-env-commands.tex => commands.tex | 10 +++++-----
ebuild-environment.tex | 2 --
pkg-mgr-commands.tex | 34 ++++++++++++++++-----------------
pms.tex | 2 ++
4 files changed, 24 insertions(+), 24 deletions(-)
diff --git a/ebuild-env-commands.tex b/commands.tex
similarity index 92%
rename from ebuild-env-commands.tex
rename to commands.tex
index 650d200..5f6fe7a 100644
--- a/ebuild-env-commands.tex
+++ b/commands.tex
@@ -1,13 +1,13 @@
-\section{Available Commands}
+\chapter{Available Commands}
-This section documents the commands available to an ebuild. Unless otherwise
specified, they may be
+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.
-\subsection{System commands}
+\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
@@ -17,7 +17,7 @@ equivalent, which is inherited by all available profiles. If
an ebuild requires
provided by the system profile, or that are provided conditionally based on
USE flags, appropriate
dependencies must be used to ensure their presence.
-\subsubsection{Guaranteed system commands}
+\subsection{Guaranteed system commands}
\label{sec:guaranteed-system-commands}
The following commands must always be available in the ebuild environment:
@@ -46,7 +46,7 @@ The following commands must always be available in the ebuild
environment:
\end{tabular}
\end{centertable}
-\subsection{Commands provided by package dependencies}
+\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
diff --git a/ebuild-environment.tex b/ebuild-environment.tex
index 99e7967..82c036c 100644
--- a/ebuild-environment.tex
+++ b/ebuild-environment.tex
@@ -4,8 +4,6 @@
\input{ebuild-env-state.tex}
-\input{ebuild-env-commands.tex}
-
\input{ebuild-env-invariancy.tex}
% vim: set filetype=tex fileencoding=utf8 et tw=100 spell spelllang=en :
diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index 6fd35ae..ab9c586 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -1,4 +1,4 @@
-\subsection{Ebuild-specific commands}
+\section{Ebuild-specific Commands}
\label{sec:pkg-mgr-commands}
The following commands will always be available in the ebuild environment,
provided by the package
@@ -8,7 +8,7 @@ behaviour.
Unless otherwise noted, any output of these commands ends with a newline.
-\subsubsection{Failure behaviour and related commands}
+\subsection{Failure behaviour and related commands}
\label{sec:failure-behaviour}
\featurelabel{die-on-failure} Where a command is listed as having EAPI
dependent failure behaviour,
@@ -41,7 +41,7 @@ The following commands affect this behaviour:
\end{tabular}
\end{centertable}
-\subsubsection{Banned commands}
+\subsection{Banned commands}
\label{sec:banned-commands}
\featurelabel{banned-commands} Some commands are banned in some EAPIs. If a
banned command is
@@ -66,7 +66,7 @@ called, the package manager must abort the build process
indicating an error.
\end{tabular}
\end{centertable}
-\subsubsection{Sandbox commands}
+\subsection{Sandbox commands}
These commands affect the behaviour of the sandbox. Each command takes a
single directory as
argument. Ebuilds must not run any of these commands once the current phase
function has returned.
\begin{description}
@@ -77,7 +77,7 @@ argument. Ebuilds must not run any of these commands once the
current phase func
\item[adddeny] Add a directory to the deny list.
\end{description}
-\subsubsection{Package manager query commands}
+\subsection{Package manager query commands}
These commands are used to extract information about the system. Ebuilds must
not run any of
these commands in parallel with any other package manager command. Ebuilds
must not run any of
these commands once the current phase function has returned.
@@ -107,7 +107,7 @@ to the host root instead of \t{ROOT}.
\end{tabular}
\end{centertable}
-\subsubsection{Output commands}
+\subsection{Output commands}
These commands display messages to the user. Unless otherwise stated, the
entire argument list is
used as a message, with backslash-escaped characters interpreted as for the
\t{echo -e} command of
bash, notably \t{\textbackslash t} for a horizontal tab, \t{\textbackslash n}
for a new line, and
@@ -130,7 +130,7 @@ stderr or some other appropriate facility.
message followed by a failure indicator. Returns its first argument as
exit status.
\end{description}
-\subsubsection{Error commands}
+\subsection{Error commands}
These commands are used when an error is detected that will prevent the build
process from
completing. Ebuilds must not run any of these commands once the current phase
function has returned.
\begin{description}
@@ -158,7 +158,7 @@ completing. Ebuilds must not run any of these commands once
the current phase fu
\end{tabular}
\end{centertable}
-\subsubsection{Patch commands}
+\subsection{Patch commands}
These commands are used during the \t{src_prepare} phase to apply patches to
the package's sources.
Ebuilds must not run any of these commands once the current phase function has
returned.
@@ -232,7 +232,7 @@ Ebuilds must not run any of these commands once the current
phase function has r
\end{tabular}
\end{centertable}
-\subsubsection{Build commands}
+\subsection{Build commands}
These commands are used during the \t{src_configure}, \t{src_compile}, and
\t{src_install}
phases to run the package's build commands. Ebuilds must not run any of these
commands once the
current phase function has returned.
@@ -356,7 +356,7 @@ emake \
\end{description}
-\subsubsection{Installation commands}
+\subsection{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
including the offset-prefix
@@ -624,7 +624,7 @@ can be extended or reduced (see below). The options that
can be passed to \t{doh
\end{tabular}
\end{centertable}
-\subsubsection{Commands affecting install destinations}
+\subsection{Commands affecting install destinations}
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
@@ -659,7 +659,7 @@ has returned.
\end{description}
-\subsubsection{Commands affecting install compression}
+\subsection{Commands affecting install compression}
\featurelabel{docompress} 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
@@ -721,7 +721,7 @@ in table~\ref{tab:compression-table} as supporting
\t{docompress}.
\end{tabular}
\end{centertable}
-\subsubsection{USE list functions}
+\subsection{USE list functions}
These functions provide behaviour based upon set or unset use flags. Ebuilds
must not run any of
these commands once the current phase function has returned. It is an error if
an ebuild calls any
of these functions in global scope.
@@ -803,7 +803,7 @@ table~\ref{tab:use-list-strictness}.
\end{tabular}
\end{centertable}
-\subsubsection{Text list functions}
+\subsection{Text list functions}
These functions check whitespace-separated lists for a particular value.
\begin{description}
@@ -813,7 +813,7 @@ These functions check whitespace-separated lists for a
particular value.
\item[hasq] Deprecated synonym for \t{has}.
\end{description}
-\subsubsection{Misc commands}
+\subsection{Misc commands}
The following commands are always available in the ebuild environment, but
don't really fit in any
of the above categories. Ebuilds must not run any of these commands once the
current phase function
has returned.
@@ -992,7 +992,7 @@ has returned.
\end{tabular}
\end{centertable}
-\subsubsection{Debug commands}
+\subsection{Debug commands}
The following commands are available for debugging. Normally all of these
commands should be no ops;
a package manager may provide a special debug mode where these commands
instead do something.
Ebuilds must not run any of these commands once the current phase function has
returned.
@@ -1005,7 +1005,7 @@ Ebuilds must not run any of these commands once the
current phase function has r
\item[debug-print-section] Calls \t{debug-print} with \t{now in section \$*}.
\end{description}
-\subsubsection{Reserved commands and variables}
+\subsection{Reserved commands and variables}
Except where documented otherwise, all functions and variables that contain
any of the following
strings (ignoring case) are reserved for package manager use and may not be
used or relied upon by
diff --git a/pms.tex b/pms.tex
index 3f338fb..4d2cd99 100644
--- a/pms.tex
+++ b/pms.tex
@@ -68,6 +68,8 @@
\include{ebuild-environment}
+\include{commands}
+
\include{merge}
\include{metadata-cache}
