Difference between revisions of "Perl Policy"

From ArchWiki
Jump to: navigation, search
(Sample Vendor PKGBUILD)
m (<tt>text</tt> -> {{Codeline|text}})
Line 26: Line 26:
  
 
# The current Arch Linux default perl installation installs <em>site</em> and <em>vendor</em> packages into the same directory tree, which frequently causes conflicts if the end user installs and upgrades Arch Linux perl (<em>vendor</em>) packages on top of <em>site</em> packages.
 
# The current Arch Linux default perl installation installs <em>site</em> and <em>vendor</em> packages into the same directory tree, which frequently causes conflicts if the end user installs and upgrades Arch Linux perl (<em>vendor</em>) packages on top of <em>site</em> packages.
# The current Arch Linux default perl installation installs updates to <em>core</em> modules into the perl <em>core</em> directories, creating file conflicts.  Examples include modules such as <tt>Data::Dumper</tt> and <tt>version</tt>.
+
# The current Arch Linux default perl installation installs updates to <em>core</em> modules into the perl <em>core</em> directories, creating file conflicts.  Examples include modules such as {{Codeline|Data::Dumper}} and {{Codeline|version}}.
# A symlink-farm is created in <tt>/usr/lib/perl5/</tt> and <tt>/usr/lib/perl5/site_perl</tt> which is un-necessary and confusing.
+
# A symlink-farm is created in {{Codeline|/usr/lib/perl5/}} and {{Codeline|/usr/lib/perl5/site_perl}} which is un-necessary and confusing.
 
# A number of standard modules seem to be missing, or were neglected to be added as <em>provides</em> in the perl package itself, causing confusion and redundant entries in AUR and Community as users try and <em>fix</em> the apparent problem of missing modules, which are provided by perl.  This is probably a matter of education.
 
# A number of standard modules seem to be missing, or were neglected to be added as <em>provides</em> in the perl package itself, causing confusion and redundant entries in AUR and Community as users try and <em>fix</em> 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.
 
# Current perl-module PKGBUILD's could be simplified and standardized quite a bit.
Line 37: Line 37:
  
 
# An update of every perl module PKGBUILD so that it installs into the correct (<em>vendor</em>) directory tree.  It remains somewhat backwards-compatible with the old structure, in that old PKGBUILD's would technically <strong>work</strong>.
 
# An update of every perl module PKGBUILD so that it installs into the correct (<em>vendor</em>) directory tree.  It remains somewhat backwards-compatible with the old structure, in that old PKGBUILD's would technically <strong>work</strong>.
# Introduces changes into the <tt>perl</tt> package, which lives in [core], and proposes a new <tt>perl-modules</tt> package, which would live in [extra].
+
# Introduces changes into the {{Codeline|perl}} package, which lives in [core], and proposes a new {{Codeline|perl-modules}} package, which would live in [extra].
# 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 <tt>vim</tt>, <tt>subversion</tt>, and <tt>irssi</tt>.  Many such examples exist.
+
# 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 {{Codeline|vim}}, {{Codeline|subversion}}, and {{Codeline|irssi}}.  Many such examples exist.
  
 
= Perl Versions =
 
= Perl Versions =
  
At any given time, the package <tt>perl</tt> should represent the current stable upstream version of Perl revision 5.  (see Perl 6).
+
At any given time, the package {{Codeline|perl}} should represent the current stable upstream version of Perl revision 5.  (see Perl 6).
  
Only one package may contain the <tt>/usr/bin/perl</tt> 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 <tt>perl</tt> 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.
+
Only one package may contain the {{Codeline|/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 {{Codeline|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 =
 
= Module Paths =
Line 50: Line 50:
 
Perl searches three different locations for modules, referred to in this document as <em>core</em> in which modules distributed with Perl are installed, <em>vendor</em> for packaged modules and <em>site</em> for modules installed by the local administrator.
 
Perl searches three different locations for modules, referred to in this document as <em>core</em> in which modules distributed with Perl are installed, <em>vendor</em> for packaged modules and <em>site</em> for modules installed by the local administrator.
  
The module search path (<tt>@INC</tt>) in the Arch Linux packages has been ordered to include these locations in the following order:
+
The module search path ({{Codeline|@INC}}) in the Arch Linux packages has been ordered to include these locations in the following order:
  
 
* <strong><em>site</em></strong>
 
* <strong><em>site</em></strong>
 
Modules installed by the local administrator for the current version of Perl.  Typically, these modules are installed using the ''cpan'' or ''cpanp'' tool, or are downloaded in source form and installed via make.
 
Modules installed by the local administrator for the current version of Perl.  Typically, these modules are installed using the ''cpan'' or ''cpanp'' tool, or are downloaded in source form and installed via make.
  
:<tt>/usr/lib/perl5/site_perl/<em>version</em></tt>
+
:{{Codeline|/usr/lib/perl5/site_perl/<em>version</em>}}
:<tt>/usr/share/perl5/site_perl/<em>version</em></tt>
+
:{{Codeline|/usr/share/perl5/site_perl/<em>version</em>}}
  
 
* <strong><em>vendor</em></strong>
 
* <strong><em>vendor</em></strong>
 
Packaged modules, installed via the pacman tool from core/extra or community, or built into proper Arch Linux packages from ABS/AUR PKGBUILDS.
 
Packaged modules, installed via the pacman tool from core/extra or community, or built into proper Arch Linux packages from ABS/AUR PKGBUILDS.
  
:<tt>/usr/lib/perl5/vendor_perl</tt>
+
:{{Codeline|/usr/lib/perl5/vendor_perl}}
:<tt>/usr/share/perl5/vendor_perl</tt>
+
:{{Codeline|/usr/share/perl5/vendor_perl}}
  
 
* <strong><em>core</em></strong>
 
* <strong><em>core</em></strong>
 
Modules included in the core Perl distribution.
 
Modules included in the core Perl distribution.
  
:<tt>/usr/lib/perl5/core_perl</tt>
+
:{{Codeline|/usr/lib/perl5/core_perl}}
:<tt>/usr/share/perl5/core_perl</tt>
+
:{{Codeline|/usr/share/perl5/core_perl}}
  
 
* <strong><em>obsolete</em></strong>
 
* <strong><em>obsolete</em></strong>
 
Obsolete is the pathname to modules installed prior to the establishment of this document.  These paths have been removed from @INC in perl 5.12.2.
 
Obsolete is the pathname to modules installed prior to the establishment of this document.  These paths have been removed from @INC in perl 5.12.2.
  
:<tt>/usr/lib/perl5/site_perl/current/arch</tt>
+
:{{Codeline|/usr/lib/perl5/site_perl/current/arch}}
:<tt>/usr/lib/perl5/site_perl/current</tt>
+
:{{Codeline|/usr/lib/perl5/site_perl/current}}
:<tt>/usr/lib/perl5/current</tt>
+
:{{Codeline|/usr/lib/perl5/current}}
  
In each of the directory pairs above, the <tt>lib</tt> component is for binary, architecture dependent (XS) modules, and <tt>share</tt> for architecture-independent (pure-perl) modules.  Under no circumstances should <tt>current</tt> be used as a replacement for <tt>version</tt>.  Core and Vendor modules <em>should</em> be matched to the current installation of perl.
+
In each of the directory pairs above, the {{Codeline|lib}} component is for binary, architecture dependent (XS) modules, and {{Codeline|share}} for architecture-independent (pure-perl) modules.  Under no circumstances should {{Codeline|current}} be used as a replacement for {{Codeline|version}}.  Core and Vendor modules <em>should</em> be matched to the current installation of perl.
  
 
= Documents =
 
= Documents =
Line 87: Line 87:
 
<strong>Programs</strong>
 
<strong>Programs</strong>
  
Manual pages for programs and scripts are installed into <tt>/usr/man/man1</tt> with the extension <tt>.1perl</tt>.
+
Manual pages for programs and scripts are installed into {{Codeline|/usr/man/man1}} with the extension {{Codeline|.1perl}}.
  
 
<strong>Modules</strong>
 
<strong>Modules</strong>
  
Manual pages for modules are installed into <tt>/usr/man/man3</tt> with the extension <tt>.3perl</tt>.
+
Manual pages for modules are installed into {{Codeline|/usr/man/man3}} with the extension {{Codeline|.3perl}}.
  
 
= Binaries and Scripts =
 
= Binaries and Scripts =
  
In order to prevent file collisions, it's important to keep binaries generated by <em>core</em>, <em>vendor</em>, and <em>site</em> installs separate.  It's also important that the default <tt>PATH</tt> environment variable set in each users profile to search for binaries in the same order as perl's <tt>@INC</tt> path.  In order to accomplish this, binaries should be installed into the following directories:
+
In order to prevent file collisions, it's important to keep binaries generated by <em>core</em>, <em>vendor</em>, and <em>site</em> installs separate.  It's also important that the default {{Codeline|PATH}} environment variable set in each users profile to search for binaries in the same order as perl's {{Codeline|@INC}} path.  In order to accomplish this, binaries should be installed into the following directories:
  
 
:<strong>Core</strong>
 
:<strong>Core</strong>
:Binaries and scripts for all <em>core</em> packages should be installed into <tt>/usr/bin/core_perl</tt>.
+
:Binaries and scripts for all <em>core</em> packages should be installed into {{Codeline|/usr/bin/core_perl}}.
 
:<strong>Vendor</strong>
 
:<strong>Vendor</strong>
:Binaries and scripts for all <em>vendor</em> packages should be installed into <tt>/usr/bin/vendor_perl</tt>.
+
:Binaries and scripts for all <em>vendor</em> packages should be installed into {{Codeline|/usr/bin/vendor_perl}}.
 
:<strong>Site</strong>
 
:<strong>Site</strong>
:Binaries and scripts for all <em>site</em> should default to be installed into <tt>/usr/bin/site_perl</tt>.
+
:Binaries and scripts for all <em>site</em> should default to be installed into {{Codeline|/usr/bin/site_perl}}.
  
The <tt>perl</tt> package should include a mechanism to adjust end-users <tt>PATH</tt> entries accordingly so that perl binaries are searched for in the following order: <em>site</em>, <em>vendor</em>, <em>core</em>.
+
The {{Codeline|perl}} package should include a mechanism to adjust end-users {{Codeline|PATH}} entries accordingly so that perl binaries are searched for in the following order: <em>site</em>, <em>vendor</em>, <em>core</em>.
  
 
= Site =
 
= Site =
Line 112: Line 112:
 
== Site Directories ==
 
== Site Directories ==
  
The Perl packages must provide a mechanism for the local administrator to install modules under <tt>/usr/lib/perl5/site_perl</tt> but must not create or remove those directories.
+
The Perl packages must provide a mechanism for the local administrator to install modules under {{Codeline|/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 <tt>site</tt>, programs to <tt>/usr/bin/site_perl</tt> and manual pages under <tt>/usr/man</tt>.
+
Modules should be installed to the directories described above in Module Path {{Codeline|site}}, programs to {{Codeline|/usr/bin/site_perl}} and manual pages under {{Codeline|/usr/man}}.
  
 
== Site Installation ==
 
== Site Installation ==
Line 133: Line 133:
 
== Vendor Directories ==
 
== Vendor Directories ==
  
The installation directory for Arch Linux modules must be different from that for <tt>site</tt> modules.  Some guidelines include:
+
The installation directory for Arch Linux modules must be different from that for {{Codeline|site}} modules.  Some guidelines include:
  
* The current Perl packaging uses the <em>vendor</em> directories for this purpose, which are at present as described in above as <tt>vendor</tt>.
+
* The current Perl packaging uses the <em>vendor</em> directories for this purpose, which are at present as described in above as {{Codeline|vendor}}.
* No version subdirectory exists on these directories as the dependencies for packaged modules should ensure that all work with the current <tt>perl</tt> package.
+
* No version subdirectory exists on these directories as the dependencies for packaged modules should ensure that all work with the current {{Codeline|perl}} package.
* The Perl distribution includes many modules available separately from CPAN, which may have a newer version.  The intent of the <tt>@INC</tt> ordering (described above) is to allow such modules to be packaged to <em>vendor</em> which take precedence over the version in <em>core</em>. A packaged module which shadows a <em>core</em> module in this way must be a newer version.
+
* The Perl distribution includes many modules available separately from CPAN, which may have a newer version.  The intent of the {{Codeline|@INC}} ordering (described above) is to allow such modules to be packaged to <em>vendor</em> which take precedence over the version in <em>core</em>. A packaged module which shadows a <em>core</em> module in this way must be a newer version.
* Module packages must install manual pages into the standard directories using the extensions <tt>.1p</tt> and <tt>.3pm</tt> to ensure that no conflict arises where a packaged module duplicates a <em>core</em> module.
+
* Module packages must install manual pages into the standard directories using the extensions {{Codeline|.1p}} and {{Codeline|.3pm}} to ensure that no conflict arises where a packaged module duplicates a <em>core</em> module.
* <tt>.packlist</tt> (used for module uninstalls) and <tt>perllocal.pod</tt> (used to record local/site installations) files should not be installed, and should be removed from the package if found.
+
* {{Codeline|.packlist}} (used for module uninstalls) and {{Codeline|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.
 
* Empty directories should be pruned.
  
Line 156: Line 156:
 
  make install DESTDIR=$startdir/pkg install || return 1
 
  make install DESTDIR=$startdir/pkg install || return 1
  
A depends on perl (>= 5.10.0) is required in order ensure that the module is correctly installed into the new <tt>@INC</tt> path.
+
A depends on perl (>= 5.10.0) is required in order ensure that the module is correctly installed into the new {{Codeline|@INC}} path.
  
 
== Sample Vendor PKGBUILD ==
 
== Sample Vendor PKGBUILD ==
Line 196: Line 196:
  
 
=== Architecture-Independent Modules ===
 
=== Architecture-Independent Modules ===
Architecture-independent modules which require <em>core</em> modules from the <tt>perl</tt> package must specify a dependency on that package.
+
Architecture-independent modules which require <em>core</em> modules from the {{Codeline|perl}} package must specify a dependency on that package.
  
Modules which contain explicit <tt>require <em>version</em></tt> or <tt>use <em>version</em></tt> statements must specify a dependency on <tt>perl</tt> with the minimum required version, or more simply the current version.
+
Modules which contain explicit {{Codeline|require <em>version</em>}} or {{Codeline|use <em>version</em>}} statements must specify a dependency on {{Codeline|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 <tt>perl</tt> version of <tt>5.10.0</tt> due to the changes in <tt>@INC</tt> introduced by that version.
+
In the absence of an explicit requirement, architecture-independent modules must depend on a minimum {{Codeline|perl}} version of {{Codeline|5.10.0}} due to the changes in {{Codeline|@INC}} introduced by that version.
  
 
=== Binary Modules ===
 
=== Binary Modules ===
Binary modules must specify a dependency on either <tt>perl</tt> with a minimum version of the <tt>perl</tt> package used to build the module, and must additionally depend on the expansion of <tt>perlapi-$Config{version} </tt>using the <tt>Config</tt> module.
+
Binary modules must specify a dependency on either {{Codeline|perl}} with a minimum version of the {{Codeline|perl}} package used to build the module, and must additionally depend on the expansion of {{Codeline|perlapi-$Config{version} }}using the {{Codeline|Config}} module.
  
 
= Core =
 
= Core =
Line 211: Line 211:
 
== Core Directories ==
 
== Core Directories ==
  
* Modules included in the core Perl distribution should be installed into <tt>/usr/lib/perl5</tt> and <tt>/usr/share/perl5</tt>.
+
* Modules included in the core Perl distribution should be installed into {{Codeline|/usr/lib/perl5}} and {{Codeline|/usr/share/perl5}}.
* Only modules contained in the <tt>perl</tt> package should be installed into this directory tree.
+
* Only modules contained in the {{Codeline|perl}} package should be installed into this directory tree.
* No version subdirectory exists in these paths as the dependencies for packaged modules should ensure that all work with the current <tt>perl</tt> package.
+
* No version subdirectory exists in these paths as the dependencies for packaged modules should ensure that all work with the current {{Codeline|perl}} package.
  
 
== Core perl packages ==
 
== Core perl packages ==
Line 219: Line 219:
 
=== perl ===
 
=== perl ===
  
The <tt>perl</tt> package should contain the <tt>/usr/bin/perl</tt> 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 {{Codeline|perl}} package should contain the {{Codeline|/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 offical list).
 
The following is a list of a few modules (for example), which are provided in the perl package.  (See the PKGBUILD for the offical list).
  
<tt>'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'</tt>.
+
{{Codeline|'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 <tt>provides</tt> array in the PKGBUILD.  Modules in this array should NOT appear in the perl packages <tt>conflicts</tt> or <tt>replaces</tt> arrays.  End users should be able to install newer versions of core modules, either in <em>vendor</em> or <em>site</em> directories without file collisions.
+
Every module supplied in the perl package shall be added into the {{Codeline|provides}} array in the PKGBUILD.  Modules in this array should NOT appear in the perl packages {{Codeline|conflicts}} or {{Codeline|replaces}} arrays.  End users should be able to install newer versions of core modules, either in <em>vendor</em> or <em>site</em> directories without file collisions.
  
 
==== Sample perl PKGBUILD ====
 
==== Sample perl PKGBUILD ====
Line 237: Line 237:
 
The current stable upstream version at the time of this writing is 5.10.0 (in testing, 5.8.8 in core). There is currently work in progress on the next major revision, although the specifications have yet to be finalised.
 
The current stable upstream version at the time of this writing is 5.10.0 (in testing, 5.8.8 in core). 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 <tt>/usr/bin/perl6</tt> and use different directories for packaged modules to perl:
+
It is anticipated that when Perl 6 is released it will initially be packaged as perl6, install the binary as {{Codeline|/usr/bin/perl6}} and use different directories for packaged modules to perl:
  
: <tt>/usr/lib/perl6</tt>
+
: {{Codeline|/usr/lib/perl6}}
: <tt>/usr/share/perl6</tt>
+
: {{Codeline|/usr/share/perl6}}
  
 
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.
 
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 <tt>perl</tt> package contains Perl 6 and the current package becomes <tt>perl5</tt>.
+
At some stage in the future when Perl 6 is sufficiently mature, the package naming may be reversed such that the {{Codeline|perl}} package contains Perl 6 and the current package becomes {{Codeline|perl5}}.

Revision as of 21:27, 6 September 2011


Note

There seems to be some confusion where people think this policy is about packaging perl modules. This page covers the policy for how perl itself is configured and packaged. So the policy does influence module packaging especially where files will be installed.

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.


5.10 Caveats

NOT TRUE: The directories for scripts do not conform to FHS standards.

Note: FHS describes what directories must be in /usr/bin and does not prohibit adding other directories.


Reasoning

Apparent problems with pre-5.10.0 perl packaging conventions included:

  1. 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.
  2. 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 Template:Codeline and Template:Codeline.
  3. A symlink-farm is created in Template:Codeline and Template:Codeline which is un-necessary and confusing.
  4. 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 Community as users try and fix the apparent problem of missing modules, which are provided by perl. This is probably a matter of education.
  5. 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:

  1. 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.
  2. Introduces changes into the Template:Codeline package, which lives in [core], and proposes a new Template:Codeline package, which would live in [extra].
  3. 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 Template:Codeline, Template:Codeline, and Template:Codeline. Many such examples exist.

Perl Versions

At any given time, the package Template:Codeline should represent the current stable upstream version of Perl revision 5. (see Perl 6).

Only one package may contain the Template:Codeline 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 Template:Codeline 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 (Template:Codeline) 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 cpanp tool, or are downloaded in source form and installed via make.

Template:Codeline
Template:Codeline
  • vendor

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

Template:Codeline
Template:Codeline
  • core

Modules included in the core Perl distribution.

Template:Codeline
Template:Codeline
  • obsolete

Obsolete is the pathname to modules installed prior to the establishment of this document. These paths have been removed from @INC in perl 5.12.2.

Template:Codeline
Template:Codeline
Template:Codeline

In each of the directory pairs above, the Template:Codeline component is for binary, architecture dependent (XS) modules, and Template:Codeline for architecture-independent (pure-perl) modules. Under no circumstances should Template:Codeline be used as a replacement for Template:Codeline. Core and Vendor modules should be matched to the current installation of perl.

Documents

The POD files and manual pages and html documentation which 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 Template:Codeline with the extension Template:Codeline.

Modules

Manual pages for modules are installed into Template:Codeline with the extension Template:Codeline.

Binaries and Scripts

In order to prevent file collisions, it's important to keep binaries generated by core, vendor, and site installs separate. It's also important that the default Template:Codeline environment variable set in each users profile to search for binaries in the same order as perl's Template:Codeline path. In order to accomplish this, binaries should be installed into the following directories:

Core
Binaries and scripts for all core packages should be installed into Template:Codeline.
Vendor
Binaries and scripts for all vendor packages should be installed into Template:Codeline.
Site
Binaries and scripts for all site should default to be installed into Template:Codeline.

The Template:Codeline package should include a mechanism to adjust end-users Template:Codeline 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 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 Template:Codeline but must not create or remove those directories.

Modules should be installed to the directories described above in Module Path Template:Codeline, programs to Template:Codeline and manual pages under Template:Codeline.

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 which have been built into proper Arch Linux packages from a PKGBUILD and makepkg.

Vendor Directories

The installation directory for Arch Linux modules must be different from that for Template:Codeline modules. Some guidelines include:

  • The current Perl packaging uses the vendor directories for this purpose, which are at present as described in above as Template:Codeline.
  • No version subdirectory exists on these directories as the dependencies for packaged modules should ensure that all work with the current Template:Codeline package.
  • The Perl distribution includes many modules available separately from CPAN, which may have a newer version. The intent of the Template:Codeline 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 Template:Codeline and Template:Codeline to ensure that no conflict arises where a packaged module duplicates a core module.
  • Template:Codeline (used for module uninstalls) and Template:Codeline (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 || return 1

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

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

A depends on perl (>= 5.10.0) is required in order ensure that the module is correctly installed into the new Template:Codeline path.

Sample Vendor PKGBUILD

# $Id$
# Contributer: Barry User <barry@user.com>
# Maintainer: Harry Hacker <harry@hacker.com>

pkgname=perl-html-template
_realname=HTML-Template
pkgver=2.9
pkgrel=2
pkgdesc="Perl/CPAN Module HTML::Template : a simple HTML templating system"
arch=('any')
url="http://search.cpan.org/dist/${_realname}/"
license=('GPL' 'Artistic')
depends=('perl>=5.10.0')
source=("http://www.cpan.org/authors/id/S/SA/SAMTREGAR/${_realname}-${pkgver}.tar.gz")
md5sums=("cbf88a486b36284be55765ac7357c187")
options=(!emptydirs)

build() {
  cd "${srcdir}/${_realname}-${pkgver}"
  # Install module into the vendor directories.
  perl Makefile.PL INSTALLDIRS=vendor
  make
}   

package() {
  cd "${srcdir}/${_realname}-${pkgver}"
  make DESTDIR="${pkgdir}" install

  # Remove .packlist and perllocal.pod files.
  find "${pkgdir}" -name '.packlist' -delete
  find "${pkgdir}" -name 'perllocal.pod' -delete
}

Dependencies

Architecture-Independent Modules

Architecture-independent modules which require core modules from the Template:Codeline package must specify a dependency on that package.

Modules which contain explicit Template:Codeline or Template:Codeline statements must specify a dependency on Template:Codeline 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 Template:Codeline version of Template:Codeline due to the changes in Template:Codeline introduced by that version.

Binary Modules

Binary modules must specify a dependency on either Template:Codeline with a minimum version of the Template:Codeline package used to build the module, and must additionally depend on the expansion of Template:Codelineusing the Template:Codeline module.

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 Template:Codeline and Template:Codeline.
  • Only modules contained in the Template:Codeline package should be installed into this directory tree.
  • No version subdirectory exists in these paths as the dependencies for packaged modules should ensure that all work with the current Template:Codeline package.

Core perl packages

perl

The Template:Codeline package should contain the Template:Codeline 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 offical list).

Template:Codeline.

Every module supplied in the perl package shall be added into the Template:Codeline array in the PKGBUILD. Modules in this array should NOT appear in the perl packages Template:Codeline or Template:Codeline arrays. End users should be able to install newer versions of core modules, either in vendor or site directories without file collisions.

Sample perl PKGBUILD

unfinished, see this working sample configuration which meets the criteria of this document.

(Dec 4, 2007: the above URL is dead)

Perl6

The current stable upstream version at the time of this writing is 5.10.0 (in testing, 5.8.8 in core). 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 Template:Codeline and use different directories for packaged modules to perl:

Template:Codeline
Template:Codeline

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 Template:Codeline package contains Perl 6 and the current package becomes Template:Codeline.