Packaging Perl
Modules
Kirrily Robert

Look familiar?
~skud/.cpan/build/Archive-Any-0.093 $ ls
Build.PL META.yml README pm_to_blib
Changes Makefile blib t
MANIFEST Makefile.PL lib

Today...
• How CPAN modules are packaged
• Why it rocks
• Why you should use it everywhere
• How to integrate it with release mgt

Creating CPAN modules
• Always use h2xs
• Always use h2xs
• ALWAYS use h2xs

Wrong.

Two main options
• h2xs
• module-starter

h2xs
• Old-school
• Comes with Perl
• Few modern features
• Good XS stubs, though

module-starter
• Module::Starter on CPAN
• Modern features
• Better stubs
• Higher Kwalitee

module-starter
$ module-starter --module Gift::Basket
Created starter directories and files
$ ls Gift-Basket/
Build.PL MANIFEST lib
Changes README t

Configuration
$ cat ~/.module-starter/config
builder: Module::Build
author: Kirrily Robert
email: skud@cpan.org

Module layout
Build.PL MANIFEST lib
Changes README t

Build.PL
use strict;
use warnings;
use Module::Build;
my $builder = Module::Build->new(
module_name => 'Gift::Basket',
license => 'perl',
dist_author => 'Kirrily Robert <skud@cpan.org>',
dist_version_from => 'lib/Gift/Basket.pm',
build_requires => {
'Test::More' => 0,
},
add_to_cleanup => [ 'Gift-Basket-*' ],
);
$builder->create_build_script();

Changes
Revision history for Gift-Basket
0.03 2007-11-20
Added support for shipping gift baskets to
addresses within Australia and NZ.
0.02 2007-11-05
Fixed a bug with adding chocolates to the basket.
0.01 2007-11-01
Initial release. Includes methods for building a
gift basket and calculating prices. Not ready for
production.

MANIFEST
Build.PL
Changes
MANIFEST
META.yml # Will be created by \"make dist\"
README
lib/Gift/Basket.pm
t/00-load.t
t/boilerplate.t
t/pod-coverage.t
t/pod.t

README
• Description
• Installation
• Support
• License

lib/
$ find lib
lib
lib/Gift
lib/Gift/Basket.pm

t/
$ find t
t
t/00-load.t
t/boilerplate.t
t/pod-coverage.t
t/pod.t

Building modules
• ./Build dist
• ./Build disttest
• Upload to PAUSE
• http://pause.perl.org
• cpaninject

Why this rocks
• Standard build/install tools
• Metadata and tests included by
default
• Encourages modularity

Non-CPAN
CPAN Modules

Standard build tools
• Save time and effort
• Already familiar to many developers
• Easy release path to CPAN

Metadata and tests
• Encourage testing
• Specify dependencies

Modularity
• Reduce spaghetti
• Share code between projects
• Easy release path to CPAN

Example
$ ls code/
GiftCo-Core GiftCo-Payments
GiftCo-DB GiftCo-Reporting
GiftCo-MailTools GiftCo-Website

Web Server
GiftCo::Website
GiftCo::Core
GiftCo::DB
GiftCo::Payments

Backend
GiftCo::Reporting
GiftCo::Payments
GiftCo::DB
GiftCo::Core
GiftCo::MailTools

Installation
• Local CPAN
• Distro packages

Local CPAN
• MiniCPAN
• Add local packages
• Configure CPAN.pm

MiniCPAN
• perl -MCPAN -e ‘install CPAN::Mini’
• minicpan -l $LOCAL -r $REMOTE

Inject
• perl -MCPAN -e
‘install CPAN::Mini::Inject’
• mcpani --add --module GiftCo::DB
--authorid SKUD
--modversion 0.01
--file GiftCo::DB-0.01.tar.gz

Configure
cpan[1]> o conf urllist
urllist
0 [file:///Users/skud/mirrors/cpan/]
1 [ftp://cpan.pair.com/pub/CPAN/]
2 [ftp://cpan.hexten.net/]

Distro packages
• Integrates with non-Perl packages
• Standardised install procedure
• Sysadmins like them

Dependencies
GiftCo::DB
DBI
DBD::mysql
mysql-lib

Packaging
• cpan2rpm
• dh-make-perl

cpan2rpm
• Creates RPMs from CPAN modules
• Redhat-derived distros
• cpan2rpm -U GiftCo::DB
• Creates full RPM package

dh-make-perl
• Comes with Debian/Ubuntu
• Creates .deb packages
• dh-make-perl GiftCo-DB-0.01/
• Creates debian/ directory

Issues
• Neither follows CPAN dependencies
• You must walk the dep tree (once)
• Can specify deps thereafter

Example
GiftCo::Website GiftCo::DB
requires
becomes
becomes
libgiftco-website-perl libgiftco-db-perl
requires

apt-get install
$ sudo apt-get install giftco-website
Reading package lists... Done
Building dependency tree... Done
The following extra packages will be installed:
libgiftco-website-perl libgiftco-db-perl libgiftco-core-perl
libgiftco-payments-perl libdbi-perl libdbd-mysql-perl libmysql
The following NEW packages will be installed:
giftco-website libgiftco-website-perl libgiftco-db-perl
libgiftco-core-perl libgiftco-payments-perl libdbi-perl
libdbd-mysql-perl libmysql
0 upgraded, 7 newly installed, 0 to remove and 0 not upgraded.
Need to get 8.3MB of archives.
After unpacking 25MB of additional disk space will be used.
Do you want to continue [Y/n]?

Kirrily Robert
http://infotrope.net
skud@infotrope.net