Source-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[pkgsrc/trunk]: pkgsrc/doc doc/pkgsrc.*: regen
details: https://anonhg.NetBSD.org/pkgsrc/rev/e3f677a11326
branches: trunk
changeset: 433088:e3f677a11326
user: rillig <rillig%pkgsrc.org@localhost>
date: Sat May 30 19:25:38 2020 +0000
description:
doc/pkgsrc.*: regen
diffstat:
doc/pkgsrc.html | 209 +++++++++++++++++++------------------------------------
doc/pkgsrc.txt | 203 ++++++++++++++++++------------------------------------
2 files changed, 142 insertions(+), 270 deletions(-)
diffs (truncated from 678 to 300 lines):
diff -r 147842e5490b -r e3f677a11326 doc/pkgsrc.html
--- a/doc/pkgsrc.html Sat May 30 19:25:17 2020 +0000
+++ b/doc/pkgsrc.html Sat May 30 19:25:38 2020 +0000
@@ -126,18 +126,15 @@
<dt><span class="sect1"><a href="#bulk.req">8.3. Requirements of a full bulk build</a></span></dt>
<dt><span class="sect1"><a href="#bulk.var">8.4. Bulk build variants</a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="#bulk.var.subst_noop">8.4.1. Strict SUBST blocks</a></span></dt>
-<dt><span class="sect2"><a href="#bulk.var.confopt">8.4.2. Detect unknown configure options</a></span></dt>
-<dt><span class="sect2"><a href="#bulk.var.comperr">8.4.3. Detect classes of bugs by forcing compiler warnings</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>
-<dt><span class="sect2"><a href="#bulk.var.options">8.4.11. Select random sets of options</a></span></dt>
-<dt><span class="sect2"><a href="#bulk.var.build_defs">8.4.12. Select random configurations of BUILD_DEFS</a></span></dt>
+<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>
</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>
@@ -886,18 +883,15 @@
<dt><span class="sect1"><a href="#bulk.req">8.3. Requirements of a full bulk build</a></span></dt>
<dt><span class="sect1"><a href="#bulk.var">8.4. Bulk build variants</a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="#bulk.var.subst_noop">8.4.1. Strict SUBST blocks</a></span></dt>
-<dt><span class="sect2"><a href="#bulk.var.confopt">8.4.2. Detect unknown configure options</a></span></dt>
-<dt><span class="sect2"><a href="#bulk.var.comperr">8.4.3. Detect classes of bugs by forcing compiler warnings</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>
-<dt><span class="sect2"><a href="#bulk.var.options">8.4.11. Select random sets of options</a></span></dt>
-<dt><span class="sect2"><a href="#bulk.var.build_defs">8.4.12. Select random configurations of BUILD_DEFS</a></span></dt>
+<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>
</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>
@@ -1250,7 +1244,7 @@
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="using-pkg"></a>5.1. Using binary packages</h2></div></div></div>
-<p>On the <a class="ulink" href="https://cdn.NetBSD.org/"; target="_top">cdn.NetBSD.org</a>
+<p>On the <a class="ulink" href="http://cdn.NetBSD.org/"; target="_top">cdn.NetBSD.org</a>
site and mirrors, there are collections of binary packages,
ready to be installed. These binary packages have been built using the
default settings for the directories, that is:</p>
@@ -1267,7 +1261,8 @@
<a name="finding-binary-packages"></a>5.1.1. Finding binary packages</h3></div></div></div>
<p>To install binary packages, you first need to know from where
to get them. The first place where you should look is on the main
- pkgsrc FTP server in the directory <a class="ulink" href="https://cdn.NetBSD.org/pub/pkgsrc/packages/"; target="_top"><code class="filename">/pub/pkgsrc/packages</code></a>.</p>
+
+ pkgsrc FTP server in the directory <a class="ulink" href="http://cdn.NetBSD.org/pub/pkgsrc/packages/"; target="_top"><code class="filename">/pub/pkgsrc/packages</code></a>.</p>
<p>This directory contains binary packages for multiple
platforms. First, select your operating system. (Ignore the
directories with version numbers attached to it, they just exist for
@@ -1294,7 +1289,8 @@
<span class="command"><strong>su</strong></span> to root first):</p>
<pre class="screen">
<code class="prompt">#</code> <strong class="userinput"><code>PATH="/usr/pkg/sbin:$PATH"</code></strong>
-<code class="prompt">#</code> <strong class="userinput"><code>PKG_PATH="https://cdn.NetBSD.org/pub/pkgsrc/packages";</code></strong>
+
+<code class="prompt">#</code> <strong class="userinput"><code>PKG_PATH="http://cdn.NetBSD.org/pub/pkgsrc/packages";</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>PKG_PATH="$PKG_PATH/<em class="replaceable"><code>OPSYS</code></em>/<em class="replaceable"><code>ARCH</code></em>/<em
class="replaceable"><code>VERSIONS</code></em>/All/"</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>export PATH PKG_PATH</code></strong>
</pre>
@@ -1360,7 +1356,8 @@
The pkgsrc Security Team and Packages Groups maintain a list of
known security vulnerabilities to packages which are (or have been)
included in pkgsrc. The list is available from the NetBSD
- FTP site at <a class="ulink" href="https://ftp.NetBSD.org/pub/NetBSD/packages/vulns/pkg-vulnerabilities"; target="_top">https://ftp.NetBSD.org/pub/NetBSD/packages/vulns/pkg-vulnerabilities</a>.
+
+ FTP site at <a class="ulink" href="http://ftp.NetBSD.org/pub/NetBSD/packages/vulns/pkg-vulnerabilities"; target="_top">http://ftp.NetBSD.org/pub/NetBSD/packages/vulns/pkg-vulnerabilities</a>.
</p>
<p>
Through <span class="command"><strong>pkg_admin fetch-pkg-vulnerabilities</strong></span>,
@@ -1381,7 +1378,8 @@
https://www.samba.org/samba/whatsnew/macroexploit.html</pre>
<p>
You may wish to have the
- <a class="ulink" href="https://ftp.NetBSD.org/pub/pkgsrc/distfiles/vulnerabilities"; target="_top">vulnerabilities</a>
+
+ <a class="ulink" href="http://ftp.NetBSD.org/pub/pkgsrc/distfiles/vulnerabilities"; target="_top">vulnerabilities</a>
file downloaded daily so that
it remains current. This may be done by adding an appropriate entry
to the root users <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?crontab+5.i386+NetBSD-9.0";><span class="citerefentry"><span
class="refentrytitle">crontab</span>(5)</span></a> entry. For example the entry
@@ -2093,18 +2091,15 @@
<dt><span class="sect1"><a href="#bulk.req">8.3. Requirements of a full bulk build</a></span></dt>
<dt><span class="sect1"><a href="#bulk.var">8.4. Bulk build variants</a></span></dt>
<dd><dl>
-<dt><span class="sect2"><a href="#bulk.var.subst_noop">8.4.1. Strict SUBST blocks</a></span></dt>
-<dt><span class="sect2"><a href="#bulk.var.confopt">8.4.2. Detect unknown configure options</a></span></dt>
-<dt><span class="sect2"><a href="#bulk.var.comperr">8.4.3. Detect classes of bugs by forcing compiler warnings</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>
-<dt><span class="sect2"><a href="#bulk.var.options">8.4.11. Select random sets of options</a></span></dt>
-<dt><span class="sect2"><a href="#bulk.var.build_defs">8.4.12. Select random configurations of BUILD_DEFS</a></span></dt>
+<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>
</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>
@@ -2238,37 +2233,7 @@
fail if they don't follow the pkgsrc style.</p>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="bulk.var.subst_noop"></a>8.4.1. Strict SUBST blocks</h3></div></div></div>
-<p>Up to May 2020, the SUBST blocks ignored files that didn't exist,
-as well as substitutions that didn't have any effect. There were quite a
-few SUBST blocks that were redundant, and these have been removed
-already.</p>
-<p>The next step would be to not only check that each filename pattern
-has an effect but also that each substitution in SUBST_SED or SUBST_VARS
-applies to at least one file.</p>
-<p>To do this, <code class="filename">mk/subst.mk</code> would have to be
-adjusted, in a similar way as the check for no-op SUBST_FILES. There are
-several regression tests in <code class="filename">regress/infra-unittests</code>
-that help to get all edge cases correct.</p>
-<p>When a package fails this additional check, there are various
-possible causes why the <code class="varname">SUBST_SED</code> became a
-no-op.</p>
-<div class="orderedlist"><ol class="orderedlist" type="1">
-<li class="listitem"><p>The pattern used to be found in a former version of the
-package, but is not needed anymore. In that case, just remove
-it.</p></li>
-<li class="listitem"><p>The pattern contains a typo. In that case, fix the typo
-and bump <code class="varname">PKGREVISION</code>, since the fixed typo will
-probably modify the resulting binary package.</p></li>
-<li class="listitem"><p>There is a patch that is applied before the SUBST block,
-and the patch accidentally contains the change that was intended for the
-SUBST block. In that case, remove the respective hunk from the
-patch.</p></li>
-</ol></div>
-</div>
-<div class="sect2">
-<div class="titlepage"><div><div><h3 class="title">
-<a name="bulk.var.confopt"></a>8.4.2. Detect unknown configure options</h3></div></div></div>
+<a name="bulk.var.confopt"></a>8.4.1. Detect unknown configure options</h3></div></div></div>
<p>Add the following line to <a class="link" href="#mk.conf"><code class="filename">mk.conf</code></a>.</p>
<pre class="programlisting">
GNU_CONFIGURE_STRICT= yes
@@ -2279,41 +2244,53 @@
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="bulk.var.comperr"></a>8.4.3. Detect classes of bugs by forcing compiler warnings</h3></div></div></div>
+<a name="bulk.var.comperr"></a>8.4.2. Detect classes of bugs by forcing compiler warnings</h3></div></div></div>
<p>The job of a compiler is not restricted to producing executable
-code, most compilers also detects typical mistakes.</p>
-<p>Add the following line to <a class="link" href="#mk.conf"><code class="filename">mk.conf</code></a>.</p>
+code, most compilers also detect typical programming mistakes. The pkgsrc
+compiler wrappers make it easy to force compiler options when the package
+is built. This can be used to find typical bugs across all packages that
+are in pkgsrc. By reporting these bugs upstream, the packages will be
+more reliable with the next updates.</p>
+<p>Add some of the following lines to <a class="link" href="#mk.conf"><code class="filename">mk.conf</code></a>:</p>
<pre class="programlisting">
CFLAGS+= -Werror=char-subscripts
-</pre>
-<p>When a package fails this additional check, first document the
-circumstances in which the compiler produced the error message. This
-includes:</p>
+CFLAGS+= -Werror=implicit-function-declaration
+</pre>
+<p>When a package fails to build using these stricter compiler
+options, document the circumstances in which the compiler produced the
+error message. This includes:</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>The platform
(<code class="varname">MACHINE_PLATFORM</code>)</p></li>
<li class="listitem"><p>The source file</p></li>
<li class="listitem"><p>An excerpt of the code. GCC and Clang already do this as
part of the diagnostic.</p></li>
-<li class="listitem"><p>The error message from the compiler.</p></li>
+<li class="listitem"><p>The exact error message from the compiler.</p></li>
</ul></div>
<p>If a package produces these error messages, but the package is
-fine, document this in the package Makefile, like this:</p>
-<pre class="programlisting">
+fine, record this in your local <a class="link" href="#mk.conf"><code class="filename">mk.conf</code></a>, like this, to skip this check
+in the next builds:</p>
+<pre class="programlisting">
+.if ${PKGPATH} == category/package
# Version ${VERSION} failed on ${MACHINE_PLATFORM}:
# error message
# code
-# reason why the code does not need to be fixed
+# Reason why the code does not need to be fixed.
BUILDLINK_TRANSFORM+= rm:-Werror=char-subscripts
+.endif
</pre>
<p>If the error messages from the compiler are valid and the code
-needs to be fixed, prepare a patch for a single source file, or if it's a
-one-liner fix, add a SUBST block to the package Makefile. In any case,
-report it to the upstream authors of the package.</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>
+needs to be fixed, prepare a local patch (see
+<code class="varname">LOCALPATCHES</code>) and report the bug to the upstream
+authors of the package, providing them with the information you collected
+above.</p>
+<p>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.</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>
<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
@@ -2329,7 +2306,7 @@
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="bulk.var.warn"></a>8.4.5. Turn warnings into errors</h3></div></div></div>
+<a name="bulk.var.warn"></a>8.4.4. 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>
@@ -2339,7 +2316,7 @@
</pre>
<p>(There are many more classes of warnings in pkgsrc, and most of
them can be redefined with a simple definition like above.</p>
-<p>If a package suggest to add <code class="varname">USE_TOOLS+=perl</code> to
+<p>If a package suggests to add <code class="varname">USE_TOOLS+=perl</code> to
the package Makefile, research whether the package actually needs Perl.
If it does, add <code class="varname">USE_TOOLS+=perl</code> to the package
Makefile, and if it doesn't, add
@@ -2347,7 +2324,7 @@
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="bulk.var.pkglint"></a>8.4.6. Reject packages for which pkglint reports errors</h3></div></div></div>
+<a name="bulk.var.pkglint"></a>8.4.5. 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
@@ -2355,7 +2332,7 @@
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="bulk.var.strings"></a>8.4.7. Reject packages that contain forbidden strings</h3></div></div></div>
+<a name="bulk.var.strings"></a>8.4.6. 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
@@ -2372,7 +2349,7 @@
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="bulk.var.test"></a>8.4.8. Reject packages whose self-test fails</h3></div></div></div>
+<a name="bulk.var.test"></a>8.4.7. 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">
@@ -2385,7 +2362,7 @@
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="bulk.var.shvar"></a>8.4.9. Reject packages that use undefined shell variables</h3></div></div></div>
+<a name="bulk.var.shvar"></a>8.4.8. 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
Home |
Main Index |
Thread Index |
Old Index