Authoring CPAN modules

Authoring CPAN modules
PAUSE, CPAN, Git, Github, Dist::Zilla

Your first CPAN module
PAUSE

Perl Authors Upload Server

http://pause.perl.org

Account requests are manually
verified, can take weeks.

Sign up early!

Getting ready to write some code
% module-starter --module='My::New::Module'
--author='me' --email='me@lokku.com' --mb

Learn the CPAN module code layout:

lib/ - Perl modules
t/ - tests

Changes - change log file
META.yml - distribution metadata
LICENSE - legal stuff
README - installation details
MANIFEST - list of files included

MakeFile.PL - installation script (autoconf)
Build.PL - installation script (pure Perl)

If you're unsure...
Copy somebody else's code!

There are many different types of CPAN module...

● App::*
● WebService::*
● *::XS
● *::Tiny
● *::Manual

All have different layouts and conventions. When in doubt look
at a few popular examples, or examples by popular authors.

Of course you use source control
Go sign up to Github - http://github.com

If you're unfamiliar with Git read Pro Git - http://progit.org/book/

Getting started using Git and Github for your CPAN module is
easy

Create "My-New-Module" repository on Github

% cd My-New-Module
% git init
% git remote add origin git@github.com:you/My-New-Module.git
% git push origin master

% vim README.pod
% git commit -a "Added README.pod"
% git push origin master

Writing your module
This is the bit you are already familiar with.

Write your module in lib/My/New/Module.pm

Write your tests in t/*.t

Test your code using prove -l and perl -cw

Write good quality code and tests, somebody might read it!

Getting your module on CPAN
The manual, non-Dist::Zilla way...

% perl Build.PL # creates Build

% ./Build distmeta # creates Makefile.PL and META.yml
% ./Build manifest # creates MANIFEST

% git diff / git add / git commit as necessary

% ./Build disttest # test the distribution
% ./Build dist # spit out a tarball

Upload your distribution tarball to PAUSE...

https://pause.perl.org/pause/authenquery?ACTION=add_uri

Dist::Zilla
Dist::Zilla is a package to help CPAN authors.
% dzil help
Available commands:

commands: list the application's commands
help: display a command's help screen

authordeps: list your distribution's author dependencies
build: build your dist
clean: clean up after build, test, or install
install: install your dist
listdeps: print your distribution's prerequisites
new: mint a new dist
nop: do nothing: initialize dzil, then exit
release: release your dist
run: run stuff in a dir where your dist is built
setup: set up a basic global config file
smoke: smoke your dist
test: test your dist

Creating a new Dist::Zilla-based dist
% dzil new My::New::Module

Creates only dist.ini and lib/My/New/Module.pm

The default dist.ini contains...
name = My-New-Module
author = Alex Balhatchet <kaoru@slackwise.net>
license = Perl_5
copyright_holder = Alex Balhatchet
copyright_year = 2010

version = 0.001

[@Basic]

You can find out about @Basic here:
http://search.cpan.org/dist/Dist-Zilla/lib/Dist/Zilla/PluginBundle/Basic.pm

Converting a dist to Dist::Zilla
% rm -f Build.PL Makefile.PL MANIFEST META.yml t/pod-*.t

Didn't that feel good? :-)

% vim ~/dzil/config.ini

Global defaults

% vim dist.ini

Distribution-specific config

Dist::Zilla config files (1)
% cat ~/.dzil/config.ini

[%User]
name = Alex Balhatchet
email = kaoru@slackwise.net

[%Rights]
license_class = Perl_5
copyright_holder = Alex Balhatchet

[%PAUSE]
username = kaoru
password = *********

Dist::Zilla config files (2)
% cat dist.ini [MetaResources]
homepage = http://www.nestoria.co.uk/help/api
name = WebService-Nestoria-Search repository.web = http://github.com/kaoru/WebSer...
version = 1.018004 repository.url = git://github...
abstract = ... repository.type = git

author = Alex Balhatchet (alex@lokku.com) [GatherDir]
license = Perl_5 [PruneCruft]
copyright_holder = Lokku Ltd. [ManifestSkip]
[MetaYAML]
[Prereqs / RuntimeRequires] [MetaJSON]
Carp =0 [License]
HTTP::Request = 0 [Readme]
JSON = 2.0 [PkgVersion]
LWP::UserAgent = 0 [PodVersion]
URI =0 [PodSyntaxTests]
version =0 [ExtraTests]
XML::Simple = 0 [ExecDir]
[ShareDir]
[Prereqs / TestRequires] [MakeMaker]
List::MoreUtils = 0 [Manifest]
Test::More = 0 [ConfirmRelease]
Test::Warn = 0 [UploadToCPAN]

Build, test & release with Dist::Zilla
% dzil test
% dzil release

Yep, that's it :-)

My Dist::Zilla config adds the $VERSION variable, adds a
POD syntax checking test, creates the META.yml and META.
json files, and creates the LICENSE, README, MANIFEST
and Makefile.PL files.

Dist::Zilla can also interact with SVN or Git, determine your
dependencies automatically, or Tweet when you release a new
version of your module!

http://search.cpan.org/search?query=Dist::Zilla::Plugin

The waiting game
After running the dzil release command or uploading your
distribution via the PAUSE web interface, you should get an
two emails letting you know everything is OK.

After that it takes a few hours for your distribution to be fully
indexed in all the CPAN mirrors. Once it's there it will show up
on http://search.cpan.org/~you/ as you would expect.

Once it's on the web, let people know about it.

CPAN Testers
Once you've uploaded your distribution, the CPAN Testers
testing service will start testing it for you.

You will get emails about the results, and you can also check
them online.

For example, http://www.cpantesters.org/distro/N/Number-
Format-SouthAsian.html

In the case of Number::Format::SouthAsian the CPAN testers
quickly flagged two important bugs - it was broken on 32bit
systems, and it was broken on Windows.

Version 0.07 has both those bugs fixed. Woohoo!

Authoring CPAN modules

More Related Content

What's hot (20)

Similar to Authoring CPAN modules (20)

More from Alex Balhatchet (10)

Recently uploaded (20)

Authoring CPAN modules