pkgsrc-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/710d421fb14f
branches: trunk
changeset: 411911:710d421fb14f
user: rillig <rillig%pkgsrc.org@localhost>
date: Sun Feb 23 16:53:07 2020 +0000
description:
doc/pkgsrc.*: regen
diffstat:
doc/pkgsrc.html | 2186 ++++++++++++++++++++++++++++--------------------------
doc/pkgsrc.txt | 1521 ++++++++++++++++++++-----------------
2 files changed, 1965 insertions(+), 1742 deletions(-)
diffs (truncated from 4980 to 300 lines):
diff -r dbac7250a89b -r 710d421fb14f doc/pkgsrc.html
--- a/doc/pkgsrc.html Sun Feb 23 16:52:02 2020 +0000
+++ b/doc/pkgsrc.html Sun Feb 23 16:53:07 2020 +0000
@@ -333,8 +333,9 @@
<dd><dl>
<dt><span class="sect2"><a href="#fixes.build.cpp">21.5.1. Compiling C and C++ code conditionally</a></span></dt>
<dt><span class="sect2"><a href="#compiler-bugs">21.5.2. How to handle compiler bugs</a></span></dt>
-<dt><span class="sect2"><a href="#undefined-reference">21.5.3. Undefined reference to <span class="quote">“<span class="quote">...</span>”</span></a></span></dt>
-<dt><span class="sect2"><a href="#out-of-memory">21.5.4. Running out of memory</a></span></dt>
+<dt><span class="sect2"><a href="#fixes.build.header">21.5.3. No such file or directory</a></span></dt>
+<dt><span class="sect2"><a href="#undefined-reference">21.5.4. Undefined reference to <span class="quote">“<span class="quote">...</span>”</span></a></span></dt>
+<dt><span class="sect2"><a href="#out-of-memory">21.5.5. Running out of memory</a></span></dt>
</dl></dd>
<dt><span class="sect1"><a href="#fixes.install">21.6. The <span class="emphasis"><em>install</em></span> phase</a></span></dt>
<dd><dl>
@@ -425,7 +426,7 @@
<dt><span class="sect2"><a href="#example-Makefile">A.1.1. Makefile</a></span></dt>
<dt><span class="sect2"><a href="#example-descr">A.1.2. DESCR</a></span></dt>
<dt><span class="sect2"><a href="#example-plist">A.1.3. PLIST</a></span></dt>
-<dt><span class="sect2"><a href="#checking-package-with-pkglint">A.1.4. Checking a package with <span class="command"><strong>pkglint</strong></span></a></span></dt>
+<dt><span class="sect2"><a href="#checking-package-with-pkglint">A.1.4. Checking a package with pkglint</a></span></dt>
</dl></dd>
<dt><span class="sect1"><a href="#steps-for-b-i-p">A.2. Steps for building, installing, packaging</a></span></dt>
</dl></dd>
@@ -2754,6 +2755,22 @@
programmers write so bad code that it only works for the
specific combination of <code class="varname">CFLAGS</code> they have
chosen.</p>
+<p>To find out where the CFLAGS are ignored, add the following lines to <a class="link" href="#mk.conf"><code class="filename">mk.conf</code></a>:</p>
+<pre class="programlisting">
+CPPFLAGS+= -Dpkgsrc___CPPFLAGS
+CFLAGS+= -Dpkgsrc___CFLAGS
+CXXFLAGS+= -Dpkgsrc___CXXFLAGS
+</pre>
+<p>Then run <span class="command"><strong>bmake show-all-configure show-all-build</strong></span>
+to see whether the above flags are passed to the actual build
+commands in general.</p>
+<p>To find out whether the flags are passed to individual compiler
+commands, have a look at the file <code class="filename">work/.work.log</code>. In
+most cases, the flags from the original command lines (the lines starting
+with <code class="literal">[*]</code>) are passed unmodified to the actual compiler
+(the lines starting with <code class="literal"><.></code>). If the flag is
+missing from the actual compiler command, it must have been removed by
+the <a class="link" href="#build.wrapper" title="19.10. The wrapper phase">pkgsrc compiler wrappers</a>.</p>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
@@ -2982,8 +2999,9 @@
<dd><dl>
<dt><span class="sect2"><a href="#fixes.build.cpp">21.5.1. Compiling C and C++ code conditionally</a></span></dt>
<dt><span class="sect2"><a href="#compiler-bugs">21.5.2. How to handle compiler bugs</a></span></dt>
-<dt><span class="sect2"><a href="#undefined-reference">21.5.3. Undefined reference to <span class="quote">“<span class="quote">...</span>”</span></a></span></dt>
-<dt><span class="sect2"><a href="#out-of-memory">21.5.4. Running out of memory</a></span></dt>
+<dt><span class="sect2"><a href="#fixes.build.header">21.5.3. No such file or directory</a></span></dt>
+<dt><span class="sect2"><a href="#undefined-reference">21.5.4. Undefined reference to <span class="quote">“<span class="quote">...</span>”</span></a></span></dt>
+<dt><span class="sect2"><a href="#out-of-memory">21.5.5. Running out of memory</a></span></dt>
</dl></dd>
<dt><span class="sect1"><a href="#fixes.install">21.6. The <span class="emphasis"><em>install</em></span> phase</a></span></dt>
<dd><dl>
@@ -4126,13 +4144,10 @@
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="files-dir"></a>13.7. <code class="filename">files/*</code>
</h2></div></div></div>
-<p>If you have any files that you wish to be placed in the package prior
- to configuration or building, you could place these files here and use
- a <span class="command"><strong>${CP}</strong></span> command in the
- <span class="quote">“<span class="quote">pre-configure</span>”</span> target to achieve
- this. Alternatively, you could simply diff the file against
- <code class="filename">/dev/null</code> and use the patch mechanism to manage
- the creation of this file.</p>
+<p>If you have any files that you wish to be placed in the package
+ prior to configuration or building, you can place these files here
+ and use a <span class="command"><strong>${CP}</strong></span> command in the
+ <span class="quote">“<span class="quote">post-extract</span>”</span> target to achieve this.</p>
<p>If you want to share files in this way with other
packages, set the <code class="varname">FILESDIR</code> variable to point
to the other package's <code class="filename">files</code> directory,
@@ -6909,8 +6924,9 @@
<dd><dl>
<dt><span class="sect2"><a href="#fixes.build.cpp">21.5.1. Compiling C and C++ code conditionally</a></span></dt>
<dt><span class="sect2"><a href="#compiler-bugs">21.5.2. How to handle compiler bugs</a></span></dt>
-<dt><span class="sect2"><a href="#undefined-reference">21.5.3. Undefined reference to <span class="quote">“<span class="quote">...</span>”</span></a></span></dt>
-<dt><span class="sect2"><a href="#out-of-memory">21.5.4. Running out of memory</a></span></dt>
+<dt><span class="sect2"><a href="#fixes.build.header">21.5.3. No such file or directory</a></span></dt>
+<dt><span class="sect2"><a href="#undefined-reference">21.5.4. Undefined reference to <span class="quote">“<span class="quote">...</span>”</span></a></span></dt>
+<dt><span class="sect2"><a href="#out-of-memory">21.5.5. Running out of memory</a></span></dt>
</dl></dd>
<dt><span class="sect1"><a href="#fixes.install">21.6. The <span class="emphasis"><em>install</em></span> phase</a></span></dt>
<dd><dl>
@@ -7460,7 +7476,17 @@
or when the replacement text varies, patches alone cannot help.
This is where the SUBST framework comes in. It provides an
easy-to-use interface for replacing text in files.
- Example:</p>
+ It just needs the following information:</p>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
+<li class="listitem"><p><span class="emphasis"><em>When</em></span> should the replacement
+happen?</p></li>
+<li class="listitem"><p><span class="emphasis"><em>Where</em></span> should the replacement happen,
+i.e. in which files?</p></li>
+<li class="listitem"><p><span class="emphasis"><em>Which</em></span> text should be
+replaced with what?</p></li>
+</ul></div>
+<p>This information is encoded in a block of <code class="varname">SUBST</code>
+variables, like in this example:</p>
<pre class="programlisting">
SUBST_CLASSES+= fix-paths
SUBST_STAGE.fix-paths= pre-configure
@@ -7474,8 +7500,7 @@
that are used to identify the different SUBST blocks that are
defined. The SUBST framework is heavily used by pkgsrc, so it is
important to always use the <code class="literal">+=</code> operator with
- this variable. Otherwise some substitutions may be
- skipped.</p>
+ this variable. Otherwise some substitutions may be skipped.</p>
<p>The remaining variables of each SUBST block are
parameterized with the identifier from the first line
(<code class="literal">fix-paths</code> in this case.) They can be seen as
@@ -7508,6 +7533,10 @@
<a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?sed+1.i386+NetBSD-8.1";><span class="citerefentry"><span class="refentrytitle">sed</span>(1)</span></a> that specify the actual
substitution. Every sed
command should be prefixed with <code class="literal">-e</code>, so that
all SUBST blocks look uniform.</p>
+<p><code class="varname">SUBST_VARS.*</code> is a list of variable names.
+ For each of these variables, the text <code class="literal">@VAR@</code> is
+ replaced with the value of the variable
+ <code class="varname">VAR</code>.</p>
<p>There are some more variables, but they are so seldomly
used that they are only documented in the
<code class="filename">mk/subst.mk</code> file.</p>
@@ -8027,7 +8056,93 @@
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="undefined-reference"></a>21.5.3. Undefined reference to <span class="quote">“<span class="quote">...</span>”</span>
+<a name="fixes.build.header"></a>21.5.3. No such file or directory</h3></div></div></div>
+<p>Compilation sometimes fails with an error message like this:</p>
+<pre class="programlisting">
+.../x11/gtk3/work/gtk+-3.24.12/gdk/gdktypes.h:35:10:
+ fatal error: pango/pango.h: No such file or directory
+</pre>
+<p>The proper way to fix this problem depends on the type of the
+header, which is described in the following sections.</p>
+<div class="sect3">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="fixes.build.header.bl3"></a>21.5.3.1. Headers from other packages</h4></div></div></div>
+<p>If the header name looks like it comes from a different package,
+that other package should be included via the buildlink3
+framework.</p>
+<p>First, look whether the header is somewhere in the buildlink3
+directory below <code class="varname">WRKDIR</code>. In the above case of
+the missing Pango header:</p>
+<pre class="programlisting">
+<code class="prompt">$</code> find work/.buildlink/ -print | grep -F pango/pango.h
+</pre>
+<p>In the case of Pango, the output is:</p>
+<pre class="programlisting">
+work/.buildlink/include/pango-1.0/pango/pango.h
+</pre>
+<p>If the <code class="filename">pango/pango.h</code> file were placed directly
+in the <code class="filename">.buildlink</code> directory, it would have been
+found automatically. There is an extra <code class="filename">pango-1.0</code>
+path component though, which means that the compiler command line must
+contain an option of the form
+<code class="literal">-I${BUILDLINK3_PREFIX.pango}/include/pango-1.0</code>. In
+most cases this option is generated by the configure script, which can be examined using:</p>
+<pre class="programlisting">
+<code class="prompt">$</code> $ 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
+</pre>
+<p>This looks good. These options are transformed by the buildlink
+wrapper to refer to the correct path inside
+<code class="filename">work/.buildlink</code>.</p>
+<p>Since the compilation fails though, examine the compiler command
+lines in <code class="filename">work/.work.log</code> to see whether the
+<code class="literal">-I</code> option is included in the particular command
+line.</p>
+<p>To further analyze the situation, run <span class="command"><strong>bmake
+build-env</strong></span>, 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.</p>
+</div>
+<div class="sect3">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="fixes.build.header.gen"></a>21.5.3.2. Headers generated during the build</h4></div></div></div>
+<p>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 <code class="filename">.c</code> and the
+<code class="filename">.h</code> files, and a C file is compiled before its
+required header is generated.</p>
+<p>To see whether the build runs with parallel jobs, run
+<span class="command"><strong>bmake show-all-build | grep JOBS</strong></span>. Its output looks
+like this:</p>
+<pre class="programlisting">
+ usr MAKE_JOBS= 7
+ pkg MAKE_JOBS_SAFE # undefined
+ def _MAKE_JOBS_N= 7
+</pre>
+<p>In this case the pkgsrc user has asked pkgsrc to build packages
+with 7 jobs in parallel (<code class="varname">MAKE_JOBS</code>). The
+package could have disabled parallel builds by setting
+<code class="varname">MAKE_JOBS_SAFE</code> to <code class="literal">no</code>, but
+in this case it hasn't.</p>
+<p>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:</p>
+<pre class="programlisting">
+MAKE_JOBS_SAFE=no bmake clean build
+</pre>
+<p>If that succeeds, <a class="ulink" href="https://www.NetBSD.org/cgi-bin/sendpr.cgi?gndb=netbsd"; target="_top">file a bug
+report</a> against the pkgsrc package, including the exact error
+message and the contents of your <a class="link" href="#mk.conf"><code class="filename">mk.conf</code></a> file.</p>
+</div>
+</div>
+<div class="sect2">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="undefined-reference"></a>21.5.4. Undefined reference to <span class="quote">“<span class="quote">...</span>”</span>
</h3></div></div></div>
<p>This error message often means that a package did not
link to a shared library it needs. The following functions are
@@ -8090,7 +8205,7 @@
bmake</strong></span>.</p>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
-<a name="undefined-reference-sunpro"></a>21.5.3.1. Special issue: The SunPro compiler</h4></div></div></div>
+<a name="undefined-reference-sunpro"></a>21.5.4.1. Special issue: The SunPro compiler</h4></div></div></div>
<p>When you are using the SunPro compiler, there is another
possibility. That compiler cannot handle the following code:</p>
<pre class="programlisting">
@@ -8116,7 +8231,7 @@
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
-<a name="out-of-memory"></a>21.5.4. Running out of memory</h3></div></div></div>
+<a name="out-of-memory"></a>21.5.5. Running out of memory</h3></div></div></div>
<p>Sometimes packages fail to build because the compiler runs
into an operating system specific soft limit. With the
<code class="varname">UNLIMIT_RESOURCES</code> variable pkgsrc can be told
@@ -9044,7 +9159,7 @@
and if you still don't have the answer, ask on the
<code class="literal">pkgsrc-users</code> mailing list.</p>
<div class="qandaset">
-<a name="idm79478288"></a><dl>
+<a name="idm79431952"></a><dl>
<dt>24.1. <a href="#devfaq.makeflags">What is the difference between
MAKEFLAGS, .MAKEFLAGS and
MAKE_FLAGS?</a>
@@ -9089,7 +9204,7 @@
<tbody>
<tr class="question">
<td align="left" valign="top">
-<a name="devfaq.makeflags"></a><a name="idm79477904"></a><p><b>24.1.</b></p>
+<a name="devfaq.makeflags"></a><a name="idm79431568"></a><p><b>24.1.</b></p>
</td>
<td align="left" valign="top"><p>What is the difference between
<code class="varname">MAKEFLAGS</code>, <code class="varname">.MAKEFLAGS</code> and
@@ -9105,7 +9220,7 @@
</tr>
<tr class="question">
<td align="left" valign="top">
-<a name="devfaq.make"></a><a name="idm79473936"></a><p><b>24.2.</b></p>
+<a name="devfaq.make"></a><a name="idm79427600"></a><p><b>24.2.</b></p>
</td>
<td align="left" valign="top"><p>What is the difference between
<code class="varname">MAKE</code>, <code class="varname">GMAKE</code> and
@@ -9123,7 +9238,7 @@
</tr>
<tr class="question">
<td align="left" valign="top">
-<a name="devfaq.cc"></a><a name="idm79469456"></a><p><b>24.3.</b></p>
+<a name="devfaq.cc"></a><a name="idm79423120"></a><p><b>24.3.</b></p>
</td>
<td align="left" valign="top"><p>What is the difference between
<code class="varname">CC</code>, <code class="varname">PKG_CC</code> and
@@ -9141,7 +9256,7 @@
</tr>
<tr class="question">
<td align="left" valign="top">
-<a name="devfaq.bl3flags"></a><a name="idm79465360"></a><p><b>24.4.</b></p>
+<a name="devfaq.bl3flags"></a><a name="idm79419024"></a><p><b>24.4.</b></p>
</td>
<td align="left" valign="top"><p>What is the difference between
<code class="varname">BUILDLINK_LDFLAGS</code>,
@@ -9154,7 +9269,7 @@
</tr>
<tr class="question">
<td align="left" valign="top">
-<a name="devfaq.bl3prefix"></a><a name="idm79463184"></a><p><b>24.5.</b></p>
+<a name="devfaq.bl3prefix"></a><a name="idm79416720"></a><p><b>24.5.</b></p>
</td>
<td align="left" valign="top"><p>Why does <span class="command"><strong>make show-var
VARNAME=BUILDLINK_PREFIX.<em class="replaceable"><code>foo</code></em></strong></span>
@@ -9170,7 +9285,7 @@
</tr>
<tr class="question">
<td align="left" valign="top">
Home |
Main Index |
Thread Index |
Old Index