[ Perl tips index]
[ Subscribe to Perl tips ]
Starting a new module can be a lot of work. A good module should have a build system, documentation, a test suite, and numerous other bits and pieces to assist in its easy packaging and development. These are useful even if we never release our module to CPAN.
Setting this up can be a lot of work, especially if you've
never done it before. While the h2xs tool that
comes with Perl will do some of this for you, it's showing its
age, and doesn't allow us to take advantage of recent tools.
We want to spend our time writing code, not trying to decode
our build system.
That's where Module::Starter comes in handy.
It provides a simple, command-line tool to create a skeleton
module quickly and easily.
Before we can build our module, we need to
install Module::Starter from the CPAN.
Module::Starter allows us to choose from a variety of
build frameworks, from the aging ExtUtils::MakeMaker
to Module::Install and Module::Build.
While ExtUtils::MakeMaker comes standard with Perl,
you may need to install the other build frameworks. At Perl
Training Australia we generally use Module::Install.
Creating a module with Module::Starter couldn't be easier. On
the command line we simply write:
module-starter --module=My::Module --author="Jane Smith"
--email=jane.smith@example.com --builder=Module::Install
The module name, author, and e-mail switches are all required.
We've used the optional --builder switch to specify
we want to use Module::Install as our build-system,
instead of the default ExtUtils::MakeMaker.
Once this is done, you should have a My-Module
directory with a skeleton module inside.
If you've never created a module before, or you've been making
them by hand, then it's nice to take a look at what you get for
your Module::Starter skeleton.
$ ls -la
total 8
drwxr-xr-x 4 pjf pjf 0 Jul 4 16:59 .
drwxr-xr-x 51 pjf pjf 0 Jul 4 16:59 ..
-rw-r--r-- 1 pjf pjf 96 Jul 4 16:59 .cvsignore
-rw-r--r-- 1 pjf pjf 109 Jul 4 16:59 Changes
-rw-r--r-- 1 pjf pjf 90 Jul 4 16:59 MANIFEST
-rw-r--r-- 1 pjf pjf 183 Jul 4 16:59 Makefile.PL
-rw-r--r-- 1 pjf pjf 1378 Jul 4 16:59 README
drwxr-xr-x 3 pjf pjf 0 Jul 4 16:59 lib
drwxr-xr-x 2 pjf pjf 0 Jul 4 16:59 t
Let's look at each of these files in turn:
Module::Starter assumes you'll be using CVS for
revision control, and provides a .cvsignore file with
the names of files that are auto-generated and not to be tracked
with revision control. At Perl Training Australia we use git
for new projects, and so we rename this to .gitignore.
(As of version 1.52, this file is now called "ignores.txt", so you can use it however you like.)
This is a human-readable file tracking module revisions and changes. If you're going to release your code to the CPAN, it's essential for your users to know what has changed in each release. Even if you're only using your code internally, this is a good place to document the history of your project.
The MANIFEST file tracks all the files that should be
packaged when you run a make tardist to distribute
your module. Normally it includes your source code, any file
needed for the build system, a META.yml that contains
module meta-data (usually auto-generated by your build system),
tests, documentation, and anything else that you want your
end-user to have.
If you don't want to manually worry about adding entries to the
MANIFEST file yourself, most build systems (including
Module::Install) allow you to write make
manifest to auto-generate it. For this to work, you'll
want to make a MANIFEST.skip file which contains
filenames and regular expressions that match files which should
be excluded from the MANIFEST.
This is the front-end onto our build system. When we wish to build, test, or install our module, we'll always invoke Makefile.PL first:
perl Makefile.PL
make
make test
make install
Most build systems will provide a make tardist target
for building a tarball of all the files in our MANIFEST,
a make disttest for making sure our tests work
with only the MANIFEST listed files, and make
clean and make distclean targets for clearing
up auto-generated files, including those from the build system
itself if a make distclean is run.
You'll almost certainly wish to customise your
Makefile.PL a little, especially if your module
has dependencies. You'll want to consult your build
system documentation for what options you can uses. For
Module::Install this documentation can be found at
http://search.cpan.org/perldoc.
The README file should contain basic information for someone thinking of installing your module. Mentioning dependencies, how to build, and how to find/report bugs are all good things to mention in the README file. Some systems (including the CPAN) will extract the README and make it available separate from the main distribution.
The lib/ directory will contain your skeleton
module, and is where you'll be doing much of your work.
Module::Starter will have already added some skeleton
documentation, a version number, and some skeleton functions.
You can add more modules to the lib/ directory if you wish. Splitting a very large module into smaller, logical pieces can significantly improve maintainability.
The t/ directory contains all the tests that will be
executed when you run a make test. By default,
Module::Starter will provide some simple tests
to ensure that your module compiles, that you'll filled in
relevant sections of the boilerplate documentation, and that your
documentation covers all your subroutines and doesn't contain
any syntax errors.
If you're new to testing in Perl, then you should
start by reading the Test::Tutorial at
http://search.cpan.org/perldoc.
At Perl Training Australia, we usually add a test based on
Test::Perl::Critic http://search.cpan.org/perldoc
to encourage good coding practices, and Test::Kwalitee
http://search.cpan.org/perldoc to catch common
mistakes that are made in distributions.
Ideally when developing your module, the more tests you have,
the better. If you already have a test suite and you're wondering
which parts of your code are not being tested, you can use the
excellent Devel::Cover tool from
http://search.cpan.org/perldoc.
[ Perl tips index ]
[ Subscribe to Perl tips ]
This Perl tip and associated text is copyright Perl Training Australia. You may freely distribute this text so long as it is distributed in full with this Copyright notice attached.
If you have any questions please don't hesitate to contact us:
| Email: | contact@perltraining.com.au |
| Phone: | 03 9354 6001 (Australia) |
| International: | +61 3 9354 6001 |
Copyright 2001-2008 Perl Training Australia. Contact us at contact@perltraining.com.au