* [gentoo-pms] [PATCH 1/2] Move shell options to "Ebuild file format" chapter.
2017-09-29 15:29 ` [gentoo-pms] " Ulrich Mueller
@ 2017-09-29 15:01 ` Ulrich Müller
2017-09-29 15:16 ` [gentoo-pms] [PATCH 2/2] Promote "Available commands" from section to chapter Ulrich Müller
2017-10-08 16:05 ` [gentoo-pms] Re: RFC: Promote 11.3.3 "Ebuild-specific commands" to a section Ulrich Mueller
2 siblings, 0 replies; 5+ messages in thread
From: Ulrich Müller @ 2017-09-29 15:01 UTC (permalink / raw
To: gentoo-pms
[-- Attachment #1: Type: text/plain, Size: 5009 bytes --]
Since this paragraph is about Bash options like failglob, it fits
better with the Bash version than with "System commands".
---
eapi-differences.tex | 8 ++++----
ebuild-env-commands.tex | 16 ++++------------
ebuild-format.tex | 15 ++++++++++-----
3 files changed, 18 insertions(+), 21 deletions(-)
diff --git a/eapi-differences.tex b/eapi-differences.tex
index 8f8bf72..2b74e05 100644
--- a/eapi-differences.tex
+++ b/eapi-differences.tex
@@ -46,6 +46,9 @@ Stable use masking/forcing & \compactfeatureref{stablemask} &
Bash version & \compactfeatureref{bash-version} &
3.2 & 3.2 & 3.2 & 3.2 & 4.2 \\
+\t{failglob} in global scope & \compactfeatureref{failglob} &
+ No & No & No & No & Yes \\
+
\t{IUSE} defaults & \compactfeatureref{iuse-defaults} &
* & Yes & Yes & Yes & Yes \\
@@ -147,9 +150,6 @@ Profile \t{IUSE} injection & \compactfeatureref{profile-iuse-inject} &
\t{EPREFIX}, \t{ED}, \t{EROOT} & \compactfeatureref{offset-prefix-vars} &
No & Yes & Yes & Yes & Yes \\
-\t{failglob} in global scope & \compactfeatureref{failglob} &
- No & No & No & No & Yes \\
-
\t{find} is GNU? & \compactfeatureref{gnu-find} &
Undefined & Undefined & Undefined & Yes & Yes \\
@@ -346,10 +346,10 @@ EAPI 6 is EAPI 5 with the following changes:
\begin{compactitem}
\item Bash version is 4.2, \featureref{bash-version}.
+\item \t{failglob} is enabled in global scope, \featureref{failglob}.
\item Default \t{src_prepare} no longer a no-op, \featureref{src-prepare-6}.
\item Different \t{src_install} implementation, \featureref{src-install-6}.
\item \t{LC_CTYPE} and \t{LC_COLLATE} compatible with POSIX locale, \featureref{locale-settings}.
-\item \t{failglob} is enabled in global scope, \featureref{failglob}.
\item \t{einstall} banned, \featureref{banned-commands}.
\item \t{die} and \t{assert} called with \t{-n} respect \t{nonfatal}, \featureref{nonfatal-die}.
\item \t{eapply} support, \featureref{eapply}.
diff --git a/ebuild-env-commands.tex b/ebuild-env-commands.tex
index d1773f5..650d200 100644
--- a/ebuild-env-commands.tex
+++ b/ebuild-env-commands.tex
@@ -32,24 +32,16 @@ The following commands must always be available in the ebuild environment:
table~\ref{tab:system-commands-table} as requiring GNU find.
\end{compactitem}
-\subsubsection{Shell options}
-
-\featurelabel{failglob} For EAPIs listed such in table~\ref{tab:system-commands-table}, the
-\t{failglob} option of bash is set in the global scope of ebuilds. If set, failed pattern matches
-during filename expansion result in an error when the ebuild is being sourced.
-
\ChangeWhenAddingAnEAPI{6}
\begin{centertable}{System commands for EAPIs}
\label{tab:system-commands-table}
- \begin{tabular}{lll}
+ \begin{tabular}{ll}
\toprule
\multicolumn{1}{c}{\textbf{EAPI}} &
- \multicolumn{1}{c}{\textbf{GNU \t{find}?}} &
- \multicolumn{1}{c}{\textbf{\t{failglob} in global scope?}} \\
+ \multicolumn{1}{c}{\textbf{GNU \t{find}?}} \\
\midrule
- 0, 1, 2, 3, 4 & Undefined & No \\
- 5 & Yes & No \\
- 6 & Yes & Yes \\
+ 0, 1, 2, 3, 4 & Undefined \\
+ 5, 6 & Yes \\
\bottomrule
\end{tabular}
\end{centertable}
diff --git a/ebuild-format.tex b/ebuild-format.tex
index 638f773..fac5c81 100644
--- a/ebuild-format.tex
+++ b/ebuild-format.tex
@@ -7,21 +7,26 @@ table~\ref{tab:bash-version}, or any later version. If possible, the package man
the shell's compatibility level to the exact version specified. It must ensure that any such
compatibility settings (e.\,g.\ the \t{BASH_COMPAT} variable) are not exported to external programs.
+\featurelabel{failglob} For EAPIs listed such in table~\ref{tab:bash-version}, the \t{failglob}
+option of bash is set in the global scope of ebuilds. If set, failed pattern matches during
+filename expansion result in an error when the ebuild is being sourced.
+
The file encoding must be UTF-8 with Unix-style newlines. When sourced, the ebuild must define
certain variables and functions (see sections~\ref{sec:ebuild-vars} and~\ref{sec:ebuild-functions}
for specific information), and must not call any external programs, write anything to standard
output or standard error, or modify the state of the system in any way.
\ChangeWhenAddingAnEAPI{6}
-\begin{centertable}{Bash version}
+\begin{centertable}{Bash version and options}
\label{tab:bash-version}
- \begin{tabular}{ll}
+ \begin{tabular}{lll}
\toprule
\multicolumn{1}{c}{\textbf{EAPI}} &
- \multicolumn{1}{c}{\textbf{Bash version}} \\
+ \multicolumn{1}{c}{\textbf{Bash version}} &
+ \multicolumn{1}{c}{\textbf{\t{failglob} in global scope?}} \\
\midrule
- 0, 1, 2, 3, 4, 5 & 3.2 \\
- 6 & 4.2 \\
+ 0, 1, 2, 3, 4, 5 & 3.2 & No \\
+ 6 & 4.2 & Yes \\
\bottomrule
\end{tabular}
\end{centertable}
--
2.14.2
[-- Attachment #2: Type: application/pgp-signature, Size: 490 bytes --]
^ permalink raw reply related [flat|nested] 5+ messages in thread* [gentoo-pms] [PATCH 2/2] Promote "Available commands" from section to chapter.
2017-09-29 15:29 ` [gentoo-pms] " Ulrich Mueller
2017-09-29 15:01 ` [gentoo-pms] [PATCH 1/2] Move shell options to "Ebuild file format" chapter Ulrich Müller
@ 2017-09-29 15:16 ` Ulrich Müller
2017-10-08 16:05 ` [gentoo-pms] Re: RFC: Promote 11.3.3 "Ebuild-specific commands" to a section Ulrich Mueller
2 siblings, 0 replies; 5+ messages in thread
From: Ulrich Müller @ 2017-09-29 15:16 UTC (permalink / raw
To: gentoo-pms
[-- Attachment #1: Type: text/plain, Size: 10207 bytes --]
"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(-)
rename ebuild-env-commands.tex => commands.tex (92%)
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}
--
2.14.2
[-- Attachment #2: Type: application/pgp-signature, Size: 490 bytes --]
^ permalink raw reply related [flat|nested] 5+ messages in thread