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/f35c466a298a
branches: trunk
changeset: 433587:f35c466a298a
user: rillig <rillig%pkgsrc.org@localhost>
date: Fri Jun 05 07:34:49 2020 +0000
description:
doc/pkgsrc.*: regen
diffstat:
doc/pkgsrc.html | 2933 ++++++++++++++++++++++++++++--------------------------
doc/pkgsrc.txt | 1694 +++++++++++++++++--------------
2 files changed, 2455 insertions(+), 2172 deletions(-)
diffs (truncated from 6057 to 300 lines):
diff -r 2c6f4ffb69b9 -r f35c466a298a doc/pkgsrc.html
--- a/doc/pkgsrc.html Fri Jun 05 07:34:17 2020 +0000
+++ b/doc/pkgsrc.html Fri Jun 05 07:34:49 2020 +0000
@@ -121,7 +121,7 @@
builds)</a></span></dt>
<dd><dl>
<dt><span class="sect1"><a href="#bulk.pre">8.1. Preparations</a></span></dt>
-<dt><span class="sect1"><a href="#bulk.pbulk">8.2. Running a pbulk-style bulk build</a></span></dt>
+<dt><span class="sect1"><a href="#bulk.pbulk">8.2. Running a bulk build</a></span></dt>
<dd><dl><dt><span class="sect2"><a href="#bulk.pbulk.conf">8.2.1. Configuration</a></span></dt></dl></dd>
<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>
@@ -878,7 +878,7 @@
builds)</a></span></dt>
<dd><dl>
<dt><span class="sect1"><a href="#bulk.pre">8.1. Preparations</a></span></dt>
-<dt><span class="sect1"><a href="#bulk.pbulk">8.2. Running a pbulk-style bulk build</a></span></dt>
+<dt><span class="sect1"><a href="#bulk.pbulk">8.2. Running a bulk build</a></span></dt>
<dd><dl><dt><span class="sect2"><a href="#bulk.pbulk.conf">8.2.1. Configuration</a></span></dt></dl></dd>
<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>
@@ -2086,7 +2086,7 @@
<p><b>Table of Contents</b></p>
<dl class="toc">
<dt><span class="sect1"><a href="#bulk.pre">8.1. Preparations</a></span></dt>
-<dt><span class="sect1"><a href="#bulk.pbulk">8.2. Running a pbulk-style bulk build</a></span></dt>
+<dt><span class="sect1"><a href="#bulk.pbulk">8.2. Running a bulk build</a></span></dt>
<dd><dl><dt><span class="sect2"><a href="#bulk.pbulk.conf">8.2.1. Configuration</a></span></dt></dl></dd>
<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>
@@ -2141,8 +2141,8 @@
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
-<a name="bulk.pbulk"></a>8.2. Running a pbulk-style bulk build</h2></div></div></div>
-<p>Running a pbulk-style bulk build works roughly as follows:</p>
+<a name="bulk.pbulk"></a>8.2. Running a bulk build</h2></div></div></div>
+<p>Running a bulk build works roughly as follows:</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>First, build the pbulk infrastructure in a fresh pkgsrc location.</p></li>
<li class="listitem"><p>Then, build each of the packages from a clean installation directory using the infrastructure.</p></li>
@@ -6373,12 +6373,10 @@
<code class="filename">.rej</code> are ignored. Any special options to
<a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?patch+1.i386+NetBSD-9.0";><span class="citerefentry"><span class="refentrytitle">patch</span>(1)</span></a> can be handed in
<code class="varname">PATCH_DIST_ARGS</code>. See <a class="xref" href="#components.patches" title="13.3. patches/*">Section 13.3, “<code class="filename">patches/*</code>”</a> for
more details.</p>
-<p>By default <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?patch+1.i386+NetBSD-9.0";><span class="citerefentry"><span class="refentrytitle">patch</span>(1)</span></a> is given
special args to make
- it fail if the patches apply with some lines of fuzz. Please
- fix (regen) the patches so that they apply cleanly. The
- rationale behind this is that patches that don't apply cleanly
- may end up being applied in the wrong place, and cause severe
- harm there.</p>
+<p>By default <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?patch+1.i386+NetBSD-9.0";><span class="citerefentry"><span class="refentrytitle">patch</span>(1)</span></a> is given
special arguments to make it
+ fail if the expected text from the patch context is not found in the
+ patched file. If that happens, fix the patch file by comparing it
+ with the actual text in the file to be patched.</p>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
@@ -7680,74 +7678,221 @@
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="fixes.subst"></a>21.1.11. Substituting variable text in the package files (the SUBST framework)</h3></div></div></div>
-<p>When you want to replace the same text in multiple files
- 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.
- It just needs the following information:</p>
+<p>When you want to replace the same text in multiple files, or
+multiple times in the same file, it is cumbersome to maintain a patch
+file for this. This is where the SUBST framework steps in. It provides an
+easy-to-use interface for replacing text in files. 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
+<li class="listitem"><p>In which phase of the package build cycle should the
+replacement happen?</p></li>
+<li class="listitem"><p>In which files 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>
+<li class="listitem"><p>Which 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
-SUBST_MESSAGE.fix-paths= Fixing absolute paths.
-SUBST_FILES.fix-paths= src/*.c
-SUBST_FILES.fix-paths+= scripts/*.sh
-SUBST_SED.fix-paths= -e 's,"/usr/local,"${PREFIX},g'
-SUBST_SED.fix-paths+= -e 's,"/var/log,"${VARBASE}/log,g'
-</pre>
-<p><code class="varname">SUBST_CLASSES</code> is a list of identifiers
- 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>
-<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
- parameters to a function call.</p>
-<p><code class="varname">SUBST_STAGE.*</code> specifies the stage at
- which the replacement will take place. All combinations of
- <code class="literal">pre-</code>, <code class="literal">do-</code> and
- <code class="literal">post-</code> together with a phase name are
- possible, though only few are actually used. Most commonly used
- are <code class="literal">post-patch</code> and
- <code class="literal">pre-configure</code>. Of these two,
- <code class="literal">pre-configure</code> should be preferred because
- then it is possible to run <span class="command"><strong>bmake patch</strong></span> and
- have the state after applying the patches but before making any
- other changes. This is especially useful when you are debugging
- a package in order to create new patches for it. Similarly,
- <code class="literal">post-build</code> is preferred over
- <code class="literal">pre-install</code>, because the install phase should
- generally be kept as simple as possible. When you use
- <code class="literal">post-build</code>, you have the same files in the
- working directory that will be installed later, so you can check
- if the substitution has succeeded.</p>
-<p><code class="varname">SUBST_MESSAGE.*</code> is an optional text
- that is printed just before the substitution is done.</p>
-<p><code class="varname">SUBST_FILES.*</code> is the list of shell
- globbing patterns that specifies the files in which the
- substitution will take place. The patterns are interpreted
- relatively to the <code class="varname">WRKSRC</code> directory.</p>
-<p><code class="varname">SUBST_SED.*</code> is a list of arguments to
- <a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?sed+1.i386+NetBSD-9.0";><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>
+variables. A minimal example is:</p>
+<pre class="programlisting">
+SUBST_CLASSES+= paths
+SUBST_STAGE.paths= pre-configure
+SUBST_FILES.paths= src/*.c
+SUBST_SED.paths= -e 's,/usr/local,${PREFIX},g'
+</pre>
+<p>Translated into English, it means: In the pre-configure stage (that
+is, after applying the patches from the patches/ directory and before
+running the configure script and the portability check), replace the text
+<code class="literal">/usr/local</code> with the content of the variable
+<code class="varname">PREFIX</code>.</p>
+<p>Each SUBST block starts by appending an identifier to
+<code class="varname">SUBST_CLASSES</code> (note the <code class="literal">+=</code>). This
+identifier can be chosen freely by the package. If there should ever be
+duplicate identifiers, the pkgsrc infrastructure will catch this and fail
+early, so don't worry about name collisions.</p>
+<p>Except for <code class="varname">SUBST_CLASSES</code>, all variables in a
+SUBST block are parameterized using this identifier. In the remainder of
+this section, these parameterized variables are written as
+<code class="varname">SUBST_STAGE.*</code>.</p>
+<pre class="programlisting">
+SUBST_CLASSES+= paths
+SUBST_STAGE.paths= pre-configure
+SUBST_MESSAGE.paths= Fixing absolute paths.
+SUBST_FILES.paths= src/*.c
+SUBST_FILES.paths+= scripts/*.sh
+SUBST_SED.paths= -e 's,"/usr/local,"${PREFIX},g'
+SUBST_SED.paths+= -e 's,"/var/log,"${VARBASE}/log,g'
+SUBST_VARS.paths= LOCALBASE PREFIX PKGVERSION
+</pre>
+<p>To get a complete picture about the SUBST substitutions, run
+<span class="command"><strong>bmake show-all-subst</strong></span>. If something doesn't work as
+expected, run pkglint on the package, which detects several typical
+mistakes surrounding the SUBST blocks. For any questions that might
+remain after this, have a look at
+<code class="filename">mk/subst.mk</code>.</p>
+<div class="sect3">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="fixes.subst.when"></a>21.1.11.1. Choosing the time where the substitutions happen</h4></div></div></div>
+<p>The <code class="varname">SUBST_STAGE.*</code> is one of
+{pre,do,post}-{extract,patch,configure,build,test,install}. Of these,
+<code class="literal">pre-configure</code> is used most often, by far. The most
+popular stages are, in chronological order:</p>
+<div class="variablelist"><dl class="variablelist">
+<dt><span class="term"><code class="literal">post-extract</code></span></dt>
+<dd>
+<p>The substitutions are applied immediately after the
+distfiles are extracted. Running <span class="command"><strong>bmake extract</strong></span> on the
+package will leave no traces of the original files.</p>
+<p>When the substitution applies to files for which there is also a
+patch in the <code class="filename">patches/</code> directory, this means that the
+patches will be computed based on the result of the substitution. When
+these patches are sent to the upstream maintainer later, to be fixed in
+the upstream package, these patches may no longer match what the upstream
+author is used to. Because of this, <code class="literal">pre-configure</code> is
+often a better choice.</p>
+</dd>
+<dt><span class="term"><code class="literal">pre-configure</code></span></dt>
+<dd>
+<p>The substitutions are applied after the patches from the
+<code class="filename">patches/</code> directory. This makes it possible to run
+<span class="command"><strong>bmake patch</strong></span> on the package, after which the patches
+can be edited using the tools pkgvi and mkpatches from the <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/pkgdiff/README.html"; target="_top"><code
class="filename">pkgtools/pkgdiff</code></a> package.</p>
+<p>When updating the patches, it is helpful to explicitly separate the
+<span class="command"><strong>bmake patch</strong></span> from the <span class="command"><strong>bmake
+configure</strong></span>, and to only edit the patches between these commands.
+Otherwise the substitutions from the SUBST block will end up in the patch
+file. When this happens in really obvious ways, pkglint will complain
+about patches that contain a hard-coded <code class="literal">/usr/pkg</code>
+instead of the correct and intended <code class="literal">@PREFIX@</code>, but it
+can only detect these really obvious
+cases.</p>
+</dd>
+<dt><span class="term"><code class="literal">do-configure</code></span></dt>
+<dd><p>This stage should only be used if the package defines a
+<code class="literal">pre-configure</code> action itself, and the substitution must
+happen after that. Typical examples are packages that use the
+<code class="literal">pre-configure</code> stage to regenerate the GNU configure
+script from
+<code class="filename">configure.ac</code>.</p></dd>
+<dt><span class="term"><code class="literal">post-configure</code></span></dt>
+<dd><p>This stage is used to fix up any mistakes by the
+configure stage.</p></dd>
+<dt><span class="term"><code class="literal">pre-build</code></span></dt>
+<dd><p>This stage should only be used for substitutions that are
+clearly related to building the package, not for fixing the
+configuration. Substitutions for pathnames (such as replacing
+<code class="filename">/usr/local</code> with <code class="literal">${PREFIX}</code>) or
+user names (such as replacing <code class="literal">@MY_USER@</code> with the
+actual username) belong in pre-configure or post-configure
+instead.</p></dd>
+<dt><span class="term"><code class="literal">post-build</code></span></dt>
+<dd>
+<p>Just as with pre-build, this stage should only be used
+for substitutions that are clearly related to building the package, not
+for fixing the configuration. Substitutions for pathnames (such as
+replacing <code class="filename">/usr/local</code> with
+<code class="literal">${PREFIX}</code>) or user names (such as replacing
+<code class="literal">@MY_USER@</code> with the actual username) belong in
+pre-configure or post-configure instead.</p>
+<p>A typical use is to update pkg-config files to include the rpath
+compiler options.</p>
+</dd>
+<dt><span class="term"><code class="literal">pre-install</code></span></dt>
+<dd><p>In general, the install phase should be as simple as
+possible. As with the pre-build and post-build stages, it should not be
+used to fix pathnames or user names, these belong in pre-configure
+instead. There are only few legitimate use cases for applying
+substitutions in this stage.</p></dd>
+</dl></div>
+</div>
+<div class="sect3">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="fixes.subst.where"></a>21.1.11.2. Choosing the time where the substitutions happen</h4></div></div></div>
+<p>The <code class="varname">SUBST_FILES.*</code> variable contains a list of
+filename patterns. These patterns are relative to
+<code class="varname">WRKSRC</code> since that is where most substitutions happen.
+A typical example is:</p>
+<pre class="programlisting">
+SUBST_FILES.path= Makefile */Makefile */*/Makefile *.[ch]
+</pre>
+<p>The above patterns, especially the last, are quite broad. The SUBST
+implementation checks that each filename pattern that is mentioned here
+has an effect. For example, if none of the
+<code class="filename">*/*/Makefile</code> files contains the patterns to be found
+and substituted, that filename pattern is redundant and should be left
+out. If the text to be substituted occurs in some of the files from a
+single pattern, but not in all of them, that is totally ok, and the SUBST
+framework will only print an INFO message for those files.</p>
+<p>If there is a good reason for having redundant filename patterns,
+set <code class="varname">SUBST_NOOP_OK.path=yes</code> in the above
+example.</p>
+<p>Another popular way of choosing the files for the substitutions is
+via a shell command, like this:</p>
+<pre class="programlisting">
+C_FILES_CMD= cd ${WRKSRC} && ${FIND} -name '*.c'
+SUBST_FILES.path= ${C_FILES_CMD:sh}
+</pre>
+<p>The variable name <code class="varname">C_FILES_CMD</code> in this example is
+freely chosen and independent of the SUBST framework.</p>
+<p>In this variant, the <code class="varname">SUBST_FILES.*</code> variable
+lists each file individually. Thereby chances are higher that there are
+filename patterns in which no substitution happens. Since the SUBST
+framework cannot know whether the filename patterns in
+<code class="varname">SUBST_FILES.*</code> have been explicitly listed in the
+Makefile (where any redundant filename pattern would be suspicious) or
+been generated by a shell command (in which redundant filename patterns
+are more likely and to be expected), it will complain about these
+redundant filename patterns. Therefore, SUBST blocks that use a shell
+command to generate the list of filename patterns often need to set
+<code class="varname">SUBST_NOOP_OK.*</code> to <code class="literal">yes</code>.</p>
+</div>
+<div class="sect3">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="fixes.subst.what"></a>21.1.11.3. Choosing what to substitute</h4></div></div></div>
+<p>In most cases, the substitutions are given using one or more
+<a class="citerefentry" href="https://netbsd.gw.com/cgi-bin/man-cgi?sed+1.i386+NetBSD-9.0";><span class="citerefentry"><span class="refentrytitle">sed</span>(1)</span></a> commands, like this:</p>
+<pre class="programlisting">
+SUBST_SED.path= -e 's|/usr/local|${PREFIX}|g'
Home |
Main Index |
Thread Index |
Old Index