 @@ -1,14 +1,14 @@
-<!-- $NetBSD: fixes.xml,v 1.151 2020/01/28 05:07:58 rillig Exp $ -->
+<!-- $NetBSD: fixes.xml,v 1.152 2020/02/23 16:52:02 rillig Exp $ -->
 <chapter id="fixes"> <?dbhtml filename="fixes.html"?>
 <title>Making your package work</title>
 <sect1 id="general-operation">
   <title>General operation</title>
   <para>One appealing feature of pkgsrc is that it runs on many
   different platforms. As a result, it is important to ensure,
   where possible, that packages in pkgsrc are portable. This
   chapter mentions some particular details you should pay
   attention to while working on pkgsrc.</para>
 @@ -1339,26 +1339,135 @@ SunPro C++  __SUNPRO_CC (0x580 for Sun C
 	<para>Typically, a workaround involves testing the
         <varname>MACHINE_ARCH</varname> and compiler version, disabling
         optimisation for that combination of file,
 	<varname>MACHINE_ARCH</varname> and compiler.</para>
 	<para>This used to be a big problem in the past, but is rarely
 	needed now as compiler technology has matured. If you still need
 	to add a compiler specific workaround, please do so in the file
 	<filename>hacks.mk</filename> and describe the symptom and
 	compiler version as detailed as possible.</para>
 </sect2>
 <sect2 id="fixes.build.header">
 <title>No such file or directory</title>
 <para>Compilation sometimes fails with an error message like this:</para>
 <programlisting>
 .../x11/gtk3/work/gtk+-3.24.12/gdk/gdktypes.h:35:10:
     fatal error: pango/pango.h: No such file or directory
 </programlisting>
 <para>The proper way to fix this problem depends on the type of the
 header, which is described in the following sections.</para>
 <sect3 id="fixes.build.header.bl3">
 <title>Headers from other packages</title>
 <para>If the header name looks like it comes from a different package,
 that other package should be included via the buildlink3
 framework.</para>
 <para>First, look whether the header is somewhere in the buildlink3
 directory below <varname>WRKDIR</varname>. In the above case of
 the missing Pango header:</para>
 <programlisting>
 &uprompt; find work/.buildlink/ -print | grep -F pango/pango.h
 </programlisting>
 <para>In the case of Pango, the output is:</para>
 <programlisting>
 work/.buildlink/include/pango-1.0/pango/pango.h
 </programlisting>
 <para>If the <filename>pango/pango.h</filename> file were placed directly
 in the <filename>.buildlink</filename> directory, it would have been
 found automatically. There is an extra <filename>pango-1.0</filename>
 path component though, which means that the compiler command line must
 contain an option of the form
 <literal>-I${BUILDLINK3_PREFIX.pango}/include/pango-1.0</literal>. In
 most cases this option is generated by the configure script, which can be examined using:</para>
 <programlisting>
 &uprompt; $ grep -o '[-]I[^[:space:]]*/pango[^[:space:]]*' work/*/Makefile
 -I/usr/pkg/include/pango-1.0
 -I/usr/pkg/include/pango-1.0
 -I/usr/pkg/include/pango-1.0
 -I/usr/pkg/include/pango-1.0
 -I/usr/pkg/include/pango-1.0
 </programlisting>
 <para>This looks good. These options are transformed by the buildlink
 wrapper to refer to the correct path inside
 <filename>work/.buildlink</filename>.</para>
 <para>Since the compilation fails though, examine the compiler command
 lines in <filename>work/.work.log</filename> to see whether the
 <literal>-I</literal> option is included in the particular command
 line.</para>
 <para>To further analyze the situation, run <command>bmake
 build-env</command>, which sets up an interactive, realistic environment
 including all the pkgsrc wrapper commands and environment variables. From
 there, try to compile some simple example programs that use the
 header.</para>
 </sect3>
 <sect3 id="fixes.build.header.gen">
 <title>Headers generated during the build</title>
 <para>If the name of the header seems to come from the package itself,
 and if the build is run with parallel jobs, the package may have some
 undeclared dependencies between the <filename>.c</filename> and the
 <filename>.h</filename> files, and a C file is compiled before its
 required header is generated.</para>
 <para>To see whether the build runs with parallel jobs, run
 <command>bmake show-all-build | grep JOBS</command>. Its output looks
 like this:</para>
 <programlisting>
   usr   MAKE_JOBS=              7
   pkg   MAKE_JOBS_SAFE          # undefined
   def   _MAKE_JOBS_N=           7
 </programlisting>
 <para>In this case the pkgsrc user has asked pkgsrc to build packages
 with 7 jobs in parallel (<varname>MAKE_JOBS</varname>). The
 package could have disabled parallel builds by setting
 <varname>MAKE_JOBS_SAFE</varname> to <literal>no</literal>, but
 in this case it hasn't.</para>
 <para>To see whether the build failure is caused by parallel builds,
 first save the exact error message and a bit of context, maybe you need
 it later for reporting a bug. Next, run:</para>
 <programlisting>
 MAKE_JOBS_SAFE=no bmake clean build
 </programlisting>
 <para>If that succeeds, <ulink
 url="https://www.NetBSD.org/cgi-bin/sendpr.cgi?gndb=netbsd">file a bug
 report</ulink> against the pkgsrc package, including the exact error
 message and the contents of your &mk.conf; file.</para>
 </sect3>
 </sect2>
 <sect2 id="undefined-reference">
 <title>Undefined reference to <quote>...</quote></title>
 	<para>This error message often means that a package did not
 	link to a shared library it needs. The following functions are
 	known to cause this error message over and over.</para>
     <informaltable id="undefined-reference-functions">
       <tgroup cols="3">
 	<thead><row><entry>Function</entry><entry>Library</entry><entry>Affected platforms</entry></row></thead>
 	<tbody>
 	  <row><entry>accept, bind, connect</entry><entry>-lsocket</entry><entry>Solaris</entry></row>
 	  <row><entry>crypt</entry><entry>-lcrypt</entry><entry>DragonFly, NetBSD</entry></row>