Ali Anari

Lessons learned publishing my first CPAN module

So you want to join the ranks of thousands of other #perl hackers and release something to the community? I just developed my first standalone Perl module at Crowdtilt called WebService::NationBuilder, and the process was actually a lot more straightforward than I thought it would be. Keep reading to find out how simple it really is to write your own module and become a published CPAN (Comprehensive Perl Archive Network) author!

PAUSE then play

Head on over to PAUSE, the Perl Authors Upload SErver and register your very own account using this form. Your account will get its own directory (mine turned out to be authors/id/A/AA/AANARI) where your uploaded distributions will be indexed and rapidly propogated across CPAN and its mirrors thanks to some of the fast rsync stuff the PAUSE workers have developed. Don’t let the old-school feel of the PAUSE site fool you, it’s a serious platform that was created by Andreas Koenig in 1995 and has been closely maintained since. For the ever curious, you can dive into the source GitHub repo here.

My::Module v0.0001

You may want to follow some naming convention to make sure your module fits in with everything else already on CPAN. Mine was simple because WebService is a standard namespace for Perl HTTP client libraries, but you can always ask the good folks over at modules@perl.org if you’re ever unsure. Versioning can be tricky because Perl honors backwards compatibility, so I recommend using your first digit for Major version, two digits denoting your Minor version, and two final digits for your bugfix or incrementing version number: 1.2501 means v1.25.1. Most importantly, don’t switch version number schemes for a published module or your users won’t know in advance the right format to request.

dzil to the rescue

Dist::Zilla automates away common distribution tasks, and we love using it here at Crowdtilt. The dzil website is chock full of useful tutorials, plugins, and other goodies that helped me get up and running in no time. Run dzil setup and enter your PAUSE credentials, and you’ll never have to manually upload your releases again! Now invoke dzil new and do what you do best – write some killer Perl code.

PODs you can trust

Perl’s documentation system is POD (Plain Old Documentation) and it’s easy to get up and running if you’ve ever used any other human-readable documentation format like Markdown or YAML. You can even generate your repo’s README.md from POD using a dzil plugin, but for WebService::NationBuilder I created separate documentation files for now. You should definitely spend the extra few minutes and define PODs so that your beautiful docs show up on CPAN, or in the terminal when one of your users runs perldoc against your module.

D (deploy) day

Run dzil release and your shiny new module is on its way for the world to see! You can view your distribution’s page on MetaCPAN within an hour (usually 30 minutes), as this site updates very quickly from PAUSE. Now you can install your distribution from CPAN using your favorite CPAN client like cpanm, although you might need to wait until your distribution reaches your configured CPAN mirror.

Perl IRL?

Many of the talks at Perl conferences involve authors talking about their work, because after all, who is better qualified to help others use your module than you? For the non-public-speaking-inclined, there’s always the small casual setting of your local Perl user group (you can find one near you on the Perl Mongers website.

« Your First Hire Should be a Sysadmin 10 Reasons to Never Use Perl, Ever »