Chapter 2. Perl Packaging
Prev |  | Next

# Chapter 2. Perl Packaging

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

Prev |  | Next
Chapter 1. About this document | Home | Chapter 3. Locally Installed Modules