authoring cpan modules

16

Click here to load reader

Upload: alex-balhatchet

Post on 11-Jun-2015

1.474 views

Category:

Technology


2 download

DESCRIPTION

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

TRANSCRIPT

Page 1: Authoring CPAN modules

Authoring CPAN modulesPAUSE, CPAN, Git, Github, Dist::Zilla

Page 2: Authoring CPAN modules

Your first CPAN modulePAUSE

Perl Authors Upload Server

http://pause.perl.org

Account requests are manually verified, can take weeks.

Sign up early!

Page 3: Authoring CPAN modules

Getting ready to write some code% module-starter --module='My::New::Module' \ --author='me' --email='[email protected]' --mb

Learn the CPAN module code layout:

lib/ - Perl modulest/ - tests

Changes - change log fileMETA.yml - distribution metadataLICENSE - legal stuffREADME - installation detailsMANIFEST - list of files included

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

Page 4: Authoring CPAN modules

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.

Page 5: Authoring CPAN modules

Of course you use source controlGo 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 [email protected]:you/My-New-Module.git% git push origin master

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

Page 6: Authoring CPAN modules

Writing your moduleThis 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!

Page 7: Authoring CPAN modules

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 tarball

Upload your distribution tarball to PAUSE...

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

Page 8: Authoring CPAN modules

Dist::ZillaDist::Zilla is a package to help CPAN authors.

% dzil helpAvailable 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

Page 9: Authoring CPAN modules

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-Moduleauthor = Alex Balhatchet <[email protected]>license = Perl_5copyright_holder = Alex Balhatchetcopyright_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

Page 10: Authoring CPAN modules

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

Page 11: Authoring CPAN modules

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

[%User]name = Alex Balhatchetemail = [email protected]

[%Rights]license_class = Perl_5copyright_holder = Alex Balhatchet

[%PAUSE]username = kaorupassword = *********

Page 12: Authoring CPAN modules

Dist::Zilla config files (2)% cat dist.ini

name = WebService-Nestoria-Searchversion = 1.018004abstract = ...

author = Alex Balhatchet ([email protected])license = Perl_5copyright_holder = Lokku Ltd.

[Prereqs / RuntimeRequires]Carp = 0HTTP::Request = 0JSON = 2.0LWP::UserAgent = 0URI = 0version = 0XML::Simple = 0

[Prereqs / TestRequires]List::MoreUtils = 0Test::More = 0Test::Warn = 0

[MetaResources]homepage = http://www.nestoria.co.uk/help/apirepository.web = http://github.com/kaoru/WebSer...repository.url = git://github...repository.type = git

[GatherDir][PruneCruft][ManifestSkip][MetaYAML][MetaJSON][License][Readme][PkgVersion][PodVersion][PodSyntaxTests][ExtraTests][ExecDir][ShareDir][MakeMaker][Manifest][ConfirmRelease][UploadToCPAN]

Page 13: Authoring CPAN modules

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

Page 14: Authoring CPAN modules

The waiting gameAfter 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.

Page 15: Authoring CPAN modules

CPAN TestersOnce 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!

Page 16: Authoring CPAN modules

Any questions?