[pkgsrc/trunk]: pkgsrc/doc/guide/files Try to improve the BUILDLINK_A{B,P}I_D...

[wiz <wiz%pkgsrc.org@localhost>]

details:   https://anonhg.NetBSD.org/pkgsrc/rev/b5642bd2f601
branches:  trunk
changeset: 434575:b5642bd2f601
user:      wiz <wiz%pkgsrc.org@localhost>
date:      Thu Jun 18 20:30:12 2020 +0000

description:
Try to improve the BUILDLINK_A{B,P}I_DEPENDS description after
comments from rillig@.

diffstat:

 doc/guide/files/buildlink.xml |  62 ++++++++++++++++++++++++++----------------
 doc/guide/files/fixes.xml     |  12 ++++++-
 2 files changed, 48 insertions(+), 26 deletions(-)

diffs (128 lines):

diff -r 21ca0b228581 -r b5642bd2f601 doc/guide/files/buildlink.xml
--- a/doc/guide/files/buildlink.xml     Thu Jun 18 20:01:17 2020 +0000
+++ b/doc/guide/files/buildlink.xml     Thu Jun 18 20:30:12 2020 +0000
@@ -1,4 +1,4 @@
-<!-- $NetBSD: buildlink.xml,v 1.41 2017/06/29 14:22:49 leot Exp $ -->
+<!-- $NetBSD: buildlink.xml,v 1.42 2020/06/18 20:30:12 wiz Exp $ -->
 
 <chapter id="buildlink">
   <title>Buildlink methodology</title>
@@ -232,11 +232,11 @@
       <itemizedlist>
        <listitem>
          <para><varname>BUILDLINK_API_DEPENDS.<replaceable>pkg</replaceable></varname>
-         is the actual dependency recorded in the installed
+         is the dependency version recorded in the installed
          package; this should always be set using
          <command>+=</command> 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.
          </para>
        </listitem>
@@ -379,43 +379,57 @@
       <varname>BUILDLINK_ABI_DEPENDS.<replaceable>pkg</replaceable></varname>
       in <filename>buildlink3.mk</filename> files</title>
 
-      <para>These two variables differ in that one describes source
+      <para>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.</para>
 
-      <para>Changes to the
+      <para>The
       <varname>BUILDLINK_API_DEPENDS.<replaceable>pkg</replaceable></varname>
-      variable in a <filename>buildlink3.mk</filename> 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.</para>
+      variable in a <filename>buildlink3.mk</filename> should be
+      changed very rarely.  (One possible scenario: If all packages
+      using this package need a higher version than defined in the
+      <filename>buildlink3.mk</filename>,
+      <varname>BUILDLINK_API_DEPENDS.<replaceable>pkg</replaceable></varname>
+      could be updated to that higher version.)</para>
 
-      <para>The most common example of an ABI change is that the major
-      version of a shared library is increased. In this case,
+      <para>On the other hand, changes to
       <varname>BUILDLINK_ABI_DEPENDS.<replaceable>pkg</replaceable></varname>
-      should be adjusted to require at least the new package version.
-      Then the packages that depend on this package need their
-      <varname>PKGREVISION</varname>s increased and, if they have
+      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.</para>
+
+      <para>In such a case, the package's
+      <varname>BUILDLINK_ABI_DEPENDS.<replaceable>pkg</replaceable></varname>
+      must be increased to require the new package version.  Then the
+      <varname>PKGREVISION</varname> of all packages that depend on
+      this package need to be increased, and if they have
       <filename>buildlink3.mk</filename> files, their
       <varname>BUILDLINK_ABI_DEPENDS.<replaceable>pkg</replaceable></varname>
-      adjusted, too. This is needed so pkgsrc will require the correct
-      package dependency and not settle for an older one when building
-      the source.</para>
+      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'
+      <varname>PKGREVISION</varname>s uniquely identify the packages
+      built against the new ABI. The <filename
+      role="pkg">pkgtools/revbump</filename> package can help with
+      these updates.</para>
 
-      <para>See <xref linkend="dependencies"/> for
-      more information about dependencies on other packages,
-      including the <varname>BUILDLINK_ABI_DEPENDS</varname> and
-      <varname>ABI_DEPENDS</varname> definitions.</para>
+      <para>See <xref linkend="dependencies"/> for more information
+      about dependencies on other packages, including the
+      <varname>BUILDLINK_API_DEPENDS</varname> definitions.</para>
 
       <para>Please take careful consideration before adjusting
       <varname>BUILDLINK_API_DEPENDS.<replaceable>pkg</replaceable></varname>
       or
       <varname>BUILDLINK_ABI_DEPENDS.<replaceable>pkg</replaceable></varname>
-      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.</para>
+      in a <filename>buildlink3.mk</filename> 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.</para>
 
       <para>Also it is not needed to set
       <varname>BUILDLINK_ABI_DEPENDS.<replaceable>pkg</replaceable></varname>
diff -r 21ca0b228581 -r b5642bd2f601 doc/guide/files/fixes.xml
--- a/doc/guide/files/fixes.xml Thu Jun 18 20:01:17 2020 +0000
+++ b/doc/guide/files/fixes.xml Thu Jun 18 20:30:12 2020 +0000
@@ -1,4 +1,4 @@
-<!-- $NetBSD: fixes.xml,v 1.157 2020/06/05 14:24:17 rillig Exp $ -->
+<!-- $NetBSD: fixes.xml,v 1.158 2020/06/18 20:30:12 wiz Exp $ -->
 
 <chapter id="fixes"> <?dbhtml filename="fixes.html"?>
 <title>Making your package work</title>
@@ -440,7 +440,15 @@
        have changed.</para>
 
        <para>If you need to depend on minimum versions of libraries,
-       see the buildlink section of the pkgsrc guide.</para>
+       set
+       <varname>BUILDLINK_API_DEPENDS.<replaceable>pkg</replaceable></varname>
+       to the appropriate pattern before including its
+       <filename>buildlink3.mk</filename> file, e.g.</para>
+
+<programlisting>
+BUILDLINK_API_DEPENDS.jpeg+=    jpeg>=9.0
+.include "../../graphics/jpeg/buildlink3.mk"
+</programlisting>
 
        <para>For security fixes, please update the package
        vulnerabilities file. See <xref