CVS commit: pkgsrc/doc/guide/files

["Roland Illig" <rillig%netbsd.org@localhost>]

Module Name:    pkgsrc
Committed By:   rillig
Date:           Sat May 30 19:25:18 UTC 2020

Modified Files:
        pkgsrc/doc/guide/files: bulk.xml

Log Message:
doc/guide: hide bulk build variants that are not yet ready

https://mail-index.netbsd.org/tech-pkg/2020/05/30/msg023273.html


To generate a diff of this commit:
cvs rdiff -u -r1.29 -r1.30 pkgsrc/doc/guide/files/bulk.xml

Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.

Modified files:

Index: pkgsrc/doc/guide/files/bulk.xml
diff -u pkgsrc/doc/guide/files/bulk.xml:1.29 pkgsrc/doc/guide/files/bulk.xml:1.30
--- pkgsrc/doc/guide/files/bulk.xml:1.29        Sat May 30 08:22:59 2020
+++ pkgsrc/doc/guide/files/bulk.xml     Sat May 30 19:25:17 2020
@@ -1,4 +1,4 @@
-<!-- $NetBSD: bulk.xml,v 1.29 2020/05/30 08:22:59 rillig Exp $ -->
+<!-- $NetBSD: bulk.xml,v 1.30 2020/05/30 19:25:17 rillig Exp $ -->
 
 <chapter id="bulk">
 <title>Creating binary packages for everything in pkgsrc (bulk
@@ -198,6 +198,10 @@ makes sense to run non-default bulk buil
 section lists some ideas for bulk builds that intentionally let packages
 fail if they don't follow the pkgsrc style.</para>
 
+<!--
+Needs to be implemented first, so that the remaining work is just
+setting a variable in mk.conf, like in the other scenarios.
+
 <sect2 id="bulk.var.subst_noop">
 <title>Strict SUBST blocks</title>
 
@@ -217,7 +221,7 @@ that help to get all edge cases correct.
 
 <para>When a package fails this additional check, there are various
 possible causes why the <varname>SUBST_SED</varname> became a
-no-op.</para>
+no-op:</para>
 
 <orderedlist>
 
@@ -237,6 +241,7 @@ patch.</para></listitem>
 </orderedlist>
 
 </sect2>
+-->
 
 <sect2 id="bulk.var.confopt">
 <title>Detect unknown configure options</title>
@@ -257,17 +262,22 @@ package but does not apply anymore. In t
 <title>Detect classes of bugs by forcing compiler warnings</title>
 
 <para>The job of a compiler is not restricted to producing executable
-code, most compilers also detects typical mistakes.</para>
+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.</para>
 
-<para>Add the following line to &mk.conf;.</para>
+<para>Add some of the following lines to &mk.conf;:</para>
 
 <programlisting>
 CFLAGS+=        -Werror=char-subscripts
+CFLAGS+=        -Werror=implicit-function-declaration
 </programlisting>
 
-<para>When a package fails this additional check, first document the
-circumstances in which the compiler produced the error message. This
-includes:</para>
+<para>When a package fails to build using these stricter compiler
+options, document the circumstances in which the compiler produced the
+error message. This includes:</para>
 
 <itemizedlist>
 
@@ -279,25 +289,33 @@ includes:</para>
 <listitem><para>An excerpt of the code. GCC and Clang already do this as
 part of the diagnostic.</para></listitem>
 
-<listitem><para>The error message from the compiler.</para></listitem>
+<listitem><para>The exact error message from the compiler.</para></listitem>
 
 </itemizedlist>
 
 <para>If a package produces these error messages, but the package is
-fine, document this in the package Makefile, like this:</para>
+fine, record this in your local &mk.conf;, like this, to skip this check
+in the next builds:</para>
 
 <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
 </programlisting>
 
 <para>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.</para>
+needs to be fixed, prepare a local patch (see
+<varname>LOCALPATCHES</varname>) and report the bug to the upstream
+authors of the package, providing them with the information you collected
+above.</para>
+
+<para>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.</para>
 
 </sect2>
 
@@ -426,6 +444,10 @@ different.</para>
 
 </sect2>
 
+<!--
+Needs to be implemented first, so that the remaining work is just
+setting a variable in mk.conf, like in the other scenarios.
+
 <sect2 id="bulk.var.options">
 <title>Select random sets of options</title>
 
@@ -465,6 +487,10 @@ per-package</para></listitem>
 </itemizedlist>
 
 </sect2>
+-->
+
+<!--
+Refers to bulk.var.options, which is not yet implemented.
 
 <sect2 id="bulk.var.build_defs">
 <title>Select random configurations of BUILD_DEFS</title>
@@ -475,6 +501,7 @@ be created. The same ideas as in <xref l
 apply.</para>
 
 </sect2>
+-->
 
 </sect1>