Hi,
I’ve recently put up a Perl wrapper for the Freesound.org OAuth2 API, and supporting goodies on CPAN : WebService::Freesound. Go me! Also available on GitHub.
Here are some notes on what I did to get it onto CPAN.
How to CPAN
Pause Id
First thing to do is to get a ‘PAUSE’ id – (Perl Authors Upload SErver). First because it could take up to three weeks to get approved (only a few hours for me though) : pause.perl.org. Read all of the about::pause words carefully,
Read the Guides
Then go and look at these links for guides on how to create your CPAN module :
- https://search.cpan.org/~rjbs/perl-5.24.0/pod/perlstyle.pod
- https://search.cpan.org/~rjbs/perl-5.24.0/pod/perlmodstyle.pod
- https://search.cpan.org/~rjbs/perl-5.24.0/pod/perlnewmod.pod
Create a template
I followed the (now old fashioned) way of creating an empty template using Module::Starter :
module-starter --module=WebService::Freesound --author="Andy Cragg" --email=andycragg@cpan.org
There seem to be plenty of other ways (ExtUtils::MakeMaker::Tutorial, Module::Install and the fantastically obfuscated Dist::Zilla). I found module-starter to be a good introduction to how a Perl module gets built.
You’ll get this (for Wibble::Wobble) :
Added to MANIFEST: Changes
Added to MANIFEST: ignore.txt
Added to MANIFEST: lib/Wibble/Wobble.pm
Added to MANIFEST: Makefile.PL
Added to MANIFEST: MANIFEST
Added to MANIFEST: README
Added to MANIFEST: t/00-load.t
Added to MANIFEST: t/manifest.t
Added to MANIFEST: t/pod-coverage.t
Added to MANIFEST: t/pod.t
Added to MANIFEST: xt/boilerplate.t
Created starter directories and files
Go do!
Do The Thing then, editing the lib/Wibble/Wobble.pm in place, following the guidelines and set the Version to 0.01 to start with :
=head1 VERSION
Version 0.01
=cut
our $VERSION = '0.01';
Make it nice
Then I recommend doing these things. Highly recommend :
perltidy --perl-best-practices Wobble.pm > Wobble.pt.pm, check that there are no comments that have gone west and copy over the module with the perl tidied version. And :
perlcritic Wobble.pm
Wobble.pm source OK – ie fix any warnings (whether you agree with them or not, it looks good on CPAN if it’s Done The Right Way, and people will like you, ditto perltidy).
Test!
Then you write the all-important tests (say in t/07-init.t) – there are some nice ways to ‘mock’ external modules to give you some pre-prepared results, like I did with WebService::Freesound, I mocked the get and post methods of User::Agent, because I didn’t want my real Freesound.org OAuth credentials in the tests. See Test::MockModule, Test::MockObject::Extends, etc. To run the test code, do :
perl Makefile.PL
make
make test
I would suggest renaming the template test files in a more modern format, ie 00-load.t 01-modules.t 02-boilerplate.t 03-manifest.t 04-pod.t 05-pod-coverage.t, and removing the xt/ directory.
Build the distribution
Then you manually edit these files:
Makefile.PL : add the dependencies, the BUILD_REQUIRES section for the modules that your t/07-init.t tests require and the PREREQ_PM for the modules dependencies, which are automagically installed when your user does sudo cpan Wibble::Wobble. The => 0 bit means use the latest version of that module.
BUILD_REQUIRES => {
'Test::More' => 0,
'Test::Exception' => 0,
'LWP::UserAgent' => 0,
'Test::MockModule' => 0,
'HTTP::Response' => 0,
'JSON' => 0,
},
PREREQ_PM => {
'LWP::Simple' => 0,
'LWP::UserAgent' => 0,
'Data::Dumper' => 0,
'JSON' => 0,
},
MANIFEST – Check that all the files you need for the distribution are here, it gets generated along the way anyway though.
INSTALL – basically just The Mantra : perl Makefile.PL, make, make test, sudo make install.
Changes – initial version as per the template, with your name and date/time.
License – copy from one of the licenses you’d like.
Then create the README files from the POD. Because you will have written some excellent POD documentation into your module (https://search.cpan.org/~rjbs/perl-5.24.0/pod/perlpod.pod). The module-starter will have generated a good starting point anyway :
pod2readme lib/Wibble/Wobble.pm
Creates a README file. If you want a README.md too, for github, then :
pod2markdown lib/Wibble/Wobble.pm > README.md
Once all done (ha!) and you’re happy with it all, then make the distribution :
make dest
Upload to CPAN
And you should have a nice Wibble-Wobble-0.01.tar.gz file to upload to PAUSE (https://pause.perl.org/pause/authenquery?ACTION=add_uri). Once uploaded, then check the CPAN Testers page, which will be like : https://cpantesters.org/author/A/ANDYCRAGG.html, for example (initial/cpan-id.html). Takes a good few hours for your precious module to ‘get onto CPAN’ but it’s much fun watching and waiting.
When you come to updating it to a new version, then simply upload the new one to PAUSE, and CPAN will work it out and CPAN Testers will start again on the new one.
That is, of course, One Way To Do It, there are others as mentioned above, it worked for me… Let me know if there are glaring errors here, it did take me a while to see what needed to be done. And you can download WebService::Freesound to see all the gory details.
Next time I shall show how to use my WebService::Freesound in a web app.
CheersO!
~andy~
