If you have a module that you think others might find useful, consider making the world a better place by uploading it to CPAN. The server that handles new module submissions is called PAUSE (the Perl Authors Upload Server) and can be found at https://pause.kbx.de/pause/. Before you can upload your module, you'll have to get a PAUSE account. This is about as close as you can get to being a "registered Perl developer".
If you call yourself a registered Perl developer, you should know enough to document your modules. Perl has a convention of embedding documentation inside your source code. (That way, you never lose it.) This embedded documentation is in a format called "pod" (for Plain Old Documentation) and is described in Chapter 26.
You should consider making your module thread safe. See Chapter 17.
You should also worry a little bit about whether your cute little module does things that could break the security of people who use it, because other folks may have some Really Good Reasons to be more concerned about security than you are (yet). See Chapter 23, for all about how to avoid being responsible for the outbreak of World War III and other such nuisances.
Modules meant to be distributed on CPAN should include a Perl program named Makefile.PL that, when run, generates a Makefile, and a README file briefly explaining what the module is and how to install it. The Makefile will expect your module to include a test suite as well. You can create all these files at once with the h2xs utility:
h2xs -X -n Foo::Bar
(Substitute -A
for
-X
if you're building a module that has an XS
component. XS is described in Chapter
21.) The h2xs program creates a single
directory with skeletal files for you to flesh out. When you've
finished, you can upload the tarballed directory to PAUSE.
The Makefile.PL generated by h2xs will look something like this:
use ExtUtils::MakeMaker; # See lib/ExtUtils/MakeMaker.pm for details of how to influence # the contents of the Makefile that is written. WriteMakefile( NAME => 'Mytest', VERSION_FROM => 'Mytest.pm', # finds $VERSION LIBS => [''], # e.g., '-lm' DEFINE => '', # e.g., '-DHAVE_SOMETHING' INC => '', # e.g., '-I/usr/include/other' );
The first thing Makefile.PL does is to pull
in the ExtUtils::MakeMaker
module.
MakeMaker
's WriteMakefile
function has oodles of options (where oodles is defined as
approximately 88) to help you customize what happens after the user
downloads your module from CPAN and types perl
MakeFile.PL to begin building it. The nice thing about all
this is that, since the user is presumably running the
perl that will be used later, you have a wealth
of configuration information available (via the
Config
module or the $^O
special
variable) to help you decide how to drive
MakeMaker
. On the other hand,
MakeMaker
is really good at finding decent defaults
for almost everything, so the skeletal file written
h2xs may well be all you need, with perhaps a
tweak or two. For more on this, see the extensive online docs for
ExtUtils::MakeMaker
.
When writing a Perl module for general consumption, you
should allow for the possibility that the user's version of Perl may
differ from yours. You should always put an English description of any
dependencies (particular versions of Perl, or system requirements, or
other modules) into the README file. However,
even that may not be sufficient, since someone using the slick
CPAN
module to automatically download and install
your module might never see the warning. So you should check those
dependencies in Makefile.PL. Here's how you might
ensure that the person who downloaded your module is running Perl 5.6
or greater:
eval { require 5.6.0 } or die <<'EOD'; ############ ### This module requires lvaluable subroutines, which are not available ### in versions of Perl earlier than 5.6. Please upgrade! ############ EOD
The standard instructions for installing a module tell
the user to run make test after building the
module with make. So please include a decent
test script with any module that you upload to CPAN. You should
emulate the ok
/not ok
style
that Perl uses in its own test suite, so that it's easy for the user
to determine the outcome of each test case. The
test.pl file generated by
h2xs will help get you started. Chapter 21 has some examples of tests
that you can add to the end of test.pl.
If you have many test cases, you might want to mimic Perl's test suite by creating a subdirectory named t/ in the module's directory and appending .t to the names of your different test scripts. When you run make test, all test files will be executed automatically.
Modules uploaded to CPAN are tested by a variety of
volunteers on different platforms. These CPAN testers are notified
by mail of each new upload, and reply to the list with
PASS
, FAIL
,
NA
(not applicable to this platform), or
UNKNOWN
(unknown), along with any relevant
notations. You can find the mailing list for CPAN testers at
[email protected]; test results are posted at
http://testers.cpan.org/.
That's all just the preliminary testing, of course. The real testing begins when someone plugs your little module into a web server that's cranking out a million pages a day. Or uses your module to help design the airplane you'll be riding in someday soon.
So go ahead, skip writing those pesky little tests. See if we care...