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

diff --git a/perl-policy.sgml b/perl-policy.sgml
index b05b3fc..12cd82c 100644
--- a/perl-policy.sgml
+++ b/perl-policy.sgml
@@ -1,4 +1,8 @@
-<!doctype debiandoc system>
+<!doctype debiandoc system [
+<!-- include version information so we don't have to hard code it
+     within the document -->
+<!entity % versiondata SYSTEM "version.ent"> %versiondata;
+]>
 
 <debiandoc>
   <book>
@@ -6,17 +10,19 @@
       <title>Debian Perl Policy</title>
       <author>
 	<name>Rapha&euml;l Hertzog</name>
-	<email>hertzog@debian.org</email>
       </author>
       <author>
 	<name>Brendan O'Dea</name>
-	<email>bod@debian.org</email>
       </author>
-      <version>version 1.20</version>
+      <author>
+	<name>The Debian Policy mailing list</name>
+	<email>debian-policy@lists.debian.org</email>
+      </author>
+      <version>version &version;, &date;</version>
 
       <abstract>
 	This document describes the packaging of Perl within the Debian
-	GNU/Linux distribution and the policy requirements for packaged
+	distribution and the policy requirements for packaged
 	Perl programs and modules.
       </abstract>
 
@@ -38,21 +44,33 @@
 	</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
+	  <tt>/usr/share/common-licenses/GPL</tt> in the Debian
 	  distribution or on the World Wide Web at 
 	  <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,
-	  Boston, MA 02111-1307, USA.
+	  Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
+	  Boston, MA 02110-1301, USA. 
 	</p>
       </copyright>
     </titlepag>
 
     <toc detail="sect">
 
+    <chapt>
+      <heading>About this document</heading>
+      <p>
+	This document is distributed as the <tt>perl-policy</tt> files
+	in the Debian package
+        <package><url name="debian-policy" id="http://packages.debian.org/debian-policy"></package>.
+	It is also available from the Debian web mirrors at
+	<tt><url name="/doc/packaging-manuals/perl-policy/"
+		id="http://www.debian.org/doc/packaging-manuals/perl-policy/"></tt>.
+      </p>
+    </chapt>
+
     <chapt id="perl">
       <heading>Perl Packaging</heading>
       <sect id="versions">
@@ -75,8 +93,12 @@
 	</p>
 	<p>
 	  The <package>perl-base</package> package must provide
-	  <package>perlapi-<var>version</var></package> for all released
-	  versions it is compatible with.
+	  <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><footnote>see the
+	  <tt>Config</tt> module</footnote>, it must be specified in
+	  <tt>$Config{debian_abi}</tt>.
 	</p>
       </sect>
 
@@ -89,18 +111,18 @@
 	  the binary and a basic set of modules.
 	</p>
 	<p>
-	  As Perl is currently used by such things as
-	  <file>update-alternatives</file> and some package maintainer
-	  scripts, it must be priority <em>required</em> and marked as
-	  <em>essential</em>.
+	  As Perl has been part of the essential set for some time and is
+	  used without dependencies by such things as package maintainer
+	  scripts, <package>perl-base</package> 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>.
+	  may change.  In general, only packages which form part of the
+	  base system should use only the facilities
+	  of <package>perl-base</package> rather than declaring a
+	  dependency on <package>perl</package>.
 	</p>
       </sect>
 
@@ -124,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>
@@ -147,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>
@@ -176,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>
@@ -196,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>
@@ -277,10 +331,17 @@ make install
 	<heading>Module Package Names</heading>
 	<p>
 	  Perl module packages should be named for the primary module
-	  provided.  The naming convention for module <tt>Foo::Bar</tt>
-	  is <package>libfoo-bar-perl</package>.  Packages which include
-	  multiple modules may additionally include provides for those
-	  modules using the same convention.
+	  provided.  The naming convention is to lowercase the Perl module
+	  name, prepend, <tt>lib</tt>, change all occurrences
+	  of <tt>::</tt> to <tt>-</tt>, and append <tt>-perl</tt>.  For
+	  example:
+	  <example>
+Foo::Bar        libfoo-bar-perl
+Foo::Bar::Baz   libfoo-bar-baz-perl
+Foo::BarBaz     libfoo-barbaz-perl
+	  </example>
+	  Packages which include multiple modules may additionally include
+	  provides for the additional modules using the same convention.
 	</p>
       </sect>
 
@@ -299,16 +360,12 @@ $(MAKE) OPTIMIZE="-O2 -g -Wall"
 	  </example>
 	  and this one to install the results into the temporary tree:
 	  <example>
-$(MAKE) install PREFIX=$(CURDIR)/debian/&lt;tmp&gt;/usr
+$(MAKE) install DESTDIR=$(CURDIR)/debian/&lt;tmp&gt;
 	  </example><footnote>
 	    <p>Replace &lt;tmp&gt; with the appropriate directory
 	    (nominally just tmp)</p>
 	  </footnote>
 	</p>
-	<p>
-	  A <tt>Build-Depends</tt> on <tt>perl (>= 5.6.0-16)</tt> is
-	  required.
-	</p>
       </sect>
 
       <sect id="module_deps">
@@ -328,25 +385,20 @@ $(MAKE) install PREFIX=$(CURDIR)/debian/&lt;tmp&gt;/usr
 	    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>
 
 	<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{version}</package> using
-	    the <tt>Config</tt> module.
+	    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>
 	</sect1>
 
@@ -356,8 +408,13 @@ $(MAKE) install PREFIX=$(CURDIR)/debian/&lt;tmp&gt;/usr
 	    Rather than hard-coding the dependencies into the control
 	    file, using a substitution such as <tt>${perl:Depends}</tt>
 	    is suggested.  This allows the dependencies to be determined
-	    as build time and written to the <file>substvars</file> file
-	    in the form <tt>perl:Depends=<var>deps</var></tt>.
+	    at build time and written to the <file>substvars</file> file
+	    in the form
+	    <tt>perl:Depends=<var>deps</var></tt>.<footnote>
+	      <p>Please note that dependencies caused by versioned
+	      uses and on separately packaged modules are not included
+	      in this variable and must be explicitly included.</p>
+	    </footnote>
 	  </p>
 	  <p>
 	    Packages built with <prgn>debhelper</prgn> may use
@@ -438,6 +495,26 @@ perl -MExtUtils::Embed -e ldopts
 	  package must depend upon it explicitly.
 	</p>
       </sect>
+
+      <sect id="perl_upgrades">
+        <heading>Perl Package Upgrades</heading>
+        <p>
+          Starting from <package>perl</package> 5.12.3-2, a dpkg trigger
+          named <var>perl-major-upgrade</var> will be triggered by the
+          postinst of the <package>perl</package> package during major
+          upgrades. Some examples of things which constitute a major upgrade
+          are an upgrade which would change the value of versioned
+          directories in <tt>@INC</tt>, or one which changes <tt>abiname</tt>.
+          Any package may declare an interest in the trigger, especially
+          packages including long-running daemons which would stop working
+          until restart.
+        </p>
+        <p>
+          It is suggested that such packages include an appropriate section
+          in their postinst to handle the trigger by restarting relevant
+          daemons or notifying users of further action.
+        </p>
+      </sect>
     </chapt>
 
     <appendix id="perl6">
@@ -469,3 +546,6 @@ perl -MExtUtils::Embed -e ldopts
     </appendix>
   </book>
 </debiandoc>
+<!-- Local variables: -->
+<!-- indent-tabs-mode: t -->
+<!-- End: -->