1 <?xml version='1.0' encoding='utf-8'?>
2 <!-- -*- DocBook -*- -->
3 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
4 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
5 <!ENTITY % versiondata SYSTEM "version.xml"> %versiondata;
9 <title>Debian Perl Policy</title>
15 <firstname>Raphaël</firstname><surname>Hertzog</surname>
20 <firstname>Brendan</firstname><surname>O'Dea</surname>
24 <othername>The Debian Policy mailing list</othername>
25 <email>debian-policy@lists.debian.org</email>
29 <releaseinfo>version &version;</releaseinfo>
30 <pubdate>&date;</pubdate>
34 This document describes the packaging of Perl within the Debian
35 distribution and the policy requirements for packaged Perl
41 <year>1999, 2001</year>
42 <holder>Software in the Public Interest</holder>
46 This manual is free software; you can redistribute it and/or
47 modify it under the terms of the GNU General Public License as
48 published by the Free Software Foundation; either version 2 of the
49 License, or (at your option) any later version.
52 This is distributed in the hope that it will be useful, but
53 WITHOUT ANY WARRANTY; without even the implied warranty of
54 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
55 General Public License for more details.
58 A copy of the GNU General Public License is available as
59 <literal>/usr/share/common-licenses/GPL</literal> in the Debian
60 distribution or on the World Wide Web at <ulink
61 url="https://www.gnu.org/copyleft/gpl.html">The GNU Public
65 You can also obtain it by writing to the Free Software Foundation,
66 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
72 <title>About this document</title>
74 This document is distributed as the <literal>perl-policy</literal>
75 files in the Debian package <systemitem role="package"><ulink
76 url="https://packages.debian.org/debian-policy">debian-policy</ulink></systemitem>.
77 It is also available from the Debian web mirrors at <literal><ulink
78 url="https://www.debian.org/doc/packaging-manuals/perl-policy/">/doc/packaging-manuals/perl-policy/</ulink></literal>.
82 <chapter id="ch-perl">
83 <title>Perl Packaging</title>
85 <section id="s-versions">
86 <title>Versions</title>
89 At any given time, the package <systemitem
90 role="package">perl</systemitem> should represent the current
91 stable upstream version of Perl revision 5 (see <xref
92 linkend="ap-perl6"/>).
95 Only one package may contain the
96 <filename>/usr/bin/perl</filename> binary and that package must
97 either be <systemitem role="package">perl</systemitem> or a
98 dependency of that package (see <xref linkend="s-base"/>).
101 Where possible, Perl should be compiled to provide binary
102 compatibility to at least the last released package version to
103 allow a grace period over which binary module packages may be
104 re-built against the new package (see <xref
105 linkend="s-binary-modules"/>).
108 The <systemitem role="package">perl-base</systemitem> package must
110 role="package">perlapi-<replaceable>abiname</replaceable></systemitem>
111 for all released package versions it is compatible with. The
112 choice of <replaceable>abiname</replaceable> is arbitrary, but if
114 <literal>$Config{version}</literal><footnote><para> see the
115 <literal>Config</literal> module </para> </footnote>, it must be
116 specified in <literal>$Config{debian_abi}</literal>.
120 <section id="s-base">
121 <title>Base Package</title>
124 In order to provide a minimal installation of Perl for use by
125 applications without requiring the whole of Perl to be installed,
126 the <systemitem role="package">perl-base</systemitem> package
127 contains the binary and a basic set of modules.
130 As Perl has been part of the essential set for some time and is
131 used without dependencies by such things as package maintainer
132 scripts, <systemitem role="package">perl-base</systemitem> must be
133 priority <emphasis>required</emphasis> and marked as
134 <emphasis>essential</emphasis>.
137 Note that the <systemitem role="package">perl-base</systemitem>
138 package is intended only to provide for exceptional circumstances
139 and the contents may change. In general, only packages which form
140 part of the base system should use only the facilities of
141 <systemitem role="package">perl-base</systemitem> rather than
142 declaring a dependency on <systemitem
143 role="package">perl</systemitem>.
147 <section id="s-paths">
148 <title>Module Path</title>
151 Perl searches several different locations for modules, referred to
152 in this document as <replaceable>core</replaceable> in which
153 modules distributed with Perl are installed,
154 <replaceable>vendor</replaceable> for packaged modules and
155 <replaceable>site</replaceable> for modules installed by the local
159 The module search path (<literal>@INC</literal>) in the current
160 Debian packages has been ordered to include these locations in the
161 following order<footnote><para>@INC contains other paths which
162 should be considered internal to the implementation of the perl
163 packaging</para></footnote>
167 <term><replaceable>site</replaceable> (current)</term>
170 Modules installed by the local administrator for the current
171 version of Perl (see <xref linkend="ch-site"/>).
174 $Config{sitearch} (currently /usr/local/lib/<replaceable>arch-triplet</replaceable>/perl/<replaceable>version</replaceable>)
175 $Config{sitelib} (currently /usr/local/share/perl/<replaceable>version</replaceable>)
178 Where <replaceable>version</replaceable> indicates the
179 current Perl version (<literal>$Config{version}</literal>).
182 These locations, particularly
183 <literal>$Config{sitearch}</literal>, may change if the
184 binary interface between the Perl interpreter and compiled
185 modules has to be changed in an incompatible way without a
186 change in <replaceable>version</replaceable>. While this
187 will only be done as a last resort, packages should use
188 <literal>$Config{sitelib}</literal> and
189 <literal>$Config{sitearch}</literal>, not hardcode the
190 current locations.<footnote><para> Build systems based on
191 <literal>ExtUtils::MakeMaker</literal> and
192 <literal>Module::Build</literal> do this
193 automatically.</para></footnote>
198 <term><replaceable>vendor</replaceable></term>
201 Packaged modules (see <xref linkend="ch-module_packages"/>).
204 $Config{vendorarch} (currently /usr/lib/<replaceable>arch-triplet</replaceable>/perl5/<replaceable>shortversion</replaceable>)
205 $Config{vendorlib} (currently /usr/share/perl5)
208 Where <replaceable>shortversion</replaceable> indicates the
209 current Perl major version (for example
210 <literal>5.22</literal>).
213 These locations, particularly
214 <literal>$Config{vendorarch}</literal>, may change if
215 necessary<footnote><para> For example, to include the
216 multiarch triplet </para> </footnote>. Packages should use
217 <literal>$Config{vendorlib}</literal> and
218 <literal>$Config{vendorarch}</literal>, not hardcode the
219 current locations.<footnote><para> Build systems based on
220 <literal>ExtUtils::MakeMaker</literal> and
221 <literal>Module::Build</literal> do this automatically.
227 <term><replaceable>core</replaceable></term>
230 Modules included in the core Perl distribution.
233 $Config{archlib} (currently /usr/lib/<replaceable>arch-triplet</replaceable>/perl/<replaceable>shortversion</replaceable>)
234 $Config{privlib} (currently /usr/share/perl/<replaceable>shortversion</replaceable>)
237 Where <replaceable>shortversion</replaceable> indicates the
238 current Perl major version (for example
239 <literal>5.22</literal>).
242 These locations should be considered internal to the
243 <systemitem role="package">perl</systemitem> source package.
244 If necessary, packages should use
245 <literal>$Config{archlib}</literal> and
246 <literal>$Config{privlib}</literal> instead of hardcoding
247 the current locations.<footnote><para> Build systems based
248 on <literal>ExtUtils::MakeMaker</literal> and
249 <literal>Module::Build</literal> do this automatically.
255 <term><replaceable>site</replaceable> (old)</term>
258 <replaceable>site</replaceable> directories (as above) for
259 modules installed with previously released <systemitem
260 role="package">perl</systemitem> packages for which the
261 current package is binary compatible are included if
268 In each of the directory pairs above, the <filename>lib</filename>
269 component is for binary (XS) modules, and
270 <filename>share</filename> for architecture-independent
275 <section id="s-docs">
276 <title>Documentation</title>
279 The POD files and manual pages which do not refer to programs may
280 be split out into a separate <systemitem
281 role="package">perl-doc</systemitem> package.
284 Manual pages distributed with packages built from the perl source
285 package must be installed into the standard directories:
289 <term>Programs</term>
292 Manual pages for programs and scripts are installed into
293 <filename>/usr/share/man/man1</filename> with the extension
294 <literal>.1</literal>.
302 Manual pages for modules are installed into
303 <filename>/usr/share/man/man3</filename> with the extension
304 <literal>.3perl</literal>.
310 The extensions used for manual pages distributed with module
311 packages are different. See <xref linkend="s-vendor-dirs"/>.
317 <chapter id="ch-site">
318 <title>Locally Installed Modules</title>
320 <section id="s-site-dirs">
321 <title>Site Directories</title>
324 The Perl packages must provide a mechanism for the local
325 administrator to install modules under
326 <filename>/usr/local</filename> but must not create or remove
330 Modules should be installed to the directories described above in
331 <xref linkend="s-paths"/> as <replaceable>site</replaceable>
332 (current), programs to <filename>/usr/local/bin</filename> and
333 manual pages under <filename>/usr/local/man</filename>.
337 <section id="s-site-install">
338 <title>Site Installation</title>
341 The following commands should be sufficient in the majority of
342 cases for the local administrator to install modules and must
343 create directories as required:
353 <chapter id="ch-module_packages">
354 <title>Packaged Modules</title>
356 <section id="s-vendor-dirs">
357 <title>Vendor Directories</title>
360 The installation directory for Debian modules must be different
361 from that for <replaceable>core</replaceable> and
362 <replaceable>site</replaceable> modules.
365 The current Perl packaging uses the
366 <replaceable>vendor</replaceable> directories for this purpose,
367 which are at present as described in <xref linkend="s-paths"/> as
368 <replaceable>vendor</replaceable>.
371 The Perl distribution includes many modules available separately
372 from CPAN<footnote><para> <ulink
373 url="https://www.perl.com/CPAN">https://www.perl.com/CPAN</ulink></para></footnote>,
374 which may have a newer version. The intent of the
375 <literal>@INC</literal> ordering (described in <xref
376 linkend="s-paths"/>) is to allow such modules to be packaged to
377 <replaceable>vendor</replaceable> which take precedence over the
378 version in <replaceable>core</replaceable>. A packaged module
379 which shadows a <replaceable>core</replaceable> module in this way
380 must be a newer version.
383 Module packages must install manual pages into the standard
384 directories (see <xref linkend="s-docs"/>) using the extensions
385 <literal>.1p</literal> and <literal>.3pm</literal> to ensure that
386 no conflict arises where a packaged module duplicates a
387 <replaceable>core</replaceable> module.
390 <filename>.packlist</filename> files should not be installed.
394 <section id="s-package-names">
395 <title>Module Package Names</title>
397 Perl module packages should be named for the primary module
398 provided. The naming convention is to lowercase the Perl module
399 name, prepend, <literal>lib</literal>, change all occurrences of
400 <literal>::</literal> to <literal>-</literal>, and append
401 <literal>-perl</literal>. For example:
404 Foo::Bar libfoo-bar-perl
405 Foo::Bar::Baz libfoo-bar-baz-perl
406 Foo::BarBaz libfoo-barbaz-perl
409 Packages which include multiple modules may additionally include
410 provides for the additional modules using the same convention.
414 <section id="s-vendor-install">
415 <title>Vendor Installation</title>
417 A module should use the following lines in the
418 <filename>debian/rules</filename> <literal>build</literal>
419 target<footnote><para> The environment variable
420 <literal>PERL_MM_OPT</literal> may be used to pass the
421 <literal>INSTALLDIRS=vendor</literal> option in cases where
422 <filename>Makefile.PL</filename> is not invoked directly from
423 <filename>debian/rules</filename></para></footnote>:
426 perl Makefile.PL INSTALLDIRS=vendor
427 $(MAKE) OPTIMIZE="-O2 -g -Wall"
430 and this one to install the results into the temporary tree:
433 $(MAKE) install DESTDIR=$(CURDIR)/debian/<tmp>
436 <footnote><para>Replace <tmp> with the appropriate directory
437 (nominally just tmp)</para></footnote>
441 <section id="s-module-deps">
442 <title>Module Dependencies</title>
444 <section id="s-indep-modules">
445 <title>Architecture-Independent Modules</title>
448 Architecture-independent modules which require
449 <replaceable>core</replaceable> modules from the <systemitem
450 role="package">perl</systemitem> package must specify a
451 dependency on that package.
454 Modules which contain explicit <literal>require
455 <replaceable>version</replaceable></literal> or <literal>use
456 <replaceable>version</replaceable></literal> statements must
457 specify a dependency on <systemitem
458 role="package">perl</systemitem> or <systemitem
459 role="package">perl-base</systemitem> with the minimum required
460 version, or more simply the current version.
464 <section id="s-binary-modules">
465 <title>Binary and Other Architecture Dependent Modules</title>
468 Binary modules must specify a dependency on either <systemitem
469 role="package">perl</systemitem> or <systemitem
470 role="package">perl-base</systemitem> with a minimum version of
471 the <systemitem role="package">perl</systemitem> package used to
472 build the module. Additionally, all binary modules (regardless
473 of their installation directory) and any other modules installed
474 into <literal>$Config{vendorarch}</literal> must depend on the
475 expansion of <systemitem
476 role="package">perlapi-$Config{debian_abi}</systemitem> using
477 the <literal>Config</literal> module. If
478 <literal>$Config{debian_abi}</literal> is empty or not set,
479 <literal>$Config{version}</literal> must be used.
483 <section id="s-dh-perl">
484 <title>Automating Perl Dependencies</title>
487 Rather than hard-coding the dependencies into the control file,
488 using a substitution such as <literal>${perl:Depends}</literal>
489 is suggested. This allows the dependencies to be determined at
490 build time and written to the <filename>substvars</filename>
492 <literal>perl:Depends=<replaceable>deps</replaceable></literal>.<footnote><para>
493 Please note that dependencies caused by versioned uses and on
494 separately packaged modules are not included in this variable
495 and must be explicitly included. </para> </footnote>
498 Packages built with <command>debhelper</command> may use
499 <citerefentry><refentrytitle>dh_perl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
500 to generate this substitution automatically. This additionally
501 requires a versioned <literal>Build-Depends</literal> (or
502 <literal>Build-Depends-Indep</literal>) on <literal>debhelper
503 (>= 3.0.18)</literal>.
509 <chapter id="ch-programs">
510 <title>Perl Programs</title>
512 <section id="s-hash-bang">
513 <title>Script Magic</title>
516 All packaged perl programs must start with
517 <literal>#!/usr/bin/perl</literal> and may append such flags as
522 <section id="s-program-deps">
523 <title>Program Dependencies</title>
526 Programs which require <replaceable>core</replaceable> modules
527 from the <systemitem role="package">perl</systemitem> package must
528 specify a dependency on that package.
531 Programs which contain explicit <literal>require
532 <replaceable>version</replaceable></literal> or <literal>use
533 <replaceable>version</replaceable></literal> statements must
534 specify a dependency on <systemitem
535 role="package">perl</systemitem> or <systemitem
536 role="package">perl-base</systemitem> with the minimum required
537 version, or more simply the current version.
540 As with modules, packages using <command>debhelper</command> may
542 <citerefentry><refentrytitle>dh_perl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
543 to automatically generate dependences (see <xref
544 linkend="s-dh-perl"/>).
550 <chapter id="ch-embed">
551 <title>Programs Embedding Perl</title>
553 <section id="s-build-embedded">
554 <title>Building Embedded Programs</title>
557 Programs which embed a perl interpreter must declare a
558 <literal>Build-Depends</literal> on <systemitem
559 role="package">libperl-dev</systemitem>.
562 The default linker options produced by
565 perl -MExtUtils::Embed -e ldopts
568 will link against the dynamic <literal>libperl</literal>. If
569 programs wish to link to the static library, then
570 <literal>-lperl</literal> should be changed to
571 <filename>/usr/lib/libperl.a</filename> in those options.
575 <section id="s-embedded-deps">
576 <title>Embedded Perl Dependencies</title>
579 Dependencies for programs linking against the shared Perl library
580 will be automatically created by
581 <command>dpkg-shlibdeps</command>. Note however that the shared
582 perl library package only suggests <systemitem
583 role="package">perl-base</systemitem> and packages requiring any
584 <replaceable>core</replaceable> modules from the <systemitem
585 role="package">perl</systemitem> package must depend upon it
590 <section id="s-perl-upgrades">
591 <title>Perl Package Upgrades</title>
594 Starting from <systemitem role="package">perl</systemitem>
595 5.12.3-2, a dpkg trigger named
596 <replaceable>perl-major-upgrade</replaceable> will be triggered by
597 the postinst of the <systemitem role="package">perl</systemitem>
598 package during major upgrades. Some examples of things which
599 constitute a major upgrade are an upgrade which would change the
600 value of versioned directories in <literal>@INC</literal>, or one
601 which changes <literal>abiname</literal>. Any package may declare
602 an interest in the trigger, especially packages including
603 long-running daemons which would stop working until restart.
606 It is suggested that such packages include an appropriate section
607 in their postinst to handle the trigger by restarting relevant
608 daemons or notifying users of further action.
614 <appendix id="ap-perl6">
615 <title>Perl 6</title>
618 The current stable upstream version at the time of this writing is
619 5.6.0. There is currently work in progress on the next major
620 revision, although the specifications have yet to be finalised.
623 It is anticipated that when Perl 6 is released it will initially be
624 packaged as <systemitem role="package">perl6</systemitem>, install
625 the binary as <filename>/usr/bin/perl6</filename> and use different
626 directories for packaged modules to <systemitem
627 role="package">perl</systemitem>:
634 This will allow Perl 5 and 6 packages and modules (which should be
635 packaged as <systemitem
636 role="package">libfoo-bar-perl6</systemitem>), to co-exist for as
640 At some stage in the future when Perl 6 is sufficiently mature, the
641 package naming may be reversed such that the <systemitem
642 role="package">perl</systemitem> package contains Perl 6 and the
643 current package becomes <systemitem
644 role="package">perl5</systemitem>.