![Makefile.PL – WriteMakefile()
WriteMakefile(
NAME => 'Foo',
AUTHOR => q{Your Name < cpan_acct [at] cpan [dot] org >},
VERSION_FROM => 'lib/Foo.pm',
ABSTRACT_FROM => 'lib/Foo.pm',
LICENSE => 'perl',
MIN_PERL_VERSION => '5.006000',
BUILD_REQUIRES => { Test::More => '0', }, # Core; needn't be
listed.
PREREQ_PM => { List::MoreUtils => '0.33', },
META_MERGE => { … },
dist => { COMPRESS => 'gzip -9f', SUFFIX => 'gz', },
clean => { FILES => 'Foo-*' },
);](https://image.slidesharecdn.com/30minutestocpan-121115192046-phpapp01/85/30-Minutes-To-CPAN-10-320.jpg)
30 Minutes To CPAN
- 1. 30 minutes to CPAN (Minimizing the magic, and demystifying the process.)
- 2. 30 minutes is pure Marketing Department hype. But with practice, it's realistic.
- 3. There are many ways to do it. This is a good way to start.
- 4. Get a PAUSE/CPAN account ● https://pause.perl.org/pause/query?ACTION=request_id ● The form takes 2 minutes. ● The response time can be 1-3 days, so be patient. ● Make sure to search CPAN ensuring you're not requesting a PAUSE ID that is already in use.
- 5. Create a directory framework $ mkdir Foo $ cd Foo $ mkdir lib $ mkdir t $ mkdir examples $ touch lib/Foo.pm $ touch t/00-load.t $ touch examples/example.pl $ touch Makefile.PL $ touch MANIFEST $ touch Changes $ touch README
- 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/Foo.pm t/00-load.t examples/example.pl
- 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. 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. Makefile.PL use strict; use warnings; use 5.006000; use ExtUtils::MakeMaker; WriteMakefile( … );
- 10. Makefile.PL – WriteMakefile() WriteMakefile( NAME => 'Foo', AUTHOR => q{Your Name < cpan_acct [at] cpan [dot] org >}, VERSION_FROM => 'lib/Foo.pm', ABSTRACT_FROM => 'lib/Foo.pm', LICENSE => 'perl', MIN_PERL_VERSION => '5.006000', BUILD_REQUIRES => { Test::More => '0', }, # Core; needn't be listed. PREREQ_PM => { List::MoreUtils => '0.33', }, META_MERGE => { … }, dist => { COMPRESS => 'gzip -9f', SUFFIX => 'gz', }, clean => { FILES => 'Foo-*' }, );
- 11. Other Makefile.PL meta info ● It's 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. 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. lib/Foo.pm ● Your module's 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. lib/Foo.pm ( =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) module's example. ● Read perldoc perlpod.
- 15. examples/example.pl ● 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. Prepare the distribution perl Makefile.PL make make test make distcheck make disttest cp Foo-0.01/META.* ./ rm -rf Foo-0.01 make dist
- 17. Upload to PAUSE ● Log in at: http://pause.perl.org ● Upload at: https://pause.perl.org/pause/authenquery?ACTION=add_uri ● Wait a few hours for the CPAN mirrors to update. ● Visit http://cpantesters.org to check smoke test results.
- 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. 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. 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 won't take as long to assemble.
- 21. Author / Release Tests ● Should run optionally ● Should not fail if a test module dependency isn't available. ● Use environment variables such as RELEASE_TESTING to trigger these sorts of tests. ● Skip and exit gracefully if an optional test's module is unavailable on the target system. ● Generic: They may be useful in your next module.
- 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. 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. 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. 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. 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. References (Really, look them over) ● POD – perlmodstyle – perlpod ● On CPAN – Module::Starter – ExtUtils::MakeMaker – CPAN::Meta::Spec ● In print – Intermediate Perl Programming (O'Reilly) ● On testing – Test::More – http://cpantesters.org ● CPAN itself! (Thousands of good – and bad – examples.)
- 28. David Oswald daoswald@gmail.com / davido@cpan.org