File: //usr/share/doc/debian-policy/perl-policy.html/ch-module_packages.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 4. Packaged Modules</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="ch-site.html" title="Chapter 3. Locally Installed Modules" />
<link rel="next" href="ch-programs.html" title="Chapter 5. Perl Programs" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Chapter 4. Packaged Modules</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="ch-site.html">Prev</a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="ch-programs.html">Next</a></td>
</tr>
</table>
<hr />
</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="ch-module_packages.html#s-vendor-dirs">4.1. Vendor Directories</a>
</span>
</dt>
<dt>
<span class="section">
<a href="ch-module_packages.html#s-package-names">4.2. Module Package Names</a>
</span>
</dt>
<dt>
<span class="section">
<a href="ch-module_packages.html#s-vendor-install">4.3. Vendor Installation</a>
</span>
</dt>
<dt>
<span class="section">
<a href="ch-module_packages.html#s-module-deps">4.4. Module Dependencies</a>
</span>
</dt>
<dd>
<dl>
<dt>
<span class="section">
<a href="ch-module_packages.html#s-indep-modules">4.4.1. Architecture-Independent Modules</a>
</span>
</dt>
<dt>
<span class="section">
<a href="ch-module_packages.html#s-binary-modules">4.4.2. Binary and Other Architecture Dependent Modules</a>
</span>
</dt>
<dt>
<span class="section">
<a href="ch-module_packages.html#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="ch-perl.html#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="ch-perl.html#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="ch-perl.html#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 />
</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" />
<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 />
<hr style="width:100; text-align:left;margin-left: 0" />
<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="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="ch-site.html">Prev</a> </td>
<td width="20%" align="center"> </td>
<td width="40%" align="right"> <a accesskey="n" href="ch-programs.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Chapter 3. Locally Installed Modules </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Chapter 5. Perl Programs</td>
</tr>
</table>
</div>
</body>
</html>