commit: e2c4c085730ea4a31af288cbb6578f8da1a426a4
Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Sun Nov 5 16:08:23 2017 +0000
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Sun Feb 18 13:35:54 2018 +0000
URL: https://gitweb.gentoo.org/proj/pms.git/commit/?id=e2c4c085
pkg-mgr-commands.tex: Join docompress and dostrip sections.
dependencies.tex | 4 +-
pkg-mgr-commands.tex | 130 +++++++++++++++++++--------------------------------
2 files changed, 49 insertions(+), 85 deletions(-)
diff --git a/dependencies.tex b/dependencies.tex
index deede34..7ae119b 100644
--- a/dependencies.tex
+++ b/dependencies.tex
@@ -507,8 +507,8 @@ The following tokens are permitted inside \t{RESTRICT}:
\item[fetch] The package's \t{SRC_URI} entries may not be downloaded
automatically. If
entries are not available, \t{pkg_nofetch} is called. Implies \t{mirror}.
\item[strip] No stripping of debug symbols from files to be installed may be
performed. In EAPIs
- listed in table~\ref{tab:dostrip} as supporting controllable stripping,
this behaviour may be
- altered by the \t{dostrip} command.
+ listed in table~\ref{tab:staging-area-commands} as supporting controllable
stripping, this
+ behaviour may be altered by the \t{dostrip} command.
\item[userpriv] The package manager may not drop root privileges when building
the package.
\item[test] The \t{src_test} phase must not be run.
\end{description}
diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index 0e4cd60..5ce9569 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -764,27 +764,25 @@ has returned.
\end{description}
-\subsection{Commands affecting install compression}
+\subsection{Commands controlling manipulation of files in the staging area}
+These commands are used to control optional manipulations that the package
manager may perform on
+files in the staging directory \t{ED}, like compressing files or stripping
symbols from object
+files.
-\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
-the \t{ED} directory. To control which directories may or may not be
compressed, the package manager
-shall maintain two lists:
-
-\begin{compactitem}
-\item An inclusion list, which initially contains \t{/usr/share/doc},
\t{/usr/share/info} and
- \t{/usr/share/man}.
-\item An exclusion list, which initially contains
\t{/usr/share/doc/\$\{PF\}/html}.
-\end{compactitem}
+For each of the operations mentioned below, the package manager shall maintain
an inclusion list
+and an exclusion list, in order to control which directories and files the
operation may or may not
+be performed upon. The initial contents of the two lists is specified below
for each of the
+commands, respectively.
-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{ED} variable prepended, then:
+Any of these operations 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{ED} variable prepended, then:
\begin{compactitem}
\item If it is a directory, act as if every file or directory immediately
under this directory
were in the inclusion list.
-\item If the item is a file, it may be compressed unless it has been excluded
as described below.
+\item If the item is a file, the operation may be performed on it, unless it
has been excluded as
+ described below.
\item If the item does not exist, it is ignored.
\end{compactitem}
@@ -794,96 +792,62 @@ pretend it has the value of the \t{ED} variable
prepended, then:
\begin{compactitem}
\item If it is a directory, act as if every file or directory immediately
under this directory
were in the exclusion list.
-\item If the item is a file, it shall not be compressed.
+\item If the item is a file, the operation shall not be performed on it.
\item If the item does not exist, it is ignored.
\end{compactitem}
-The package manager shall take appropriate steps to ensure that its
compression mechanisms behave
-sensibly even if an item is listed in the inclusion list multiple times, if an
item is a symlink,
-or if a file is already compressed.
-
-The following commands may be used in \t{src_install} to alter these lists. It
is an error to call
-any of these functions from any other phase.
-
-\begin{description}
-\item[docompress] If the first argument is \t{-x}, add each of its subsequent
arguments to the
-exclusion list. Otherwise, add each argument to the inclusion list. Only
available in EAPIs listed
-in table~\ref{tab:compression-table} as supporting \t{docompress}.
-\end{description}
-
-\ChangeWhenAddingAnEAPI{7}
-\begin{centertable}{EAPIs supporting controllable compression}
- \label{tab:compression-table}
- \begin{tabular}{lll}
- \toprule
- \multicolumn{1}{c}{\textbf{EAPI}} &
- \multicolumn{1}{c}{\textbf{Supports controllable compression?}} &
- \multicolumn{1}{c}{\textbf{Supports \t{docompress}?}} \\
- \midrule
- 0, 1, 2, 3 & No & No \\
- 4, 5, 6, 7 & Yes & Yes \\
- \bottomrule
- \end{tabular}
-\end{centertable}
-
-\subsection{Commands affecting stripping of symbols}
+The package manager shall take appropriate steps to ensure that any operations
that it performs on
+files in the staging area behave sensibly even if an item is listed in the
inclusion list multiple
+times or if an item is a symlink.
-\featurelabel{dostrip} In EAPIs listed in table~\ref{tab:dostrip} as
supporting controllable
-stripping of symbols, the package manager may strip a subset of the files
under the \t{ED}
-directory. To control which files may or may not be stripped, the package
manager shall maintain
-two lists:
+\featurelabel{docompress} In EAPIs listed in
table~\ref{tab:staging-area-commands} as supporting
+controllable compression, the package manager may optionally compress a subset
of the files under
+the \t{ED} directory. The package manager shall ensure that its compression
mechanisms behave
+sensibly even if a file is already compressed. For compression, the initial
values of the two lists
+are as follows:
\begin{compactitem}
-\item An inclusion list. If the \t{RESTRICT} variable described in
section~\ref{sec:restrict}
- enables a \t{strip} token, this list is initially empty; otherwise it
initially contains \t{/}
- (the root path).
-\item An exclusion list, which initially is empty.
+\item The inclusion list contains \t{/usr/share/doc}, \t{/usr/share/info} and
\t{/usr/share/man}.
+\item The exclusion list contains \t{/usr/share/doc/\$\{PF\}/html}.
\end{compactitem}
-Stripping of symbols 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{ED} variable prepended, then:
+\featurelabel{dostrip} In EAPIs listed in
table~\ref{tab:staging-area-commands} as supporting
+controllable stripping of symbols, the package manager may strip a subset of
the files under the
+\t{ED} directory. For stripping of symbols, the initial values of the two
lists are as follows:
\begin{compactitem}
-\item If it is a directory, act as if every file or directory immediately
under this directory
- were in the inclusion list.
-\item If the item is a file, it may be stripped unless it has been excluded as
described below.
-\item If the item does not exist, it is ignored.
+\item If the \t{RESTRICT} variable described in section~\ref{sec:restrict}
enables a \t{strip}
+ token, the inclusion list is empty; otherwise it contains \t{/} (the root
path).
+\item The exclusion list is empty.
\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{ED} variable prepended, then:
-
-\begin{compactitem}
-\item If it is a directory, act as if every file or directory immediately
under this directory
- were in the exclusion list.
-\item If the item is a file, it shall not be stripped.
-\item If the item does not exist, it is ignored.
-\end{compactitem}
-
-The package manager shall take appropriate steps to ensure that its stripping
mechanisms behave
-sensibly even if an item is listed in the inclusion list multiple times or if
an item is a symlink.
-
-The following command may be used in \t{src_install} to alter these lists. It
is an error to call
-this function from any other phase.
+The following commands may be used in \t{src_install} to alter these lists. It
is an error to call
+any of these functions from any other phase.
\begin{description}
+\item[docompress] If the first argument is \t{-x}, add each of its subsequent
arguments to the
+ exclusion list for compression. Otherwise, add each argument to the
respective inclusion list.
+ Only available in EAPIs listed in table~\ref{tab:staging-area-commands} as
supporting
+ \t{docompress}.
+
\item[dostrip] If the first argument is \t{-x}, add each of its subsequent
arguments to the
- exclusion list. Otherwise, add each argument to the inclusion list. Only
available in EAPIs
- listed in table~\ref{tab:dostrip} as supporting \t{dostrip}.
+ exclusion list for stripping of symbols. Otherwise, add each argument to
the respective
+ inclusion list. Only available in EAPIs listed in
table~\ref{tab:staging-area-commands} as
+ supporting \t{dostrip}.
\end{description}
\ChangeWhenAddingAnEAPI{7}
-\begin{centertable}{EAPIs supporting controllable stripping}
- \label{tab:dostrip}
+\begin{centertable}{Commands controlling manipulation of files in the staging
area in EAPIs}
+ \label{tab:staging-area-commands}
\begin{tabular}{lll}
\toprule
\multicolumn{1}{c}{\textbf{EAPI}} &
- \multicolumn{1}{c}{\textbf{Supports controllable stripping?}} &
- \multicolumn{1}{c}{\textbf{Supports \t{dostrip}?}} \\
+ \multicolumn{1}{P{13.5em}}{\textbf{Supports controllable compression and
\t{docompress}?}} &
+ \multicolumn{1}{P{10.5em}}{\textbf{Supports controllable stripping and
\t{dostrip}?}} \\
\midrule
- 0, 1, 2, 3, 4, 5, 6 & No & No \\
- 7 & Yes & Yes \\
+ 0, 1, 2, 3 & No & No \\
+ 4, 5, 6 & Yes & No \\
+ 7 & Yes & Yes \\
\bottomrule
\end{tabular}
\end{centertable}
