/usr/share/doc/debian-policy/perl-policy.html/ch-perl.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">

<html>

<head>

<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">

<title>Debian Perl Policy - Perl Packaging</title>

<link href="index.html" rel="start">
<link href="ch1.html" rel="prev">
<link href="ch-site.html" rel="next">
<link href="index.html#contents" rel="contents">
<link href="index.html#copyright" rel="copyright">
<link href="ch1.html" rel="chapter" title="1 About this document">
<link href="ch-perl.html" rel="chapter" title="2 Perl Packaging">
<link href="ch-site.html" rel="chapter" title="3 Locally Installed Modules">
<link href="ch-module_packages.html" rel="chapter" title="4 Packaged Modules">
<link href="ch-programs.html" rel="chapter" title="5 Perl Programs">
<link href="ch-embed.html" rel="chapter" title="6 Programs Embedding Perl">
<link href="ap-perl6.html" rel="appendix" title="A Perl 6">
<link href="ch-perl.html#s-versions" rel="section" title="2.1 Versions">
<link href="ch-perl.html#s-base" rel="section" title="2.2 Base Package">
<link href="ch-perl.html#s-paths" rel="section" title="2.3 Module Path">
<link href="ch-perl.html#s-docs" rel="section" title="2.4 Documentation">
<link href="ch-site.html#s-site_dirs" rel="section" title="3.1 Site Directories">
<link href="ch-site.html#s-site_install" rel="section" title="3.2 Site Installation">
<link href="ch-module_packages.html#s-vendor_dirs" rel="section" title="4.1 Vendor Directories">
<link href="ch-module_packages.html#s-package_names" rel="section" title="4.2 Module Package Names">
<link href="ch-module_packages.html#s-vendor_install" rel="section" title="4.3 Vendor Installation">
<link href="ch-module_packages.html#s-module_deps" rel="section" title="4.4 Module Dependencies">
<link href="ch-programs.html#s-hash_bang" rel="section" title="5.1 Script Magic">
<link href="ch-programs.html#s-program_deps" rel="section" title="5.2 Program Dependencies">
<link href="ch-embed.html#s-build_embedded" rel="section" title="6.1 Building Embedded Programs">
<link href="ch-embed.html#s-embedded_deps" rel="section" title="6.2 Embedded Perl Dependencies">
<link href="ch-embed.html#s-perl_upgrades" rel="section" title="6.3 Perl Package Upgrades">
<link href="ch-module_packages.html#s-indep_modules" rel="subsection" title="4.4.1 Architecture-Independent Modules">
<link href="ch-module_packages.html#s-binary_modules" rel="subsection" title="4.4.2 Binary Modules">
<link href="ch-module_packages.html#s-dh_perl" rel="subsection" title="4.4.3 Automating Perl Dependencies">

</head>

<body>

<p><a name="ch-perl"></a></p>
<hr>

<p>
[ <a href="ch1.html">previous</a> ]
[ <a href="index.html#contents">Contents</a> ]
[ <a href="ch1.html">1</a> ]
[ 2 ]
[ <a href="ch-site.html">3</a> ]
[ <a href="ch-module_packages.html">4</a> ]
[ <a href="ch-programs.html">5</a> ]
[ <a href="ch-embed.html">6</a> ]
[ <a href="ap-perl6.html">A</a> ]
[ <a href="ch-site.html">next</a> ]
</p>

<hr>

<h1>
Debian Perl Policy
<br>Chapter 2 - Perl Packaging
</h1>

<hr>

<h2><a name="s-versions"></a>2.1 Versions</h2>

<p>
At any given time, the package <code>perl</code> should represent the current
stable upstream version of Perl revision 5 (see <a href="ap-perl6.html">Perl 6,
Appendix A</a>).
</p>

<p>
Only one package may contain the <code>/usr/bin/perl</code> binary and that
package must either be <code>perl</code> or a dependency of that package (see
<a href="#s-base">Base Package, Section 2.2</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
href="ch-module_packages.html#s-binary_modules">Binary Modules, Section
4.4.2</a>).
</p>

<p>
The <code>perl-base</code> package must provide
<code>perlapi-<var>abiname</var></code> for all released package versions it is
compatible with.  The choice of <var>abiname</var> is arbitrary, but if it
differs from <samp>$Config{version}</samp>, it must be specified in
<samp>$Config{debian_abi}</samp>.
</p>

<hr>

<h2><a name="s-base"></a>2.2 Base Package</h2>

<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>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>perl-base</code> must be priority <em>required</em> and marked as
<em>essential</em>.
</p>

<p>
Note that the <code>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>perl-base</code> rather than declaring a dependency on <code>perl</code>.
</p>

<hr>

<h2><a name="s-paths"></a>2.3 Module Path</h2>

<p>
Perl searches three different locations for modules, referred to in this
document as <var>core</var> in which modules distributed with Perl are
installed, <var>vendor</var> for packaged modules and <var>site</var> for
modules installed by the local administrator.
</p>

<p>
The module search path (<samp>@INC</samp>) in the Debian packages has been
ordered to include these locations in the following order:
</p>
<dl>
<dt><var>site</var> (current)</dt>
<dd>
<p>
Modules installed by the local administrator for the current version of Perl
(see <a href="ch-site.html">Locally Installed Modules, Chapter 3</a>).
</p>

<pre>
     /usr/local/lib/perl/<var>version</var>
     /usr/local/share/perl/<var>version</var>
</pre>

<p>
Where <var>version</var> indicates the current Perl version
(<samp>$Config{version}</samp>[<a href="footnotes.html#f1" name="fr1">1</a>]).
</p>
</dd>
</dl>
<dl>
<dt><var>vendor</var></dt>
<dd>
<p>
Packaged modules (see <a href="ch-module_packages.html">Packaged Modules,
Chapter 4</a>).
</p>

<pre>
     /usr/lib/perl5
     /usr/share/perl5
</pre>
</dd>
</dl>
<dl>
<dt><var>core</var></dt>
<dd>
<p>
Modules included in the core Perl distribution.
</p>

<pre>
     /usr/lib/perl/<var>version</var>
     /usr/share/perl/<var>version</var>
</pre>
</dd>
</dl>
<dl>
<dt><var>site</var> (old)</dt>
<dd>
<p>
<var>site</var> directories (as above) for modules installed with previously
released <code>perl</code> packages for which the current package is binary
compatible are included if present.
</p>
</dd>
</dl>

<p>
In each of the directory pairs above, the <code>lib</code> component is for
binary (XS) modules, and <code>share</code> for architecture-independent
(pure-perl) modules.
</p>

<hr>

<h2><a name="s-docs"></a>2.4 Documentation</h2>

<p>
The POD files and manual pages which do not refer to programs may be split out
into a separate <code>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>
<dl>
<dt>Programs</dt>
<dd>
<p>
Manual pages for programs and scripts are installed into
<code>/usr/share/man/man1</code> with the extension <samp>.1</samp>.
</p>
</dd>
</dl>
<dl>
<dt>Modules</dt>
<dd>
<p>
Manual pages for modules are installed into <code>/usr/share/man/man3</code>
with the extension <samp>.3perl</samp>.
</p>
</dd>
</dl>

<p>
The extensions used for manual pages distributed with module packages are
different.  See <a href="ch-module_packages.html#s-vendor_dirs">Vendor
Directories, Section 4.1</a>.
</p>

<hr>

<p>
[ <a href="ch1.html">previous</a> ]
[ <a href="index.html#contents">Contents</a> ]
[ <a href="ch1.html">1</a> ]
[ 2 ]
[ <a href="ch-site.html">3</a> ]
[ <a href="ch-module_packages.html">4</a> ]
[ <a href="ch-programs.html">5</a> ]
[ <a href="ch-embed.html">6</a> ]
[ <a href="ap-perl6.html">A</a> ]
[ <a href="ch-site.html">next</a> ]
</p>

<hr>

<p>
Debian Perl Policy
</p>

<address>
version 3.9.3.1, 2012-03-13<br>
<br>
Rapha&euml;l Hertzog<br>
Brendan O'Dea<br>
The Debian Policy mailing list <code><a href="mailto:debian-policy@lists.debian.org">debian-policy@lists.debian.org</a></code><br>
<br>
</address>
<hr>

</body>

</html>
debian-policy 3.9.3.1 / usr / share / doc / debian-policy / perl-policy.html / ch-perl.html
