-<!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>
<name>The Debian Policy mailing list</name>
<email>debian-policy@lists.debian.org</email>
</author>
- <version>version 1.20</version>
+ <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>
</p>
<p>
A copy of the GNU General Public License is available as
- <tt>/usr/share/common-licenses/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">
</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>
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>
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>
<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>
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>
</p>
</item>
</taglist>
+ The extensions used for manual pages distributed with module
+ packages are different. See <ref id="vendor_dirs">.
</p>
</sect>
</chapt>
<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>
</example>
and this one to install the results into the temporary tree:
<example>
-$(MAKE) install PREFIX=$(CURDIR)/debian/<tmp>/usr
+$(MAKE) install DESTDIR=$(CURDIR)/debian/<tmp>
</example><footnote>
<p>Replace <tmp> 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">
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>
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
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">
</appendix>
</book>
</debiandoc>
+<!-- Local variables: -->
+<!-- indent-tabs-mode: t -->
+<!-- End: -->
projects / debian / debian-policy.git / blobdiff