pkgsrc-Changes archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
CVS commit: pkgsrc/doc
Module Name: pkgsrc
Committed By: rillig
Date: Sun Jun 7 23:11:29 UTC 2020
Modified Files:
pkgsrc/doc: pkgsrc.html pkgsrc.txt
Log Message:
doc/pkgsrc.*: regen
To generate a diff of this commit:
cvs rdiff -u -r1.295 -r1.296 pkgsrc/doc/pkgsrc.html
cvs rdiff -u -r1.293 -r1.294 pkgsrc/doc/pkgsrc.txt
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: pkgsrc/doc/pkgsrc.html
diff -u pkgsrc/doc/pkgsrc.html:1.295 pkgsrc/doc/pkgsrc.html:1.296
--- pkgsrc/doc/pkgsrc.html:1.295 Fri Jun 5 07:34:49 2020
+++ pkgsrc/doc/pkgsrc.html Sun Jun 7 23:11:29 2020
@@ -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" >> cc; \
+ done; \
+ > ${.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"><.></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, “Detect classes of bugs by forcing compiler
warnings”</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. Th
</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 w
</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 lo
</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
<p>See <a class="xref" href="#print-PLIST" title="15.3.�Tweaking output of make print-PLIST">Section�15.3, “Tweaking output of <span class="command"><strong>make
print-PLIST</strong></span>”</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">“<span class="quote">up-to-date</span>”</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
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} && ${FIND} -name '*.c'
+C_FILES_CMD= cd ${WRKSRC} && ${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>
Index: pkgsrc/doc/pkgsrc.txt
diff -u pkgsrc/doc/pkgsrc.txt:1.293 pkgsrc/doc/pkgsrc.txt:1.294
--- pkgsrc/doc/pkgsrc.txt:1.293 Fri Jun 5 07:34:49 2020
+++ pkgsrc/doc/pkgsrc.txt Sun Jun 7 23:11:29 2020
@@ -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+=
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
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
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,
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 ${VARN
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 sendfil
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
Home |
Main Index |
Thread Index |
Old Index