1 <!doctype debiandoc system>
6 <title>Debian Perl Policy</title>
8 <name>Raphaël Hertzog</name>
9 <email>hertzog@debian.org</email>
12 <name>Brendan O'Dea</name>
13 <email>bod@debian.org</email>
15 <version>version 1.20</version>
18 This document describes the packaging of Perl within the Debian
19 GNU/Linux distribution and the policy requirements for packaged
20 Perl programs and modules.
25 Copyright © 1999, 2001 Software in the Public Interest
28 This manual is free software; you can redistribute it and/or
29 modify it under the terms of the GNU General Public License
30 as published by the Free Software Foundation; either version
31 2 of the License, or (at your option) any later version.
34 This is distributed in the hope that it will be useful, but
35 WITHOUT ANY WARRANTY; without even the implied warranty of
36 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
37 the GNU General Public License for more details.
40 A copy of the GNU General Public License is available as
41 <tt>/usr/share/common-licences/GPL</tt> in the Debian GNU/Linux
42 distribution or on the World Wide Web at
43 <url id="http://www.gnu.org/copyleft/gpl.html"
44 name="The GNU Public Licence">.
47 You can also obtain it by writing to the
48 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
49 Boston, MA 02111-1307, USA.
57 <heading>Perl Packaging</heading>
59 <heading>Versions</heading>
61 At any given time, the package <package>perl</package> should
62 represent the current stable upstream version of Perl revision
63 5 (see <ref id="perl6">).
66 Only one package may contain the <file>/usr/bin/perl</file>
67 binary and that package must either be <package>perl</package>
68 or a dependency of that package (see <ref id="base">).
71 Where possible, Perl should be compiled to provide binary
72 compatibility to at least the last released package version to
73 allow a grace period over which binary module packages may be
74 re-built against the new package (see <ref id="binary_modules">).
77 The <package>perl-base</package> package must provide
78 <package>perlapi-<var>version</var></package> for all released
79 versions it is compatible with.
84 <heading>Base Package</heading>
86 In order to provide a minimal installation of Perl for use by
87 applications without requiring the whole of Perl to be
88 installed, the <package>perl-base</package> package contains
89 the binary and a basic set of modules.
92 As Perl is currently used by such things as
93 <file>update-alternatives</file> and some package maintainer
94 scripts, it must be priority <em>required</em> and marked as
98 Note that the <package>perl-base</package> package is intended
99 only to provide for exceptional circumstances and the contents
100 may change. In general only packages which form part of the
101 base system should declare a dependency on
102 <package>perl-base</package> rather than
103 <package>perl</package>.
108 <heading>Module Path</heading>
110 Perl searches three different locations for modules, referred
111 to in this document as <var>core</var> in which modules
112 distributed with Perl are installed, <var>vendor</var> for
113 packaged modules and <var>site</var> for modules installed by
114 the local administrator.
117 The module search path (<tt>@INC</tt>) in the Debian packages
118 has been ordered to include these locations in the following
121 <tag><var>site</var> (current)</tag>
124 Modules installed by the local administrator for the
125 current version of Perl (see <ref id="site">).
127 /usr/local/lib/perl/<var>version</var>
128 /usr/local/share/perl/<var>version</var>
130 Where <var>version</var> indicates the current Perl
131 version (<tt>$Config{version}</tt><footnote>see the
132 <tt>Config</tt> module</footnote>).
135 <tag><var>vendor</var></tag>
138 Packaged modules (see <ref id="module_packages">).
145 <tag><var>core</var></tag>
148 Modules included in the core Perl distribution.
150 /usr/lib/perl/<var>version</var>
151 /usr/share/perl/<var>version</var>
155 <tag><var>site</var> (old)</tag>
158 <var>site</var> directories (as above) for modules
159 installed with previously released
160 <package>perl</package> packages for which the current
161 package is binary compatible are included if present.
165 In each of the directory pairs above, the <file>lib</file>
166 component is for binary (XS) modules, and <file>share</file>
167 for architecture-independent (pure-perl) modules.
172 <heading>Documentation</heading>
174 The POD files and manual pages which do not refer to programs
175 may be split out into a separate <package>perl-doc</package>
179 Manual pages distributed with Perl packages must be installed
180 into the standard directories:
185 Manual pages for programs and scripts are installed into
186 <file>/usr/share/man/man1</file> with the extension
193 Manual pages for modules are installed into
194 <file>/usr/share/man/man3</file> with the extension
204 <heading>Locally Installed Modules</heading>
205 <sect id="site_dirs">
206 <heading>Site Directories</heading>
208 The Perl packages must provide a mechanism for the local
209 administrator to install modules under <file>/usr/local</file>
210 but must not create or remove those directories.
213 Modules should be installed to the directories described above
214 in <ref id="paths"> as <var>site</var> (current), programs to
215 <file>/usr/local/bin</file> and manual pages under
216 <file>/usr/local/man</file>.
220 <sect id="site_install">
221 <heading>Site Installation</heading>
223 The following commands should be sufficient in the majority of
224 cases for the local administrator to install modules and must
225 create directories as required:
234 <chapt id="module_packages">
235 <heading>Packaged Modules</heading>
236 <sect id="vendor_dirs">
237 <heading>Vendor Directories</heading>
239 The installation directory for Debian modules must be
240 different from that for <var>core</var> and <var>site</var>
244 The current Perl packaging uses the <var>vendor</var>
245 directories for this purpose, which are at present as
246 described in <ref id="paths"> as <var>vendor</var>.
249 No version subdirectory exists on these directories as the
250 dependencies for packaged modules (see <ref id="module_deps">)
251 should ensure that all work with the current
252 <package>perl</package> package.
255 The Perl distribution includes many modules available
256 separately from CPAN<footnote><url
257 id="http://www.perl.com/CPAN"></footnote>, which may have a
258 newer version. The intent of the <tt>@INC</tt> ordering
259 (described in <ref id="paths">) is to allow such modules to be
260 packaged to <var>vendor</var> which take precedence over the
261 version in <var>core</var>. A packaged module which shadows a
262 <var>core</var> module in this way must be a newer version.
265 Module packages must install manual pages into the standard
266 directories (see <ref id="docs">) using the extensions
267 <tt>.1p</tt> and <tt>.3pm</tt> to ensure that no conflict
268 arises where a packaged module duplicates a <var>core</var>
272 <file>.packlist</file> files should not be installed.
276 <sect id="package_names">
277 <heading>Module Package Names</heading>
279 Perl module packages should be named for the primary module
280 provided. The naming convention for module <tt>Foo::Bar</tt>
281 is <package>libfoo-bar-perl</package>. Packages which include
282 multiple modules may additionally include provides for those
283 modules using the same convention.
287 <sect id="vendor_install">
288 <heading>Vendor Installation</heading>
290 A module should use the following lines in the
291 <file>debian/rules</file> <tt>build</tt>
292 target<footnote>The environment variable <tt>PERL_MM_OPT</tt>
293 may be used to pass the <tt>INSTALLDIRS=vendor</tt> option in
294 cases where <file>Makefile.PL</file> is not invoked directly
295 from <file>debian/rules</file></footnote>:
297 perl Makefile.PL INSTALLDIRS=vendor
298 $(MAKE) OPTIMIZE="-O2 -g -Wall"
300 and this one to install the results into the temporary tree:
302 $(MAKE) install PREFIX=$(CURDIR)/debian/<tmp>/usr
304 <p>Replace <tmp> with the appropriate directory
305 (nominally just tmp)</p>
309 A <tt>Build-Depends</tt> on <tt>perl (>= 5.6.0-16)</tt> is
314 <sect id="module_deps">
315 <heading>Module Dependencies</heading>
316 <sect1 id="indep_modules">
317 <heading>Architecture-Independent Modules</heading>
319 Architecture-independent modules which require
320 <var>core</var> modules from the <package>perl</package>
321 package must specify a dependency on that package.
324 Modules which contain explicit <tt>require
325 <var>version</var></tt> or <tt>use <var>version</var></tt>
326 statements must specify a dependency on
327 <package>perl</package> or <package>perl-base</package> with
328 the minimum required version, or more simply the current
332 In the absence of an explicit requirement,
333 architecture-independent modules must depend on a minimum
334 <package>perl</package> or <package>perl-base</package>
335 version of <tt>5.6.0-16</tt> due to the changes in
336 <tt>@INC</tt> introduced by that version.
340 <sect1 id="binary_modules">
341 <heading>Binary Modules</heading>
343 Binary modules must specify a dependency on either
344 <package>perl</package> or <package>perl-base</package> with
345 a minimum version of the <package>perl</package> package
346 used to build the module, and must additionally depend on
348 <package>perlapi-$Config{version}</package> using
349 the <tt>Config</tt> module.
354 <heading>Automating Perl Dependencies</heading>
356 Rather than hard-coding the dependencies into the control
357 file, using a substitution such as <tt>${perl:Depends}</tt>
358 is suggested. This allows the dependencies to be determined
359 as build time and written to the <file>substvars</file> file
360 in the form <tt>perl:Depends=<var>deps</var></tt>.
363 Packages built with <prgn>debhelper</prgn> may use
365 <manref name="dh_perl" section="1"> to generate this
366 substitution automatically. This additionally requires a
367 versioned <tt>Build-Depends</tt> (or
368 <tt>Build-Depends-Indep</tt>) on <tt>debhelper (>=
375 <chapt id="programs">
376 <heading>Perl Programs</heading>
377 <sect id="hash_bang">
378 <heading>Script Magic</heading>
380 All packaged perl programs must start with
381 <tt>#!/usr/bin/perl</tt> and may append such flags as are
386 <sect id="program_deps">
387 <heading>Program Dependencies</heading>
389 Programs which require <var>core</var> modules from the
390 <package>perl</package> package must specify a dependency on
394 Programs which contain explicit <tt>require
395 <var>version</var></tt> or <tt>use <var>version</var></tt>
396 statements must specify a dependency on
397 <package>perl</package> or <package>perl-base</package> with
398 the minimum required version, or more simply the current
402 As with modules, packages using <prgn>debhelper</prgn> may use
403 <manref name="dh_perl" section="1"> to automatically generate
404 dependences (see <ref id="dh_perl">).
410 <heading>Programs Embedding Perl</heading>
411 <sect id="build_embedded">
412 <heading>Building Embedded Programs</heading>
414 Programs which embed a perl interpreter must declare a
415 <tt>Build-Depends</tt> on <package>libperl-dev</package>.
418 The default linker options produced by
420 perl -MExtUtils::Embed -e ldopts
422 will link against the dynamic <tt>libperl</tt>. If programs
423 wish to link to the static library, then <tt>-lperl</tt>
424 should be changed to <file>/usr/lib/libperl.a</file> in those
429 <sect id="embedded_deps">
430 <heading>Embedded Perl Dependencies</heading>
432 Dependencies for programs linking against the shared Perl
433 library will be automatically created by
434 <prgn>dpkg-shlibdeps</prgn>. Note however that the shared
435 perl library package only suggests
436 <package>perl-base</package> and packages requiring any
437 <var>core</var> modules from the <package>perl</package>
438 package must depend upon it explicitly.
443 <appendix id="perl6">
444 <heading>Perl 6</heading>
446 The current stable upstream version at the time of this writing
447 is 5.6.0. There is currently work in progress on the next major
448 revision, although the specifications have yet to be finalised.
451 It is anticipated that when Perl 6 is released it will initially
452 be packaged as <package>perl6</package>, install the binary as
453 <file>/usr/bin/perl6</file> and use different directories for
454 packaged modules to <package>perl</package>:
459 This will allow Perl 5 and 6 packages and modules (which should
460 be packaged as <package>libfoo-bar-perl6</package>), to co-exist
461 for as long as required.
464 At some stage in the future when Perl 6 is sufficiently mature,
465 the package naming may be reversed such that the
466 <package>perl</package> package contains Perl 6 and the current
467 package becomes <package>perl5</package>.