1 <!doctype debiandoc system>
6 <title>Debian Perl Policy</title>
8 <name>Raphaël Hertzog</name>
11 <name>Brendan O'Dea</name>
14 <name>The Debian Policy mailing list</name>
15 <email>debian-policy@lists.debian.org</email>
17 <version>version 1.20</version>
20 This document describes the packaging of Perl within the Debian
21 GNU/Linux distribution and the policy requirements for packaged
22 Perl programs and modules.
27 Copyright © 1999, 2001 Software in the Public Interest
30 This manual is free software; you can redistribute it and/or
31 modify it under the terms of the GNU General Public License
32 as published by the Free Software Foundation; either version
33 2 of the License, or (at your option) any later version.
36 This is distributed in the hope that it will be useful, but
37 WITHOUT ANY WARRANTY; without even the implied warranty of
38 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
39 the GNU General Public License for more details.
42 A copy of the GNU General Public License is available as
43 <tt>/usr/share/common-licenses/GPL</tt> in the Debian GNU/Linux
44 distribution or on the World Wide Web at
45 <url id="http://www.gnu.org/copyleft/gpl.html"
46 name="The GNU Public Licence">.
49 You can also obtain it by writing to the
50 Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
51 Boston, MA 02110-1301, USA.
59 <heading>About this document</heading>
61 This document is distributed as the <tt>perl-policy</tt> files
63 <package><url name="debian-policy" id="http://packages.debian.org/debian-policy"></package>.
64 It is also available from the Debian web mirrors at
65 <tt><url name="/doc/packaging-manuals/perl-policy/"
66 id="http://www.debian.org/doc/packaging-manuals/perl-policy/"></tt>.
71 <heading>Perl Packaging</heading>
73 <heading>Versions</heading>
75 At any given time, the package <package>perl</package> should
76 represent the current stable upstream version of Perl revision
77 5 (see <ref id="perl6">).
80 Only one package may contain the <file>/usr/bin/perl</file>
81 binary and that package must either be <package>perl</package>
82 or a dependency of that package (see <ref id="base">).
85 Where possible, Perl should be compiled to provide binary
86 compatibility to at least the last released package version to
87 allow a grace period over which binary module packages may be
88 re-built against the new package (see <ref id="binary_modules">).
91 The <package>perl-base</package> package must provide
92 <package>perlapi-<var>version</var></package> for all released
93 versions it is compatible with.
98 <heading>Base Package</heading>
100 In order to provide a minimal installation of Perl for use by
101 applications without requiring the whole of Perl to be
102 installed, the <package>perl-base</package> package contains
103 the binary and a basic set of modules.
106 As Perl is currently used by such things as
107 <file>update-alternatives</file> and some package maintainer
108 scripts, it must be priority <em>required</em> and marked as
112 Note that the <package>perl-base</package> package is intended
113 only to provide for exceptional circumstances and the contents
114 may change. In general only packages which form part of the
115 base system should declare a dependency on
116 <package>perl-base</package> rather than
117 <package>perl</package>.
122 <heading>Module Path</heading>
124 Perl searches three different locations for modules, referred
125 to in this document as <var>core</var> in which modules
126 distributed with Perl are installed, <var>vendor</var> for
127 packaged modules and <var>site</var> for modules installed by
128 the local administrator.
131 The module search path (<tt>@INC</tt>) in the Debian packages
132 has been ordered to include these locations in the following
135 <tag><var>site</var> (current)</tag>
138 Modules installed by the local administrator for the
139 current version of Perl (see <ref id="site">).
141 /usr/local/lib/perl/<var>version</var>
142 /usr/local/share/perl/<var>version</var>
144 Where <var>version</var> indicates the current Perl
145 version (<tt>$Config{version}</tt><footnote>see the
146 <tt>Config</tt> module</footnote>).
149 <tag><var>vendor</var></tag>
152 Packaged modules (see <ref id="module_packages">).
159 <tag><var>core</var></tag>
162 Modules included in the core Perl distribution.
164 /usr/lib/perl/<var>version</var>
165 /usr/share/perl/<var>version</var>
169 <tag><var>site</var> (old)</tag>
172 <var>site</var> directories (as above) for modules
173 installed with previously released
174 <package>perl</package> packages for which the current
175 package is binary compatible are included if present.
179 In each of the directory pairs above, the <file>lib</file>
180 component is for binary (XS) modules, and <file>share</file>
181 for architecture-independent (pure-perl) modules.
186 <heading>Documentation</heading>
188 The POD files and manual pages which do not refer to programs
189 may be split out into a separate <package>perl-doc</package>
193 Manual pages distributed with Perl packages must be installed
194 into the standard directories:
199 Manual pages for programs and scripts are installed into
200 <file>/usr/share/man/man1</file> with the extension
207 Manual pages for modules are installed into
208 <file>/usr/share/man/man3</file> with the extension
218 <heading>Locally Installed Modules</heading>
219 <sect id="site_dirs">
220 <heading>Site Directories</heading>
222 The Perl packages must provide a mechanism for the local
223 administrator to install modules under <file>/usr/local</file>
224 but must not create or remove those directories.
227 Modules should be installed to the directories described above
228 in <ref id="paths"> as <var>site</var> (current), programs to
229 <file>/usr/local/bin</file> and manual pages under
230 <file>/usr/local/man</file>.
234 <sect id="site_install">
235 <heading>Site Installation</heading>
237 The following commands should be sufficient in the majority of
238 cases for the local administrator to install modules and must
239 create directories as required:
248 <chapt id="module_packages">
249 <heading>Packaged Modules</heading>
250 <sect id="vendor_dirs">
251 <heading>Vendor Directories</heading>
253 The installation directory for Debian modules must be
254 different from that for <var>core</var> and <var>site</var>
258 The current Perl packaging uses the <var>vendor</var>
259 directories for this purpose, which are at present as
260 described in <ref id="paths"> as <var>vendor</var>.
263 No version subdirectory exists on these directories as the
264 dependencies for packaged modules (see <ref id="module_deps">)
265 should ensure that all work with the current
266 <package>perl</package> package.
269 The Perl distribution includes many modules available
270 separately from CPAN<footnote><url
271 id="http://www.perl.com/CPAN"></footnote>, which may have a
272 newer version. The intent of the <tt>@INC</tt> ordering
273 (described in <ref id="paths">) is to allow such modules to be
274 packaged to <var>vendor</var> which take precedence over the
275 version in <var>core</var>. A packaged module which shadows a
276 <var>core</var> module in this way must be a newer version.
279 Module packages must install manual pages into the standard
280 directories (see <ref id="docs">) using the extensions
281 <tt>.1p</tt> and <tt>.3pm</tt> to ensure that no conflict
282 arises where a packaged module duplicates a <var>core</var>
286 <file>.packlist</file> files should not be installed.
290 <sect id="package_names">
291 <heading>Module Package Names</heading>
293 Perl module packages should be named for the primary module
294 provided. The naming convention for module <tt>Foo::Bar</tt>
295 is <package>libfoo-bar-perl</package>. Packages which include
296 multiple modules may additionally include provides for those
297 modules using the same convention.
301 <sect id="vendor_install">
302 <heading>Vendor Installation</heading>
304 A module should use the following lines in the
305 <file>debian/rules</file> <tt>build</tt>
306 target<footnote>The environment variable <tt>PERL_MM_OPT</tt>
307 may be used to pass the <tt>INSTALLDIRS=vendor</tt> option in
308 cases where <file>Makefile.PL</file> is not invoked directly
309 from <file>debian/rules</file></footnote>:
311 perl Makefile.PL INSTALLDIRS=vendor
312 $(MAKE) OPTIMIZE="-O2 -g -Wall"
314 and this one to install the results into the temporary tree:
316 $(MAKE) install PREFIX=$(CURDIR)/debian/<tmp>/usr
318 <p>Replace <tmp> with the appropriate directory
319 (nominally just tmp)</p>
323 A <tt>Build-Depends</tt> on <tt>perl (>= 5.6.0-16)</tt> is
328 <sect id="module_deps">
329 <heading>Module Dependencies</heading>
330 <sect1 id="indep_modules">
331 <heading>Architecture-Independent Modules</heading>
333 Architecture-independent modules which require
334 <var>core</var> modules from the <package>perl</package>
335 package must specify a dependency on that package.
338 Modules which contain explicit <tt>require
339 <var>version</var></tt> or <tt>use <var>version</var></tt>
340 statements must specify a dependency on
341 <package>perl</package> or <package>perl-base</package> with
342 the minimum required version, or more simply the current
346 In the absence of an explicit requirement,
347 architecture-independent modules must depend on a minimum
348 <package>perl</package> or <package>perl-base</package>
349 version of <tt>5.6.0-16</tt> due to the changes in
350 <tt>@INC</tt> introduced by that version.
354 <sect1 id="binary_modules">
355 <heading>Binary Modules</heading>
357 Binary modules must specify a dependency on either
358 <package>perl</package> or <package>perl-base</package> with
359 a minimum version of the <package>perl</package> package
360 used to build the module, and must additionally depend on
362 <package>perlapi-$Config{version}</package> using
363 the <tt>Config</tt> module.
368 <heading>Automating Perl Dependencies</heading>
370 Rather than hard-coding the dependencies into the control
371 file, using a substitution such as <tt>${perl:Depends}</tt>
372 is suggested. This allows the dependencies to be determined
373 at build time and written to the <file>substvars</file> file
375 <tt>perl:Depends=<var>deps</var></tt>.<footnote>
376 <p>Please note that dependencies caused by versioned
377 uses and on separately packaged modules are not included
378 in this variable and must be explicitly included.</p>
382 Packages built with <prgn>debhelper</prgn> may use
384 <manref name="dh_perl" section="1"> to generate this
385 substitution automatically. This additionally requires a
386 versioned <tt>Build-Depends</tt> (or
387 <tt>Build-Depends-Indep</tt>) on <tt>debhelper (>=
394 <chapt id="programs">
395 <heading>Perl Programs</heading>
396 <sect id="hash_bang">
397 <heading>Script Magic</heading>
399 All packaged perl programs must start with
400 <tt>#!/usr/bin/perl</tt> and may append such flags as are
405 <sect id="program_deps">
406 <heading>Program Dependencies</heading>
408 Programs which require <var>core</var> modules from the
409 <package>perl</package> package must specify a dependency on
413 Programs which contain explicit <tt>require
414 <var>version</var></tt> or <tt>use <var>version</var></tt>
415 statements must specify a dependency on
416 <package>perl</package> or <package>perl-base</package> with
417 the minimum required version, or more simply the current
421 As with modules, packages using <prgn>debhelper</prgn> may use
422 <manref name="dh_perl" section="1"> to automatically generate
423 dependences (see <ref id="dh_perl">).
429 <heading>Programs Embedding Perl</heading>
430 <sect id="build_embedded">
431 <heading>Building Embedded Programs</heading>
433 Programs which embed a perl interpreter must declare a
434 <tt>Build-Depends</tt> on <package>libperl-dev</package>.
437 The default linker options produced by
439 perl -MExtUtils::Embed -e ldopts
441 will link against the dynamic <tt>libperl</tt>. If programs
442 wish to link to the static library, then <tt>-lperl</tt>
443 should be changed to <file>/usr/lib/libperl.a</file> in those
448 <sect id="embedded_deps">
449 <heading>Embedded Perl Dependencies</heading>
451 Dependencies for programs linking against the shared Perl
452 library will be automatically created by
453 <prgn>dpkg-shlibdeps</prgn>. Note however that the shared
454 perl library package only suggests
455 <package>perl-base</package> and packages requiring any
456 <var>core</var> modules from the <package>perl</package>
457 package must depend upon it explicitly.
462 <appendix id="perl6">
463 <heading>Perl 6</heading>
465 The current stable upstream version at the time of this writing
466 is 5.6.0. There is currently work in progress on the next major
467 revision, although the specifications have yet to be finalised.
470 It is anticipated that when Perl 6 is released it will initially
471 be packaged as <package>perl6</package>, install the binary as
472 <file>/usr/bin/perl6</file> and use different directories for
473 packaged modules to <package>perl</package>:
478 This will allow Perl 5 and 6 packages and modules (which should
479 be packaged as <package>libfoo-bar-perl6</package>), to co-exist
480 for as long as required.
483 At some stage in the future when Perl 6 is sufficiently mature,
484 the package naming may be reversed such that the
485 <package>perl</package> package contains Perl 6 and the current
486 package becomes <package>perl5</package>.
491 <!-- Local variables: -->
492 <!-- indent-tabs-mode: t -->