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., 59 Temple Place - Suite 330,
51 Boston, MA 02111-1307, USA.
59 <heading>Perl Packaging</heading>
61 <heading>Versions</heading>
63 At any given time, the package <package>perl</package> should
64 represent the current stable upstream version of Perl revision
65 5 (see <ref id="perl6">).
68 Only one package may contain the <file>/usr/bin/perl</file>
69 binary and that package must either be <package>perl</package>
70 or a dependency of that package (see <ref id="base">).
73 Where possible, Perl should be compiled to provide binary
74 compatibility to at least the last released package version to
75 allow a grace period over which binary module packages may be
76 re-built against the new package (see <ref id="binary_modules">).
79 The <package>perl-base</package> package must provide
80 <package>perlapi-<var>version</var></package> for all released
81 versions it is compatible with.
86 <heading>Base Package</heading>
88 In order to provide a minimal installation of Perl for use by
89 applications without requiring the whole of Perl to be
90 installed, the <package>perl-base</package> package contains
91 the binary and a basic set of modules.
94 As Perl is currently used by such things as
95 <file>update-alternatives</file> and some package maintainer
96 scripts, it must be priority <em>required</em> and marked as
100 Note that the <package>perl-base</package> package is intended
101 only to provide for exceptional circumstances and the contents
102 may change. In general only packages which form part of the
103 base system should declare a dependency on
104 <package>perl-base</package> rather than
105 <package>perl</package>.
110 <heading>Module Path</heading>
112 Perl searches three different locations for modules, referred
113 to in this document as <var>core</var> in which modules
114 distributed with Perl are installed, <var>vendor</var> for
115 packaged modules and <var>site</var> for modules installed by
116 the local administrator.
119 The module search path (<tt>@INC</tt>) in the Debian packages
120 has been ordered to include these locations in the following
123 <tag><var>site</var> (current)</tag>
126 Modules installed by the local administrator for the
127 current version of Perl (see <ref id="site">).
129 /usr/local/lib/perl/<var>version</var>
130 /usr/local/share/perl/<var>version</var>
132 Where <var>version</var> indicates the current Perl
133 version (<tt>$Config{version}</tt><footnote>see the
134 <tt>Config</tt> module</footnote>).
137 <tag><var>vendor</var></tag>
140 Packaged modules (see <ref id="module_packages">).
147 <tag><var>core</var></tag>
150 Modules included in the core Perl distribution.
152 /usr/lib/perl/<var>version</var>
153 /usr/share/perl/<var>version</var>
157 <tag><var>site</var> (old)</tag>
160 <var>site</var> directories (as above) for modules
161 installed with previously released
162 <package>perl</package> packages for which the current
163 package is binary compatible are included if present.
167 In each of the directory pairs above, the <file>lib</file>
168 component is for binary (XS) modules, and <file>share</file>
169 for architecture-independent (pure-perl) modules.
174 <heading>Documentation</heading>
176 The POD files and manual pages which do not refer to programs
177 may be split out into a separate <package>perl-doc</package>
181 Manual pages distributed with Perl packages must be installed
182 into the standard directories:
187 Manual pages for programs and scripts are installed into
188 <file>/usr/share/man/man1</file> with the extension
195 Manual pages for modules are installed into
196 <file>/usr/share/man/man3</file> with the extension
206 <heading>Locally Installed Modules</heading>
207 <sect id="site_dirs">
208 <heading>Site Directories</heading>
210 The Perl packages must provide a mechanism for the local
211 administrator to install modules under <file>/usr/local</file>
212 but must not create or remove those directories.
215 Modules should be installed to the directories described above
216 in <ref id="paths"> as <var>site</var> (current), programs to
217 <file>/usr/local/bin</file> and manual pages under
218 <file>/usr/local/man</file>.
222 <sect id="site_install">
223 <heading>Site Installation</heading>
225 The following commands should be sufficient in the majority of
226 cases for the local administrator to install modules and must
227 create directories as required:
236 <chapt id="module_packages">
237 <heading>Packaged Modules</heading>
238 <sect id="vendor_dirs">
239 <heading>Vendor Directories</heading>
241 The installation directory for Debian modules must be
242 different from that for <var>core</var> and <var>site</var>
246 The current Perl packaging uses the <var>vendor</var>
247 directories for this purpose, which are at present as
248 described in <ref id="paths"> as <var>vendor</var>.
251 No version subdirectory exists on these directories as the
252 dependencies for packaged modules (see <ref id="module_deps">)
253 should ensure that all work with the current
254 <package>perl</package> package.
257 The Perl distribution includes many modules available
258 separately from CPAN<footnote><url
259 id="http://www.perl.com/CPAN"></footnote>, which may have a
260 newer version. The intent of the <tt>@INC</tt> ordering
261 (described in <ref id="paths">) is to allow such modules to be
262 packaged to <var>vendor</var> which take precedence over the
263 version in <var>core</var>. A packaged module which shadows a
264 <var>core</var> module in this way must be a newer version.
267 Module packages must install manual pages into the standard
268 directories (see <ref id="docs">) using the extensions
269 <tt>.1p</tt> and <tt>.3pm</tt> to ensure that no conflict
270 arises where a packaged module duplicates a <var>core</var>
274 <file>.packlist</file> files should not be installed.
278 <sect id="package_names">
279 <heading>Module Package Names</heading>
281 Perl module packages should be named for the primary module
282 provided. The naming convention for module <tt>Foo::Bar</tt>
283 is <package>libfoo-bar-perl</package>. Packages which include
284 multiple modules may additionally include provides for those
285 modules using the same convention.
289 <sect id="vendor_install">
290 <heading>Vendor Installation</heading>
292 A module should use the following lines in the
293 <file>debian/rules</file> <tt>build</tt>
294 target<footnote>The environment variable <tt>PERL_MM_OPT</tt>
295 may be used to pass the <tt>INSTALLDIRS=vendor</tt> option in
296 cases where <file>Makefile.PL</file> is not invoked directly
297 from <file>debian/rules</file></footnote>:
299 perl Makefile.PL INSTALLDIRS=vendor
300 $(MAKE) OPTIMIZE="-O2 -g -Wall"
302 and this one to install the results into the temporary tree:
304 $(MAKE) install PREFIX=$(CURDIR)/debian/<tmp>/usr
306 <p>Replace <tmp> with the appropriate directory
307 (nominally just tmp)</p>
311 A <tt>Build-Depends</tt> on <tt>perl (>= 5.6.0-16)</tt> is
316 <sect id="module_deps">
317 <heading>Module Dependencies</heading>
318 <sect1 id="indep_modules">
319 <heading>Architecture-Independent Modules</heading>
321 Architecture-independent modules which require
322 <var>core</var> modules from the <package>perl</package>
323 package must specify a dependency on that package.
326 Modules which contain explicit <tt>require
327 <var>version</var></tt> or <tt>use <var>version</var></tt>
328 statements must specify a dependency on
329 <package>perl</package> or <package>perl-base</package> with
330 the minimum required version, or more simply the current
334 In the absence of an explicit requirement,
335 architecture-independent modules must depend on a minimum
336 <package>perl</package> or <package>perl-base</package>
337 version of <tt>5.6.0-16</tt> due to the changes in
338 <tt>@INC</tt> introduced by that version.
342 <sect1 id="binary_modules">
343 <heading>Binary Modules</heading>
345 Binary modules must specify a dependency on either
346 <package>perl</package> or <package>perl-base</package> with
347 a minimum version of the <package>perl</package> package
348 used to build the module, and must additionally depend on
350 <package>perlapi-$Config{version}</package> using
351 the <tt>Config</tt> module.
356 <heading>Automating Perl Dependencies</heading>
358 Rather than hard-coding the dependencies into the control
359 file, using a substitution such as <tt>${perl:Depends}</tt>
360 is suggested. This allows the dependencies to be determined
361 as build time and written to the <file>substvars</file> file
362 in the form <tt>perl:Depends=<var>deps</var></tt>.
365 Packages built with <prgn>debhelper</prgn> may use
367 <manref name="dh_perl" section="1"> to generate this
368 substitution automatically. This additionally requires a
369 versioned <tt>Build-Depends</tt> (or
370 <tt>Build-Depends-Indep</tt>) on <tt>debhelper (>=
377 <chapt id="programs">
378 <heading>Perl Programs</heading>
379 <sect id="hash_bang">
380 <heading>Script Magic</heading>
382 All packaged perl programs must start with
383 <tt>#!/usr/bin/perl</tt> and may append such flags as are
388 <sect id="program_deps">
389 <heading>Program Dependencies</heading>
391 Programs which require <var>core</var> modules from the
392 <package>perl</package> package must specify a dependency on
396 Programs which contain explicit <tt>require
397 <var>version</var></tt> or <tt>use <var>version</var></tt>
398 statements must specify a dependency on
399 <package>perl</package> or <package>perl-base</package> with
400 the minimum required version, or more simply the current
404 As with modules, packages using <prgn>debhelper</prgn> may use
405 <manref name="dh_perl" section="1"> to automatically generate
406 dependences (see <ref id="dh_perl">).
412 <heading>Programs Embedding Perl</heading>
413 <sect id="build_embedded">
414 <heading>Building Embedded Programs</heading>
416 Programs which embed a perl interpreter must declare a
417 <tt>Build-Depends</tt> on <package>libperl-dev</package>.
420 The default linker options produced by
422 perl -MExtUtils::Embed -e ldopts
424 will link against the dynamic <tt>libperl</tt>. If programs
425 wish to link to the static library, then <tt>-lperl</tt>
426 should be changed to <file>/usr/lib/libperl.a</file> in those
431 <sect id="embedded_deps">
432 <heading>Embedded Perl Dependencies</heading>
434 Dependencies for programs linking against the shared Perl
435 library will be automatically created by
436 <prgn>dpkg-shlibdeps</prgn>. Note however that the shared
437 perl library package only suggests
438 <package>perl-base</package> and packages requiring any
439 <var>core</var> modules from the <package>perl</package>
440 package must depend upon it explicitly.
445 <appendix id="perl6">
446 <heading>Perl 6</heading>
448 The current stable upstream version at the time of this writing
449 is 5.6.0. There is currently work in progress on the next major
450 revision, although the specifications have yet to be finalised.
453 It is anticipated that when Perl 6 is released it will initially
454 be packaged as <package>perl6</package>, install the binary as
455 <file>/usr/bin/perl6</file> and use different directories for
456 packaged modules to <package>perl</package>:
461 This will allow Perl 5 and 6 packages and modules (which should
462 be packaged as <package>libfoo-bar-perl6</package>), to co-exist
463 for as long as required.
466 At some stage in the future when Perl 6 is sufficiently mature,
467 the package naming may be reversed such that the
468 <package>perl</package> package contains Perl 6 and the current
469 package becomes <package>perl5</package>.