# Debian Perl Policy

Raphaël Hertzog
Brendan O'Dea
The Debian Policy Mailing List debian-policy@lists.debian.org
version &version;
&date;

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

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/.

## 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/.

## Perl Packaging

### Versions

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

Only one package may contain the `/usr/bin/perl` binary and that package must either be perl or a dependency of that package (see ).

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 ).

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}`

see the `Config` module

, it must be specified in `$Config{debian_abi}`.

### 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.

### 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

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

site (current)

  Modules installed by the local administrator for the current version of Perl (see ).

      $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.

  Build systems based on `ExtUtils::MakeMaker` and `Module::Build` do this automatically.

vendor

  Packaged modules (see ).

      $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

  For example, to include the multiarch triplet

  . Packages should use `$Config{vendorlib}` and `$Config{vendorarch}`, not hardcode the current locations.

  Build systems based on `ExtUtils::MakeMaker` and `Module::Build` do this automatically.

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.

  Build systems based on `ExtUtils::MakeMaker` and `Module::Build` do this automatically.

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.

### 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 .

## Locally Installed Modules

### 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 as site (current), programs to `/usr/local/bin` and manual pages under `/usr/local/man`.

### 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

## Packaged Modules

### 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 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 ) 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 ) 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.

### 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:

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.

### Vendor Installation

A module should use the following lines in the `debian/rules` `build` target:

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`

    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>

Replace <tmp> with the appropriate directory (nominally just tmp)

### Module Dependencies

#### 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.

#### 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.

#### 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`.

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

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)`.

## Perl Programs

### Script Magic

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

### 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 ).

## Programs Embedding Perl

### 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.

### 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.

### 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.

## 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.