Package: debian-policy
Version: 3.9.5.0
X-Debbugs-Cc: debian-p...@lists.debian.org
As discussed in the thread at
https://lists.debian.org/debian-perl/2014/05/msg00035.html
we would like to change the perl search path (@INC) to include the
multiarch triplet, to pave way for future Multi-Arch:same perl module
packages. We're still discussing whether to try to do this for the
upcoming Perl 5.20 or postpone it after jessie, but at the moment I think
it's clear that policy shouldn't recommend hardcoding /usr/lib/perl5 in
Debian packaging anymore.
I'm attaching a patch set for this. The first two changes are minor
cleanups that I discovered while drafting this. At least the first
is clearly just an editorial change and shouldn't need seconds.
I'm not quite sure about the process with second one. Apologies
if I should have filed separate bugs about those.
The third one is the meat of this and changes the documented site,
vendor, and core include paths to be dynamically resolved via the Config
module. The vendor paths have the biggest effect on other packages:
the site directories in /usr/local are in the realm of the local
administrator, and I can't think of anything outside the perl source
package that should need to use the core path.
The fourth patch is only a draft and is included for completeness.
It should not go in the policy before the multiarch path changes are
in unstable.
I've phrased the recommendations as 'should', because changing them to
hard requirements would currently break at least 64 packages. When those
are fixed, I think we should raise the requirements to 'must' level.
I'm copying the debian-perl list for input. Naturally, patches and other
suggestions for improvement are welcome. If there's anything controversial
about the wording I'm proposing, please let me know.
--
Niko Tyni nt...@debian.org
>From ec6a223e9b667b4605fb8340db17b357749cdf12 Mon Sep 17 00:00:00 2001
From: Niko Tyni <nt...@debian.org>
Date: Thu, 15 May 2014 23:35:11 +0300
Subject: [PATCH 1/4] Document that @INC has /usr/lib/perl/5.18, not
/usr/lib/perl/5.18.2
Since at least 5.8.4-8 (Debian sarge release), the Perl search
path for the core modules has used the major version (5.18)
instead of the full one (5.18.2).
---
perl-policy.sgml | 6 ++++--
1 file changed, 4 insertions(+), 2 deletions(-)
diff --git a/perl-policy.sgml b/perl-policy.sgml
index 626c514..abe04d9 100644
--- a/perl-policy.sgml
+++ b/perl-policy.sgml
@@ -168,9 +168,11 @@
<p>
Modules included in the core Perl distribution.
<example>
-/usr/lib/perl/<var>version</var>
-/usr/share/perl/<var>version</var>
+/usr/lib/perl/<var>shortversion</var>
+/usr/share/perl/<var>shortversion</var>
</example>
+ Where <var>shortversion</var> indicates the current Perl major
+ version (for example <tt>5.18</tt>).
</p>
</item>
<tag><var>site</var> (old)</tag>
--
2.0.0.rc2
>From 334756fa12ff637889df2ebdc49db878f1e0da6d Mon Sep 17 00:00:00 2001
From: Niko Tyni <nt...@debian.org>
Date: Fri, 16 May 2014 19:40:35 +0300
Subject: [PATCH 2/4] Move the footnote about the Config module to the first
reference
The new Config reference was introduced in cc34dcc0 but the
footnote wasn't moved accordingly.
---
perl-policy.sgml | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/perl-policy.sgml b/perl-policy.sgml
index abe04d9..54e97d3 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>
@@ -149,8 +150,7 @@
/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>
</item>
<tag><var>vendor</var></tag>
--
2.0.0.rc2
>From 04beab9a142597b57baae68c1888be2ec1977db4 Mon Sep 17 00:00:00 2001
From: Niko Tyni <nt...@debian.org>
Date: Thu, 15 May 2014 23:35:52 +0300
Subject: [PATCH 3/4] 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).
---
perl-policy.sgml | 41 +++++++++++++++++++++++++++++++++++------
1 file changed, 35 insertions(+), 6 deletions(-)
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>
--
2.0.0.rc2
>From 1d21f15a7b42b02393dfa451297a246807dd55ad Mon Sep 17 00:00:00 2001
From: Niko Tyni <nt...@debian.org>
Date: Fri, 16 May 2014 00:13:35 +0300
Subject: [PATCH 4/4] Change vendorarch to include the multiarch triplet
This is currently only a draft. The change will be
implemented in a future perl major version upgrade.
---
perl-policy.sgml | 12 ++++++++----
1 file changed, 8 insertions(+), 4 deletions(-)
diff --git a/perl-policy.sgml b/perl-policy.sgml
index c23f7c3..63fd730 100644
--- a/perl-policy.sgml
+++ b/perl-policy.sgml
@@ -170,14 +170,18 @@ $Config{sitelib} (currently /usr/local/share/perl/<var>version</var>)
<p>
Packaged modules (see <ref id="module_packages">).
<example>
-$Config{vendorarch} (currently /usr/lib/perl5)
+$Config{vendorarch} (currently /usr/lib/<var>triplet</var>/perl5)
$Config{vendorlib} (currently /usr/share/perl5)
</example>
+ Where <var>triplet</var> is the multiarch triplet for
+ the system architecture.
+ </p>
+ <p>
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
+ necessary<footnote>The last change was made
+ 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>
--
2.0.0.rc2
