File: //usr/share/doc/debian-policy/perl-policy-1.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Debian Perl Policy</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot"></meta><meta name="description" content="This document describes the packaging of Perl within the Debian distribution and the policy requirements for packaged Perl programs and modules."></meta></head><body><div xml:lang="en" class="book"><div class="titlepage"><div><div><h1 class="title"><a id="id-1"></a>Debian Perl Policy</h1></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Raphaël</span> <span class="surname">Hertzog</span></h3></div><div class="author"><h3 class="author"><span class="firstname">Brendan</span> <span class="surname">O'Dea</span></h3></div><div class="author"><h3 class="author"><span class="othername">The Debian Policy Mailing List</span></h3><code class="email"><<a class="email" href="mailto:debian-policy@lists.debian.org">debian-policy@lists.debian.org</a>></code></div></div></div><div><p class="releaseinfo">version 4.6.0.1</p></div><div><p class="copyright">Copyright © 1999, 2001 Raphaël Hertzog, Brendan O'Dea</p></div><div><div class="legalnotice"><a id="id-1.2.6"></a><p>
These are the copyright dates of the original Debian Perl Policy.
Since then, this document has been updated by many others. No
comprehensive collection of copyright notices for subsequent work
exists.
</p><p>
This manual is free software; you may redistribute it and/or
modify it under the terms of the GNU General Public License 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
<code class="filename">/usr/share/common-licenses/GPL</code> in the Debian
distribution or on the World Wide Web at <a class="ulink" href="https://www.gnu.org/licenses/" target="_top">https://www.gnu.org/licenses/</a>.
</p></div></div><div><p class="pubdate">2021-08-18</p></div><div><div class="abstract"><p class="title"><strong>Abstract</strong></p><p>
This document describes the packaging of Perl within the Debian
distribution and the policy requirements for packaged Perl
programs and modules.
</p></div></div></div><hr></hr></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="chapter"><a href="#ch1">1. About this document</a></span></dt><dt><span class="chapter"><a href="#ch-perl">2. Perl Packaging</a></span></dt><dd><dl><dt><span class="section"><a href="#s-versions">2.1. Versions</a></span></dt><dt><span class="section"><a href="#s-base">2.2. Base Package</a></span></dt><dt><span class="section"><a href="#s-paths">2.3. Module Path</a></span></dt><dt><span class="section"><a href="#s-docs">2.4. Documentation</a></span></dt></dl></dd><dt><span class="chapter"><a href="#ch-site">3. Locally Installed Modules</a></span></dt><dd><dl><dt><span class="section"><a href="#s-site-dirs">3.1. Site Directories</a></span></dt><dt><span class="section"><a href="#s-site-install">3.2. Site Installation</a></span></dt></dl></dd><dt><span class="chapter"><a href="#ch-module_packages">4. Packaged Modules</a></span></dt><dd><dl><dt><span class="section"><a href="#s-vendor-dirs">4.1. Vendor Directories</a></span></dt><dt><span class="section"><a href="#s-package-names">4.2. Module Package Names</a></span></dt><dt><span class="section"><a href="#s-vendor-install">4.3. Vendor Installation</a></span></dt><dt><span class="section"><a href="#s-module-deps">4.4. Module Dependencies</a></span></dt><dd><dl><dt><span class="section"><a href="#s-indep-modules">4.4.1. Architecture-Independent Modules</a></span></dt><dt><span class="section"><a href="#s-binary-modules">4.4.2. Binary and Other Architecture Dependent Modules</a></span></dt><dt><span class="section"><a href="#s-dh-perl">4.4.3. Automating Perl Dependencies</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#ch-programs">5. Perl Programs</a></span></dt><dd><dl><dt><span class="section"><a href="#s-hash-bang">5.1. Script Magic</a></span></dt><dt><span class="section"><a href="#s-program-deps">5.2. Program Dependencies</a></span></dt></dl></dd><dt><span class="chapter"><a href="#ch-embed">6. Programs Embedding Perl</a></span></dt><dd><dl><dt><span class="section"><a href="#s-build-embedded">6.1. Building Embedded Programs</a></span></dt><dt><span class="section"><a href="#s-embedded-deps">6.2. Embedded Perl Dependencies</a></span></dt><dt><span class="section"><a href="#s-perl-upgrades">6.3. Perl Package Upgrades</a></span></dt></dl></dd><dt><span class="appendix"><a href="#ap-perl6">A. Perl 6</a></span></dt></dl></div><div class="list-of-tables"><p><strong>List of Tables</strong></p><dl><dt>4.1. <a href="#id-1.6.3.3">Module to package mappings</a></dt></dl></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="ch1"></a>Chapter 1. About this document</h1></div></div></div><p>
This document is distributed as the <code class="literal">perl-policy</code>
files in the Debian package <code class="systemitem"><a class="ulink" href="https://packages.debian.org/debian-policy" target="_top">debian-policy</a></code>.
It is also available from the Debian web mirrors at <a class="ulink" href="https://www.debian.org/doc/packaging-manuals/perl-policy/" target="_top">https://www.debian.org/doc/packaging-manuals/perl-policy/</a>.
</p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="ch-perl"></a>Chapter 2. Perl Packaging</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="#s-versions">2.1. Versions</a></span></dt><dt><span class="section"><a href="#s-base">2.2. Base Package</a></span></dt><dt><span class="section"><a href="#s-paths">2.3. Module Path</a></span></dt><dt><span class="section"><a href="#s-docs">2.4. Documentation</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="s-versions"></a>2.1. Versions</h2></div></div></div><p>
At any given time, the package <code class="systemitem">perl</code> should represent the current
stable upstream version of Perl revision 5 (see <a class="xref" href="#ap-perl6" title="Appendix A. Perl 6">Appendix A, <em>Perl 6</em></a>).
</p><p>
Only one package may contain the
<code class="filename">/usr/bin/perl</code> binary and that package must
either be <code class="systemitem">perl</code> or a
dependency of that package (see <a class="xref" href="#s-base" title="2.2. Base Package">Section 2.2, “Base Package”</a>).
</p><p>
Where possible, Perl should be compiled to provide binary
compatibility to at least the last released package version to
allow a grace period over which binary module packages may be
re-built against the new package (see <a class="xref" href="#s-binary-modules" title="4.4.2. Binary and Other Architecture Dependent Modules">Section 4.4.2, “Binary and Other Architecture Dependent Modules”</a>).
</p><p>
The <code class="systemitem">perl-base</code> package must
provide <code class="systemitem">perlapi-<em class="replaceable"><code>abiname</code></em></code>
for all released package versions it is compatible with. The
choice of <em class="replaceable"><code>abiname</code></em> is arbitrary, but if
it differs from
<code class="literal">$Config{version}</code><a href="#ftn.id-1.4.2.5.5" class="footnote" id="id-1.4.2.5.5"><sup class="footnote">[1]</sup></a>, it must be
specified in <code class="literal">$Config{debian_abi}</code>.
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="s-base"></a>2.2. Base Package</h2></div></div></div><p>
In order to provide a minimal installation of Perl for use by
applications without requiring the whole of Perl to be installed,
the <code class="systemitem">perl-base</code> package
contains the binary and a basic set of modules.
</p><p>
As Perl has been part of the essential set for some time and is
used without dependencies by such things as package maintainer
scripts, <code class="systemitem">perl-base</code> must be
priority <span class="emphasis"><em>required</em></span> and marked as
<span class="emphasis"><em>essential</em></span>.
</p><p>
Note that the <code class="systemitem">perl-base</code>
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 use only the facilities of
<code class="systemitem">perl-base</code> rather than
declaring a dependency on <code class="systemitem">perl</code>.
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="s-paths"></a>2.3. Module Path</h2></div></div></div><p>
Perl searches several different locations for modules, referred to
in this document as <em class="replaceable"><code>core</code></em> in which
modules distributed with Perl are installed,
<em class="replaceable"><code>vendor</code></em> for packaged modules and
<em class="replaceable"><code>site</code></em> for modules installed by the local
administrator.
</p><p>
The module search path (<code class="literal">@INC</code>) in the current
Debian packages has been ordered to include these locations in the
following order<a href="#ftn.id-1.4.4.3.2" class="footnote" id="id-1.4.4.3.2"><sup class="footnote">[2]</sup></a>
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>site</code></em> (current)</span></dt><dd><p>
Modules installed by the local administrator for the current
version of Perl (see <a class="xref" href="#ch-site" title="Chapter 3. Locally Installed Modules">Chapter 3, <em>Locally Installed Modules</em></a>).
</p><pre class="screen">
$Config{sitearch} (currently /usr/local/lib/<em class="replaceable"><code>arch-triplet</code></em>/perl/<em class="replaceable"><code>version</code></em>)
$Config{sitelib} (currently /usr/local/share/perl/<em class="replaceable"><code>version</code></em>)</pre><p>
Where <em class="replaceable"><code>version</code></em> indicates the
current Perl version (<code class="literal">$Config{version}</code>).
</p><p>
These locations, particularly
<code class="literal">$Config{sitearch}</code>, 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 <em class="replaceable"><code>version</code></em>. While this
will only be done as a last resort, packages should use
<code class="literal">$Config{sitelib}</code> and
<code class="literal">$Config{sitearch}</code>, not hardcode the
current locations.<a href="#ftn.id-1.4.4.4.1.2.4.5" class="footnote" id="id-1.4.4.4.1.2.4.5"><sup class="footnote">[3]</sup></a>
</p></dd><dt><span class="term"><em class="replaceable"><code>vendor</code></em></span></dt><dd><p>
Packaged modules (see <a class="xref" href="#ch-module_packages" title="Chapter 4. Packaged Modules">Chapter 4, <em>Packaged Modules</em></a>).
</p><pre class="screen">
$Config{vendorarch} (currently /usr/lib/<em class="replaceable"><code>arch-triplet</code></em>/perl5/<em class="replaceable"><code>shortversion</code></em>)
$Config{vendorlib} (currently /usr/share/perl5)</pre><p>
Where <em class="replaceable"><code>shortversion</code></em> indicates the
current Perl major version (for example
<code class="literal">5.22</code>).
</p><p>
These locations, particularly
<code class="literal">$Config{vendorarch}</code>, may change if
necessary<a href="#ftn.id-1.4.4.4.2.2.4.2" class="footnote" id="id-1.4.4.4.2.2.4.2"><sup class="footnote">[4]</sup></a>. Packages should use
<code class="literal">$Config{vendorlib}</code> and
<code class="literal">$Config{vendorarch}</code>, not hardcode the
current locations.<a href="#ftn.id-1.4.4.4.2.2.4.5" class="footnote" id="id-1.4.4.4.2.2.4.5"><sup class="footnote">[5]</sup></a>
</p></dd><dt><span class="term"><em class="replaceable"><code>core</code></em></span></dt><dd><p>
Modules included in the core Perl distribution.
</p><pre class="screen">
$Config{archlib} (currently /usr/lib/<em class="replaceable"><code>arch-triplet</code></em>/perl/<em class="replaceable"><code>shortversion</code></em>)
$Config{privlib} (currently /usr/share/perl/<em class="replaceable"><code>shortversion</code></em>)</pre><p>
Where <em class="replaceable"><code>shortversion</code></em> indicates the
current Perl major version (for example
<code class="literal">5.22</code>).
</p><p>
These locations should be considered internal to the
<code class="systemitem">perl</code> source package.
If necessary, packages should use
<code class="literal">$Config{archlib}</code> and
<code class="literal">$Config{privlib}</code> instead of hardcoding
the current locations.<a href="#ftn.id-1.4.4.4.3.2.4.4" class="footnote" id="id-1.4.4.4.3.2.4.4"><sup class="footnote">[6]</sup></a>
</p></dd><dt><span class="term"><em class="replaceable"><code>site</code></em> (old)</span></dt><dd><p>
<em class="replaceable"><code>site</code></em> directories (as above) for
modules installed with previously released <code class="systemitem">perl</code> packages for which the
current package is binary compatible are included if
present.
</p></dd></dl></div><p>
In each of the directory pairs above, the <code class="filename">lib</code>
component is for binary (XS) modules, and
<code class="filename">share</code> for architecture-independent
(pure-perl) modules.
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="s-docs"></a>2.4. Documentation</h2></div></div></div><p>
The POD files and manual pages which do not refer to programs may
be split out into a separate <code class="systemitem">perl-doc</code> package.
</p><p>
Manual pages distributed with packages built from the perl source
package must be installed into the standard directories:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Programs</span></dt><dd><p>
Manual pages for programs and scripts are installed into
<code class="filename">/usr/share/man/man1</code> with the extension
<code class="literal">.1</code>.
</p></dd><dt><span class="term">Modules</span></dt><dd><p>
Manual pages for modules are installed into
<code class="filename">/usr/share/man/man3</code> with the extension
<code class="literal">.3perl</code>.
</p></dd></dl></div><p>
The extensions used for manual pages distributed with module
packages are different. See <a class="xref" href="#s-vendor-dirs" title="4.1. Vendor Directories">Section 4.1, “Vendor Directories”</a>.
</p></div><div class="footnotes"><br></br><hr style="width:100; text-align:left;margin-left: 0"></hr><div id="ftn.id-1.4.2.5.5" class="footnote"><p><a href="#id-1.4.2.5.5" class="para"><sup class="para">[1] </sup></a> see the
<code class="literal">Config</code> module </p></div><div id="ftn.id-1.4.4.3.2" class="footnote"><p><a href="#id-1.4.4.3.2" class="para"><sup class="para">[2] </sup></a>@INC contains other paths which
should be considered internal to the implementation of the perl
packaging</p></div><div id="ftn.id-1.4.4.4.1.2.4.5" class="footnote"><p><a href="#id-1.4.4.4.1.2.4.5" class="para"><sup class="para">[3] </sup></a> Build systems based on
<code class="literal">ExtUtils::MakeMaker</code> and
<code class="literal">Module::Build</code> do this
automatically.</p></div><div id="ftn.id-1.4.4.4.2.2.4.2" class="footnote"><p><a href="#id-1.4.4.4.2.2.4.2" class="para"><sup class="para">[4] </sup></a> For example, to include the
multiarch triplet </p></div><div id="ftn.id-1.4.4.4.2.2.4.5" class="footnote"><p><a href="#id-1.4.4.4.2.2.4.5" class="para"><sup class="para">[5] </sup></a> Build systems based on
<code class="literal">ExtUtils::MakeMaker</code> and
<code class="literal">Module::Build</code> do this automatically.
</p></div><div id="ftn.id-1.4.4.4.3.2.4.4" class="footnote"><p><a href="#id-1.4.4.4.3.2.4.4" class="para"><sup class="para">[6] </sup></a> Build systems based
on <code class="literal">ExtUtils::MakeMaker</code> and
<code class="literal">Module::Build</code> do this automatically.
</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="ch-site"></a>Chapter 3. Locally Installed Modules</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="#s-site-dirs">3.1. Site Directories</a></span></dt><dt><span class="section"><a href="#s-site-install">3.2. Site Installation</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="s-site-dirs"></a>3.1. Site Directories</h2></div></div></div><p>
The Perl packages must provide a mechanism for the local
administrator to install modules under
<code class="filename">/usr/local</code> but must not create or remove
those directories.
</p><p>
Modules should be installed to the directories described above in
<a class="xref" href="#s-paths" title="2.3. Module Path">Section 2.3, “Module Path”</a> as <em class="replaceable"><code>site</code></em>
(current), programs to <code class="filename">/usr/local/bin</code> and
manual pages under <code class="filename">/usr/local/man</code>.
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="s-site-install"></a>3.2. Site Installation</h2></div></div></div><p>
The following commands should be sufficient in the majority of
cases for the local administrator to install modules and must
create directories as required:
</p><pre class="screen">
perl Makefile.PL
make install</pre></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="ch-module_packages"></a>Chapter 4. Packaged Modules</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="#s-vendor-dirs">4.1. Vendor Directories</a></span></dt><dt><span class="section"><a href="#s-package-names">4.2. Module Package Names</a></span></dt><dt><span class="section"><a href="#s-vendor-install">4.3. Vendor Installation</a></span></dt><dt><span class="section"><a href="#s-module-deps">4.4. Module Dependencies</a></span></dt><dd><dl><dt><span class="section"><a href="#s-indep-modules">4.4.1. Architecture-Independent Modules</a></span></dt><dt><span class="section"><a href="#s-binary-modules">4.4.2. Binary and Other Architecture Dependent Modules</a></span></dt><dt><span class="section"><a href="#s-dh-perl">4.4.3. Automating Perl Dependencies</a></span></dt></dl></dd></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="s-vendor-dirs"></a>4.1. Vendor Directories</h2></div></div></div><p>
The installation directory for Debian modules must be different
from that for <em class="replaceable"><code>core</code></em> and
<em class="replaceable"><code>site</code></em> modules.
</p><p>
The current Perl packaging uses the
<em class="replaceable"><code>vendor</code></em> directories for this purpose,
which are at present as described in <a class="xref" href="#s-paths" title="2.3. Module Path">Section 2.3, “Module Path”</a> as
<em class="replaceable"><code>vendor</code></em>.
</p><p>
The Perl distribution includes many modules available separately
from <a class="ulink" href="https://www.cpan.org/" target="_top">CPAN</a> which may
have a newer version. The intent of the <code class="literal">@INC</code>
ordering (described in <a class="xref" href="#s-paths" title="2.3. Module Path">Section 2.3, “Module Path”</a>) is to allow such
modules to be packaged to <em class="replaceable"><code>vendor</code></em> which
take precedence over the version in
<em class="replaceable"><code>core</code></em>. A packaged module which shadows
a <em class="replaceable"><code>core</code></em> module in this way must be a
newer version.
</p><p>
Module packages must install manual pages into the standard
directories (see <a class="xref" href="#s-docs" title="2.4. Documentation">Section 2.4, “Documentation”</a>) using the extensions
<code class="literal">.1p</code> and <code class="literal">.3pm</code> to ensure that
no conflict arises where a packaged module duplicates a
<em class="replaceable"><code>core</code></em> module.
</p><p>
<code class="filename">.packlist</code> files should not be installed.
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="s-package-names"></a>4.2. Module Package Names</h2></div></div></div><p>
Perl module packages should be named for the primary module
provided. The naming convention is to lowercase the Perl module
name, prepend, <code class="literal">lib</code>, change all occurrences of
<code class="literal">::</code> to <code class="literal">-</code>, and append
<code class="literal">-perl</code>. For example:
</p><div class="table"><a id="id-1.6.3.3"></a><p class="title"><strong>Table 4.1. Module to package mappings</strong></p><div class="table-contents"><table class="table" summary="Module to package mappings" border="1"><colgroup><col></col><col></col></colgroup><thead><tr><th>Module</th><th>Package</th></tr></thead><tbody><tr><td>Foo::Bar</td><td>libfoo-bar-perl</td></tr><tr><td>Foo::Bar::Baz</td><td>libfoo-bar-baz-perl</td></tr><tr><td>Foo::BarBaz</td><td>libfoo-barbaz-perl</td></tr></tbody></table></div></div><br class="table-break"></br><p>
Packages which include multiple modules may additionally include
provides for the additional modules using the same convention.
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="s-vendor-install"></a>4.3. Vendor Installation</h2></div></div></div><p>
A module should use the following lines in the
<code class="filename">debian/rules</code> <code class="literal">build</code>
target:
<a href="#ftn.id-1.6.4.2.3" class="footnote" id="id-1.6.4.2.3"><sup class="footnote">[7]</sup></a>
</p><pre class="screen">
perl Makefile.PL INSTALLDIRS=vendor
$(MAKE) OPTIMIZE="-O2 -g -Wall"</pre><p>
and this one to install the results into the temporary tree:
</p><pre class="screen">$(MAKE) install DESTDIR=$(CURDIR)/debian/<tmp></pre><p>
<a href="#ftn.id-1.6.4.6.1" class="footnote" id="id-1.6.4.6.1"><sup class="footnote">[8]</sup></a>
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="s-module-deps"></a>4.4. Module Dependencies</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="s-indep-modules"></a>4.4.1. Architecture-Independent Modules</h3></div></div></div><p>
Architecture-independent modules which require
<em class="replaceable"><code>core</code></em> modules from the <code class="systemitem">perl</code> package must specify a
dependency on that package.
</p><p>
Modules which contain explicit <code class="literal">require
<em class="replaceable"><code>version</code></em></code> or <code class="literal">use
<em class="replaceable"><code>version</code></em></code> statements must
specify a dependency on <code class="systemitem">perl</code> or <code class="systemitem">perl-base</code> with the minimum required
version, or more simply the current version.
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="s-binary-modules"></a>4.4.2. Binary and Other Architecture Dependent Modules</h3></div></div></div><p>
Binary modules must specify a dependency on either <code class="systemitem">perl</code> or <code class="systemitem">perl-base</code> with a minimum version of
the <code class="systemitem">perl</code> package used to
build the module. Additionally, all binary modules (regardless
of their installation directory) and any other modules installed
into <code class="literal">$Config{vendorarch}</code> must depend on the
expansion of <code class="systemitem">perlapi-$Config{debian_abi}</code> using
the <code class="literal">Config</code> module. If
<code class="literal">$Config{debian_abi}</code> is empty or not set,
<code class="literal">$Config{version}</code> must be used.
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="s-dh-perl"></a>4.4.3. Automating Perl Dependencies</h3></div></div></div><p>
Rather than hard-coding the dependencies into the control file,
using a substitution such as <code class="literal">${perl:Depends}</code>
is suggested. This allows the dependencies to be determined at
build time and written to the <code class="filename">substvars</code>
file in the form
<code class="literal">perl:Depends=<em class="replaceable"><code>deps</code></em></code>.<a href="#ftn.id-1.6.5.4.2.4" class="footnote" id="id-1.6.5.4.2.4"><sup class="footnote">[9]</sup></a>
</p><p>
Packages built with <span class="command"><strong>debhelper</strong></span> may use
<span class="citerefentry"><span class="refentrytitle">dh_perl</span>(1)</span>
to generate this substitution automatically. This additionally
requires a versioned <code class="literal">Build-Depends</code> (or
<code class="literal">Build-Depends-Indep</code>) on <code class="literal">debhelper
(>= 3.0.18)</code>.
</p></div></div><div class="footnotes"><br></br><hr style="width:100; text-align:left;margin-left: 0"></hr><div id="ftn.id-1.6.4.2.3" class="footnote"><p><a href="#id-1.6.4.2.3" class="para"><sup class="para">[7] </sup></a>
The environment variable <code class="literal">PERL_MM_OPT</code> may be
used to pass the <code class="literal">INSTALLDIRS=vendor</code> option
in cases where <code class="filename">Makefile.PL</code> is not invoked
directly from
<code class="filename">debian/rules</code>
</p></div><div id="ftn.id-1.6.4.6.1" class="footnote"><p><a href="#id-1.6.4.6.1" class="para"><sup class="para">[8] </sup></a>Replace <tmp> with the appropriate directory
(nominally just tmp)</p></div><div id="ftn.id-1.6.5.4.2.4" class="footnote"><p><a href="#id-1.6.5.4.2.4" class="para"><sup class="para">[9] </sup></a>
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></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="ch-programs"></a>Chapter 5. Perl Programs</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="#s-hash-bang">5.1. Script Magic</a></span></dt><dt><span class="section"><a href="#s-program-deps">5.2. Program Dependencies</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="s-hash-bang"></a>5.1. Script Magic</h2></div></div></div><p>
All packaged perl programs should start with
<code class="literal">#!/usr/bin/perl</code> and may append such flags as
are required.
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="s-program-deps"></a>5.2. Program Dependencies</h2></div></div></div><p>
Programs which require <em class="replaceable"><code>core</code></em> modules
from the <code class="systemitem">perl</code> package must
specify a dependency on that package.
</p><p>
Programs which contain explicit <code class="literal">require
<em class="replaceable"><code>version</code></em></code> or <code class="literal">use
<em class="replaceable"><code>version</code></em></code> statements must
specify a dependency on <code class="systemitem">perl</code> or <code class="systemitem">perl-base</code> with the minimum required
version, or more simply the current version.
</p><p>
As with modules, packages using <span class="command"><strong>debhelper</strong></span> may
use
<span class="citerefentry"><span class="refentrytitle">dh_perl</span>(1)</span>
to automatically generate dependencies (see <a class="xref" href="#s-dh-perl" title="4.4.3. Automating Perl Dependencies">Section 4.4.3, “Automating Perl Dependencies”</a>).
</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="ch-embed"></a>Chapter 6. Programs Embedding Perl</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="#s-build-embedded">6.1. Building Embedded Programs</a></span></dt><dt><span class="section"><a href="#s-embedded-deps">6.2. Embedded Perl Dependencies</a></span></dt><dt><span class="section"><a href="#s-perl-upgrades">6.3. Perl Package Upgrades</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="s-build-embedded"></a>6.1. Building Embedded Programs</h2></div></div></div><p>
Programs which embed a perl interpreter must declare a
<code class="literal">Build-Depends</code> on <code class="systemitem">libperl-dev</code>.
</p><p>
The default linker options produced by
</p><pre class="screen">perl -MExtUtils::Embed -e ldopts</pre><p>
will link against the dynamic <code class="literal">libperl</code>. If
programs wish to link to the static library, then
<code class="literal">-lperl</code> should be changed to
<code class="filename">/usr/lib/libperl.a</code> in those options.
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="s-embedded-deps"></a>6.2. Embedded Perl Dependencies</h2></div></div></div><p>
Dependencies for programs linking against the shared Perl library
will be automatically created by
<span class="command"><strong>dpkg-shlibdeps</strong></span>. Note however that the shared
perl library package only suggests <code class="systemitem">perl-base</code> and packages requiring any
<em class="replaceable"><code>core</code></em> modules from the <code class="systemitem">perl</code> package must depend upon it
explicitly.
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="s-perl-upgrades"></a>6.3. Perl Package Upgrades</h2></div></div></div><p>
Starting from <code class="systemitem">perl</code>
5.12.3-2, a dpkg trigger named
<em class="replaceable"><code>perl-major-upgrade</code></em> will be triggered by
the postinst of the <code class="systemitem">perl</code>
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 <code class="literal">@INC</code>, or one
which changes <code class="literal">abiname</code>. 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></div></div><div class="appendix"><div class="titlepage"><div><div><h1 class="title"><a id="ap-perl6"></a>Appendix A. Perl 6</h1></div></div></div><p>
The current stable upstream version at the time of this writing is
5.6.0. There is currently work in progress on the next major
revision, although the specifications have yet to be finalised.
</p><p>
It is anticipated that when Perl 6 is released it will initially be
packaged as <code class="systemitem">perl6</code>, install
the binary as <code class="filename">/usr/bin/perl6</code> and use different
directories for packaged modules to <code class="systemitem">perl</code>:
</p><pre class="screen">
/usr/lib/perl6
/usr/share/perl6</pre><p>
This will allow Perl 5 and 6 packages and modules (which should be
packaged as <code class="systemitem">libfoo-bar-perl6</code>), to co-exist for as
long as required.
</p><p>
At some stage in the future when Perl 6 is sufficiently mature, the
package naming may be reversed such that the <code class="systemitem">perl</code> package contains Perl 6 and the
current package becomes <code class="systemitem">perl5</code>.
</p></div></div></body></html>