File: //usr/share/doc/debian-policy/perl-policy.html/ch-perl.html
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!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>Chapter 2. Perl Packaging</title>
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" />
<link rel="home" href="index.html" title="Debian Perl Policy" />
<link rel="up" href="index.html" title="Debian Perl Policy" />
<link rel="prev" href="ch1.html" title="Chapter 1. About this document" />
<link rel="next" href="ch-site.html" title="Chapter 3. Locally Installed Modules" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Chapter 2. Perl Packaging</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="ch1.html">Prev</a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="ch-site.html">Next</a></td>
</tr>
</table>
<hr />
</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="ch-perl.html#s-versions">2.1. Versions</a>
</span>
</dt>
<dt>
<span class="section">
<a href="ch-perl.html#s-base">2.2. Base Package</a>
</span>
</dt>
<dt>
<span class="section">
<a href="ch-perl.html#s-paths">2.3. Module Path</a>
</span>
</dt>
<dt>
<span class="section">
<a href="ch-perl.html#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.html" 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="ch-perl.html#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="ch-module_packages.html#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.html" 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.html" 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="ch-module_packages.html#s-vendor-dirs" title="4.1. Vendor Directories">Section 4.1, “Vendor Directories”</a>.
</p>
</div>
<div class="footnotes">
<br />
<hr style="width:100; text-align:left;margin-left: 0" />
<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="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="ch1.html">Prev</a> </td>
<td width="20%" align="center"> </td>
<td width="40%" align="right"> <a accesskey="n" href="ch-site.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Chapter 1. About this document </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Chapter 3. Locally Installed Modules</td>
</tr>
</table>
</div>
</body>
</html>