doc/guide: explain how to analyze and fix "No such file or directory"

https://mail-index.netbsd.org/pkgsrc-users/2020/02/23/msg030520.html

1 files changed, 110 insertions, 1 deletions

diff --git a/doc/guide/files/fixes.xml b/doc/guide/files/fixes.xml
index c17253c0e88..ada53cdad11 100644
--- a/doc/guide/files/fixes.xml
+++ b/doc/guide/files/fixes.xml
@@ -1,4 +1,4 @@
-<!-- $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>
@@ -1349,6 +1349,115 @@ SunPro C++  __SUNPRO_CC (0x580 for Sun C++ 5.8)
 
 </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>