• Share
  • Email
  • Embed
  • Like
  • Save
  • Private Content
Authoring CPAN modules

Authoring CPAN modules



A talk I gave internally at Lokku in January 2011.

A talk I gave internally at Lokku in January 2011.

Covers PAUSE, CPAN, Git, Github, Dist::Zilla and CPAN Testers.



Total Views
Views on SlideShare
Embed Views



0 Embeds 0

No embeds


Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
Post Comment
Edit your comment

    Authoring CPAN modules Authoring CPAN modules Presentation Transcript

    • Authoring CPAN modules PAUSE, CPAN, Git, Github, Dist::Zilla
    • Your first CPAN modulePAUSEPerl Authors Upload Serverhttp://pause.perl.orgAccount requests are manuallyverified, can take weeks.Sign up early!
    • Getting ready to write some code% module-starter --module=My::New::Module --author=me --email=me@lokku.com --mbLearn the CPAN module code layout:lib/ - Perl modulest/ - testsChanges - change log fileMETA.yml - distribution metadataLICENSE - legal stuffREADME - installation detailsMANIFEST - list of files includedMakeFile.PL - installation script (autoconf)Build.PL - installation script (pure Perl)
    • If youre unsure...Copy somebody elses code!There are many different types of CPAN module... ● App::* ● WebService::* ● *::XS ● *::Tiny ● *::ManualAll have different layouts and conventions. When in doubt lookat a few popular examples, or examples by popular authors.
    • Of course you use source controlGo sign up to Github - http://github.comIf youre unfamiliar with Git read Pro Git - http://progit.org/book/Getting started using Git and Github for your CPAN module iseasyCreate "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 moduleThis is the bit you are already familiar with.Write your module in lib/My/New/Module.pmWrite your tests in t/*.tTest your code using prove -l and perl -cwWrite good quality code and tests, somebody might read it!
    • Getting your module on CPANThe 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 tarballUpload your distribution tarball to PAUSE...https://pause.perl.org/pause/authenquery?ACTION=add_uri
    • Dist::ZillaDist::Zilla is a package to help CPAN authors.% dzil helpAvailable commands: commands: list the applications commands help: display a commands help screen authordeps: list your distributions author dependencies build: build your dist clean: clean up after build, test, or install install: install your dist listdeps: print your distributions 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::ModuleCreates only dist.ini and lib/My/New/Module.pmThe default dist.ini contains...name = My-New-Moduleauthor = Alex Balhatchet <kaoru@slackwise.net>license = Perl_5copyright_holder = Alex Balhatchetcopyright_year = 2010version = 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-*.tDidnt that feel good? :-)% vim ~/dzil/config.iniGlobal defaults% vim dist.iniDistribution-specific config
    • Dist::Zilla config files (1)% cat ~/.dzil/config.ini[%User]name = Alex Balhatchetemail = kaoru@slackwise.net[%Rights]license_class = Perl_5copyright_holder = Alex Balhatchet[%PAUSE]username = kaorupassword = *********
    • Dist::Zilla config files (2)% cat dist.ini [MetaResources] homepage = http://www.nestoria.co.uk/help/apiname = WebService-Nestoria-Search repository.web = http://github.com/kaoru/WebSer...version = 1.018004 repository.url = git://github...abstract = ... repository.type = gitauthor = 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 releaseYep, thats it :-)My Dist::Zilla config adds the $VERSION variable, adds aPOD syntax checking test, creates the META.yml and META.json files, and creates the LICENSE, README, MANIFESTand Makefile.PL files.Dist::Zilla can also interact with SVN or Git, determine yourdependencies automatically, or Tweet when you release a newversion of your module!http://search.cpan.org/search?query=Dist::Zilla::Plugin
    • The waiting gameAfter running the dzil release command or uploading yourdistribution via the PAUSE web interface, you should get antwo emails letting you know everything is OK.After that it takes a few hours for your distribution to be fullyindexed in all the CPAN mirrors. Once its there it will show upon http://search.cpan.org/~you/ as you would expect.Once its on the web, let people know about it.
    • CPAN TestersOnce youve uploaded your distribution, the CPAN Testerstesting service will start testing it for you.You will get emails about the results, and you can also checkthem online.For example, http://www.cpantesters.org/distro/N/Number-Format-SouthAsian.htmlIn the case of Number::Format::SouthAsian the CPAN testersquickly flagged two important bugs - it was broken on 32bitsystems, and it was broken on Windows.Version 0.07 has both those bugs fixed. Woohoo!
    • Any questions?