Creating CPAN Modules (Programming Perl)

22.3. Creating CPAN Modules

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, "Plain Old Documentation".

You should consider making your module thread safe. See Chapter 17, "Threads".

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, "Security", 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, "Internals and Externals".) 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

22.3.1. Internal Testing

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, "Internals and Externals" 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.

22.3.2. External Testing

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 cpan-testers@perl.org; 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...


22.2. Using CPAN Modules		23. Security