version 4.5.1.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/.
2020-11-17
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
List of Tables
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/.
Table of Contents
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-
for all released package versions it is compatible with. The
choice of abinameabiname is arbitrary, but if
it differs from
$Config{version}[1], it must be
specified in $Config{debian_abi}.
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.
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]
vendorPackaged 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]
coreModules 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.
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:
Manual pages for programs and scripts are installed into
/usr/share/man/man1 with the extension
.1.
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.
Table of Contents
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.
Table of Contents
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.
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.
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>
Architecture-independent modules which require
core modules from the perl package must specify a
dependency on that package.
Modules which contain explicit require
or versionuse
statements must
specify a dependency on versionperl or perl-base with the minimum required
version, or more simply the current version.
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.
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=.[9]
deps
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.
Table of Contents
All packaged perl programs should start with
#!/usr/bin/perl and may append such flags as
are required.
Programs which require core modules
from the perl package must
specify a dependency on that package.
Programs which contain explicit require
or versionuse
statements must
specify a dependency on versionperl 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”).
Table of Contents
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.
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.
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.
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.