pkgsrc-Changes archive

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]

CVS commit: pkgsrc/doc



Module Name:    pkgsrc
Committed By:   wiz
Date:           Sat Jun 20 09:47:55 UTC 2020

Modified Files:
        pkgsrc/doc: pkgsrc.html pkgsrc.txt

Log Message:
doc/pkgsrc.*: regen


To generate a diff of this commit:
cvs rdiff -u -r1.299 -r1.300 pkgsrc/doc/pkgsrc.html
cvs rdiff -u -r1.297 -r1.298 pkgsrc/doc/pkgsrc.txt

Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.

Modified files:

Index: pkgsrc/doc/pkgsrc.html
diff -u pkgsrc/doc/pkgsrc.html:1.299 pkgsrc/doc/pkgsrc.html:1.300
--- pkgsrc/doc/pkgsrc.html:1.299        Sat Jun 20 05:32:11 2020
+++ pkgsrc/doc/pkgsrc.html      Sat Jun 20 09:47:55 2020
@@ -6219,11 +6219,11 @@ BUILDLINK_TREE+=        -tiff
       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 @@ BUILDLINK_TREE+=        -tiff
       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>
-      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
+      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>
-      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, &#8220;Handling dependencies&#8221;</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, &#8220;Handling dependencies&#8221;</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 @@ adding the RCS ID the space should be om
 <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">

Index: pkgsrc/doc/pkgsrc.txt
diff -u pkgsrc/doc/pkgsrc.txt:1.297 pkgsrc/doc/pkgsrc.txt:1.298
--- pkgsrc/doc/pkgsrc.txt:1.297 Sat Jun 20 05:32:11 2020
+++ pkgsrc/doc/pkgsrc.txt       Sat Jun 20 09:47:55 2020
@@ -5197,10 +5197,10 @@ buildlink3.mk files and is used to track
 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 @@ included:
 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 @@ resulting PLIST:
 
 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