Perl Policy

This page covers the policy for how perl itself is configured and packaged. For Perl module packaging guidelines, see
Perl package guidelines
.
Introduction
This policy document was proposed, accepted, and implemented in version 5.10.0 of the
perl
package. It is the standard regarding to the
perl
package, related Perl packages, and 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.
Reasoning
Apparent problems with pre-5.10.0 perl packaging conventions included:
The current Arch Linux default perl installation installs
site
and
vendor
packages into the same directory tree, which frequently causes conflicts if the end user installs and upgrades Arch Linux perl (
vendor
) packages on top of
site
packages.
The current Arch Linux default perl installation installs updates to
core
modules into the perl
core
directories, creating file conflicts. Examples include modules such as
Data::Dumper
and
version
.
A symlink-farm is created in
/usr/lib/perl5/
and
/usr/lib/perl5/site_perl
which is unnecessary and confusing.
A number of standard modules seem to be missing, or were neglected to be added as
provides
in the
perl
package itself, causing confusion and redundant entries in AUR and repositories as users try and
fix
the apparent problem of missing modules, which are provided by
perl
. This is probably a matter of education.
Current perl-module PKGBUILD's could be simplified and standardized quite a bit.
This policy would eliminate all these problems.
Pitfalls
Current (apparent) downsides to adopting a policy such as this one:
An update of every perl module PKGBUILD so that it installs into the correct (
vendor
) directory tree. It remains somewhat backwards-compatible with the old structure, in that old PKGBUILD's would technically
work
.
Introduces changes into the
perl
package, which lives in the
core
repository, and proposes a new
perl-modules
package, which would live in the
extra
repository.
Non-perl packages which compile static copies of the perl interpreter will not operate correctly until recompiled on an Arch Linux PC which adheres to this document. Examples of such packages include
vim
,
subversion
, and
irssi
. Many such examples exist.
Perl versions
At any given time, the package
perl
should represent the current stable upstream version of Perl revision 5. (see
#Perl 7
).
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. The
perl
package should declare
provide
statements for every module provided by the base
perl
package.
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 Arch Linux 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
or
cpanm
tool, or are downloaded in source form and installed via make.
/usr/lib/perl5/
version
/site_perl
/usr/share/perl5/site_perl
vendor
Packaged modules, installed via the pacman tool from the
core
or
extra
repositories, or built into proper Arch Linux packages from ABS/AUR PKGBUILDs.
/usr/lib/perl5/
version
/vendor_perl
/usr/share/perl5/vendor_perl
core
Modules included in the core Perl distribution.
/usr/lib/perl5/
version
/core_perl
/usr/share/perl5/core_perl
obsolete
Obsolete is the path name to modules installed prior to the establishment of this document.
/usr/lib/perl5/site_perl/current/arch
/usr/lib/perl5/site_perl/current
/usr/lib/perl5/current
In each of the directory pairs above, the
lib
component is for binary, architecture dependent (XS) modules, and
share
for architecture-independent (pure-perl) modules. Under no circumstances should
current
be used as a replacement for
version
. Core and Vendor modules
should
be matched to the current installation of perl.
Note
Obsolete paths have been removed from
@INC
in perl 5.12.2
[1]
.
Documents
The POD files, manual pages, and HTML documentation that do not refer to programs may be stripped from the package, which is normal for most Arch Linux packages in general. This is optional.
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
.1perl
.
Modules
Manual pages for modules are installed into
/usr/share/man/man3
with the extension
.3perl
.
Binaries and scripts
In order to prevent file collisions, it is important to keep binaries generated by
core
,
vendor
, and
site
installs separate. It is also important that the default
PATH
environment variable set in each users profile to search for binaries in the same order as perl's
@INC
path. In order to accomplish this, binaries should be installed into the following directories:
Site
Binaries and scripts for all
site
should default to be installed into
/usr/bin/site_perl
.
Vendor
Binaries and scripts for all
vendor
packages should be installed into
/usr/bin/vendor_perl
.
Core
Binaries and scripts for all
core
packages should be installed into
/usr/bin/core_perl
.
The
perl
package should include a mechanism to adjust end-users
PATH
entries accordingly so that perl binaries are searched for in the following order:
site
,
vendor
,
core
.
Site
Site modules are perl modules installed by the local administrator for the current version of Perl. Typically, these modules are installed using the
cpan
or
cpanm
tool, or are downloaded in source form and installed via make (or MakeMaker).
Site directories
The Perl packages must provide a mechanism for the local administrator to install modules under
/usr/lib/perl5/
version
/site_perl
and
/usr/share/perl5/site_perl
but must not create or remove those directories.
Modules should be installed to the directories described in
#Module paths
"site", programs to
/usr/bin/site_perl
and manual pages under
/usr/share/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
or
# cpan Foo::Bar
Vendor
Vendor modules are packaged modules, installed via the pacman tool, or modules that have been built into proper Arch Linux packages from a PKGBUILD and makepkg.
Package naming
Perl module packages should be named for the primary module provided. The naming convention for module Foo::Bar is perl-foo-bar. Packages that include multiple modules may additionally include provides for those modules using the same convention.
Vendor directories
The installation directory for Arch Linux modules must be different from that for
site
modules. Some guidelines include:
The current Perl packaging uses the
vendor
directories for this purpose, which are at present as described in above as
vendor
.
The Perl distribution includes many modules available separately from CPAN, that 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 that 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.
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 DESTDIR="${pkgdir}" install
Sample vendor PKGBUILD
See
Perl package guidelines#PKGBUILD examples
.
Core
Core modules are Perl modules "typically" included in the core Perl distribution.
Core directories
Modules included in the core Perl distribution should be installed into
/usr/lib/perl5/
version
/core_perl
and
/usr/share/perl5/core_perl
.
Only modules contained in the
perl
package should be installed into this directory tree.
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 and for a base system to operate. It should be maintained in the
core
repository.
The following is a list of a few modules (for example), which are provided in the
perl
package. (See the
PKGBUILD
for the official list).
'perl-checktree' 'perl-collate' 'perl-config' 'perl-cwd' 'perl-dynaloader' 'perl-english' 'perl-env' 'perl-exporter' 'perl-fnctl' 'perl-filehandle' 'perl-find' 'perl-finddepth' 'perl-getopt' 'perl-makemaker' 'perl-socket' 'perl-sys-syslog' 'perl-db-file' 'perl-storable' 'perl-data-dumper' 'perl-digest-md5'
Every module supplied in the perl package shall be added into the
provides
array in the PKGBUILD. Modules in this array should NOT appear in the perl packages
conflicts
or
replaces
arrays. End users should be able to install newer versions of core modules, either in
vendor
or
site
directories without file collisions.
Dependencies
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.
Architecture-independent modules
Architecture-independent modules which require
core
modules from the
perl
package must specify a dependency on that package.
Modules that 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.
Perl 7
There is currently work in progress on the next major revision, although the specifications have yet to be finalised.
Note
Perl 6 was renamed to
Raku
which is now a different programming language
Wikipedia:Perl#Perl_6_and_Raku
. The version number and status of the work is also uncertain
Wikipedia:Perl#Perl_7
[2]
.
It is anticipated that when Perl 7 is released it will initially be packaged as perl7, install the binary as
/usr/bin/perl7
, and use different directories for packaged modules to perl:
/usr/lib/perl7
/usr/share/perl7
This will allow Perl 5 and 7 packages and modules (which should be packaged as perl7-foo-bar), to coexist for as long as required.
At some stage in the future when Perl 7 is sufficiently mature, the package naming may be reversed such that the
perl
package contains Perl 7 and the current package becomes perl5.