Prepare your first CPAN distribution, quickly, simply, and with as little magic as possible so that you become familiar with the mechanics.

1. 30 minutes to CPAN
(Minimizing the magic, and demystifying the process.)

2. 30 minutes is pure Marketing Department hype.
But with practice, it's realistic.

3. There are many ways to do it.
This is a good way to start.

4. Get a PAUSE/CPAN account
● https://pause.perl.org/pause/query?ACTION=request_id
● The form takes 2 minutes.
● The response time can be 1-3 days, so be patient.
● Make sure to search CPAN ensuring you're not requesting a
PAUSE ID that is already in use.

5. Create a directory framework
$ mkdir Foo
$ cd Foo
$ mkdir lib
$ mkdir t
$ mkdir examples
$ touch lib/Foo.pm
$ touch t/00-load.t
$ touch examples/example.pl
$ touch Makefile.PL
$ touch MANIFEST
$ touch Changes
$ touch README

6. MANIFEST
● List the files included in your distribution. Comments
may be added to the right.
MANIFEST This file. (And this is a legal comment)
README The brief introduction. (Another comment)
Changes The change log
Makefile.PL
META.json
META.yml
lib/Foo.pm
t/00-load.t
examples/example.pl

7. README
● Brief intro to your module.
● Just copy one from CPAN as an example and
modify it to suit your needs.
– Too long to post here, mostly boilerplate.
● No version numbers. No version-specific details.
– It will make your life as an author easier.

8. Changes
● The change log for CPAN releases. Newer releases are
listed above older ones. One blank line separates
releases.
Change log for Perl module Foo.
0.02 2013-01-09
- Fixed all the bugs in version 0.01.
0.01 2012-11-15
- First version.

9. Makefile.PL
use strict;
use warnings;
use 5.006000;
use ExtUtils::MakeMaker;
WriteMakefile( … );

10. Makefile.PL – WriteMakefile()
WriteMakefile(
NAME => 'Foo',
AUTHOR => q{Your Name < cpan_acct [at] cpan [dot] org >},
VERSION_FROM => 'lib/Foo.pm',
ABSTRACT_FROM => 'lib/Foo.pm',
LICENSE => 'perl',
MIN_PERL_VERSION => '5.006000',
BUILD_REQUIRES => { Test::More => '0', }, # Core; needn't be
listed.
PREREQ_PM => { List::MoreUtils => '0.33', },
META_MERGE => { … },
dist => { COMPRESS => 'gzip -9f', SUFFIX => 'gz', },
clean => { FILES => 'Foo-*' },
);

11. Other Makefile.PL meta info
● It's helpful to include a META_MERGE section
in Makefile.PL
– List the public version control repositiory.
– Other useful meta fields documented in
CPAN::Meta::Spec
– These fields are helpful, but not mandatory.

12. Testing: t/00-load.t
● Anything named t/*.t will be run in ASCII-betical
order as a test.
use strict;
use warnings;
use Test::More;
use_ok( 'Foo' );
can_ok( 'Foo', 'bar' ); # Function exists.
can_ok('main', 'bar'); # Function was imported.
done_testing();

13. lib/Foo.pm
● Your module's code and documentation:
package Foo;
use strict; use warnings;
use Exporter;
our @ISA = qw( Exporter );
our @EXPORT = qw( bar );
our $VERSION = '0.01';
sub bar { print “Hello world!n”; }
1;
=pod

14. lib/Foo.pm ( =pod )
=pod
=head1 NAME
Foo – The great Foo says hello!
=head1 SYNOPSIS
Use Foo;
Bar();
=head1 DESCRIPTION
This module implements a single function, C<bar()> which greets you by
printing “Hello world!”.
=head1 EXPORTS
L<Foo> exports a single function; C<bar()>.
● Follow your favorite (simple) module's example.
● Read perldoc perlpod.

15. examples/example.pl
● A small working script demonstrating your module.
use strict;
use warnings;
use Foo;
bar(); # This prints “Hello world.n”
● Should not be chmod +x (Nor should
anything else in the distribution).

16. Prepare the distribution
perl Makefile.PL
make
make test
make distcheck
make disttest
cp Foo-0.01/META.* ./
rm -rf Foo-0.01
make dist

17. Upload to PAUSE
● Log in at: http://pause.perl.org
● Upload at:
https://pause.perl.org/pause/authenquery?ACTION=add_uri
● Wait a few hours for the CPAN mirrors to update.
● Visit http://cpantesters.org to check smoke test results.

18. Request the namespace.
● This is a formality, and can take a week to be
approved.
● This is done via the PAUSE website.
● Top-level namespaces are more difficult.
● Upload first, then request.

19. Version Numbers
● Regular Releases
our $VERSION = '0.01';
● Always bump the version number before uploading to
CPAN.
● Minimize error-prone work: Keep version numbers in as
few places as practical.
– Consider adding a version number consistency test.

20. Module tests
● Module tests are important to you and users.
– You get feedback from the smoke testers.
– Your users gain confidence that the module will work on their
platform.
– Bugs are easier to track down.
● List additional test dependencies in BUILD_REQUIRES.
● Some tests such as Test::NoWarnings may be written
generically, and copied into your next project.
– Your next module won't take as long to assemble.

21. Author / Release Tests
● Should run optionally
● Should not fail if a test module dependency isn't
available.
● Use environment variables such as RELEASE_TESTING
to trigger these sorts of tests.
● Skip and exit gracefully if an optional test's module is
unavailable on the target system.
● Generic: They may be useful in your next module.

22. A few author tests to consider
● Test::Pod
● Test::Pod::Coverage
● Test::CPAN::Changes
● Test::Manifest
● Test::Perl::Critic
● Test::Kwalitee
● Test::Version
● Many other favorites are on CPAN – Ask around.

23. License
● Make sure the license enumerated in the POD
matches the one called for in Makefile.PL
● See:
$ perldoc perlmodstyle
$ perldoc perlartistic
$ perldoc perlgpl
● License should be referred to in Makefile.PL
so the META files list it.

24. License
● Make sure the license enumerated in the POD
matches the one called for in Makefile.PL
● See:
$ perldoc perlmodstyle
$ perldoc perlartistic
$ perldoc perlgpl
● License should be referred to in Makefile.PL
so the META files list it.

25. Next time...
● Use Module::Starter
– Creates a simple template for you, and adds a few
tests.
● Copy the generic (especially author-only) tests
from your previous distribution.
● Whenver you come up with a test that might
be useful in other distributions, copy it to them.

26. Eventually...
● Some people love Dist::Zilla; a distribution
automator / manager.
● Module::Build is a more Perlish alternative to
ExtUtils::MakeMaker
● Module::Install is yet another solution that lets
you bundle prereqs more easily. It simplifies
creating ExtUtils::MakeMaker-based
distributions.

27. References (Really, look them over)
● POD
– perlmodstyle
– perlpod
● On CPAN
– Module::Starter
– ExtUtils::MakeMaker
– CPAN::Meta::Spec
● In print
– Intermediate Perl Programming (O'Reilly)
● On testing
– Test::More
– http://cpantesters.org
● CPAN itself! (Thousands of good – and bad – examples.)

28. David Oswald
daoswald@gmail.com / davido@cpan.org