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/ef0a7d52e367
branches: trunk
changeset: 434660:ef0a7d52e367
user: wiz <wiz%pkgsrc.org@localhost>
date: Sat Jun 20 09:47:55 2020 +0000
description:
doc/pkgsrc.*: regen
diffstat:
doc/pkgsrc.html | 69 ++++++++++++++++++++++++++++++++++++--------------------
doc/pkgsrc.txt | 59 +++++++++++++++++++++++++++++-------------------
2 files changed, 80 insertions(+), 48 deletions(-)
diffs (195 lines):
diff -r dffd1d50e6c3 -r ef0a7d52e367 doc/pkgsrc.html
--- a/doc/pkgsrc.html Sat Jun 20 09:47:05 2020 +0000
+++ b/doc/pkgsrc.html Sat Jun 20 09:47:55 2020 +0000
@@ -6219,11 +6219,11 @@
added. Several important variables are set in the section:</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p><code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
- is the actual dependency recorded in the installed
+ is the dependency version recorded in the installed
package; this should always be set using
<span class="command"><strong>+=</strong></span> to ensure that
we're appending to any pre-existing list of values. This
- variable should be set to the first version of the
+ variable should be set to the last version of the
package that had an backwards-incompatible API change.
</p></li>
<li class="listitem"><p><code class="varname">BUILDLINK_PKGSRCDIR.<em class="replaceable"><code>pkg</code></em></code>
@@ -6337,39 +6337,53 @@
and
<code class="varname">BUILDLINK_ABI_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
in <code class="filename">buildlink3.mk</code> files</h3></div></div></div>
-<p>These two variables differ in that one describes source
+<p>Both variables set lower bounds for a version of this package.
+ The two variables differ in that one describes source
compatibility (API) and the other binary compatibility (ABI).
The difference is that a change in the API breaks compilation of
programs while changes in the ABI stop compiled programs from
running.</p>
-<p>Changes to the
+<p>The
+ <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
+ variable in a <code class="filename">buildlink3.mk</code> should be
+ changed very rarely. (One possible scenario: If all packages
+ using this package need a higher version than defined in the
+ <code class="filename">buildlink3.mk</code>,
<code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
- variable in a <code class="filename">buildlink3.mk</code> file happen
- very rarely. One possible reason is that all packages depending
- on this already need a newer version. In case it is bumped see
- the description below.</p>
-<p>The most common example of an ABI change is that the major
- version of a shared library is increased. In this case,
+ could be updated to that higher version.)</p>
+<p>On the other hand, changes to
+ <code class="varname">BUILDLINK_ABI_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
+ are more common. The variable will need to be updated every
+ time the major version of one of its shared libraries is changed,
+ or any other change where a binary built against the previous
+ version of the package will not run against the new version any
+ longer.</p>
+<p>In such a case, the package's
<code class="varname">BUILDLINK_ABI_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
- should be adjusted to require at least the new package version.
- Then the packages that depend on this package need their
- <code class="varname">PKGREVISION</code>s increased and, if they have
- <code class="filename">buildlink3.mk</code> files, their
- <code class="varname">BUILDLINK_ABI_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
- adjusted, too. This is needed so pkgsrc will require the correct
- package dependency and not settle for an older one when building
- the source.</p>
-<p>See <a class="xref" href="#dependencies" title="21.1.5. Handling dependencies">Section 21.1.5, “Handling dependencies”</a> for
- more information about dependencies on other packages,
- including the <code class="varname">BUILDLINK_ABI_DEPENDS</code> and
- <code class="varname">ABI_DEPENDS</code> definitions.</p>
+ must be increased to require the new package version. Then the
+ <code class="varname">PKGREVISION</code> of all packages
+ <em class="replaceable"><code>foo</code></em> that depend on this package need
+ to be increased, and if they have
+ <code class="filename">buildlink3.mk</code> files,
+ <code class="varname">BUILDLINK_ABI_DEPENDS.<em class="replaceable"><code>foo</code></em></code>
+ in their <code class="filename">buildlink3.mk</code> files must be
+ increased to the new version as well. This is required so that a
+ package will pull in the versions of the packages that use the
+ new ABI and that the packages' <code class="varname">PKGREVISION</code>s
+ uniquely identify the packages built against the new ABI. The
+ <a href="https://cdn.NetBSD.org/pub/pkgsrc/current/pkgsrc/pkgtools/revbump/README.html"; target="_top"><code class="filename">pkgtools/revbump</code></a> package can
+ help with these updates.</p>
+<p>See <a class="xref" href="#dependencies" title="21.1.5. Handling dependencies">Section 21.1.5, “Handling dependencies”</a> for more information
+ about dependencies on other packages, including the
+ <code class="varname">BUILDLINK_API_DEPENDS</code> definitions.</p>
<p>Please take careful consideration before adjusting
<code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
or
<code class="varname">BUILDLINK_ABI_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
- as we don't want to cause unneeded package deletions and
- rebuilds. In many cases, new versions of packages work just
- fine with older dependencies.</p>
+ in a <code class="filename">buildlink3.mk</code> file as we don't want to
+ cause unneeded package deletions and rebuilds. In many cases,
+ new versions of packages work just fine with older
+ dependencies.</p>
<p>Also it is not needed to set
<code class="varname">BUILDLINK_ABI_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
when it is identical to
@@ -6589,6 +6603,11 @@
<pre class="programlisting">
PRINT_PLIST_AWK+= /^libdata\/foo/ { next; }
</pre>
+<p>The <code class="varname">PRINT_PLIST_AWK</code> transformations are
+ evaluated after the file list and directory list are sorted.
+ <code class="varname">EARLY_PRINT_PLIST_AWK</code> is like
+ <code class="varname">PRINT_PLIST_AWK</code> except it operates before the file
+ list and directory list are sorted.</p>
</div>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
diff -r dffd1d50e6c3 -r ef0a7d52e367 doc/pkgsrc.txt
--- a/doc/pkgsrc.txt Sat Jun 20 09:47:05 2020 +0000
+++ b/doc/pkgsrc.txt Sat Jun 20 09:47:55 2020 +0000
@@ -5197,10 +5197,10 @@
The main section is protected from multiple inclusion and controls how the
dependency on pkg is added. Several important variables are set in the section:
- * BUILDLINK_API_DEPENDS.pkg is the actual dependency recorded in the
+ * BUILDLINK_API_DEPENDS.pkg is the dependency version recorded in the
installed package; this should always be set using += to ensure that we're
appending to any pre-existing list of values. This variable should be set
- to the first version of the package that had an backwards-incompatible API
+ to the last version of the package that had an backwards-incompatible API
change.
* BUILDLINK_PKGSRCDIR.pkg is the location of the pkg pkgsrc directory.
@@ -5272,31 +5272,40 @@
18.2.2. Updating BUILDLINK_API_DEPENDS.pkg and BUILDLINK_ABI_DEPENDS.pkg in
buildlink3.mk files
-These two variables differ in that one describes source compatibility (API) and
-the other binary compatibility (ABI). The difference is that a change in the
-API breaks compilation of programs while changes in the ABI stop compiled
-programs from running.
-
-Changes to the BUILDLINK_API_DEPENDS.pkg variable in a buildlink3.mk file
-happen very rarely. One possible reason is that all packages depending on this
-already need a newer version. In case it is bumped see the description below.
-
-The most common example of an ABI change is that the major version of a shared
-library is increased. In this case, BUILDLINK_ABI_DEPENDS.pkg should be
-adjusted to require at least the new package version. Then the packages that
-depend on this package need their PKGREVISIONs increased and, if they have
-buildlink3.mk files, their BUILDLINK_ABI_DEPENDS.pkg adjusted, too. This is
-needed so pkgsrc will require the correct package dependency and not settle for
-an older one when building the source.
+Both variables set lower bounds for a version of this package. The two
+variables differ in that one describes source compatibility (API) and the other
+binary compatibility (ABI). The difference is that a change in the API breaks
+compilation of programs while changes in the ABI stop compiled programs from
+running.
+
+The BUILDLINK_API_DEPENDS.pkg variable in a buildlink3.mk should be changed
+very rarely. (One possible scenario: If all packages using this package need a
+higher version than defined in the buildlink3.mk, BUILDLINK_API_DEPENDS.pkg
+could be updated to that higher version.)
+
+On the other hand, changes to BUILDLINK_ABI_DEPENDS.pkg are more common. The
+variable will need to be updated every time the major version of one of its
+shared libraries is changed, or any other change where a binary built against
+the previous version of the package will not run against the new version any
+longer.
+
+In such a case, the package's BUILDLINK_ABI_DEPENDS.pkg must be increased to
+require the new package version. Then the PKGREVISION of all packages foo that
+depend on this package need to be increased, and if they have buildlink3.mk
+files, BUILDLINK_ABI_DEPENDS.foo in their buildlink3.mk files must be increased
+to the new version as well. This is required so that a package will pull in the
+versions of the packages that use the new ABI and that the packages'
+PKGREVISIONs uniquely identify the packages built against the new ABI. The
+pkgtools/revbump package can help with these updates.
See Section 21.1.5, "Handling dependencies" for more information about
-dependencies on other packages, including the BUILDLINK_ABI_DEPENDS and
-ABI_DEPENDS definitions.
+dependencies on other packages, including the BUILDLINK_API_DEPENDS
+definitions.
Please take careful consideration before adjusting BUILDLINK_API_DEPENDS.pkg or
-BUILDLINK_ABI_DEPENDS.pkg as we don't want to cause unneeded package deletions
-and rebuilds. In many cases, new versions of packages work just fine with older
-dependencies.
+BUILDLINK_ABI_DEPENDS.pkg in a buildlink3.mk file as we don't want to cause
+unneeded package deletions and rebuilds. In many cases, new versions of
+packages work just fine with older dependencies.
Also it is not needed to set BUILDLINK_ABI_DEPENDS.pkg when it is identical to
BUILDLINK_API_DEPENDS.pkg.
@@ -5459,6 +5468,10 @@
PRINT_PLIST_AWK+= /^libdata\/foo/ { next; }
+The PRINT_PLIST_AWK transformations are evaluated after the file list and
+directory list are sorted. EARLY_PRINT_PLIST_AWK is like PRINT_PLIST_AWK except
+it operates before the file list and directory list are sorted.
+
19.4. Variable substitution in PLIST
A number of variables are substituted automatically in PLISTs when a package is
Home |
Main Index |
Thread Index |
Old Index