Debian Perl Policy ------------------ Raphaël Hertzog Brendan O'Dea version 1.20 ------------------------------------------------------------------------------- Abstract -------- This document describes the packaging of Perl within the Debian GNU/Linux distribution and the policy requirements for packaged Perl programs and modules. Copyright Notice ---------------- 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-licences/GPL' in the Debian GNU/Linux distribution or on the World Wide Web at The GNU Public Licence (http://www.gnu.org/copyleft/gpl.html). You can also obtain it by writing to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. ------------------------------------------------------------------------------- Contents -------- 1. Perl Packaging 1.1. Versions 1.2. Base Package 1.3. Module Path 1.4. Documentation 2. Locally Installed Modules 2.1. Site Directories 2.2. Site Installation 3. Packaged Modules 3.1. Vendor Directories 3.2. Module Package Names 3.3. Vendor Installation 3.4. Module Dependencies 4. Perl Programs 4.1. Script Magic 4.2. Program Dependencies 5. Programs Embedding Perl 5.1. Building Embedded Programs 5.2. Embedded Perl Dependencies A. Perl 6 ------------------------------------------------------------------------------- 1. Perl Packaging ----------------- 1.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 1.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 3.4.2, `Binary Modules'). The `perl-base' package must provide `perlapi-' for all released versions it is compatible with. 1.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 is currently used by such things as `update-alternatives' and some package maintainer scripts, it 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 declare a dependency on `perl-base' rather than `perl'. 1.3. Module Path ---------------- Perl searches three different locations for modules, referred to in this document as in which modules distributed with Perl are installed, for packaged modules and 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: (current) Modules installed by the local administrator for the current version of Perl (see Chapter 2, `Locally Installed Modules'). /usr/local/lib/perl/ /usr/local/share/perl/ Where indicates the current Perl version (`$Config{version}'[1]). Packaged modules (see Chapter 3, `Packaged Modules'). /usr/lib/perl5 /usr/share/perl5 Modules included in the core Perl distribution. /usr/lib/perl/ /usr/share/perl/ (old) 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. [1] see the `Config' module 1.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 Perl packages 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'. ------------------------------------------------------------------------------- 2. Locally Installed Modules ---------------------------- 2.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 1.3, `Module Path' as (current), programs to `/usr/local/bin' and manual pages under `/usr/local/man'. 2.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 ------------------------------------------------------------------------------- 3. Packaged Modules ------------------- 3.1. Vendor Directories ----------------------- The installation directory for Debian modules must be different from that for and modules. The current Perl packaging uses the directories for this purpose, which are at present as described in Section 1.3, `Module Path' as . No version subdirectory exists on these directories as the dependencies for packaged modules (see Section 3.4, `Module Dependencies') should ensure that all work with the current `perl' package. The Perl distribution includes many modules available separately from CPAN[1], which may have a newer version. The intent of the `@INC' ordering (described in Section 1.3, `Module Path') is to allow such modules to be packaged to which take precedence over the version in . A packaged module which shadows a module in this way must be a newer version. Module packages must install manual pages into the standard directories (see Section 1.4, `Documentation') using the extensions `.1p' and `.3pm' to ensure that no conflict arises where a packaged module duplicates a module. `.packlist' files should not be installed. [1] http://www.perl.com/CPAN 3.2. Module Package Names ------------------------- Perl module packages should be named for the primary module provided. The naming convention for module `Foo::Bar' is `libfoo-bar-perl'. Packages which include multiple modules may additionally include provides for those modules using the same convention. 3.3. Vendor Installation ------------------------ A module should use the following lines in the `debian/rules' `build' target[1]: perl Makefile.PL INSTALLDIRS=vendor $(MAKE) OPTIMIZE="-O2 -g -Wall" and this one to install the results into the temporary tree: $(MAKE) install PREFIX=$(CURDIR)/debian/tmp/usr A `Build-Depends' on `perl (>= 5.6.0-16)' is required. [1] 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' 3.4. Module Dependencies ------------------------ 3.4.1. Architecture-Independent Modules --------------------------------------- Architecture-independent modules which require modules from the `perl' package must specify a dependency on that package. Modules which contain explicit `require ' or `use ' statements must specify a dependency on `perl' or `perl-base' with the minimum required version, or more simply the current version. In the absence of an explicit requirement, architecture-independent modules must depend on a minimum `perl' or `perl-base' version of `5.6.0-16' due to the changes in `@INC' introduced by that version. 3.4.2. Binary 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, and must additionally depend on the expansion of `perlapi-$Config{version}' using the `Config' module. 3.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 as build time and written to the `substvars' file in the form `perl:Depends='. 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)'. ------------------------------------------------------------------------------- 4. Perl Programs ---------------- 4.1. Script Magic ----------------- All packaged perl programs must start with `#!/usr/bin/perl' and may append such flags as are required. 4.2. Program Dependencies ------------------------- Programs which require modules from the `perl' package must specify a dependency on that package. Programs which contain explicit `require ' or `use ' 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 Section 3.4.3, `Automating Perl Dependencies'). ------------------------------------------------------------------------------- 5. Programs Embedding Perl -------------------------- 5.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. 5.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 modules from the `perl' package must depend upon it explicitly. ------------------------------------------------------------------------------- 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'. ------------------------------------------------------------------------------- Debian Perl Policy Raphaël Hertzog Brendan O'Dea version 1.20