[patch] First draft of a specification.

dostrip.diff (text/plain), 5.16 KB, created by Ulrich Müller on 2017-10-24 17:49:16 UTC

diff --git a/dependencies.tex b/dependencies.tex
index b81b603..ca2131f 100644
--- a/dependencies.tex
+++ b/dependencies.tex
@@ -502,7 +502,9 @@ The following tokens are permitted inside \t{RESTRICT}:
     be checked when fetching.
 \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.
+\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.
 \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/eapi-differences.tex b/eapi-differences.tex
index beba23f..222e333 100644
--- a/eapi-differences.tex
+++ b/eapi-differences.tex
@@ -290,6 +290,12 @@ Controllable compression & \compactfeatureref{docompress} &
 \t{docompress} & \compactfeatureref{docompress} &
     No & Yes & Yes & Yes & Yes \\
 
+Controllable stripping & \compactfeatureref{dostrip} &
+    No & No & No & No & Yes \\
+
+\t{dostrip} & \compactfeatureref{dostrip} &
+    No & No & No & No & Yes \\
+
 \t{use_with} empty third arg & \compactfeatureref{use-with} &
     No & Yes & Yes & Yes & Yes \\
 
@@ -479,6 +485,7 @@ EAPI 7 is EAPI 6 with the following changes:
 \item binding leftmost-of (\t{||=}) dependency group is supported, \featureref{binding-leftmost-of}.
 \item runtime-modifiable USE flags (\t{IUSE_RUNTIME}) are supported, \featureref{iuse-runtime}.
 \item sandbox path removal flags (\t{rm*}) are supported, \featureref{sandbox-rm}.
+\item Controllable stripping and \t{dostrip}, \featureref{dostrip}.
 \end{compactitem}
 
 \ChangeWhenAddingAnEAPI{7}
diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index ff54d69..0cd9b00 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -828,6 +828,69 @@ in table~\ref{tab:compression-table} as supporting \t{docompress}.
     \end{tabular}
 \end{centertable}
 
+\subsection{Commands affecting stripping of debug symbols}
+
+\featurelabel{dostrip} In EAPIs listed in table~\ref{tab:dostrip} as supporting controllable
+stripping of debug symbols, the package manager may compress 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:
+
+\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.
+\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:
+
+\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.
+\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, if an item is a symlink,
+or if a file is already stripped.
+
+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[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}.
+\end{description}
+
+\ChangeWhenAddingAnEAPI{7}
+\begin{centertable}{EAPIs supporting controllable stripping}
+    \label{tab:dostrip}
+    \begin{tabular}{lll}
+      \toprule
+      \multicolumn{1}{c}{\textbf{EAPI}} &
+      \multicolumn{1}{c}{\textbf{Supports controllable stripping?}} &
+      \multicolumn{1}{c}{\textbf{Supports \t{dostrip}?}} \\
+      \midrule
+      0, 1, 2, 3, 4, 5, 6 & No  & No  \\
+      7                   & Yes & Yes \\
+      \bottomrule
+    \end{tabular}
+\end{centertable}
+
 \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