Bug#83977: PROPOSED] include Perl Policy

[Brendan O'Dea <bod@debian.org>]

Final revision of the Perl policy.  Full text at:

  http://people.debian.org/~bod/perl-policy/perl-policy.sgml

This version incorporates the following major changes:

  * Indicate that the INSTALLDIRS option may be passed via the
    PERL_MM_OPT environment variable (Ben Gertzfield).

  * arch-indep modules need to declare a minimum dependency on the first
    version of perl which changed @INC (Roderick Schertler).

  * Indicate that dependencies on perl-base are a special case.

Given that this proposal has acquired two seconds[0], in absence of any
opposition I will escalate this bug to "normal" in the next day or so.

[0] <87snlpgfno.fsf@glaurung.green-gryphon.com> Manoj Srivastava
    <20010211134043.B26771@azure.humbug.org.au> Anthony Towns

--- perl-policy.sgml.orig	Thu Mar  1 01:44:13 2001
+++ perl-policy.sgml	Tue Apr 17 01:20:49 2001
@@ -12,7 +12,7 @@
 	<name>Brendan O'Dea</name>
 	<email>bod@debian.org</email>
       </author>
-      <version>version 1.17</version>
+      <version>version 1.18</version>
 
       <abstract>
 	This document describes the packaging of Perl within the Debian
@@ -30,14 +30,12 @@
 	  as published by the Free Software Foundation; either version
 	  2 of the License, or (at your option) any later version.
 	</p>
- 
 	<p>
 	  This is distributed in the hope that it will be useful, but
 	  WITHOUT ANY WARRANTY; without even the implied warranty of
 	  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See
 	  the GNU General Public License for more details.
 	</p>
- 
 	<p>
 	  A copy of the GNU General Public License is available as
 	  <tt>/usr/share/common-licences/GPL</tt> in the Debian GNU/Linux
@@ -45,7 +43,6 @@
 	  <url id="http://www.gnu.org/copyleft/gpl.html";
 	  name="The GNU Public Licence">.
 	</p>
-	       
 	<p>
 	  You can also obtain it by writing to the
 	  Free Software Foundation, Inc., 59 Temple Place - Suite 330,
@@ -68,7 +65,7 @@
 	<p>
 	  Only one package may contain the <file>/usr/bin/perl</file>
 	  binary and that package must either be <package>perl</package>
-	  or a dependancy of that package (see <ref id="base">).
+	  or a dependency of that package (see <ref id="base">).
 	</p>
 	<p>
 	  Where possible, Perl should be compiled to provide binary
@@ -97,6 +94,14 @@
 	  scripts, it must be priority <em>required</em> and marked as
 	  <em>essential</em>.
 	</p>
+	<p>
+	  Note that the <package>perl-base</package> package is intended
+	  only to provide for exceptional circumstances and the contents
+	  may change.  In general only packages which form part of the
+	  base system should declare a dependency on
+	  <package>perl-base</package> rather than
+	  <package>perl</package>.
+	</p>
       </sect>
 
       <sect id="paths">
@@ -123,7 +128,8 @@
 /usr/local/share/perl/<var>version</var>
 		</example>
 		Where <var>version</var> indicates the current Perl
-		version (<tt>$Config{version}</tt>).
+		version (<tt>$Config{version}</tt><footnote>see the
+		<tt>Config</tt> module</footnote>).
 	      </p>
 	    </item>
 	    <tag><var>vendor</var></tag>
@@ -152,7 +158,7 @@
 		<var>site</var> directories (as above) for modules
 		installed with previously released
 		<package>perl</package> packages for which the current
-		package is binary compatable are included if present.
+		package is binary compatible are included if present.
 	      </p>
 	    </item>
 	  </taglist>
@@ -186,7 +192,7 @@
 	      <p>
 		Manual pages for modules are installed into
 		<file>/usr/share/man/man3</file> with the extension
-		<tt>.3</tt>.
+		<tt>.3perl</tt>.
 	      </p>
 	    </item>
 	  </taglist>
@@ -282,14 +288,18 @@
 	<heading>Vendor Installation</heading>
 	<p>
 	  A module should use the following lines in the
-	  <file>debian/rules</file> <tt>build</tt> target:
+	  <file>debian/rules</file> <tt>build</tt>
+	  target<footnote>The environment variable <tt>PERL_MM_OPT</tt>
+	  may be used to pass the <tt>INSTALLDIRS=vendor</tt> option in
+	  cases where <file>Makefile.PL</file> is not invoked directly
+	  from <file>debian/rules</file></footnote>:
 	  <example>
 perl Makefile.PL INSTALLDIRS=vendor
 $(MAKE) OPTIMIZE="-O2 -g -Wall"
 	  </example>
 	  and this one to install the results into the temporary tree:
 	  <example>
-$(MAKE) install PREFIX=$(PWD)/debian/tmp/usr
+$(MAKE) install PREFIX=$(CURDIR)/debian/tmp/usr
 	  </example>
 	</p>
 	<p>
@@ -312,7 +322,15 @@
 	    <var>version</var></tt> or <tt>use <var>version</var></tt>
 	    statements must specify a dependency on
 	    <package>perl</package> or <package>perl-base</package> with
-	    the minimum required version.
+	    the minimum required version, or more simply the current
+	    version.
+	  </p>
+	  <p>
+	    In the absence of an explicit requirement,
+	    architecture-independent modules must depend on a minimum
+	    <package>perl</package> or <package>perl-base</package>
+	    version of <tt>5.6.0-16</tt> due to the changes in
+	    <tt>@INC</tt> introduced by that version.
 	  </p>
 	</sect1>
 
@@ -361,8 +379,22 @@
       <sect id="program_deps">
 	<heading>Program Dependencies</heading>
 	<p>
-	  Packages containing perl programs must declare the same
-	  dependencies as outlined for <ref id="indep_modules">.
+	  Programs which require <var>core</var> modules from the
+	  <package>perl</package> package must specify a dependency on
+	  that package.
+	</p>
+	<p>
+	  Programs which contain explicit <tt>require
+	  <var>version</var></tt> or <tt>use <var>version</var></tt>
+	  statements must specify a dependency on
+	  <package>perl</package> or <package>perl-base</package> with
+	  the minimum required version, or more simply the current
+	  version.
+	</p>
+	<p>
+	  As with modules, packages using <prgn>debhelper</prgn> may use
+	  <manref name="dh_perl" section=1> to automatically generate
+	  dependences (see <ref id="dh_perl">).
 	</p>
       </sect>
     </chapt>

Regards,
-- 
Brendan O'Dea                                        bod@compusol.com.au
Compusol Pty. Limited                  (NSW, Australia)  +61 2 9810 3633