diff options
author | wiz <wiz@pkgsrc.org> | 2011-08-30 15:17:44 +0000 |
---|---|---|
committer | wiz <wiz@pkgsrc.org> | 2011-08-30 15:17:44 +0000 |
commit | 08ad68e459c4aaffb924e78a9d92b21535054a53 (patch) | |
tree | 0385afcb40e9adbc77e8bd2f8dba61bcd4bd3153 /doc/pkgsrc.html | |
parent | d010357db84ed9743933f8f47ffd51b43224a139 (diff) | |
download | pkgsrc-08ad68e459c4aaffb924e78a9d92b21535054a53.tar.gz |
regen
Diffstat (limited to 'doc/pkgsrc.html')
-rw-r--r-- | doc/pkgsrc.html | 108 |
1 files changed, 62 insertions, 46 deletions
diff --git a/doc/pkgsrc.html b/doc/pkgsrc.html index bcdd81db5de..98a037e6914 100644 --- a/doc/pkgsrc.html +++ b/doc/pkgsrc.html @@ -244,7 +244,11 @@ builds)</a></span></dt> <dt><span class="sect1"><a href="#creating-buildlink3.mk">14.2. Writing <code class="filename">buildlink3.mk</code> files</a></span></dt> <dd><dl> <dt><span class="sect2"><a href="#anatomy-of-bl3">14.2.1. Anatomy of a buildlink3.mk file</a></span></dt> -<dt><span class="sect2"><a href="#updating-buildlink-depends">14.2.2. Updating <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code> in <code class="filename">buildlink3.mk</code> files</a></span></dt> +<dt><span class="sect2"><a href="#updating-buildlink-depends">14.2.2. Updating + <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code> + and + <code class="varname">BUILDLINK_ABI_DEPENDS.<em class="replaceable"><code>pkg</code></em></code> + in <code class="filename">buildlink3.mk</code> files</a></span></dt> </dl></dd> <dt><span class="sect1"><a href="#writing-builtin.mk">14.3. Writing <code class="filename">builtin.mk</code> files</a></span></dt> <dd><dl> @@ -3655,7 +3659,11 @@ anymore, you can remove that file and run <span class="command"><strong>cvs -q u <dt><span class="sect1"><a href="#creating-buildlink3.mk">14.2. Writing <code class="filename">buildlink3.mk</code> files</a></span></dt> <dd><dl> <dt><span class="sect2"><a href="#anatomy-of-bl3">14.2.1. Anatomy of a buildlink3.mk file</a></span></dt> -<dt><span class="sect2"><a href="#updating-buildlink-depends">14.2.2. Updating <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code> in <code class="filename">buildlink3.mk</code> files</a></span></dt> +<dt><span class="sect2"><a href="#updating-buildlink-depends">14.2.2. Updating + <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code> + and + <code class="varname">BUILDLINK_ABI_DEPENDS.<em class="replaceable"><code>pkg</code></em></code> + in <code class="filename">buildlink3.mk</code> files</a></span></dt> </dl></dd> <dt><span class="sect1"><a href="#writing-builtin.mk">14.3. Writing <code class="filename">builtin.mk</code> files</a></span></dt> <dd><dl> @@ -5334,7 +5342,11 @@ ${PLIST.foo}@dirrm share/bar <dt><span class="sect1"><a href="#creating-buildlink3.mk">14.2. Writing <code class="filename">buildlink3.mk</code> files</a></span></dt> <dd><dl> <dt><span class="sect2"><a href="#anatomy-of-bl3">14.2.1. Anatomy of a buildlink3.mk file</a></span></dt> -<dt><span class="sect2"><a href="#updating-buildlink-depends">14.2.2. Updating <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code> in <code class="filename">buildlink3.mk</code> files</a></span></dt> +<dt><span class="sect2"><a href="#updating-buildlink-depends">14.2.2. Updating + <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code> + and + <code class="varname">BUILDLINK_ABI_DEPENDS.<em class="replaceable"><code>pkg</code></em></code> + in <code class="filename">buildlink3.mk</code> files</a></span></dt> </dl></dd> <dt><span class="sect1"><a href="#writing-builtin.mk">14.3. Writing <code class="filename">builtin.mk</code> files</a></span></dt> <dd><dl> @@ -5500,7 +5512,7 @@ BUILDLINK_TREE+= -tiff <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 - package that had an API change. + 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> is the location of the <em class="replaceable"><code>pkg</code></em> @@ -5581,34 +5593,38 @@ BUILDLINK_TREE+= -tiff file is included. Dependencies are only added for directly include <code class="filename">buildlink3.mk</code> files.</p> </div> -<div class="sect2" title="14.2.2. Updating BUILDLINK_API_DEPENDS.pkg in buildlink3.mk files"> +<div class="sect2" title="14.2.2. Updating BUILDLINK_API_DEPENDS.pkg and BUILDLINK_ABI_DEPENDS.pkg in buildlink3.mk files"> <div class="titlepage"><div><div><h3 class="title"> -<a name="updating-buildlink-depends"></a>14.2.2. Updating <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code> in <code class="filename">buildlink3.mk</code> files</h3></div></div></div> -<p>The situation that requires increasing the dependency listed in - <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code> - after a package update is when the API or interface to the - header files change.</p> -<p>In this case, +<a name="updating-buildlink-depends"></a>14.2.2. Updating <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code> - should be adjusted to require at least the new package - version. In some cases, the packages that depend on this new - version may 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_API_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><code class="varname">BUILDLINK_ABI_DEPENDS.<em class="replaceable"><code>pkg</code></em></code> - should be increased when the binary interface or sonames - (major number of the library version) of any installed - shared libraries change. This is needed so that binary - packages made using it will require the correct package - dependency and not settle for an older one which will not - contain the necessary shared libraries.</p> + 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 + 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 + <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em>replaceable></code>varname> + 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, + <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="19.1.6. Handling dependencies">Section 19.1.6, “Handling dependencies”</a> for - more information about dependencies on other packages, - including the <code class="varname">BUILDLINK_ABI_DEPENDS</code> and + 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> <p>Please take careful consideration before adjusting <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code> @@ -5618,8 +5634,8 @@ BUILDLINK_TREE+= -tiff 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 + <code class="varname">BUILDLINK_ABI_DEPENDS.<em class="replaceable"><code>pkg</code></em></code> + when it is identical to <code class="varname">BUILDLINK_API_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>. </p> </div> </div> @@ -6716,7 +6732,7 @@ ${MASTER_SITE_XEMACS} </pre> <p>Some explanations for the less self-explaining ones: <code class="varname">MASTER_SITE_BACKUP</code> contains backup sites - for packages that are maintained in <a class="ulink" href="ftp://ftp.NetBSD.org/pkgsrc/distfiles/%24%7BDIST_SUBDIR%7D" target="_top">ftp://ftp.NetBSD.org/pkgsrc/distfiles/${DIST_SUBDIR}</a>. <code class="varname">MASTER_SITE_LOCAL</code> contains local + for packages that are maintained in <a class="ulink" href="ftp://ftp.NetBSD.org/pub/pkgsrc/distfiles/%24%7BDIST_SUBDIR%7D" target="_top">ftp://ftp.NetBSD.org/pub/pkgsrc/distfiles/${DIST_SUBDIR}</a>. <code class="varname">MASTER_SITE_LOCAL</code> contains local package source distributions that are maintained in <a class="ulink" href="ftp://ftp.NetBSD.org/pub/pkgsrc/distfiles/LOCAL_PORTS/" target="_top">ftp://ftp.NetBSD.org/pub/pkgsrc/distfiles/LOCAL_PORTS/</a>.</p> <p>If you choose one of these predefined sites, you may want to specify a subdirectory of that site. Since these @@ -7521,7 +7537,7 @@ TOOLS_PLATFORM.true?= true # shell builtin <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="tools.questions"></a>18.4. Questions regarding the tools</h2></div></div></div> <div class="qandaset" title="Frequently Asked Questions"> -<a name="id1168229333580"></a><dl> +<a name="id1168229333724"></a><dl> <dt>18.4.1. <a href="#tools.new">How do I add a new tool?</a> </dt> <dt>18.4.2. <a href="#tools.listall">How do I get a list of all available @@ -7538,7 +7554,7 @@ TOOLS_PLATFORM.true?= true # shell builtin <tbody> <tr class="question" title="18.4.1."> <td align="left" valign="top"> -<a name="tools.new"></a><a name="id1168229333584"></a><p><b>18.4.1.</b></p> +<a name="tools.new"></a><a name="id1168229333728"></a><p><b>18.4.1.</b></p> </td> <td align="left" valign="top"><p>How do I add a new tool?</p></td> </tr> @@ -7548,7 +7564,7 @@ TOOLS_PLATFORM.true?= true # shell builtin </tr> <tr class="question" title="18.4.2."> <td align="left" valign="top"> -<a name="tools.listall"></a><a name="id1168229333592"></a><p><b>18.4.2.</b></p> +<a name="tools.listall"></a><a name="id1168229333736"></a><p><b>18.4.2.</b></p> </td> <td align="left" valign="top"><p>How do I get a list of all available tools?</p></td> @@ -7559,7 +7575,7 @@ TOOLS_PLATFORM.true?= true # shell builtin </tr> <tr class="question" title="18.4.3."> <td align="left" valign="top"> -<a name="tools.used"></a><a name="id1168229333601"></a><p><b>18.4.3.</b></p> +<a name="tools.used"></a><a name="id1168229333745"></a><p><b>18.4.3.</b></p> </td> <td align="left" valign="top"><p>How can I get a list of all the tools that a package is using while being built? I want to know whether it @@ -9534,7 +9550,7 @@ place.</p></li> and if you still don't have the answer, ask on the <code class="literal">pkgsrc-users</code> mailing list.</p> <div class="qandaset" title="Frequently Asked Questions"> -<a name="id1168229337993"></a><dl> +<a name="id1168229338137"></a><dl> <dt>22.1. <a href="#devfaq.makeflags">What is the difference between MAKEFLAGS, .MAKEFLAGS and MAKE_FLAGS?</a> @@ -9577,7 +9593,7 @@ do?</a> <tbody> <tr class="question" title="22.1."> <td align="left" valign="top"> -<a name="devfaq.makeflags"></a><a name="id1168229337996"></a><p><b>22.1.</b></p> +<a name="devfaq.makeflags"></a><a name="id1168229338140"></a><p><b>22.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 @@ -9593,7 +9609,7 @@ do?</a> </tr> <tr class="question" title="22.2."> <td align="left" valign="top"> -<a name="devfaq.make"></a><a name="id1168229338029"></a><p><b>22.2.</b></p> +<a name="devfaq.make"></a><a name="id1168229338173"></a><p><b>22.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 @@ -9611,7 +9627,7 @@ do?</a> </tr> <tr class="question" title="22.3."> <td align="left" valign="top"> -<a name="devfaq.cc"></a><a name="id1168229338067"></a><p><b>22.3.</b></p> +<a name="devfaq.cc"></a><a name="id1168229338211"></a><p><b>22.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 @@ -9629,7 +9645,7 @@ do?</a> </tr> <tr class="question" title="22.4."> <td align="left" valign="top"> -<a name="devfaq.bl3flags"></a><a name="id1168229338101"></a><p><b>22.4.</b></p> +<a name="devfaq.bl3flags"></a><a name="id1168229338245"></a><p><b>22.4.</b></p> </td> <td align="left" valign="top"><p>What is the difference between <code class="varname">BUILDLINK_LDFLAGS</code>, @@ -9642,7 +9658,7 @@ do?</a> </tr> <tr class="question" title="22.5."> <td align="left" valign="top"> -<a name="devfaq.bl3prefix"></a><a name="id1168229338120"></a><p><b>22.5.</b></p> +<a name="devfaq.bl3prefix"></a><a name="id1168229338264"></a><p><b>22.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> @@ -9658,7 +9674,7 @@ do?</a> </tr> <tr class="question" title="22.6."> <td align="left" valign="top"> -<a name="devfaq.master_sites"></a><a name="id1168229338146"></a><p><b>22.6.</b></p> +<a name="devfaq.master_sites"></a><a name="id1168229338290"></a><p><b>22.6.</b></p> </td> <td align="left" valign="top"><p>What does <code class="literal">${MASTER_SITE_SOURCEFORGE:=package/}</code> mean? I @@ -9682,7 +9698,7 @@ do?</a> </tr> <tr class="question" title="22.7."> <td align="left" valign="top"> -<a name="devfaq.mailinglists"></a><a name="id1168229338247"></a><p><b>22.7.</b></p> +<a name="devfaq.mailinglists"></a><a name="id1168229338391"></a><p><b>22.7.</b></p> </td> <td align="left" valign="top"><p>Which mailing lists are there for package developers?</p></td> @@ -9707,7 +9723,7 @@ do?</a> </tr> <tr class="question" title="22.8."> <td align="left" valign="top"> -<a name="devfaq.documentation"></a><a name="id1168229338278"></a><p><b>22.8.</b></p> +<a name="devfaq.documentation"></a><a name="id1168229338423"></a><p><b>22.8.</b></p> </td> <td align="left" valign="top"><p>Where is the pkgsrc documentation?</p></td> @@ -9755,7 +9771,7 @@ do?</a> </tr> <tr class="question" title="22.9."> <td align="left" valign="top"> -<a name="devfaq.too-much-time"></a><a name="id1168229338332"></a><p><b>22.9.</b></p> +<a name="devfaq.too-much-time"></a><a name="id1168229338476"></a><p><b>22.9.</b></p> </td> <td align="left" valign="top"><p>I have a little time to kill. What shall I do?</p></td> |