1 <!doctype debiandoc system [
2 <!-- include version information so we don't have to hard code it
3 within the document -->
4 <!entity % versiondata SYSTEM "version.ent"> %versiondata;
10 <title>Debian Perl Policy</title>
12 <name>Raphaël Hertzog</name>
15 <name>Brendan O'Dea</name>
18 <name>The Debian Policy mailing list</name>
19 <email>debian-policy@lists.debian.org</email>
21 <version>version &version;, &date;</version>
24 This document describes the packaging of Perl within the Debian
25 distribution and the policy requirements for packaged
26 Perl programs and modules.
31 Copyright © 1999, 2001 Software in the Public Interest
34 This manual is free software; you can redistribute it and/or
35 modify it under the terms of the GNU General Public License
36 as published by the Free Software Foundation; either version
37 2 of the License, or (at your option) any later version.
40 This is distributed in the hope that it will be useful, but
41 WITHOUT ANY WARRANTY; without even the implied warranty of
42 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
43 the GNU General Public License for more details.
46 A copy of the GNU General Public License is available as
47 <tt>/usr/share/common-licenses/GPL</tt> in the Debian
48 distribution or on the World Wide Web at
49 <url id="http://www.gnu.org/copyleft/gpl.html"
50 name="The GNU Public Licence">.
53 You can also obtain it by writing to the
54 Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
55 Boston, MA 02110-1301, USA.
63 <heading>About this document</heading>
65 This document is distributed as the <tt>perl-policy</tt> files
67 <package><url name="debian-policy" id="http://packages.debian.org/debian-policy"></package>.
68 It is also available from the Debian web mirrors at
69 <tt><url name="/doc/packaging-manuals/perl-policy/"
70 id="http://www.debian.org/doc/packaging-manuals/perl-policy/"></tt>.
75 <heading>Perl Packaging</heading>
77 <heading>Versions</heading>
79 At any given time, the package <package>perl</package> should
80 represent the current stable upstream version of Perl revision
81 5 (see <ref id="perl6">).
84 Only one package may contain the <file>/usr/bin/perl</file>
85 binary and that package must either be <package>perl</package>
86 or a dependency of that package (see <ref id="base">).
89 Where possible, Perl should be compiled to provide binary
90 compatibility to at least the last released package version to
91 allow a grace period over which binary module packages may be
92 re-built against the new package (see <ref id="binary_modules">).
95 The <package>perl-base</package> package must provide
96 <package>perlapi-<var>abiname</var></package> for all released
97 package versions it is compatible with. The choice of
98 <var>abiname</var> is arbitrary, but if it differs from
99 <tt>$Config{version}</tt><footnote>see the
100 <tt>Config</tt> module</footnote>, it must be specified in
101 <tt>$Config{debian_abi}</tt>.
106 <heading>Base Package</heading>
108 In order to provide a minimal installation of Perl for use by
109 applications without requiring the whole of Perl to be
110 installed, the <package>perl-base</package> package contains
111 the binary and a basic set of modules.
114 As Perl has been part of the essential set for some time and is
115 used without dependencies by such things as package maintainer
116 scripts, <package>perl-base</package> must be
117 priority <em>required</em> and marked as <em>essential</em>.
120 Note that the <package>perl-base</package> package is intended
121 only to provide for exceptional circumstances and the contents
122 may change. In general, only packages which form part of the
123 base system should use only the facilities
124 of <package>perl-base</package> rather than declaring a
125 dependency on <package>perl</package>.
130 <heading>Module Path</heading>
132 Perl searches three different locations for modules, referred
133 to in this document as <var>core</var> in which modules
134 distributed with Perl are installed, <var>vendor</var> for
135 packaged modules and <var>site</var> for modules installed by
136 the local administrator.
139 The module search path (<tt>@INC</tt>) in the Debian packages
140 has been ordered to include these locations in the following
143 <tag><var>site</var> (current)</tag>
146 Modules installed by the local administrator for the
147 current version of Perl (see <ref id="site">).
149 $Config{sitearch} (currently /usr/local/lib/perl/<var>version</var>)
150 $Config{sitelib} (currently /usr/local/share/perl/<var>version</var>)
152 Where <var>version</var> indicates the current Perl
153 version (<tt>$Config{version}</tt>).
156 These locations, particularly <tt>$Config{sitearch}</tt>,
157 may change if the binary interface between the
158 Perl interpreter and compiled modules has to be
159 changed in an incompatible way without a change in
160 <var>version</var>. While this will only be done as a
161 last resort, packages should use <tt>$Config{sitelib}</tt>
162 and <tt>$Config{sitearch}</tt>, not hardcode the current
163 locations.<footnote>Build systems based on
164 <tt>ExtUtils::MakeMaker</tt> and <tt>Module::Build</tt>
165 do this automatically.</footnote>
168 <tag><var>vendor</var></tag>
171 Packaged modules (see <ref id="module_packages">).
173 $Config{vendorarch} (currently /usr/lib/perl5)
174 $Config{vendorlib} (currently /usr/share/perl5)
176 These locations, particularly
177 <tt>$Config{vendorarch}</tt>, may change if
178 necessary<footnote>For example, to include
179 the multiarch triplet</footnote>. Packages
180 should use <tt>$Config{vendorlib}</tt> and
181 <tt>$Config{vendorarch}</tt>, not hardcode the current
182 locations.<footnote>Build systems based on
183 <tt>ExtUtils::MakeMaker</tt> and <tt>Module::Build</tt>
184 do this automatically.</footnote>
187 <tag><var>core</var></tag>
190 Modules included in the core Perl distribution.
192 $Config{archlib} (currently /usr/lib/perl/<var>shortversion</var>)
193 $Config{privlib} (currently /usr/share/perl/<var>shortversion</var>)
195 Where <var>shortversion</var> indicates the current Perl major
196 version (for example <tt>5.18</tt>).
199 These locations should be considered internal to the <package>
200 perl</package> source package. If necessary, packages should use
201 <tt>$Config{archlib}</tt> and <tt>$Config{privlib}</tt> instead of
202 hardcoding the current locations.<footnote>Build systems based on
203 <tt>ExtUtils::MakeMaker</tt> and <tt>Module::Build</tt>
204 do this automatically.</footnote>
207 <tag><var>site</var> (old)</tag>
210 <var>site</var> directories (as above) for modules
211 installed with previously released
212 <package>perl</package> packages for which the current
213 package is binary compatible are included if present.
217 In each of the directory pairs above, the <file>lib</file>
218 component is for binary (XS) modules, and <file>share</file>
219 for architecture-independent (pure-perl) modules.
224 <heading>Documentation</heading>
226 The POD files and manual pages which do not refer to programs
227 may be split out into a separate <package>perl-doc</package>
231 Manual pages distributed with packages built from the perl
232 source package must be installed into the standard directories:
237 Manual pages for programs and scripts are installed into
238 <file>/usr/share/man/man1</file> with the extension
245 Manual pages for modules are installed into
246 <file>/usr/share/man/man3</file> with the extension
251 The extensions used for manual pages distributed with module
252 packages are different. See <ref id="vendor_dirs">.
258 <heading>Locally Installed Modules</heading>
259 <sect id="site_dirs">
260 <heading>Site Directories</heading>
262 The Perl packages must provide a mechanism for the local
263 administrator to install modules under <file>/usr/local</file>
264 but must not create or remove those directories.
267 Modules should be installed to the directories described above
268 in <ref id="paths"> as <var>site</var> (current), programs to
269 <file>/usr/local/bin</file> and manual pages under
270 <file>/usr/local/man</file>.
274 <sect id="site_install">
275 <heading>Site Installation</heading>
277 The following commands should be sufficient in the majority of
278 cases for the local administrator to install modules and must
279 create directories as required:
288 <chapt id="module_packages">
289 <heading>Packaged Modules</heading>
290 <sect id="vendor_dirs">
291 <heading>Vendor Directories</heading>
293 The installation directory for Debian modules must be
294 different from that for <var>core</var> and <var>site</var>
298 The current Perl packaging uses the <var>vendor</var>
299 directories for this purpose, which are at present as
300 described in <ref id="paths"> as <var>vendor</var>.
303 No version subdirectory exists on these directories as the
304 dependencies for packaged modules (see <ref id="module_deps">)
305 should ensure that all work with the current
306 <package>perl</package> package.
309 The Perl distribution includes many modules available
310 separately from CPAN<footnote><url
311 id="http://www.perl.com/CPAN"></footnote>, which may have a
312 newer version. The intent of the <tt>@INC</tt> ordering
313 (described in <ref id="paths">) is to allow such modules to be
314 packaged to <var>vendor</var> which take precedence over the
315 version in <var>core</var>. A packaged module which shadows a
316 <var>core</var> module in this way must be a newer version.
319 Module packages must install manual pages into the standard
320 directories (see <ref id="docs">) using the extensions
321 <tt>.1p</tt> and <tt>.3pm</tt> to ensure that no conflict
322 arises where a packaged module duplicates a <var>core</var>
326 <file>.packlist</file> files should not be installed.
330 <sect id="package_names">
331 <heading>Module Package Names</heading>
333 Perl module packages should be named for the primary module
334 provided. The naming convention is to lowercase the Perl module
335 name, prepend, <tt>lib</tt>, change all occurrences
336 of <tt>::</tt> to <tt>-</tt>, and append <tt>-perl</tt>. For
339 Foo::Bar libfoo-bar-perl
340 Foo::Bar::Baz libfoo-bar-baz-perl
341 Foo::BarBaz libfoo-barbaz-perl
343 Packages which include multiple modules may additionally include
344 provides for the additional modules using the same convention.
348 <sect id="vendor_install">
349 <heading>Vendor Installation</heading>
351 A module should use the following lines in the
352 <file>debian/rules</file> <tt>build</tt>
353 target<footnote>The environment variable <tt>PERL_MM_OPT</tt>
354 may be used to pass the <tt>INSTALLDIRS=vendor</tt> option in
355 cases where <file>Makefile.PL</file> is not invoked directly
356 from <file>debian/rules</file></footnote>:
358 perl Makefile.PL INSTALLDIRS=vendor
359 $(MAKE) OPTIMIZE="-O2 -g -Wall"
361 and this one to install the results into the temporary tree:
363 $(MAKE) install DESTDIR=$(CURDIR)/debian/<tmp>
365 <p>Replace <tmp> with the appropriate directory
366 (nominally just tmp)</p>
371 <sect id="module_deps">
372 <heading>Module Dependencies</heading>
373 <sect1 id="indep_modules">
374 <heading>Architecture-Independent Modules</heading>
376 Architecture-independent modules which require
377 <var>core</var> modules from the <package>perl</package>
378 package must specify a dependency on that package.
381 Modules which contain explicit <tt>require
382 <var>version</var></tt> or <tt>use <var>version</var></tt>
383 statements must specify a dependency on
384 <package>perl</package> or <package>perl-base</package> with
385 the minimum required version, or more simply the current
390 <sect1 id="binary_modules">
391 <heading>Binary Modules</heading>
393 Binary modules must specify a dependency on either
394 <package>perl</package> or <package>perl-base</package> with
395 a minimum version of the <package>perl</package> package
396 used to build the module, and must additionally depend on
398 <package>perlapi-$Config{debian_abi}</package> using
399 the <tt>Config</tt> module. If <tt>$Config{debian_abi}</tt>
400 is empty or not set, <tt>$Config{version}</tt> must be used.
405 <heading>Automating Perl Dependencies</heading>
407 Rather than hard-coding the dependencies into the control
408 file, using a substitution such as <tt>${perl:Depends}</tt>
409 is suggested. This allows the dependencies to be determined
410 at build time and written to the <file>substvars</file> file
412 <tt>perl:Depends=<var>deps</var></tt>.<footnote>
413 <p>Please note that dependencies caused by versioned
414 uses and on separately packaged modules are not included
415 in this variable and must be explicitly included.</p>
419 Packages built with <prgn>debhelper</prgn> may use
421 <manref name="dh_perl" section="1"> to generate this
422 substitution automatically. This additionally requires a
423 versioned <tt>Build-Depends</tt> (or
424 <tt>Build-Depends-Indep</tt>) on <tt>debhelper (>=
431 <chapt id="programs">
432 <heading>Perl Programs</heading>
433 <sect id="hash_bang">
434 <heading>Script Magic</heading>
436 All packaged perl programs must start with
437 <tt>#!/usr/bin/perl</tt> and may append such flags as are
442 <sect id="program_deps">
443 <heading>Program Dependencies</heading>
445 Programs which require <var>core</var> modules from the
446 <package>perl</package> package must specify a dependency on
450 Programs which contain explicit <tt>require
451 <var>version</var></tt> or <tt>use <var>version</var></tt>
452 statements must specify a dependency on
453 <package>perl</package> or <package>perl-base</package> with
454 the minimum required version, or more simply the current
458 As with modules, packages using <prgn>debhelper</prgn> may use
459 <manref name="dh_perl" section="1"> to automatically generate
460 dependences (see <ref id="dh_perl">).
466 <heading>Programs Embedding Perl</heading>
467 <sect id="build_embedded">
468 <heading>Building Embedded Programs</heading>
470 Programs which embed a perl interpreter must declare a
471 <tt>Build-Depends</tt> on <package>libperl-dev</package>.
474 The default linker options produced by
476 perl -MExtUtils::Embed -e ldopts
478 will link against the dynamic <tt>libperl</tt>. If programs
479 wish to link to the static library, then <tt>-lperl</tt>
480 should be changed to <file>/usr/lib/libperl.a</file> in those
485 <sect id="embedded_deps">
486 <heading>Embedded Perl Dependencies</heading>
488 Dependencies for programs linking against the shared Perl
489 library will be automatically created by
490 <prgn>dpkg-shlibdeps</prgn>. Note however that the shared
491 perl library package only suggests
492 <package>perl-base</package> and packages requiring any
493 <var>core</var> modules from the <package>perl</package>
494 package must depend upon it explicitly.
498 <sect id="perl_upgrades">
499 <heading>Perl Package Upgrades</heading>
501 Starting from <package>perl</package> 5.12.3-2, a dpkg trigger
502 named <var>perl-major-upgrade</var> will be triggered by the
503 postinst of the <package>perl</package> package during major
504 upgrades. Some examples of things which constitute a major upgrade
505 are an upgrade which would change the value of versioned
506 directories in <tt>@INC</tt>, or one which changes <tt>abiname</tt>.
507 Any package may declare an interest in the trigger, especially
508 packages including long-running daemons which would stop working
512 It is suggested that such packages include an appropriate section
513 in their postinst to handle the trigger by restarting relevant
514 daemons or notifying users of further action.
519 <appendix id="perl6">
520 <heading>Perl 6</heading>
522 The current stable upstream version at the time of this writing
523 is 5.6.0. There is currently work in progress on the next major
524 revision, although the specifications have yet to be finalised.
527 It is anticipated that when Perl 6 is released it will initially
528 be packaged as <package>perl6</package>, install the binary as
529 <file>/usr/bin/perl6</file> and use different directories for
530 packaged modules to <package>perl</package>:
535 This will allow Perl 5 and 6 packages and modules (which should
536 be packaged as <package>libfoo-bar-perl6</package>), to co-exist
537 for as long as required.
540 At some stage in the future when Perl 6 is sufficiently mature,
541 the package naming may be reversed such that the
542 <package>perl</package> package contains Perl 6 and the current
543 package becomes <package>perl5</package>.
548 <!-- Local variables: -->
549 <!-- indent-tabs-mode: t -->