Difference between revisions of "Perl package guidelines"

From ArchWiki
Jump to: navigation, search
m (add tag i18n)
m (Automation: Bauerbill has been officially discontinued)
Line 62: Line 62:
 
There is also a script called {{Codeline|pacpan}}, which can recursively generate PKGBUILDs for a module: http://www.archlinux.org/packages/community/any/pacpan/
 
There is also a script called {{Codeline|pacpan}}, which can recursively generate PKGBUILDs for a module: http://www.archlinux.org/packages/community/any/pacpan/
  
It is worth mentioning that [[Bauerbill | Bauerbill]] has similar support for generating PKGBUILDs to {{Codeline|pacpan}}. As well as adding the ability to upgrade all installed CPAN modules directly from CPAN via a pacman interface. Make sure to read the Bauerbill man file for usage instructions.
+
It is worth mentioning that [[Bauerbill]] has similar support for generating PKGBUILDs to {{Codeline|pacpan}}. As well as adding the ability to upgrade all installed CPAN modules directly from CPAN via a pacman interface. Make sure to read the Bauerbill man file for usage instructions.
 +
{{Warning|''Bauerbill'' development has been officially discontinued: its latest version does not work with            ''pacman>=3.5''. See [[https://bbs.archlinux.org/viewtopic.php?id=115660]].}}
  
 
==Advanced Topics==
 
==Advanced Topics==

Revision as of 18:28, 25 March 2011


This template has only maintenance purposes. For linking to local translations please use interlanguage links, see Help:i18n#Interlanguage links.


Local languages: Català – Dansk – English – Español – Esperanto – Hrvatski – Indonesia – Italiano – Lietuviškai – Magyar – Nederlands – Norsk Bokmål – Polski – Português – Slovenský – Česky – Ελληνικά – Български – Русский – Српски – Українська – עברית – العربية – ไทย – 日本語 – 正體中文 – 简体中文 – 한국어


External languages (all articles in these languages should be moved to the external wiki): Deutsch – Français – Română – Suomi – Svenska – Tiếng Việt – Türkçe – فارسی

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.

Example

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 <youremail@domain.com>
pkgname=perl-foo-bar
pkgver=VERSION
pkgrel=1
pkgdesc=""
arch=()
url=""
license=('GPL' 'PerlArtistic')
depends=('perl>=5.10.0')
makedepends=()
provides=()
conflicts=()
replaces=()
backup=()
options=(!emptydirs)
install=
source=(http://search.cpan.org/CPAN/authors/id/***/***-$pkgver.tar.gz)
md5sums=()

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.

Automation

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 http://aur.archlinux.org/packages.php?ID=24971

There is also a script called Template:Codeline, which can recursively generate PKGBUILDs for a module: http://www.archlinux.org/packages/community/any/pacpan/

It is worth mentioning that Bauerbill has similar support for generating PKGBUILDs to Template:Codeline. As well as adding the ability to upgrade all installed CPAN modules directly from CPAN via a pacman interface. Make sure to read the Bauerbill man file for usage instructions.

Warning: Bauerbill development has been officially discontinued: its latest version does not work with pacman>=3.5. See [[1]].

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.

Glossary

You should be familiar with the following terms.

Module

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.

Distributions

(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).

User-Installed perl

A subtle problem is that advanced perl programmers may like to have multiple versions of perl installed. This is useful for testing backwards-compatibility in created programs. There are also speed benefits to compiling your own custom perl interpreter (i.e. without threads). Another reason for a custom perl is simply because the official perl ArchLinux package sometimes lags behind perl releases. The user may be trying out the latest perl... who knows?

If the user has the custom perl executable in their Template:Codeline, the custom perl will be run when the user types the perl command on the shell. In fact the custom perl will run inside the Template:Filename as well! This can lead to insidious problems that are difficult to understand.

The problem lies in compiled XS modules. These modules bridge perl and C. As such they must use perl's internal C API to accomplish this bridge. Perl's C API changes slightly with different versions of perl. If the user has a different version of perl than the system perl (Template:Filename) then any XS module compiled with the user's perl will be incompatible with the system-wide perl. When trying to use the compiled XS module with the system perl, the module will fail to load with a link error.

A simple solution is to always use the absolute path of the system-wide perl interpreter (Template:Filename) when running perl in the Template:Filename.

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.

ExtUtils::MakeMaker

Build script
Template:Filename
CPAN link
http://search.cpan.org/dist/ExtUtils-MakeMaker

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.

Module::Build

Build script
Template:Filename
CPAN link
http://search.cpan.org/dist/Module-Build

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.

Module::Install

Build script
Template:Filename
CPAN link
http://search.cpan.org/dist/Module-Install

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.

PERL_MM_USE_DEFAULT

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!

PERL_AUTOINSTALL

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'

PERL_MM_OPT

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

export PERL_MM_OPT=INSTALLBASE=~/perl5

PERL_MB_OPT

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

export PERL_MB_OPT=--install_base=~/perl5

MODULEBUILDRC

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.

Hardened Example

Using all of our new accumulated knowledge, we can create a more hardened PKGBUILD that will resist any environment variables' attempts to sabotage it:

# Contributor: Your Name <youremail@domain.com>
pkgname=perl-foo-bar
pkgver=VERSION
pkgrel=1
pkgdesc='This is the awesome Foo::Bar module!'
arch=('any')
url='http://search.cpan.org/dist/Foo-Bar'
license=('GPL' 'PerlArtistic')
depends=('perl>=5.10.0')
makedepends=()
provides=()
conflicts=()
replaces=()
backup=()
options=(!emptydirs)
install=
source=("http://search.cpan.org/CPAN/authors/id/***/***-$pkgver.tar.gz")
md5sums=()

build() {
  cd "$srcdir/***-$pkgver"
  
  # Setting these env variables overwrites any command-line-options we don't want...
  export PERL_MM_USE_DEFAULT=1 PERL_AUTOINSTALL=--skipdeps \
    PERL_MM_OPT="INSTALLDIRS=vendor DESTDIR='$pkgdir'" \
    PERL_MB_OPT="--installdirs vendor --destdir '$pkgdir'" \
    MODULEBUILDRC=/dev/null

  # If using Makefile.PL
  { /usr/bin/perl Makefile.PL &&
    make &&
    make test &&
    make install; } || return 1

  # If using Build.PL
  { /usr/bin/perl Build.PL &&
    ./Build &&
    ./Build test &&
    ./Build install; } || return 1

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