SlideShare a Scribd company logo

Authoring CPAN modules

•
•
Alex Balhatchet
Alex Balhatchet

A talk I gave internally at Lokku in January 2011. Covers PAUSE, CPAN, Git, Github, Dist::Zilla and CPAN Testers.

Related slideshows

Ansible - Swiss Army Knife Orchestration
Ansible - Swiss Army Knife OrchestrationAnsible - Swiss Army Knife Orchestration
Ansible - Swiss Army Knife Orchestration
 
PuppetCamp SEA 1 - Version Control with Puppet
PuppetCamp SEA 1 - Version Control with PuppetPuppetCamp SEA 1 - Version Control with Puppet
PuppetCamp SEA 1 - Version Control with Puppet
 
Configuration Surgery with Augeas
Configuration Surgery with AugeasConfiguration Surgery with Augeas
Configuration Surgery with Augeas
 
1 of 16
Download to read offline
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!
Any questions?

More Related Content

Authoring CPAN modules

  • 1. Authoring CPAN modules PAUSE, CPAN, Git, Github, Dist::Zilla
  • 2. Your first CPAN module PAUSE Perl Authors Upload Server http://pause.perl.org Account requests are manually verified, can take weeks. Sign up early!
  • 3. 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)
  • 4. 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.
  • 5. 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
  • 6. 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!
  • 7. 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
  • 8. 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
  • 9. 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
  • 10. 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
  • 11. 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 = *********
  • 12. 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]
  • 13. 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
  • 14. 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.
  • 15. 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!