regen

2 files changed, 83 insertions, 29 deletions

diff --git a/doc/pkgsrc.html b/doc/pkgsrc.html
index 930c9d5f1a9..56805bfdc71 100644
--- a/doc/pkgsrc.html
+++ b/doc/pkgsrc.html
@@ -5667,6 +5667,29 @@ BUILDLINK_TREE+=	-tiff
       <code class="filename">buildlink3.mk</code>
       file is included. Dependencies are only added for directly
       include <code class="filename">buildlink3.mk</code> files.</p>
+<p>When providing a <code class="filename">buildlink3.mk</code> and
+      including other <code class="filename">buildlink3.mk</code> files in it,
+      please only add necessary ones. I.e. those whose libraries or
+      header files are automatically exposed when the package is
+      use.</p>
+<p>In particular, if only an executable
+      (<code class="filename">bin/foo</code>) is linked against a library, that
+      library does not need to be propagated in the
+      <code class="filename">buildlink3.mk</code> file.</p>
+<p>The following steps should help you decide if a
+      <code class="filename">buildlink3.mk</code> file needs to be included:
+      </p>
+<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
+<li class="listitem"><p>Run <code class="filename">ldd</code> on all installed
+	libraries and look against what other libraries they link. The
+	packages providing these must be
+	buildlinked.</p></li>
+<li class="listitem"><p>Look at the installed header files: What
+	headers do they include? The packages providing these files
+	must be buildlinked.</p></li>
+</ul></div>
+<p>
+      </p>
 </div>
 <div class="sect2">
 <div class="titlepage"><div><div><h3 class="title">
@@ -7615,7 +7638,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">
-<a name="idm80364112"></a><dl>
+<a name="idm80445136"></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
@@ -7634,7 +7657,7 @@ TOOLS_PLATFORM.true?=           true                    # shell builtin
 <tbody>
 <tr class="question">
 <td align="left" valign="top">
-<a name="tools.new"></a><a name="idm80363728"></a><p><b>18.4.1.</b></p>
+<a name="tools.new"></a><a name="idm80444752"></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>
@@ -7644,7 +7667,7 @@ TOOLS_PLATFORM.true?=           true                    # shell builtin
 </tr>
 <tr class="question">
 <td align="left" valign="top">
-<a name="tools.listall"></a><a name="idm80362704"></a><p><b>18.4.2.</b></p>
+<a name="tools.listall"></a><a name="idm80443600"></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>
@@ -7655,7 +7678,7 @@ TOOLS_PLATFORM.true?=           true                    # shell builtin
 </tr>
 <tr class="question">
 <td align="left" valign="top">
-<a name="tools.used"></a><a name="idm80361680"></a><p><b>18.4.3.</b></p>
+<a name="tools.used"></a><a name="idm80442576"></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
@@ -8983,17 +9006,28 @@ REPLACE_FILES.tcl=      # list of tcl scripts which need to be fixed,
     the installed <code class="filename">.packlist</code> file generated by
     most perl5 modules.  This is invoked by defining
     <code class="varname">PERL5_PACKLIST</code> to a space-separated list of
-    paths to packlist files, e.g.:</p>
+    packlist files relative to <code class="varname">PERL5_PACKLIST_DIR</code>
+    (<code class="varname">PERL5_INSTALLVENDORARCH</code> by default),
+    e.g.:</p>
 <pre class="programlisting">
-PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist
+PERL5_PACKLIST= auto/Pg/.packlist
     </pre>
-<p>The variables <code class="varname">PERL5_SITELIB</code>,
-    <code class="varname">PERL5_SITEARCH</code>, and
-    <code class="varname">PERL5_ARCHLIB</code> represent the three locations
-    in which perl5 modules may be installed, and may be used by
-    perl5 packages that don't have a packlist.  These three
-    variables are also substituted for in the
-    <code class="filename">PLIST</code>.</p>
+<p>The perl5 config variables
+    <code class="varname">installarchlib</code>,
+    <code class="varname">installscript</code>,
+    <code class="varname">installvendorbin</code>,
+    <code class="varname">installvendorscript</code>,
+    <code class="varname">installvendorarch</code>,
+    <code class="varname">installvendorlib</code>,
+    <code class="varname">installvendorman1dir</code>, and
+    <code class="varname">installvendorman3dir</code> represent those
+    locations in which components of perl5 modules may be installed,
+    provided as variable with uppercase and prefixed with
+    <code class="varname">PERL5_</code>, e.g. <code class="varname">PERL5_INSTALLARCHLIB</code>
+    and may be used by perl5 packages that don't have a packlist.
+    These variables are also substituted for in the
+    <code class="filename">PLIST</code> as uppercase prefixed with
+    <code class="varname">PERL5_SUB_</code>.</p>
 </div>
 <div class="sect2">
 <div class="titlepage"><div><div><h3 class="title">
@@ -9676,7 +9710,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">
-<a name="idm81902800"></a><dl>
+<a name="idm81992016"></a><dl>
 <dt>22.1. <a href="#devfaq.makeflags">What is the difference between
 	MAKEFLAGS, .MAKEFLAGS and
 	MAKE_FLAGS?</a>
@@ -9721,7 +9755,7 @@ do?</a>
 <tbody>
 <tr class="question">
 <td align="left" valign="top">
-<a name="devfaq.makeflags"></a><a name="idm81902416"></a><p><b>22.1.</b></p>
+<a name="devfaq.makeflags"></a><a name="idm81991632"></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
@@ -9737,7 +9771,7 @@ do?</a>
 </tr>
 <tr class="question">
 <td align="left" valign="top">
-<a name="devfaq.make"></a><a name="idm81898320"></a><p><b>22.2.</b></p>
+<a name="devfaq.make"></a><a name="idm81987536"></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
@@ -9755,7 +9789,7 @@ do?</a>
 </tr>
 <tr class="question">
 <td align="left" valign="top">
-<a name="devfaq.cc"></a><a name="idm81893968"></a><p><b>22.3.</b></p>
+<a name="devfaq.cc"></a><a name="idm81983184"></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
@@ -9773,7 +9807,7 @@ do?</a>
 </tr>
 <tr class="question">
 <td align="left" valign="top">
-<a name="devfaq.bl3flags"></a><a name="idm81889744"></a><p><b>22.4.</b></p>
+<a name="devfaq.bl3flags"></a><a name="idm81978960"></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>,
@@ -9786,7 +9820,7 @@ do?</a>
 </tr>
 <tr class="question">
 <td align="left" valign="top">
-<a name="devfaq.bl3prefix"></a><a name="idm81887568"></a><p><b>22.5.</b></p>
+<a name="devfaq.bl3prefix"></a><a name="idm81976784"></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>
@@ -9802,7 +9836,7 @@ do?</a>
 </tr>
 <tr class="question">
 <td align="left" valign="top">
-<a name="devfaq.master_sites"></a><a name="idm81884496"></a><p><b>22.6.</b></p>
+<a name="devfaq.master_sites"></a><a name="idm81973712"></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
@@ -9826,7 +9860,7 @@ do?</a>
 </tr>
 <tr class="question">
 <td align="left" valign="top">
-<a name="devfaq.mailinglists"></a><a name="idm81876432"></a><p><b>22.7.</b></p>
+<a name="devfaq.mailinglists"></a><a name="idm81965648"></a><p><b>22.7.</b></p>
 </td>
 <td align="left" valign="top"><p>Which mailing lists are there for package
 	developers?</p></td>
@@ -9851,7 +9885,7 @@ do?</a>
 </tr>
 <tr class="question">
 <td align="left" valign="top">
-<a name="devfaq.documentation"></a><a name="idm81872592"></a><p><b>22.8.</b></p>
+<a name="devfaq.documentation"></a><a name="idm81961808"></a><p><b>22.8.</b></p>
 </td>
 <td align="left" valign="top"><p>Where is the pkgsrc
 	documentation?</p></td>
@@ -9899,7 +9933,7 @@ do?</a>
 </tr>
 <tr class="question">
 <td align="left" valign="top">
-<a name="devfaq.too-much-time"></a><a name="idm81866192"></a><p><b>22.9.</b></p>
+<a name="devfaq.too-much-time"></a><a name="idm81955280"></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>
diff --git a/doc/pkgsrc.txt b/doc/pkgsrc.txt
index b947fabdf03..d7a28c9fdee 100644
--- a/doc/pkgsrc.txt
+++ b/doc/pkgsrc.txt
@@ -4824,6 +4824,22 @@ headers and libraries for these dependencies are also symlinked into $
 {BUILDLINK_DIR} whenever the pkg buildlink3.mk file is included. Dependencies
 are only added for directly include buildlink3.mk files.
 
+When providing a buildlink3.mk and including other buildlink3.mk files in it,
+please only add necessary ones. I.e. those whose libraries or header files are
+automatically exposed when the package is use.
+
+In particular, if only an executable (bin/foo) is linked against a library,
+that library does not need to be propagated in the buildlink3.mk file.
+
+The following steps should help you decide if a buildlink3.mk file needs to be
+included:
+
+  * Run ldd on all installed libraries and look against what other libraries
+    they link. The packages providing these must be buildlinked.
+
+  * Look at the installed header files: What headers do they include? The
+    packages providing these files must be buildlinked.
+
 14.2.2. Updating BUILDLINK_API_DEPENDS.pkg and BUILDLINK_ABI_DEPENDS.pkg in
 buildlink3.mk files
 
@@ -7496,15 +7512,19 @@ Perl5 modules will install into different places depending on the version of
 perl used during the build process. To address this, pkgsrc will append lines
 to the PLIST corresponding to the files listed in the installed .packlist file
 generated by most perl5 modules. This is invoked by defining PERL5_PACKLIST to
-a space-separated list of paths to packlist files, e.g.:
+a space-separated list of packlist files relative to PERL5_PACKLIST_DIR
+(PERL5_INSTALLVENDORARCH by default), e.g.:
 
-PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist
+PERL5_PACKLIST= auto/Pg/.packlist
 
 
-The variables PERL5_SITELIB, PERL5_SITEARCH, and PERL5_ARCHLIB represent the
-three locations in which perl5 modules may be installed, and may be used by
-perl5 packages that don't have a packlist. These three variables are also
-substituted for in the PLIST.
+The perl5 config variables installarchlib, installscript, installvendorbin,
+installvendorscript, installvendorarch, installvendorlib, installvendorman1dir,
+and installvendorman3dir represent those locations in which components of perl5
+modules may be installed, provided as variable with uppercase and prefixed with
+PERL5_, e.g. PERL5_INSTALLARCHLIB and may be used by perl5 packages that don't
+have a packlist. These variables are also substituted for in the PLIST as
+uppercase prefixed with PERL5_SUB_.
 
 19.6.7. Packages installing info files