From: Niko Tyni <ntyni@debian.org>
Date: Thu, 15 May 2014 20:35:52 +0000 (+0300)
Subject: Recommend $Config{vendorarch} et al. over hardcoding @INC locations
X-Git-Url: https://git.donarmstrong.com/?p=debian%2Fdebian-policy.git;a=commitdiff_plain;h=40b04e9fdc32136c52ee6ef3a053e0b01375d2fd

Recommend $Config{vendorarch} et al. over hardcoding @INC locations

The most pressing need for this is for including the multiarch
triplet in vendorarch, but it is also a logical continuation for the
$Config{debian_abi} concept introduced earlier.

If we ever have to make a binary incompatible change without a major
version bump, we'll probably have to change @INC too, at least for
locally installed binary modules (sitearch).
---

diff --git a/perl-policy.sgml b/perl-policy.sgml
index 54e97d3..c23f7c3 100644
--- a/perl-policy.sgml
+++ b/perl-policy.sgml
@@ -146,21 +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>).
 	      </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,12 +189,20 @@
 	      <p>
 		Modules included in the core Perl distribution.
 	        <example>
-/usr/lib/perl/<var>shortversion</var>
-/usr/share/perl/<var>shortversion</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>
 	    <item>