Perl package guidelines

From ArchWiki
Revision as of 01:41, 11 May 2010 by Juster (talk | contribs) (PERL_MB_OPT: Fix bad bash.)
Jump to: navigation, search

Package Naming

For modules the package name should begin with perl- and the rest of the name should be constructed from the module name by converting it to lowercase and then replacing colons with hyphens. For example the package name corresponding to HTML::Parser will be perl-html-parser. Perl applications should have the same name as that of the application but in lowercase.

File Placement

Perl modules should install module files in Template:Filename (this is done by setting the Template:Codeline variable as shown below). No files should be stored in Template:Filename as that directory is reserved for use by the system administrator to install Perl packages outside the package management system. The files Template:Filename and Template:Filename also should not be present; this is taken care of by the example PKGBUILD given below.


An example PKGBUILD can be found at Template:Filename which is present in the Template:Package Official package. It is also reproduced below (without the comments):

# Contributor: Your Name <>
license=('GPL' 'PerlArtistic')

build() {
  cd "$srcdir/***-$pkgver"

  # install module in vendor directories.
  PERL_MM_USE_DEFAULT=1 perl Makefile.PL INSTALLDIRS=vendor || return 1
  make || return 1
  make install DESTDIR="$pkgdir/" || return 1

  ## for packages with Build.PL, do this instead:
  # perl Build.PL installdirs=vendor destdir="$pkgdir/"
  # perl Build
  # perl Build install

  # remove perllocal.pod and .packlist
  find "$pkgdir" -name perllocal.pod -delete
  find "$pkgdir" -name .packlist -delete

# vim:set ts=2 sw=2 et:

In most cases, you should put any in the Template:Codeline array since most Perl packages are architecture independent.


As Perl is centered around the CPAN, there are a few scripts to make the most of this, and save you writing PKGBUILDs by hand.

The more perlish method is to use a Template:Codeline plugin for installing CPAN modules as dynamically generated pacman packages, available at

There is also a script called Template:Codeline, which can recursively generate PKGBUILDs for a module:

Advanced Topics

If the packager has become comfortable enough with creating perl packages, the below sections may offer some new ideas to consider. This information might also help troubleshooting packaging problems.


You should be familiar with the following terms.


Modules are declared with the Template:Codeline keyword in perl. Modules are contained inside a Template:Filename ("dot-pee-em") file. Though it's possible more than one module (Template:Codeline) is in the file. Modules have namespaces separated with Template:Codeline (double colons), like: Template:Codeline. When loading a module, the Template:Codelines are replaced with directory separators. For example: Template:Filename will be loaded for the module Template:Codeline.

Core Module

Core modules are included with an installation of perl. Some core modules are only available bundled with perl. Other modules can still be downloaded and installed separately from CPAN.


(aka dist, package) This is the equivalent of an Archlinux package in CPAN-lingo. Distributions are Template:Filename archives full of files. These archives contain primarily .pm module files, tests for the included modules, documentation for the modules, and whatever else is deemed necessary.

Usually a distribution contains a primary module with the same name. Sometimes this is not true, like with the Template-Toolkit distribution. The latest package, Template:Filename, for the Template:Codeline dist, contains no Template:Codeline module!

Sometimes because distributions are named after a main module, their names are used interchangeably and they get muddled together. However it is sometimes useful to consider them a separate entity (like in Template-Toolkit's case).

Installation Modules

One of perl's greatest advantages is the sheer number of modules[/dists] available on CPAN. Not too surprisingly, there are also several different modules used for installing... well... modules! TMTOWTDI! I am not aware of a standard name for these types of modules, so I just called them "Installation Modules".

All these modules are concerned with is building the package and installing wherever the user wants. This seems straightforward, but considering the number of different systems perl runs on, this can get complex. These modules all place a perl code file inside the dist tarball. Running this perl script will initiate the build/installation process. I have called this the "Build script" in the below list.


Build script
CPAN link

The original, oldest module for installing modules is Template:Codeline. The major downside to this module is that it requires the Template:Filename program to build and install everything. This may not seem like a big deal to linux users but is a real hassle for Windows people! In the name of progress the perl community is trying to encourage people to use the newer modules instead.


Build script
CPAN link

The main advantage of Module::Build is that it is pure-perl. This means it does not require a Template:Filename program to be installed for you to build/install modules. Its adoption was rocky because if Template:Codeline was not already installed, you could not run the bundled Template:Filename script! This is not a problem with recent versions of perl because Template:Codeline is a core module.


Build script
CPAN link

Another modern build/installation module, Template:Codeline still requires the Template:Filename program be installed to function. It was designed as a drop-in replacement for Template:Codeline, to address some of Template:Codeline's shortcomings.

One very interesting feature is that Template:Codeline bundles a complete copy of itself into the distribution file. Because of this, unlike Template:Codeline or Template:Codeline, you do not need Template:Codeline to be installed on your system.

Another very unique feature is auto-install. This appears to be not recommended, but seems used quite often. When the module author enables auto-install for his distribution, Template:Codeline will search for and install any pre-requisite modules that are not installed when Template:Filename is executed. This feature is skipped when Template:Codeline detects it is being run by Template:Codeline or Template:Codeline. However, this feature is not skipped when run inside... oh I don't know... a PKGBUILD! I hope you can see how a rogue perl program downloading and installing modules willy-nilly inside a PKGBUILD can be a problem. See the #PERL_AUTOINSTALL environment variable to see how to fix this.

Environment Variables

A number of environment variables can affect the way the modules are built or installed. Some have a very dramatic effect and can cause problems if misunderstood. An advanced user could be using these environment variables. Some of these will break an unsuspecting Template:Filename; or cause unexpected behavior.


When this variable is set to a true value, the installation module will pretend the default answer was given to any question it would normally ask. This does not always work, but all of the installation modules honour it. That doesn't mean the module author will!


You can pass additional command-line arguments to Template:Codeline's Template:Filename with this variable. In order to turn off auto-install (highly recommended), assign Template:Codeline to this.

export PERL_AUTOINSTALL='--skipdeps'


You can pass additional command-line arguments to Template:Filename with this variable. For example, you can install modules into your home-dir by using:



This is the same thing as PERL_MM_OPT, except for Template:Codeline. For example, you could install modules into your home-dir by using:

export PERL_MB_OPT=--install_base=~/perl5


Template:Codeline allows you to override its command-line-arguments with an rcfile. This defaults to Template:Filename. You can override which file it uses by setting the path to the rcfile in Template:Codeline. The paranoid might set Template:Codeline to Template:Filename... just in case.