doc/pkgsrc.*: regen

2 files changed, 319 insertions, 210 deletions

diff --git a/doc/pkgsrc.html b/doc/pkgsrc.html
index f314f57d488..e2b3efccaf5 100644
--- a/doc/pkgsrc.html
+++ b/doc/pkgsrc.html
@@ -128,13 +128,14 @@ builds)</a></span></dt>
 <dd><dl>
 <dt><span class="sect2"><a href="#bulk.var.confopt">8.4.1. Detect unknown configure options</a></span></dt>
 <dt><span class="sect2"><a href="#bulk.var.comperr">8.4.2. Detect classes of bugs by forcing compiler warnings</a></span></dt>
-<dt><span class="sect2"><a href="#bulk.var.dirs">8.4.3. Use custom directories</a></span></dt>
-<dt><span class="sect2"><a href="#bulk.var.warn">8.4.4. Turn warnings into errors</a></span></dt>
-<dt><span class="sect2"><a href="#bulk.var.pkglint">8.4.5. Reject packages for which pkglint reports errors</a></span></dt>
-<dt><span class="sect2"><a href="#bulk.var.strings">8.4.6. Reject packages that contain forbidden strings</a></span></dt>
-<dt><span class="sect2"><a href="#bulk.var.test">8.4.7. Reject packages whose self-test fails</a></span></dt>
-<dt><span class="sect2"><a href="#bulk.var.shvar">8.4.8. Reject packages that use undefined shell variables</a></span></dt>
-<dt><span class="sect2"><a href="#bulk.var.quiet">8.4.9. Turn off verbose logging</a></span></dt>
+<dt><span class="sect2"><a href="#bulk.var.builderr">8.4.3. Force compiler options only in the build phase</a></span></dt>
+<dt><span class="sect2"><a href="#bulk.var.dirs">8.4.4. Use custom directories</a></span></dt>
+<dt><span class="sect2"><a href="#bulk.var.warn">8.4.5. Turn warnings into errors</a></span></dt>
+<dt><span class="sect2"><a href="#bulk.var.pkglint">8.4.6. Reject packages for which pkglint reports errors</a></span></dt>
+<dt><span class="sect2"><a href="#bulk.var.strings">8.4.7. Reject packages that contain forbidden strings</a></span></dt>
+<dt><span class="sect2"><a href="#bulk.var.test">8.4.8. Reject packages whose self-test fails</a></span></dt>
+<dt><span class="sect2"><a href="#bulk.var.shvar">8.4.9. Reject packages that use undefined shell variables</a></span></dt>
+<dt><span class="sect2"><a href="#bulk.var.quiet">8.4.10. Turn off verbose logging</a></span></dt>
 </dl></dd>
 <dt><span class="sect1"><a href="#creating-cdroms">8.5. Creating a multiple CD-ROM packages collection</a></span></dt>
 <dd><dl><dt><span class="sect2"><a href="#cdpack-example">8.5.1. Example of cdpack</a></span></dt></dl></dd>
@@ -885,13 +886,14 @@ builds)</a></span></dt>
 <dd><dl>
 <dt><span class="sect2"><a href="#bulk.var.confopt">8.4.1. Detect unknown configure options</a></span></dt>
 <dt><span class="sect2"><a href="#bulk.var.comperr">8.4.2. Detect classes of bugs by forcing compiler warnings</a></span></dt>
-<dt><span class="sect2"><a href="#bulk.var.dirs">8.4.3. Use custom directories</a></span></dt>
-<dt><span class="sect2"><a href="#bulk.var.warn">8.4.4. Turn warnings into errors</a></span></dt>
-<dt><span class="sect2"><a href="#bulk.var.pkglint">8.4.5. Reject packages for which pkglint reports errors</a></span></dt>
-<dt><span class="sect2"><a href="#bulk.var.strings">8.4.6. Reject packages that contain forbidden strings</a></span></dt>
-<dt><span class="sect2"><a href="#bulk.var.test">8.4.7. Reject packages whose self-test fails</a></span></dt>
-<dt><span class="sect2"><a href="#bulk.var.shvar">8.4.8. Reject packages that use undefined shell variables</a></span></dt>
-<dt><span class="sect2"><a href="#bulk.var.quiet">8.4.9. Turn off verbose logging</a></span></dt>
+<dt><span class="sect2"><a href="#bulk.var.builderr">8.4.3. Force compiler options only in the build phase</a></span></dt>
+<dt><span class="sect2"><a href="#bulk.var.dirs">8.4.4. Use custom directories</a></span></dt>
+<dt><span class="sect2"><a href="#bulk.var.warn">8.4.5. Turn warnings into errors</a></span></dt>
+<dt><span class="sect2"><a href="#bulk.var.pkglint">8.4.6. Reject packages for which pkglint reports errors</a></span></dt>
+<dt><span class="sect2"><a href="#bulk.var.strings">8.4.7. Reject packages that contain forbidden strings</a></span></dt>
+<dt><span class="sect2"><a href="#bulk.var.test">8.4.8. Reject packages whose self-test fails</a></span></dt>
+<dt><span class="sect2"><a href="#bulk.var.shvar">8.4.9. Reject packages that use undefined shell variables</a></span></dt>
+<dt><span class="sect2"><a href="#bulk.var.quiet">8.4.10. Turn off verbose logging</a></span></dt>
 </dl></dd>
 <dt><span class="sect1"><a href="#creating-cdroms">8.5. Creating a multiple CD-ROM packages collection</a></span></dt>
 <dd><dl><dt><span class="sect2"><a href="#cdpack-example">8.5.1. Example of cdpack</a></span></dt></dl></dd>
@@ -2093,13 +2095,14 @@ builds)</h2></div></div></div>
 <dd><dl>
 <dt><span class="sect2"><a href="#bulk.var.confopt">8.4.1. Detect unknown configure options</a></span></dt>
 <dt><span class="sect2"><a href="#bulk.var.comperr">8.4.2. Detect classes of bugs by forcing compiler warnings</a></span></dt>
-<dt><span class="sect2"><a href="#bulk.var.dirs">8.4.3. Use custom directories</a></span></dt>
-<dt><span class="sect2"><a href="#bulk.var.warn">8.4.4. Turn warnings into errors</a></span></dt>
-<dt><span class="sect2"><a href="#bulk.var.pkglint">8.4.5. Reject packages for which pkglint reports errors</a></span></dt>
-<dt><span class="sect2"><a href="#bulk.var.strings">8.4.6. Reject packages that contain forbidden strings</a></span></dt>
-<dt><span class="sect2"><a href="#bulk.var.test">8.4.7. Reject packages whose self-test fails</a></span></dt>
-<dt><span class="sect2"><a href="#bulk.var.shvar">8.4.8. Reject packages that use undefined shell variables</a></span></dt>
-<dt><span class="sect2"><a href="#bulk.var.quiet">8.4.9. Turn off verbose logging</a></span></dt>
+<dt><span class="sect2"><a href="#bulk.var.builderr">8.4.3. Force compiler options only in the build phase</a></span></dt>
+<dt><span class="sect2"><a href="#bulk.var.dirs">8.4.4. Use custom directories</a></span></dt>
+<dt><span class="sect2"><a href="#bulk.var.warn">8.4.5. Turn warnings into errors</a></span></dt>
+<dt><span class="sect2"><a href="#bulk.var.pkglint">8.4.6. Reject packages for which pkglint reports errors</a></span></dt>
+<dt><span class="sect2"><a href="#bulk.var.strings">8.4.7. Reject packages that contain forbidden strings</a></span></dt>
+<dt><span class="sect2"><a href="#bulk.var.test">8.4.8. Reject packages whose self-test fails</a></span></dt>
+<dt><span class="sect2"><a href="#bulk.var.shvar">8.4.9. Reject packages that use undefined shell variables</a></span></dt>
+<dt><span class="sect2"><a href="#bulk.var.quiet">8.4.10. Turn off verbose logging</a></span></dt>
 </dl></dd>
 <dt><span class="sect1"><a href="#creating-cdroms">8.5. Creating a multiple CD-ROM packages collection</a></span></dt>
 <dd><dl><dt><span class="sect2"><a href="#cdpack-example">8.5.1. Example of cdpack</a></span></dt></dl></dd>
@@ -2290,7 +2293,86 @@ easier.</p>
 </div>
 <div class="sect2">
 <div class="titlepage"><div><div><h3 class="title">
-<a name="bulk.var.dirs"></a>8.4.3. Use custom directories</h3></div></div></div>
+<a name="bulk.var.builderr"></a>8.4.3. Force compiler options only in the build phase</h3></div></div></div>
+<p>When adding custom compiler flags via <code class="varname">CFLAGS</code>,
+these apply to all phases of the package build process. Especially in the
+configure phase, adding <code class="literal">-Werror</code> leads to wrong
+decisions. The GNU configure scripts feed many small test programs to the
+C compiler to see whether certain headers are available, functions are
+defined in a library and programs can be run. In many cases these
+programs would not survive a strict compiler run with <code class="literal">-Wall
+-Wextra -Werror</code>.</p>
+<p>The pkgsrc infrastructure is flexible enough to support compiler
+options being added between the <code class="literal">configure</code> and
+<code class="literal">build</code> phases. It's a little more complicated than the
+other examples in this section but still easy enough.</p>
+<p>The basic idea is to use the pkgsrc compiler wrapper to inject the
+desired compiler options. The compiler wrapper's original task is to hide
+unwanted directories of include files and to normalize compiler options.
+It does this by wrapping the compiler command and rewriting the command
+line. To see this in action, run <span class="command"><strong>bmake patch</strong></span> in a
+package directory and examine the
+<code class="filename">work/.cwrappers/config</code> directory. It contains
+individual configurations for the C compiler and the related tools. The
+plan is to find a hook between the configure and build phases, and to
+modify these configuration files at that point.</p>
+<p>To find this hook, have a look at
+<code class="filename">mk/build/build.mk</code>, which contains among others the
+<code class="literal">pre-build-checks-hook</code>. The word
+<code class="literal">checks</code> doesn't quite fit, but the
+<code class="literal">pre-build-hook</code> sounds good enough.</p>
+<p>The code to be included in <a class="link" href="#mk.conf"><code class="filename">mk.conf</code></a> is:</p>
+<pre class="programlisting">
+# Just a few example options.
+BUILD_ONLY_CFLAGS=      -Wall -Werror -O2 -DTEMPDIR='"/tmp"'
+
+.if ${BUILD_ONLY_CFLAGS:U:M*}
+pre-build-checks-hook: add-build-only-cflags
+
+add-build-only-cflags: .PHONY
+        ${RUN} cd ${CWRAPPERS_CONFIG_DIR};      \
+        ${TEST} ! -f ${.TARGET} || exit 0;      \
+        for flag in ${BUILD_ONLY_CFLAGS}; do    \
+                ${ECHO} "append=$$flag" &gt;&gt; cc;  \
+        done;                                   \
+        &gt; ${.TARGET}
+.endif
+</pre>
+<p>(When editing the <a class="link" href="#mk.conf"><code class="filename">mk.conf</code></a>, make sure that the commands of the
+<code class="literal">add-build-only-cflags</code> target are indented with a tab,
+not with spaces.)</p>
+<p>The condition in the <code class="literal">.if</code> statement contains the
+<code class="literal">:U</code> modifier to prevent parse errors if the variable
+should be undefined, possibly because it is only defined for a subset of
+the packages. The <code class="literal">:M*</code> modifier ensures that there is
+at least one compiler option, to prevent a syntax error in the shell
+parser.</p>
+<p>The code around the <code class="literal">${.TARGET}</code> variable ensures
+that the additional compiler options are only appended once, even if
+<span class="command"><strong>bmake build</strong></span> is run multiple times. To do this, it
+creates a marker file.</p>
+<p>To verify that this setup works, run <span class="command"><strong>bmake
+configure</strong></span> in a package directory. Up to now, everything works
+as usual. Examine the directory
+<code class="filename">work/.cwrappers/config</code> to see that the compiler
+options from <code class="varname">BUILD_ONLY_CFLAGS</code> are not yet added to
+the file <code class="filename">cc</code>. Examine the tail of the
+<code class="filename">work/.work.log</code> file to see that the normal compiler
+options are used.</p>
+<p>Now run <span class="command"><strong>bmake build</strong></span>. This will append the
+options to the file <code class="filename">cc</code> and will create the marker
+file in the same directory. After that, the build starts as usual, but
+with the added compiler options. Examine the tail of the file
+<code class="filename">work/.work.log</code> to see that the lines starting with
+<code class="literal">[*]</code> don't contain the compiler options, but the
+corresponding lines starting with <code class="literal">&lt;.&gt;</code> do end
+with these options.</p>
+<p>Building packages using this setup variant and fixing the resulting
+bugs is the same as in <a class="xref" href="#bulk.var.comperr" title="8.4.2. Detect classes of bugs by forcing compiler warnings">Section 8.4.2, &#8220;Detect classes of bugs by forcing compiler warnings&#8221;</a>.</p>
+</div>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="bulk.var.dirs"></a>8.4.4. Use custom directories</h3></div></div></div>
 <p>Some directories like <code class="varname">PREFIX</code>,
 <code class="varname">VARBASE</code>, <code class="varname">PKG_SYSCONFDIR</code>,
 <code class="varname">PKGMANDIR</code>, <code class="varname">PKG_INFODIR</code> can be
@@ -2306,7 +2388,7 @@ PKG_INFODIR=	a-random-uuid
 </div>
 <div class="sect2">
 <div class="titlepage"><div><div><h3 class="title">
-<a name="bulk.var.warn"></a>8.4.4. Turn warnings into errors</h3></div></div></div>
+<a name="bulk.var.warn"></a>8.4.5. Turn warnings into errors</h3></div></div></div>
 <p>When building a package, warnings are typically ignored since they
 just flow by and do not cause the build to fail immediately. To find
 these warnings, redefine them to errors in <a class="link" href="#mk.conf"><code class="filename">mk.conf</code></a>.</p>
@@ -2324,7 +2406,7 @@ Makefile, and if it doesn't, add
 </div>
 <div class="sect2">
 <div class="titlepage"><div><div><h3 class="title">
-<a name="bulk.var.pkglint"></a>8.4.5. Reject packages for which pkglint reports errors</h3></div></div></div>
+<a name="bulk.var.pkglint"></a>8.4.6. Reject packages for which pkglint reports errors</h3></div></div></div>
 <p>Using pkglint as part of the regular build process is mostly a
 waste of time. If you want to fix some of the warnings, just run pkglint
 recursively on the whole pkgsrc tree. This will take a few minutes (up to
@@ -2332,7 +2414,7 @@ recursively on the whole pkgsrc tree. This will take a few minutes (up to
 </div>
 <div class="sect2">
 <div class="titlepage"><div><div><h3 class="title">
-<a name="bulk.var.strings"></a>8.4.6. Reject packages that contain forbidden strings</h3></div></div></div>
+<a name="bulk.var.strings"></a>8.4.7. Reject packages that contain forbidden strings</h3></div></div></div>
 <p>To ensure that the binary packages don't contain references to the
 build directory, there is already <code class="varname">CHECK_WRKREF</code>. If
 that variable includes the item <code class="literal">extra</code>, it is
@@ -2349,7 +2431,7 @@ therefore the results need to be taken with a grain of salt.</p>
 </div>
 <div class="sect2">
 <div class="titlepage"><div><div><h3 class="title">
-<a name="bulk.var.test"></a>8.4.7. Reject packages whose self-test fails</h3></div></div></div>
+<a name="bulk.var.test"></a>8.4.8. Reject packages whose self-test fails</h3></div></div></div>
 <p>To run the test suites that come with each package, add this line
 to <a class="link" href="#mk.conf"><code class="filename">mk.conf</code></a>.</p>
 <pre class="programlisting">
@@ -2362,19 +2444,23 @@ cyclic dependencies. There is still a lot to do in this area.</p>
 </div>
 <div class="sect2">
 <div class="titlepage"><div><div><h3 class="title">
-<a name="bulk.var.shvar"></a>8.4.8. Reject packages that use undefined shell variables</h3></div></div></div>
+<a name="bulk.var.shvar"></a>8.4.9. Reject packages that use undefined shell variables</h3></div></div></div>
 <p>To catch typos in the shell snippets from the Makefile fragments,
 add the <code class="literal">-u</code> flag to most of the commands by adding this
 line to <a class="link" href="#mk.conf"><code class="filename">mk.conf</code></a>.</p>
 <pre class="programlisting">
 RUN=    @set -eu;
 </pre>
+<p>After that, ensure that none of the bulk build log files (even
+those for successfully built packages) contains the string
+<code class="literal">parameter not set</code> or whatever error message the
+command <span class="command"><strong>sh -ceu '$undefined'</strong></span> outputs.</p>
 <p>See <code class="filename">mk/misc/common.mk</code> for the existing
 definition.</p>
 </div>
 <div class="sect2">
 <div class="titlepage"><div><div><h3 class="title">
-<a name="bulk.var.quiet"></a>8.4.9. Turn off verbose logging</h3></div></div></div>
+<a name="bulk.var.quiet"></a>8.4.10. Turn off verbose logging</h3></div></div></div>
 <p>The build logs of a package are often quite long. This allows error
 messages or other interesting details to hide between the noise. To make
 the actual error message stand out more, add these lines to
@@ -6962,40 +7048,6 @@ ${FETCH_CMD} ${FETCH_BEFORE_ARGS} ${site}${file} ${FETCH_AFTER_ARGS}
 <p>See <a class="xref" href="#print-PLIST" title="15.3. Tweaking output of make print-PLIST">Section 15.3, &#8220;Tweaking output of <span class="command"><strong>make print-PLIST</strong></span>&#8221;</a> for more
 	  information on this target.</p>
 </dd>
-<dt><span class="term">bulk-package</span></dt>
-<dd>
-<p>Used to do bulk builds. If an appropriate binary
-	  package already exists, no action is taken. If not, this
-	  target will compile, install and package it (and its
-	  depends, if <code class="varname">PKG_DEPENDS</code> is set
-	  properly. See <a class="xref" href="#bulk" title="Chapter 8. Creating binary packages for everything in pkgsrc (bulk builds)">Chapter 8, <i>Creating binary packages for everything in pkgsrc (bulk
-builds)</i></a>).
-	  After creating the binary package, the sources, the
-	  just-installed package and its required packages are
-	  removed, preserving free disk space.</p>
-<p><span class="emphasis"><em>Beware that this target may deinstall
-	  all packages installed on a system!</em></span></p>
-</dd>
-<dt><span class="term">bulk-install</span></dt>
-<dd>
-<p>Used during bulk-installs to install required
-	  packages. If an up-to-date binary package is available,
-	  it will be installed via <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?pkg_add+1.i386+NetBSD-9.0"><span class="citerefentry"><span class="refentrytitle">pkg_add</span>(1)</span></a>. If not,
-	  <span class="command"><strong>make bulk-package</strong></span> will be executed,
-	  but the installed binary won't be removed.</p>
-<p>A binary package is considered
-	  <span class="quote">&#8220;<span class="quote">up-to-date</span>&#8221;</span> to be installed via
-	  <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?pkg_add+1.i386+NetBSD-9.0"><span class="citerefentry"><span class="refentrytitle">pkg_add</span>(1)</span></a> if:</p>
-<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
-<li class="listitem"><p>None of the package's files
-	      (<code class="filename">Makefile</code>, ...) were modified
-	      since it was built.</p></li>
-<li class="listitem"><p>None of the package's required (binary)
-	      packages were modified since it was built.</p></li>
-</ul></div>
-<p><span class="emphasis"><em>Beware that this target may deinstall
-	  all packages installed on a system!</em></span></p>
-</dd>
 </dl></div>
 </div>
 </div>
@@ -7806,7 +7858,7 @@ substitutions in this stage.</p></dd>
 </div>
 <div class="sect3">
 <div class="titlepage"><div><div><h4 class="title">
-<a name="fixes.subst.where"></a>21.1.11.2. Choosing the time where the substitutions happen</h4></div></div></div>
+<a name="fixes.subst.where"></a>21.1.11.2. Choosing the files where the substitutions happen</h4></div></div></div>
 <p>The <code class="varname">SUBST_FILES.*</code> variable contains a list of
 filename patterns. These patterns are relative to
 <code class="varname">WRKSRC</code> since that is where most substitutions happen.
@@ -7819,16 +7871,16 @@ implementation checks that each filename pattern that is mentioned here
 has an effect. For example, if none of the
 <code class="filename">*/*/Makefile</code> files contains the patterns to be found
 and substituted, that filename pattern is redundant and should be left
-out. If the text to be substituted occurs in some of the files from a
-single pattern, but not in all of them, that is totally ok, and the SUBST
+out. By default, the SUBST framework will complain with an error message.
+If the text to be substituted occurs in some of the files from a single
+pattern, but not in all of them, that is totally ok, and the SUBST
 framework will only print an INFO message for those files.</p>
 <p>If there is a good reason for having redundant filename patterns,
-set <code class="varname">SUBST_NOOP_OK.path=yes</code> in the above
-example.</p>
+set <code class="varname">SUBST_NOOP_OK.*</code> to <code class="literal">yes</code>.</p>
 <p>Another popular way of choosing the files for the substitutions is
 via a shell command, like this:</p>
 <pre class="programlisting">
-C_FILES_CMD=            cd ${WRKSRC} &amp;&amp; ${FIND} -name '*.c'
+C_FILES_CMD=            cd ${WRKSRC} &amp;&amp; ${FIND} . -name '*.c'
 SUBST_FILES.path=       ${C_FILES_CMD:sh}
 </pre>
 <p>The variable name <code class="varname">C_FILES_CMD</code> in this example is
@@ -7866,15 +7918,15 @@ to enclose them in single quotes.</p>
 SUBST_VARS.path=        PREFIX
 </pre>
 <p>This type of substitutions is typically done by the GNU configure
-scripts, but in some cases these need to be overridden. The same pattern
-is also used when a package defines patches that replace previously
-hard-coded paths like <code class="literal">/usr/local</code> with a
-<code class="literal">@PREFIX@</code> placeholder first, which then gets
-substituted by the actual <code class="literal">${PREFIX}</code> in the
-pre-configure stage. In many of these cases, it works equally well to
-just use the SUBST framework to directly replace
-<code class="literal">/usr/local</code> with <code class="literal">${PREFIX}</code>, thereby
-omitting the intermediate patch file.</p>
+scripts during the do-configure stage, but in some cases these need to be
+overridden. The same pattern is also used when a package defines patches
+that replace previously hard-coded paths like
+<code class="literal">/usr/local</code> with a <code class="literal">@PREFIX@</code>
+placeholder first, which then gets substituted by the actual
+<code class="literal">${PREFIX}</code> in the pre-configure stage. In many of these
+cases, it works equally well to just use the SUBST framework to directly
+replace <code class="literal">/usr/local</code> with <code class="literal">${PREFIX}</code>,
+thereby omitting the intermediate patch file.</p>
 <p>If the above is not flexible enough, it is possible to not use sed
 at all for the substitution but to specify an entirely different command,
 like this:</p>
@@ -13766,132 +13818,136 @@ source packages</h2></div></div></div>
 <td>sh</td>
 </tr>
 <tr>
+<td>shebang</td>
 <td>show</td>
-<td>show-all</td>
 </tr>
 <tr>
+<td>show-all</td>
 <td>show-build-defs</td>
-<td>show-depends</td>
 </tr>
 <tr>
+<td>show-depends</td>
 <td>show-deps</td>
-<td>show-distfiles</td>
 </tr>
 <tr>
+<td>show-distfiles</td>
 <td>show-downlevel</td>
-<td>show-subdir-var</td>
 </tr>
 <tr>
+<td>show-subdir-var</td>
 <td>show-tools</td>
-<td>show-var</td>
 </tr>
 <tr>
+<td>show-var</td>
 <td>show-vars</td>
-<td>snprintf</td>
 </tr>
 <tr>
+<td>snprintf</td>
 <td>socket</td>
-<td>ssp</td>
 </tr>
 <tr>
+<td>ssp</td>
 <td>st_mode</td>
-<td>stage-install</td>
 </tr>
 <tr>
+<td>stage-install</td>
 <td>strcasestr</td>
-<td>strict</td>
 </tr>
 <tr>
+<td>strict</td>
 <td>strip</td>
-<td>strndup</td>
 </tr>
 <tr>
+<td>strndup</td>
 <td>strnlen</td>
-<td>strsep</td>
 </tr>
 <tr>
+<td>strsep</td>
 <td>subst</td>
-<td>substitutions</td>
 </tr>
 <tr>
+<td>substitutions</td>
 <td>subversion</td>
-<td>sun</td>
 </tr>
 <tr>
+<td>sun</td>
 <td>sunpro</td>
-<td>sunwspro</td>
 </tr>
 <tr>
+<td>sunwspro</td>
 <td>svn</td>
-<td>symlink</td>
 </tr>
 <tr>
+<td>symlink</td>
 <td>test</td>
-<td>test-env</td>
 </tr>
 <tr>
+<td>test-env</td>
 <td>tex</td>
-<td>texlive</td>
 </tr>
 <tr>
+<td>texlive</td>
 <td>tmp</td>
-<td>tool</td>
 </tr>
 <tr>
+<td>tool</td>
 <td>tools</td>
-<td>tools-libtool-m4-override</td>
 </tr>
 <tr>
+<td>tools-libtool-m4-override</td>
 <td>type</td>
-<td>ulimit</td>
 </tr>
 <tr>
+<td>ulimit</td>
 <td>undefined</td>
-<td>undo-replace</td>
 </tr>
 <tr>
+<td>undo-replace</td>
 <td>unlimit</td>
-<td>unprivileged</td>
 </tr>
 <tr>
+<td>unprivileged</td>
 <td>unprivileged-install-hook</td>
-<td>unstripped</td>
 </tr>
 <tr>
+<td>unstripped</td>
 <td>update</td>
-<td>upload</td>
 </tr>
 <tr>
+<td>upload</td>
 <td>upload-distfiles</td>
-<td>use_tools</td>
 </tr>
 <tr>
+<td>use_tools</td>
 <td>user</td>
-<td>utimes</td>
 </tr>
 <tr>
+<td>utimes</td>
 <td>vasprintf</td>
-<td>verbose</td>
 </tr>
 <tr>
+<td>verbose</td>
 <td>vsnprintf</td>
-<td>warn</td>
 </tr>
 <tr>
+<td>warn</td>
 <td>warning</td>
-<td>warnings</td>
 </tr>
 <tr>
+<td>warnings</td>
 <td>warnx</td>
-<td>wattr_off</td>
 </tr>
 <tr>
+<td>wattr_off</td>
 <td>wattr_on</td>
-<td>work</td>
 </tr>
 <tr>
+<td>work</td>
 <td>wrapper</td>
+</tr>
+<tr>
 <td>wrkdir</td>
+<td> </td>
 </tr>
 </table>
 </div>
diff --git a/doc/pkgsrc.txt b/doc/pkgsrc.txt
index 570c712b80a..4fa3efe4a3a 100644
--- a/doc/pkgsrc.txt
+++ b/doc/pkgsrc.txt
@@ -111,13 +111,14 @@ I. The pkgsrc user's guide
 
             8.4.1. Detect unknown configure options
             8.4.2. Detect classes of bugs by forcing compiler warnings
-            8.4.3. Use custom directories
-            8.4.4. Turn warnings into errors
-            8.4.5. Reject packages for which pkglint reports errors
-            8.4.6. Reject packages that contain forbidden strings
-            8.4.7. Reject packages whose self-test fails
-            8.4.8. Reject packages that use undefined shell variables
-            8.4.9. Turn off verbose logging
+            8.4.3. Force compiler options only in the build phase
+            8.4.4. Use custom directories
+            8.4.5. Turn warnings into errors
+            8.4.6. Reject packages for which pkglint reports errors
+            8.4.7. Reject packages that contain forbidden strings
+            8.4.8. Reject packages whose self-test fails
+            8.4.9. Reject packages that use undefined shell variables
+            8.4.10. Turn off verbose logging
 
         8.5. Creating a multiple CD-ROM packages collection
 
@@ -764,13 +765,14 @@ Table of Contents
 
         8.4.1. Detect unknown configure options
         8.4.2. Detect classes of bugs by forcing compiler warnings
-        8.4.3. Use custom directories
-        8.4.4. Turn warnings into errors
-        8.4.5. Reject packages for which pkglint reports errors
-        8.4.6. Reject packages that contain forbidden strings
-        8.4.7. Reject packages whose self-test fails
-        8.4.8. Reject packages that use undefined shell variables
-        8.4.9. Turn off verbose logging
+        8.4.3. Force compiler options only in the build phase
+        8.4.4. Use custom directories
+        8.4.5. Turn warnings into errors
+        8.4.6. Reject packages for which pkglint reports errors
+        8.4.7. Reject packages that contain forbidden strings
+        8.4.8. Reject packages whose self-test fails
+        8.4.9. Reject packages that use undefined shell variables
+        8.4.10. Turn off verbose logging
 
     8.5. Creating a multiple CD-ROM packages collection
 
@@ -1734,13 +1736,14 @@ Table of Contents
 
     8.4.1. Detect unknown configure options
     8.4.2. Detect classes of bugs by forcing compiler warnings
-    8.4.3. Use custom directories
-    8.4.4. Turn warnings into errors
-    8.4.5. Reject packages for which pkglint reports errors
-    8.4.6. Reject packages that contain forbidden strings
-    8.4.7. Reject packages whose self-test fails
-    8.4.8. Reject packages that use undefined shell variables
-    8.4.9. Turn off verbose logging
+    8.4.3. Force compiler options only in the build phase
+    8.4.4. Use custom directories
+    8.4.5. Turn warnings into errors
+    8.4.6. Reject packages for which pkglint reports errors
+    8.4.7. Reject packages that contain forbidden strings
+    8.4.8. Reject packages whose self-test fails
+    8.4.9. Reject packages that use undefined shell variables
+    8.4.10. Turn off verbose logging
 
 8.5. Creating a multiple CD-ROM packages collection
 
@@ -1926,7 +1929,79 @@ collected above.
 Patches that are not essential for the package to work should only be reported
 upstream but not committed to pkgsrc, to make future updates easier.
 
-8.4.3. Use custom directories
+8.4.3. Force compiler options only in the build phase
+
+When adding custom compiler flags via CFLAGS, these apply to all phases of the
+package build process. Especially in the configure phase, adding -Werror leads
+to wrong decisions. The GNU configure scripts feed many small test programs to
+the C compiler to see whether certain headers are available, functions are
+defined in a library and programs can be run. In many cases these programs
+would not survive a strict compiler run with -Wall -Wextra -Werror.
+
+The pkgsrc infrastructure is flexible enough to support compiler options being
+added between the configure and build phases. It's a little more complicated
+than the other examples in this section but still easy enough.
+
+The basic idea is to use the pkgsrc compiler wrapper to inject the desired
+compiler options. The compiler wrapper's original task is to hide unwanted
+directories of include files and to normalize compiler options. It does this by
+wrapping the compiler command and rewriting the command line. To see this in
+action, run bmake patch in a package directory and examine the work/.cwrappers/
+config directory. It contains individual configurations for the C compiler and
+the related tools. The plan is to find a hook between the configure and build
+phases, and to modify these configuration files at that point.
+
+To find this hook, have a look at mk/build/build.mk, which contains among
+others the pre-build-checks-hook. The word checks doesn't quite fit, but the
+pre-build-hook sounds good enough.
+
+The code to be included in mk.conf is:
+
+# Just a few example options.
+BUILD_ONLY_CFLAGS=      -Wall -Werror -O2 -DTEMPDIR='"/tmp"'
+
+.if ${BUILD_ONLY_CFLAGS:U:M*}
+pre-build-checks-hook: add-build-only-cflags
+
+add-build-only-cflags: .PHONY
+        ${RUN} cd ${CWRAPPERS_CONFIG_DIR};      \
+        ${TEST} ! -f ${.TARGET} || exit 0;      \
+        for flag in ${BUILD_ONLY_CFLAGS}; do    \
+                ${ECHO} "append=$$flag" >> cc;  \
+        done;                                   \
+        > ${.TARGET}
+.endif
+
+(When editing the mk.conf, make sure that the commands of the
+add-build-only-cflags target are indented with a tab, not with spaces.)
+
+The condition in the .if statement contains the :U modifier to prevent parse
+errors if the variable should be undefined, possibly because it is only defined
+for a subset of the packages. The :M* modifier ensures that there is at least
+one compiler option, to prevent a syntax error in the shell parser.
+
+The code around the ${.TARGET} variable ensures that the additional compiler
+options are only appended once, even if bmake build is run multiple times. To
+do this, it creates a marker file.
+
+To verify that this setup works, run bmake configure in a package directory. Up
+to now, everything works as usual. Examine the directory work/.cwrappers/config
+to see that the compiler options from BUILD_ONLY_CFLAGS are not yet added to
+the file cc. Examine the tail of the work/.work.log file to see that the normal
+compiler options are used.
+
+Now run bmake build. This will append the options to the file cc and will
+create the marker file in the same directory. After that, the build starts as
+usual, but with the added compiler options. Examine the tail of the file work
+/.work.log to see that the lines starting with [*] don't contain the compiler
+options, but the corresponding lines starting with <.> do end with these
+options.
+
+Building packages using this setup variant and fixing the resulting bugs is the
+same as in Section 8.4.2, "Detect classes of bugs by forcing compiler warnings"
+.
+
+8.4.4. Use custom directories
 
 Some directories like PREFIX, VARBASE, PKG_SYSCONFDIR, PKGMANDIR, PKG_INFODIR
 can be configured in pkgsrc. Set these to arbitrary paths during bootstrap or
@@ -1938,7 +2013,7 @@ VARBASE=        /a-random-uuid
 PKGMANDIR=      a-random-uuid
 PKG_INFODIR=    a-random-uuid
 
-8.4.4. Turn warnings into errors
+8.4.5. Turn warnings into errors
 
 When building a package, warnings are typically ignored since they just flow by
 and do not cause the build to fail immediately. To find these warnings,
@@ -1954,14 +2029,14 @@ If a package suggests to add USE_TOOLS+=perl to the package Makefile, research
 whether the package actually needs Perl. If it does, add USE_TOOLS+=perl to the
 package Makefile, and if it doesn't, add TOOLS_BROKEN+=perl.
 
-8.4.5. Reject packages for which pkglint reports errors
+8.4.6. Reject packages for which pkglint reports errors
 
 Using pkglint as part of the regular build process is mostly a waste of time.
 If you want to fix some of the warnings, just run pkglint recursively on the
 whole pkgsrc tree. This will take a few minutes (up to 10), which is much
 faster than a complete bulk build.
 
-8.4.6. Reject packages that contain forbidden strings
+8.4.7. Reject packages that contain forbidden strings
 
 To ensure that the binary packages don't contain references to the build
 directory, there is already CHECK_WRKREF. If that variable includes the item
@@ -1976,7 +2051,7 @@ CHECK_WRKREF_EXTRA_DIRS+=       @[A-Z][A-Z]*@
 The above patterns will probably generate many false positives, therefore the
 results need to be taken with a grain of salt.
 
-8.4.7. Reject packages whose self-test fails
+8.4.8. Reject packages whose self-test fails
 
 To run the test suites that come with each package, add this line to mk.conf.
 
@@ -1987,16 +2062,20 @@ build with this, it will often abort in the early phase where the packages are
 scanned for their dependencies since there are cyclic dependencies. There is
 still a lot to do in this area.
 
-8.4.8. Reject packages that use undefined shell variables
+8.4.9. Reject packages that use undefined shell variables
 
 To catch typos in the shell snippets from the Makefile fragments, add the -u
 flag to most of the commands by adding this line to mk.conf.
 
 RUN=    @set -eu;
 
+After that, ensure that none of the bulk build log files (even those for
+successfully built packages) contains the string parameter not set or whatever
+error message the command sh -ceu '$undefined' outputs.
+
 See mk/misc/common.mk for the existing definition.
 
-8.4.9. Turn off verbose logging
+8.4.10. Turn off verbose logging
 
 The build logs of a package are often quite long. This allows error messages or
 other interesting details to hide between the noise. To make the actual error
@@ -5759,35 +5838,6 @@ print-PLIST
     See Section 15.3, "Tweaking output of make print-PLIST" for more
     information on this target.
 
-bulk-package
-
-    Used to do bulk builds. If an appropriate binary package already exists, no
-    action is taken. If not, this target will compile, install and package it
-    (and its depends, if PKG_DEPENDS is set properly. See Chapter 8, Creating
-    binary packages for everything in pkgsrc (bulk builds)). After creating the
-    binary package, the sources, the just-installed package and its required
-    packages are removed, preserving free disk space.
-
-    Beware that this target may deinstall all packages installed on a system!
-
-bulk-install
-
-    Used during bulk-installs to install required packages. If an up-to-date
-    binary package is available, it will be installed via pkg_add(1). If not, 
-    make bulk-package will be executed, but the installed binary won't be
-    removed.
-
-    A binary package is considered "up-to-date" to be installed via pkg_add(1)
-    if:
-
-      + None of the package's files (Makefile, ...) were modified since it was
-        built.
-
-      + None of the package's required (binary) packages were modified since it
-        was built.
-
-    Beware that this target may deinstall all packages installed on a system!
-
 Chapter 20. Tools needed for building or running
 
 Table of Contents
@@ -6463,7 +6513,7 @@ pre-install
     user names, these belong in pre-configure instead. There are only few
     legitimate use cases for applying substitutions in this stage.
 
-21.1.11.2. Choosing the time where the substitutions happen
+21.1.11.2. Choosing the files where the substitutions happen
 
 The SUBST_FILES.* variable contains a list of filename patterns. These patterns
 are relative to WRKSRC since that is where most substitutions happen. A typical
@@ -6475,17 +6525,18 @@ The above patterns, especially the last, are quite broad. The SUBST
 implementation checks that each filename pattern that is mentioned here has an
 effect. For example, if none of the */*/Makefile files contains the patterns to
 be found and substituted, that filename pattern is redundant and should be left
-out. If the text to be substituted occurs in some of the files from a single
-pattern, but not in all of them, that is totally ok, and the SUBST framework
-will only print an INFO message for those files.
+out. By default, the SUBST framework will complain with an error message. If
+the text to be substituted occurs in some of the files from a single pattern,
+but not in all of them, that is totally ok, and the SUBST framework will only
+print an INFO message for those files.
 
 If there is a good reason for having redundant filename patterns, set
-SUBST_NOOP_OK.path=yes in the above example.
+SUBST_NOOP_OK.* to yes.
 
 Another popular way of choosing the files for the substitutions is via a shell
 command, like this:
 
-C_FILES_CMD=            cd ${WRKSRC} && ${FIND} -name '*.c'
+C_FILES_CMD=            cd ${WRKSRC} && ${FIND} . -name '*.c'
 SUBST_FILES.path=       ${C_FILES_CMD:sh}
 
 The variable name C_FILES_CMD in this example is freely chosen and independent
@@ -6520,13 +6571,14 @@ their pkgsrc counterpart variable ${VARNAME}. A typical example is:
 
 SUBST_VARS.path=        PREFIX
 
-This type of substitutions is typically done by the GNU configure scripts, but
-in some cases these need to be overridden. The same pattern is also used when a
-package defines patches that replace previously hard-coded paths like /usr/
-local with a @PREFIX@ placeholder first, which then gets substituted by the
-actual ${PREFIX} in the pre-configure stage. In many of these cases, it works
-equally well to just use the SUBST framework to directly replace /usr/local
-with ${PREFIX}, thereby omitting the intermediate patch file.
+This type of substitutions is typically done by the GNU configure scripts
+during the do-configure stage, but in some cases these need to be overridden.
+The same pattern is also used when a package defines patches that replace
+previously hard-coded paths like /usr/local with a @PREFIX@ placeholder first,
+which then gets substituted by the actual ${PREFIX} in the pre-configure stage.
+In many of these cases, it works equally well to just use the SUBST framework
+to directly replace /usr/local with ${PREFIX}, thereby omitting the
+intermediate patch file.
 
 If the above is not flexible enough, it is possible to not use sed at all for
 the substitution but to specify an entirely different command, like this:
@@ -9710,38 +9762,39 @@ send                             sendfile
 sendto                           setenv
 setgid                           setprogname
 setuid                           sh
-show                             show-all
-show-build-defs                  show-depends
-show-deps                        show-distfiles
-show-downlevel                   show-subdir-var
-show-tools                       show-var
-show-vars                        snprintf
-socket                           ssp
-st_mode                          stage-install
-strcasestr                       strict
-strip                            strndup
-strnlen                          strsep
-subst                            substitutions
-subversion                       sun
-sunpro                           sunwspro
-svn                              symlink
-test                             test-env
-tex                              texlive
-tmp                              tool
-tools                            tools-libtool-m4-override
-type                             ulimit
-undefined                        undo-replace
-unlimit                          unprivileged
-unprivileged-install-hook        unstripped
-update                           upload
-upload-distfiles                 use_tools
-user                             utimes
-vasprintf                        verbose
-vsnprintf                        warn
-warning                          warnings
-warnx                            wattr_off
-wattr_on                         work
-wrapper                          wrkdir
+shebang                          show
+show-all                         show-build-defs
+show-depends                     show-deps
+show-distfiles                   show-downlevel
+show-subdir-var                  show-tools
+show-var                         show-vars
+snprintf                         socket
+ssp                              st_mode
+stage-install                    strcasestr
+strict                           strip
+strndup                          strnlen
+strsep                           subst
+substitutions                    subversion
+sun                              sunpro
+sunwspro                         svn
+symlink                          test
+test-env                         tex
+texlive                          tmp
+tool                             tools
+tools-libtool-m4-override        type
+ulimit                           undefined
+undo-replace                     unlimit
+unprivileged                     unprivileged-install-hook
+unstripped                       update
+upload                           upload-distfiles
+use_tools                        user
+utimes                           vasprintf
+verbose                          vsnprintf
+warn                             warning
+warnings                         warnx
+wattr_off                        wattr_on
+work                             wrapper
+wrkdir                            
 
 Appendix E. Editing guidelines for the pkgsrc guide