                               Debian Perl Policy

  Raphaël Hertzog

  Brendan O'Dea

  The Debian Policy Mailing List

   <debian-policy@lists.debian.org>

   version 4.7.4.0

   Copyright © 1999, 2001 Raphaël Hertzog, Brendan O'Dea

   These are the copyright dates of the original Debian Perl Policy. Since
   then, this document has been updated by many others. No comprehensive
   collection of copyright notices for subsequent work exists.

   This manual is free software; you may redistribute it and/or modify it
   under the terms of the GNU General Public License as published by the Free
   Software Foundation; either version 2 of the License, or (at your option)
   any later version.

   This is distributed in the hope that it will be useful, but WITHOUT ANY
   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
   FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
   details.

   A copy of the GNU General Public License is available as
   /usr/share/common-licenses/GPL in the Debian distribution or on the World
   Wide Web at https://www.gnu.org/licenses/.

   2026-03-31

   Abstract

   This document describes the packaging of Perl within the Debian
   distribution and the policy requirements for packaged Perl programs and
   modules.

     ----------------------------------------------------------------------

   Table of Contents

   1. About this document

   2. Perl Packaging

                2.1. Versions

                2.2. Base Package

                2.3. Module Path

                2.4. Documentation

   3. Locally Installed Modules

                3.1. Site Directories

                3.2. Site Installation

   4. Packaged Modules

                4.1. Vendor Directories

                4.2. Module Package Names

                4.3. Vendor Installation

                4.4. Module Dependencies

                             4.4.1. Architecture-Independent Modules

                             4.4.2. Binary and Other Architecture Dependent
                             Modules

                             4.4.3. Automating Perl Dependencies

   5. Perl Programs

                5.1. Script Magic

                5.2. Program Dependencies

   6. Programs Embedding Perl

                6.1. Building Embedded Programs

                6.2. Embedded Perl Dependencies

                6.3. Perl Package Upgrades

   A. Perl 6

   List of Tables

   4.1. Module to package mappings

                         Chapter 1. About this document

   This document is distributed as the perl-policy files in the Debian
   package debian-policy. It is also available from the Debian web mirrors at
   https://www.debian.org/doc/packaging-manuals/perl-policy/.

                           Chapter 2. Perl Packaging

   Table of Contents

   2.1. Versions

   2.2. Base Package

   2.3. Module Path

   2.4. Documentation

2.1. Versions

   At any given time, the package perl should represent the current stable
   upstream version of Perl revision 5 (see Appendix A, Perl 6).

   Only one package may contain the /usr/bin/perl binary and that package
   must either be perl or a dependency of that package (see Section 2.2,
   “Base Package”).

   Where possible, Perl should be compiled to provide binary compatibility to
   at least the last released package version to allow a grace period over
   which binary module packages may be re-built against the new package (see
   Section 4.4.2, “Binary and Other Architecture Dependent Modules”).

   The perl-base package must provide perlapi-abiname for all released
   package versions it is compatible with. The choice of abiname is
   arbitrary, but if it differs from $Config{version}^[1], it must be
   specified in $Config{debian_abi}.

2.2. Base Package

   In order to provide a minimal installation of Perl for use by applications
   without requiring the whole of Perl to be installed, the perl-base package
   contains the binary and a basic set of modules.

   As Perl has been part of the essential set for some time and is used
   without dependencies by such things as package maintainer scripts,
   perl-base must be priority required and marked as essential.

   Note that the perl-base package is intended only to provide for
   exceptional circumstances and the contents may change. In general, only
   packages which form part of the base system should use only the facilities
   of perl-base rather than declaring a dependency on perl.

2.3. Module Path

   Perl searches several different locations for modules, referred to in this
   document as core in which modules distributed with Perl are installed,
   vendor for packaged modules and site for modules installed by the local
   administrator.

   The module search path (@INC) in the current Debian packages has been
   ordered to include these locations in the following order^[2]

   site (current)

           Modules installed by the local administrator for the current
           version of Perl (see Chapter 3, Locally Installed Modules).

 $Config{sitearch}  (currently /usr/local/lib/arch-triplet/perl/version)
 $Config{sitelib}   (currently /usr/local/share/perl/version)

           Where version indicates the current Perl version
           ($Config{version}).

           These locations, particularly $Config{sitearch}, may change if the
           binary interface between the Perl interpreter and compiled modules
           has to be changed in an incompatible way without a change in
           version. While this will only be done as a last resort, packages
           should use $Config{sitelib} and $Config{sitearch}, not hardcode
           the current locations.^[3]

   vendor

           Packaged modules (see Chapter 4, Packaged Modules).

 $Config{vendorarch} (currently /usr/lib/arch-triplet/perl5/shortversion)
 $Config{vendorlib}  (currently /usr/share/perl5)

           Where shortversion indicates the current Perl major version (for
           example 5.22).

           These locations, particularly $Config{vendorarch}, may change if
           necessary^[4]. Packages should use $Config{vendorlib} and
           $Config{vendorarch}, not hardcode the current locations.^[5]

   core

           Modules included in the core Perl distribution.

 $Config{archlib} (currently /usr/lib/arch-triplet/perl/shortversion)
 $Config{privlib} (currently /usr/share/perl/shortversion)

           Where shortversion indicates the current Perl major version (for
           example 5.22).

           These locations should be considered internal to the perl source
           package. If necessary, packages should use $Config{archlib} and
           $Config{privlib} instead of hardcoding the current locations.^[6]

   site (old)

           site directories (as above) for modules installed with previously
           released perl packages for which the current package is binary
           compatible are included if present.

   In each of the directory pairs above, the lib component is for binary (XS)
   modules, and share for architecture-independent (pure-perl) modules.

2.4. Documentation

   The POD files and manual pages which do not refer to programs may be split
   out into a separate perl-doc package.

   Manual pages distributed with packages built from the perl source package
   must be installed into the standard directories:

   Programs

           Manual pages for programs and scripts are installed into
           /usr/share/man/man1 with the extension .1.

   Modules

           Manual pages for modules are installed into /usr/share/man/man3
           with the extension .3perl.

   The extensions used for manual pages distributed with module packages are
   different. See Section 4.1, “Vendor Directories”.

     ----------------------------------------------------------------------

   ^[1] see the Config module

   ^[2] @INC contains other paths which should be considered internal to the
   implementation of the perl packaging

   ^[3] Build systems based on ExtUtils::MakeMaker and Module::Build do this
   automatically.

   ^[4] For example, to include the multiarch triplet

   ^[5] Build systems based on ExtUtils::MakeMaker and Module::Build do this
   automatically.

   ^[6] Build systems based on ExtUtils::MakeMaker and Module::Build do this
   automatically.

                      Chapter 3. Locally Installed Modules

   Table of Contents

   3.1. Site Directories

   3.2. Site Installation

3.1. Site Directories

   The Perl packages must provide a mechanism for the local administrator to
   install modules under /usr/local but must not create or remove those
   directories.

   Modules should be installed to the directories described above in
   Section 2.3, “Module Path” as site (current), programs to /usr/local/bin
   and manual pages under /usr/local/man.

3.2. Site Installation

   The following commands should be sufficient in the majority of cases for
   the local administrator to install modules and must create directories as
   required:

 perl Makefile.PL
 make install

                          Chapter 4. Packaged Modules

   Table of Contents

   4.1. Vendor Directories

   4.2. Module Package Names

   4.3. Vendor Installation

   4.4. Module Dependencies

                4.4.1. Architecture-Independent Modules

                4.4.2. Binary and Other Architecture Dependent Modules

                4.4.3. Automating Perl Dependencies

4.1. Vendor Directories

   The installation directory for Debian modules must be different from that
   for core and site modules.

   The current Perl packaging uses the vendor directories for this purpose,
   which are at present as described in Section 2.3, “Module Path” as vendor.

   The Perl distribution includes many modules available separately from CPAN
   which may have a newer version. The intent of the @INC ordering (described
   in Section 2.3, “Module Path”) is to allow such modules to be packaged to
   vendor which take precedence over the version in core. A packaged module
   which shadows a core module in this way must be a newer version.

   Module packages must install manual pages into the standard directories
   (see Section 2.4, “Documentation”) using the extensions .1p and .3pm to
   ensure that no conflict arises where a packaged module duplicates a core
   module.

   .packlist files should not be installed.

4.2. Module Package Names

   Perl module packages should be named for the primary module provided. The
   naming convention is to lowercase the Perl module name, prepend, lib,
   change all occurrences of :: to -, and append -perl. For example:

   Table 4.1. Module to package mappings

   +-------------------------------------+
   | Module        | Package             |
   |---------------+---------------------|
   | Foo::Bar      | libfoo-bar-perl     |
   |---------------+---------------------|
   | Foo::Bar::Baz | libfoo-bar-baz-perl |
   |---------------+---------------------|
   | Foo::BarBaz   | libfoo-barbaz-perl  |
   +-------------------------------------+

   Packages which include multiple modules may additionally include provides
   for the additional modules using the same convention.

4.3. Vendor Installation

   A module should use the following lines in the debian/rules build target:
   ^[7]

 perl Makefile.PL INSTALLDIRS=vendor
 $(MAKE) OPTIMIZE="-O2 -g -Wall"

   and this one to install the results into the temporary tree:

 $(MAKE) install DESTDIR=$(CURDIR)/debian/<tmp>

   ^[8]

4.4. Module Dependencies

  4.4.1. Architecture-Independent Modules

   Architecture-independent modules which require core modules from the perl
   package must specify a dependency on that package.

   Modules which contain explicit require version or use version statements
   must specify a dependency on perl or perl-base with the minimum required
   version, or more simply the current version.

  4.4.2. Binary and Other Architecture Dependent Modules

   Binary modules must specify a dependency on either perl or perl-base with
   a minimum version of the perl package used to build the module.
   Additionally, all binary modules (regardless of their installation
   directory) and any other modules installed into $Config{vendorarch} must
   depend on the expansion of perlapi-$Config{debian_abi} using the Config
   module. If $Config{debian_abi} is empty or not set, $Config{version} must
   be used.

  4.4.3. Automating Perl Dependencies

   Rather than hard-coding the dependencies into the control file, using a
   substitution such as ${perl:Depends} is suggested. This allows the
   dependencies to be determined at build time and written to the substvars
   file in the form perl:Depends=deps.^[9]

   Packages built with debhelper may use dh_perl(1) to generate this
   substitution automatically. This additionally requires a versioned
   Build-Depends (or Build-Depends-Indep) on debhelper (>= 3.0.18).

     ----------------------------------------------------------------------

   ^[7] The environment variable PERL_MM_OPT may be used to pass the
   INSTALLDIRS=vendor option in cases where Makefile.PL is not invoked
   directly from debian/rules

   ^[8] Replace <tmp> with the appropriate directory (nominally just tmp)

   ^[9] Please note that dependencies caused by versioned uses and on
   separately packaged modules are not included in this variable and must be
   explicitly included.

                            Chapter 5. Perl Programs

   Table of Contents

   5.1. Script Magic

   5.2. Program Dependencies

5.1. Script Magic

   All packaged perl programs should start with #!/usr/bin/perl and may
   append such flags as are required.

5.2. Program Dependencies

   Programs which require core modules from the perl package must specify a
   dependency on that package.

   Programs which contain explicit require version or use version statements
   must specify a dependency on perl or perl-base with the minimum required
   version, or more simply the current version.

   As with modules, packages using debhelper may use dh_perl(1) to
   automatically generate dependencies (see Section 4.4.3, “Automating Perl
   Dependencies”).

                       Chapter 6. Programs Embedding Perl

   Table of Contents

   6.1. Building Embedded Programs

   6.2. Embedded Perl Dependencies

   6.3. Perl Package Upgrades

6.1. Building Embedded Programs

   Programs which embed a perl interpreter must declare a Build-Depends on
   libperl-dev.

   The default linker options produced by

 perl -MExtUtils::Embed -e ldopts

   will link against the dynamic libperl. If programs wish to link to the
   static library, then -lperl should be changed to /usr/lib/libperl.a in
   those options.

6.2. Embedded Perl Dependencies

   Dependencies for programs linking against the shared Perl library will be
   automatically created by dpkg-shlibdeps. Note however that the shared perl
   library package only suggests perl-base and packages requiring any core
   modules from the perl package must depend upon it explicitly.

6.3. Perl Package Upgrades

   Starting from perl 5.12.3-2, a dpkg trigger named perl-major-upgrade will
   be triggered by the postinst of the perl package during major upgrades.
   Some examples of things which constitute a major upgrade are an upgrade
   which would change the value of versioned directories in @INC, or one
   which changes abiname. Any package may declare an interest in the trigger,
   especially packages including long-running daemons which would stop
   working until restart.

   It is suggested that such packages include an appropriate section in their
   postinst to handle the trigger by restarting relevant daemons or notifying
   users of further action.

                               Appendix A. Perl 6

   The current stable upstream version at the time of this writing is 5.6.0.
   There is currently work in progress on the next major revision, although
   the specifications have yet to be finalised.

   It is anticipated that when Perl 6 is released it will initially be
   packaged as perl6, install the binary as /usr/bin/perl6 and use different
   directories for packaged modules to perl:

 /usr/lib/perl6
 /usr/share/perl6

   This will allow Perl 5 and 6 packages and modules (which should be
   packaged as libfoo-bar-perl6), to co-exist for as long as required.

   At some stage in the future when Perl 6 is sufficiently mature, the
   package naming may be reversed such that the perl package contains Perl 6
   and the current package becomes perl5.
