Authoring CPAN modules
Upcoming SlideShare
Loading in...5
×
 

Authoring CPAN modules

on

  • 1,563 views

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.

Statistics

Views

Total Views
1,563
Views on SlideShare
1,563
Embed Views
0

Actions

Likes
0
Downloads
6
Comments
0

0 Embeds 0

No embeds

Accessibility

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.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
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?