Perl Policy

From ArchWiki
Revision as of 16:09, 22 May 2007 by Xterminus (Talk | contribs)

Jump to: navigation, search

Tango-document-new.pngThis article is a stub.Tango-document-new.png

Notes: please use the first argument of the template to provide more detailed indications. (Discuss in Talk:Perl Policy#)


This document is currently a proposal for standards regarding to the perl package, related perl packages, creating perl module packages (both in binary form and in the form of PKGBUILDs). Portions are derived from the Debian Perl Policy document, and from various portions of the perl man pages.

It does not reflect the current ArchLinux perl package(s) layout. This policy, if implemented - represents a major change in way Arch handles perl. Please do not use this document as a template for creating new perl module packages... yet...

The current ArchLinux default perl installation installs site and vendor packages into the same directory tree, which frequently causes conflicts if the end user installs local packages. In addition, a symlink-farm is created in /usr/lib/perl5/ and /usr/lib/perl5/site_perl. This policy would eliminate both.

This policy would require an update of every perl module PKGBUILD so that it installs into the correct directory tree. It remains somewhat backwards-compatible with the old structure, in that old PKGBUILD's would technically work, however local installs would clobber files installed with the "old" method.


At any given time, the package perl should represent the current stable upstream version of Perl revision 5. (see 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. In order to provide a minimal installation of Perl for use by applications without requiring the whole of Perl to be installed, the perl package contains the binary and a basic set of modules.

Module Paths

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 Archlinux packages has been ordered to include these locations in the following order:

  • site

Modules installed by the local administrator for the current version of Perl. Typically, these modules are installed using the cpan tool, or are downloaded in source form and installed via make.

  • vendor

Packaged modules, installed via the pacman tool from current/extra or community, or built into proper archlinux packages from ABS/AUR PKGBUILDS.

  • core

Modules included in the core Perl distribution. Also modules included in the perl-modules package. See core-perl-modules.


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 packages, which is normal for most archlinux packages in general. This is optional however.

Manual pages distributed with Perl packages 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.


Site Modules are perl modules installed by the local administrator for the current version of Perl. Typically, these modules are installed using the cpan tool, or are downloaded in source form and installed via make.

Site Directories

The Perl packages must provide a mechanism for the local administrator to install modules under /usr/lib/perl5/site_perl but must not create or remove those directories.

Modules should be installed to the directories described above in Module Path site, 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


cpan Foo::Bar


Vendor modules are packaged modules, installed via the pacman tool which grabs pre-compiled modules from a repository, or modules which have been built into proper archlinux packages from a PKGBUILD.

Vendor Directories

The installation directory for Archlinux modules must be different from that for site modules.

The current Perl packaging uses the vendor directories for this purpose, which are at present as described in above as vendor.

No version subdirectory exists on these directories as the dependencies for packaged modules should ensure that all work with the current perl package.

The Perl distribution includes many modules available separately from CPAN, which may have a newer version. The intent of the @INC ordering (described above) 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 using the extensions .1p and .3pm to ensure that no conflict arises where a packaged module duplicates a core module.

.packlist (used for module uninstalls) and perllocal.pod (used to record local/site installations) files should not be installed, and should be removed from the package if found.

Empty directories should be pruned.

Module Package Names

Perl module packages should be named for the primary module provided. The naming convention for module Foo::Bar is perl-foo-bar. Packages which include multiple modules may additionally include provides for those modules using the same convention.

Vendor Installation

A module should use the following lines in the PKGBUILD build target.

perl Makefile.PL INSTALLDIRS=vendor

and this one to install the results into the temporary tree...

make install DESTDIR=$startdir/pkg install || return 1

A makedepends on perl (>= 5.8.8-6) is required.

Sample Vendor PKGBUILD

# Maintainer: Harry Hacker <>
pkgdesc="Perl/CPAN Module HTML::Template : a simple HTML templating system"
arch=("i686" "x86_64")
license=("GPL" "Artistic")
build() {
  cd $startdir/src/HTML-Template-2.9
  /usr/bin/perl Makefile.PL INSTALLDIRS=vendor || return 1
  make || return 1
  make DESTDIR=$startdir/pkg install || return 1
  /usr/bin/find $startdir/pkg -name '.packlist' -exec rm  '{}' \; && \
  /usr/bin/find $startdir/pkg -name 'perllocal.pod' -exec rm  '{}' \; && \

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 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 version of 5.8.8-6 due to the changes in @INC introduced by that version.

Binary Modules

Binary modules must specify a dependency on either perl 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.


Core Directories

Modules included in the core Perl distribution should be installed into /usr/lib/perl5 and /usr/share/perl5.

Only modules contained in the perl or perl-modules package should touch this directory.

No version subdirectory exists on these directories as the dependencies for packaged modules should ensure that all work with the current perl package.

Core perl packages


The perl package should contain the /usr/bin/perl binary, and a minimal set of modules needed in order for simple perl scripts to run.

Sample perl PKGBUILD



The perl-modules package should contain all the extra modules provided in the perl package, as well as all of the the pragmatic and standard modules listed by executing perldoc perlmodlib. This package should provide modules which are expected to be present on any standard perl installation; such as Data::Dumper, CGI, and Encode. In addition, this package should includes provides for the perl-equivalent packagenames for each of the modules contained.

This package is complex, with many dependencies which need to be built by hand. It should be updated only when the perl package is.

Users requiring a newer modules than what is provided in perl-modules are advised to install a site package until the next version of the perl package is released.


The current stable upstream version at the time of this writing is 5.8.8. 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:


This will allow Perl 5 and 6 packages and modules (which should be packaged as perl6-foo-bar), 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.