X-Git-Url: https://git.donarmstrong.com/?p=debian%2Fdebian-policy.git;a=blobdiff_plain;f=perl-policy.sgml;h=12cd82c136e46c7f88b38727f12e6687edf8c77b;hp=70c5bfcc7ab149b9a86fe2bbd4b03ad8aeea842c;hb=HEAD;hpb=fee1838470a56f3f5595dfd949ec01010e85c96e

diff --git a/perl-policy.sgml b/perl-policy.sgml
index 70c5bfc..12cd82c 100644
--- a/perl-policy.sgml
+++ b/perl-policy.sgml
@@ -96,7 +96,8 @@
 	  <package>perlapi-<var>abiname</var></package> for all released
 	  package versions it is compatible with. The choice of
 	  <var>abiname</var> is arbitrary, but if it differs from
-	  <tt>$Config{version}</tt>, it must be specified in
+	  <tt>$Config{version}</tt><footnote>see the
+	  <tt>Config</tt> module</footnote>, it must be specified in
 	  <tt>$Config{debian_abi}</tt>.
 	</p>
       </sect>
@@ -145,22 +146,42 @@
 		Modules installed by the local administrator for the
 		current version of Perl (see <ref id="site">).
 	        <example>
-/usr/local/lib/perl/<var>version</var>
-/usr/local/share/perl/<var>version</var>
+$Config{sitearch}  (currently /usr/local/lib/perl/<var>version</var>)
+$Config{sitelib}   (currently /usr/local/share/perl/<var>version</var>)
 		</example>
 		Where <var>version</var> indicates the current Perl
-		version (<tt>$Config{version}</tt><footnote>see the
-		<tt>Config</tt> module</footnote>).
+		version (<tt>$Config{version}</tt>).
 	      </p>
+	      <p>
+		These locations, particularly <tt>$Config{sitearch}</tt>,
+		may change if the binary interface between the
+		Perl interpreter and compiled modules has to be
+		changed in an incompatible way without a change in
+		<var>version</var>. While this will only be done as a
+		last resort, packages should use <tt>$Config{sitelib}</tt>
+		and <tt>$Config{sitearch}</tt>, not hardcode the current
+		locations.<footnote>Build systems based on
+		<tt>ExtUtils::MakeMaker</tt> and <tt>Module::Build</tt>
+		do this automatically.</footnote>
+	      <p>
 	    </item>
 	    <tag><var>vendor</var></tag>
 	    <item>
 	      <p>
 		Packaged modules (see <ref id="module_packages">).
 	        <example>
-/usr/lib/perl5
-/usr/share/perl5
+$Config{vendorarch} (currently /usr/lib/perl5)
+$Config{vendorlib}  (currently /usr/share/perl5)
 	        </example>
+		These locations, particularly
+		<tt>$Config{vendorarch}</tt>, may change if
+		necessary<footnote>For example, to include
+		the multiarch triplet</footnote>.  Packages
+		should use <tt>$Config{vendorlib}</tt> and
+		<tt>$Config{vendorarch}</tt>, not hardcode the current
+		locations.<footnote>Build systems based on
+		<tt>ExtUtils::MakeMaker</tt> and <tt>Module::Build</tt>
+		do this automatically.</footnote>
 	      </p>
 	    </item>
 	    <tag><var>core</var></tag>
@@ -168,9 +189,19 @@
 	      <p>
 		Modules included in the core Perl distribution.
 	        <example>
-/usr/lib/perl/<var>version</var>
-/usr/share/perl/<var>version</var>
+$Config{archlib} (currently /usr/lib/perl/<var>shortversion</var>)
+$Config{privlib} (currently /usr/share/perl/<var>shortversion</var>)
 	        </example>
+		Where <var>shortversion</var> indicates the current Perl major
+		version (for example <tt>5.18</tt>).
+	      </p>
+	      <p>
+		These locations should be considered internal to the <package>
+		perl</package> source package. If necessary, packages should use
+		<tt>$Config{archlib}</tt> and <tt>$Config{privlib}</tt> instead of
+		hardcoding the current locations.<footnote>Build systems based on
+		<tt>ExtUtils::MakeMaker</tt> and <tt>Module::Build</tt>
+		do this automatically.</footnote>
 	      </p>
 	    </item>
 	    <tag><var>site</var> (old)</tag>
@@ -197,8 +228,8 @@
 	  package.
 	</p>
 	<p>
-	  Manual pages distributed with Perl packages must be installed
-	  into the standard directories:
+	  Manual pages distributed with packages built from the perl
+	  source package must be installed into the standard directories:
 	  <taglist>
 	    <tag>Programs</tag>
 	    <item>
@@ -217,6 +248,8 @@
 	      </p>
 	    </item>
 	  </taglist>
+	  The extensions used for manual pages distributed with module
+	  packages are different.  See <ref id="vendor_dirs">.
 	</p>
       </sect>
     </chapt>
@@ -355,14 +388,15 @@ $(MAKE) install DESTDIR=$(CURDIR)/debian/&lt;tmp&gt;
 	</sect1>
 
 	<sect1 id="binary_modules">
-	  <heading>Binary Modules</heading>
+	  <heading>Binary and Other Architecture Dependent Modules</heading>
 	  <p>
 	    Binary modules must specify a dependency on either
 	    <package>perl</package> or <package>perl-base</package> with
 	    a minimum version of the <package>perl</package> package
-	    used to build the module, and must additionally depend on
-	    the expansion of
-	    <package>perlapi-$Config{debian_abi}</package> using
+	    used to build the module. Additionally, all binary modules
+	    (regardless of their installation directory) and any other modules
+	    installed into <tt>$Config{vendorarch}</tt> must depend on the
+	    expansion of <package>perlapi-$Config{debian_abi}</package> using
 	    the <tt>Config</tt> module. If <tt>$Config{debian_abi}</tt>
 	    is empty or not set, <tt>$Config{version}</tt> must be used.
 	  </p>