I'm sure even Santa's elves appreciate any head start they can get when they start building a new toy, and Module::Starter is a great way to get a leg up when crafting a new Perl module.
Module::Starter is a little different from most Perl modules. Typically, you wouldn't use it directly. When installed, it provides the module-starter script. The script will create the basic framework of a module suitable for distribution. If you're new to creating modules for CPAN this can be a great help.
h2xs predates Module::Starter, and is mainly designed to get a head start when creating a module from C header files. It can be used to create a pure-Perl module via the -X option, however the module skeleton that it creates is not as complete as what is provided by Module::Starter. h2xs also assumes that the module you're creating will be based on Exporter, and its generated documentation also requires significantly more editing.
module-starter accepts a few different options to control its behavior. Here are a few of the most important:
perl Makefile.PL; make; make installincantation whereas Module::Build uses the new-fangled, make-free
perl Build.PL; ./Build; ./Build installIf you're new to creating modules, the latter can be a friendlier way to go.
Let's look at what it does, using a hypothetical Toy::Factory as an example:
santa@northpole:~ $ module-starter --verbose --module=Toy::Factory \
--author="Kris Kringle" --email=santa@northpole.com --builder=Module::Build
Created Toy-Factory
Created Toy-Factory/lib/Toy
Created Toy-Factory/lib/Toy/Factory.pm
Created Toy-Factory/t
Created Toy-Factory/t/pod-coverage.t
Created Toy-Factory/t/pod.t
Created Toy-Factory/t/boilerplate.t
Created Toy-Factory/t/00-load.t
Created Toy-Factory/.cvsignore
Created Toy-Factory/Build.PL
Created Toy-Factory/MANIFEST
Created starter directories and files
And so module-starter created a skeleton for us to start working with, complete with sample tests. Can we build it?
santa@northpole:~ $ cd Toy-Factory santa@northpole:~/Toy-Factory $ perl Build.PL Checking whether your kit is complete... WARNING: the following files are missing in your kit: META.yml Please inform the author. Checking prerequisites... Looks good Creating new 'Build' script for 'Toy-Factory' version '0.01' santa@northpole:~/Toy-Factory $ ./Build lib/Toy/Factory.pm -> blib/lib/Toy/Factory.pm Manifying blib/lib/Toy/Factory.pm -> blib/libdoc/Toy::Factory.3pm
Yes we can! But I wonder if it passes its tests?
santa@northpole:~/Toy-Factory $ ./Build test
t/00-load.........ok 1/1# Testing Toy::Factory 0.01, Perl 5.008006, /usr/bin/perl
t/00-load.........ok
t/boilerplate.....NOK 1/3
# Failed test 'README contains boilerplate text'
# in t/boilerplate.t at line 23.
# The README is used... appears on lines 3
# 'version information here' appears on lines 11
t/boilerplate.....NOK 2/3
# Failed test 'Changes contains boilerplate text'
# in t/boilerplate.t at line 23.
# placeholder date/time appears on lines 3
t/boilerplate.....NOK 3/3
# Failed test 'lib/Toy/Factory.pm contains boilerplate text'
# in t/boilerplate.t at line 23.
# stub function definition appears on lines 36 40 43 47
# boilerplate description appears on lines 20
# the great new $MODULENAME appears on lines 8
# Looks like you failed 3 tests of 3.
t/boilerplate.....dubious
Test returned status 3 (wstat 768, 0x300)
DIED. FAILED tests 1-3
Failed 3/3 tests, 0.00% okay
t/pod-coverage....ok
t/pod.............ok
Failed Test Stat Wstat Total Fail List of Failed
-------------------------------------------------------------------------------
t/boilerplate.t 3 768 3 3 1-3
Failed 1/4 test scripts. 3/6 subtests failed.
Files=4, Tests=6, 2 wallclock secs ( 0.84 cusr + 0.21 csys = 1.05 CPU)
Failed 1/4 test programs. 3/6 subtests failed.
Doh! As a part of the framework it provided module-starter created sample README and Changes files, as well as tests to check these files and ensure that we've replaced the default text with something more meaningful. If you've ever noticed a module on CPAN that claims to be a "Perl extension for blah blah blah" you can appreciate how these tests would have come in handy. In addition, these POD tests will raise your module's Kwalitee score on CPANTS.
After editing lib/Toy/Factory.pm, README and Changes appropriately let's try this again:
santa@northpole:~/Toy-Factory $ ./Build test
Deleting blib/lib/Toy/Factory.pm
lib/Toy/Factory.pm -> blib/lib/Toy/Factory.pm
t/00-load.........ok 1/1# Testing Toy::Factory 0.01, Perl 5.008006, /usr/bin/perl
t/00-load.........ok
t/boilerplate.....ok
t/pod-coverage....ok
t/pod.............ok
All tests successful.
Files=4, Tests=6, 2 wallclock secs ( 0.83 cusr + 0.22 csys = 1.05 CPU)
Great! We're all set to teach Toy::Factory how to make toys. But what about that warning we got when we first built it, about META.yml missing? META.yml is created auotmagically when you issue the ./Build dist command.
santa@northpole:~/Toy-Factory $ ./Build dist
Creating META.yml
Creating Toy-Factory-0.01
Creating Toy-Factory-0.01.tar.gz
tar cf Toy-Factory-0.01.tar Toy-Factory-0.01
gzip Toy-Factory-0.01.tar
Deleting Toy-Factory-0.01
Now we won't get that pesky error the next time we build! This also created the tarball we'd use to distribute our module, Toy-Factory-0.01.tar.gz.
santa@northpole:~/Toy-Factory $ perl Build.PL
Checking whether your kit is complete...
Looks good
Checking prerequisites...
Looks good
Deleting Build
Removed previous script 'Build'
Creating new 'Build' script for 'Toy-Factory' version '0.01'
If only building a real toy factory was so easy!
Editor's note: Module::Starter is pluggable, and you could therefore create a subclass which generates templates suited to your organization's needs.