Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

30 Minutes To CPAN


Published on

Prepare your first CPAN distribution, quickly, simply, and with as little magic as possible so that you become familiar with the mechanics.

Published in: Technology
  • Be the first to comment

30 Minutes To CPAN

  1. 1. 30 minutes to CPAN(Minimizing the magic, and demystifying the process.)
  2. 2. 30 minutes is pure Marketing Department hype. But with practice, its realistic.
  3. 3. There are many ways to do it. This is a good way to start.
  4. 4. Get a PAUSE/CPAN account●● The form takes 2 minutes.● The response time can be 1-3 days, so be patient.● Make sure to search CPAN ensuring youre not requesting a PAUSE ID that is already in use.
  5. 5. Create a directory framework$ mkdir Foo$ cd Foo$ mkdir lib$ mkdir t$ mkdir examples$ touch lib/$ touch t/00-load.t$ touch examples/$ touch Makefile.PL$ touch MANIFEST$ touch Changes$ touch README
  6. 6. MANIFEST● List the files included in your distribution. Comments may be added to the right. MANIFEST This file. (And this is a legal comment) README The brief introduction. (Another comment) Changes The change log Makefile.PL META.json META.yml lib/ t/00-load.t examples/
  7. 7. README● Brief intro to your module.● Just copy one from CPAN as an example and modify it to suit your needs. – Too long to post here, mostly boilerplate.● No version numbers. No version-specific details. – It will make your life as an author easier.
  8. 8. Changes● The change log for CPAN releases. Newer releases are listed above older ones. One blank line separates releases. Change log for Perl module Foo. 0.02 2013-01-09 - Fixed all the bugs in version 0.01. 0.01 2012-11-15 - First version.
  9. 9. Makefile.PLuse strict;use warnings;use 5.006000;use ExtUtils::MakeMaker;WriteMakefile( … );
  10. 10. Makefile.PL – WriteMakefile()WriteMakefile( NAME => Foo, AUTHOR => q{Your Name < cpan_acct [at] cpan [dot] org >}, VERSION_FROM => lib/, ABSTRACT_FROM => lib/, LICENSE => perl, MIN_PERL_VERSION => 5.006000, BUILD_REQUIRES => { Test::More => 0, }, # Core; neednt belisted. PREREQ_PM => { List::MoreUtils => 0.33, }, META_MERGE => { … }, dist => { COMPRESS => gzip -9f, SUFFIX => gz, }, clean => { FILES => Foo-* },);
  11. 11. Other Makefile.PL meta info● Its helpful to include a META_MERGE section in Makefile.PL – List the public version control repositiory. – Other useful meta fields documented in CPAN::Meta::Spec – These fields are helpful, but not mandatory.
  12. 12. Testing: t/00-load.t● Anything named t/*.t will be run in ASCII-betical order as a test. use strict; use warnings; use Test::More; use_ok( Foo ); can_ok( Foo, bar ); # Function exists. can_ok(main, bar); # Function was imported. done_testing();
  13. 13. lib/● Your modules code and documentation: package Foo; use strict; use warnings; use Exporter; our @ISA = qw( Exporter ); our @EXPORT = qw( bar ); our $VERSION = 0.01; sub bar { print “Hello world!n”; } 1; =pod
  14. 14. lib/ ( =pod ) =pod =head1 NAME Foo – The great Foo says hello! =head1 SYNOPSIS Use Foo; Bar(); =head1 DESCRIPTION This module implements a single function, C<bar()> which greets you by printing “Hello world!”. =head1 EXPORTS L<Foo> exports a single function; C<bar()>.● Follow your favorite (simple) modules example.● Read perldoc perlpod.
  15. 15. examples/● A small working script demonstrating your module. use strict; use warnings; use Foo; bar(); # This prints “Hello world.n”● Should not be chmod +x (Nor should anything else in the distribution).
  16. 16. Prepare the distributionperl Makefile.PLmakemake testmake distcheckmake disttestcp Foo-0.01/META.* ./rm -rf Foo-0.01make dist
  17. 17. Upload to PAUSE● Log in at:● Upload at:● Wait a few hours for the CPAN mirrors to update.● Visit to check smoke test results.
  18. 18. Request the namespace.● This is a formality, and can take a week to be approved.● This is done via the PAUSE website.● Top-level namespaces are more difficult.● Upload first, then request.
  19. 19. Version Numbers● Regular Releases our $VERSION = 0.01;● Always bump the version number before uploading to CPAN.● Minimize error-prone work: Keep version numbers in as few places as practical. – Consider adding a version number consistency test.
  20. 20. Module tests● Module tests are important to you and users. – You get feedback from the smoke testers. – Your users gain confidence that the module will work on their platform. – Bugs are easier to track down.● List additional test dependencies in BUILD_REQUIRES.● Some tests such as Test::NoWarnings may be written generically, and copied into your next project. – Your next module wont take as long to assemble.
  21. 21. Author / Release Tests● Should run optionally● Should not fail if a test module dependency isnt available.● Use environment variables such as RELEASE_TESTING to trigger these sorts of tests.● Skip and exit gracefully if an optional tests module is unavailable on the target system.● Generic: They may be useful in your next module.
  22. 22. A few author tests to consider● Test::Pod● Test::Pod::Coverage● Test::CPAN::Changes● Test::Manifest● Test::Perl::Critic● Test::Kwalitee● Test::Version● Many other favorites are on CPAN – Ask around.
  23. 23. License● Make sure the license enumerated in the POD matches the one called for in Makefile.PL● See: $ perldoc perlmodstyle $ perldoc perlartistic $ perldoc perlgpl● License should be referred to in Makefile.PL so the META files list it.
  24. 24. License● Make sure the license enumerated in the POD matches the one called for in Makefile.PL● See: $ perldoc perlmodstyle $ perldoc perlartistic $ perldoc perlgpl● License should be referred to in Makefile.PL so the META files list it.
  25. 25. Next time...● Use Module::Starter – Creates a simple template for you, and adds a few tests.● Copy the generic (especially author-only) tests from your previous distribution.● Whenver you come up with a test that might be useful in other distributions, copy it to them.
  26. 26. Eventually...● Some people love Dist::Zilla; a distribution automator / manager.● Module::Build is a more Perlish alternative to ExtUtils::MakeMaker● Module::Install is yet another solution that lets you bundle prereqs more easily. It simplifies creating ExtUtils::MakeMaker-based distributions.
  27. 27. References (Really, look them over)● POD – perlmodstyle – perlpod● On CPAN – Module::Starter – ExtUtils::MakeMaker – CPAN::Meta::Spec● In print – Intermediate Perl Programming (OReilly)● On testing – Test::More –● CPAN itself! (Thousands of good – and bad – examples.)
  28. 28. David /