[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ A ] [ next ]
This document describes the packaging of Perl within the Debian distribution and the policy requirements for packaged Perl programs and modules.
Copyright © 1999, 2001 Software in the Public Interest
This manual is free software; you can 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 The
GNU Public Licence
.
You can also obtain it by writing to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ A ] [ next ]
This document is distributed as the perl-policy files in the
Debian package
.
It is also available from the Debian web mirrors at debian-policy
/doc/packaging-manuals/perl-policy/
.
[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ A ] [ next ]
At any given time, the package perl
should represent the current
stable upstream version of Perl revision 5 (see Perl 6,
Appendix A).
Only one package may contain the /usr/bin/perl
binary and that
package must either be perl
or a dependency of that package (see
Base Package, Section 2.2).
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 Binary Modules, Section 4.4.2).
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}, 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 three 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 Debian packages has been ordered to include these locations in the following order:
Modules installed by the local administrator for the current version of Perl (see Locally Installed Modules, Chapter 3).
/usr/local/lib/perl/version /usr/local/share/perl/version
Where version indicates the current Perl version ($Config{version}[1]).
Packaged modules (see Packaged Modules, Chapter 4).
/usr/lib/perl5 /usr/share/perl5
Modules included in the core Perl distribution.
/usr/lib/perl/version /usr/share/perl/version
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 Vendor Directories, Section 4.1.
[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ A ] [ next ]
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 Module Path, Section 2.3 as site (current),
programs to /usr/local/bin
and manual pages under
/usr/local/man
.
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
[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ A ] [ next ]
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 Module Path, Section 2.3 as vendor.
No version subdirectory exists on these directories as the dependencies for
packaged modules (see Module Dependencies, Section
4.4) should ensure that all work with the current perl
package.
The Perl distribution includes many modules available separately from CPAN[2], which may have a newer version. The intent of the @INC ordering (described in Module Path, Section 2.3) 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 Documentation, Section 2.4) 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:
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[3]:
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>
[4]
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 modules must specify a dependency on either perl
or
perl-base
with a minimum version of the perl
package
used to build the module, and must additionally 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=deps.[5]
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).
[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ A ] [ next ]
All packaged perl programs must 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 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 dependences (see Automating Perl Dependencies, Section 4.4.3).
[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ A ] [ next ]
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.
[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ A ] [ next ]
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
.
see the Config module
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
Replace <tmp> with the appropriate directory (nominally just tmp)
Please note that dependencies caused by versioned uses and on separately packaged modules are not included in this variable and must be explicitly included.
[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ A ] [ next ]
Debian Perl Policy
version 3.9.3.1, 2012-03-13debian-policy@lists.debian.org