PERLNEWMOD(1) Perl Programmers Reference Guide PERLNEWMOD(1)NAMEperlnewmod - preparing a new module for distribution
DESCRIPTION
This document gives you some suggestions about how to go
about writing Perl modules, preparing them for distribu
tion, and making them available via CPAN.
One of the things that makes Perl really powerful is the
fact that Perl hackers tend to want to share the solutions
to problems they've faced, so you and I don't have to bat
tle with the same problem again.
The main way they do this is by abstracting the solution
into a Perl module. If you don't know what one of these
is, the rest of this document isn't going to be much use
to you. You're also missing out on an awful lot of useful
code; consider having a look at the perlmod manpage, the
perlmodlib manpage and the perlmodinstall manpage before
coming back here.
When you've found that there isn't a module available for
what you're trying to do, and you've had to write the code
yourself, consider packaging up the solution into a module
and uploading it to CPAN so that others can benefit.
Warning
We're going to primarily concentrate on Perl-only modules
here, rather than XS modules. XS modules serve a rather
different purpose, and you should consider different
things before distributing them - the popularity of the
library you are gluing, the portability to other operating
systems, and so on. However, the notes on preparing the
Perl side of the module and packaging and distributing it
will apply equally well to an XS module as a pure-Perl
one.
What should I make into a module?
You should make a module out of any code that you think is
going to be useful to others. Anything that's likely to
fill a hole in the communal library and which someone else
can slot directly into their program. Any part of your
code which you can isolate and extract and plug into some
thing else is a likely candidate.
Let's take an example. Suppose you're reading in data from
a local format into a hash-of-hashes in Perl, turning that
into a tree, walking the tree and then piping each node to
an Acme Transmogrifier Server.
Now, quite a few people have the Acme Transmogrifier, and
you've had to write something to talk the protocol from
scratch - you'd almost certainly want to make that into a
module. The level at which you pitch it is up to you: you
might want protocol-level modules analogous to Net::SMTP
which then talk to higher level modules analogous to
Mail::Send. The choice is yours, but you do want to get a
module out for that server protocol.
Nobody else on the planet is going to talk your local data
format, so we can ignore that. But what about the thing in
the middle? Building tree structures from Perl variables
and then traversing them is a nice, general problem, and
if nobody's already written a module that does that, you
might want to modularise that code too.
So hopefully you've now got a few ideas about what's good
to modularise. Let's now see how it's done.
Step-by-step: Preparing the ground
Before we even start scraping out the code, there are a
few things we'll want to do in advance.
Look around
Dig into a bunch of modules to see how they're written.
I'd suggest starting with Text::Tabs, since it's in the
standard library and is nice and simple, and then look
ing at something like Time::Zone, File::Copy and then
some of the "Mail::*" modules if you're planning on
writing object oriented code.
These should give you an overall feel for how modules
are laid out and written.
Check it's new
There are a lot of modules on CPAN, and it's easy to
miss one that's similar to what you're planning on con
tributing. Have a good plough through the modules list
and the by-module directories, and make sure you're not
the one reinventing the wheel!
Discuss the need
You might love it. You might feel that everyone else
needs it. But there might not actually be any real
demand for it out there. If you're unsure about the
demand you're module will have, consider sending out
feelers on the "comp.lang.perl.modules" newsgroup, or
as a last resort, ask the modules list at "mod
ules@perl.org". Remember that this is a closed list
with a very long turn-around time - be prepared to wait
a good while for a response from them.
Choose a name
Perl modules included on CPAN have a naming hierarchy
you should try to fit in with. See the perlmodlib man
page for more details on how this works, and browse
around CPAN and the modules list to get a feel of it.
At the very least, remember this: modules should be
title capitalised, (This::Thing) fit in with a cate
gory, and explain their purpose succinctly.
Check again
While you're doing that, make really sure you haven't
missed a module similar to the one you're about to
write.
When you've got your name sorted out and you're sure
that your module is wanted and not currently available,
it's time to start coding.
Step-by-step: Making the module
Start with h2xs
Originally a utility to convert C header files into XS
modules, h2xs has become a useful utility for churning
out skeletons for Perl-only modules as well. If you
don't want to use the Autoloader which splits up big
modules into smaller subroutine-sized chunks, you'll
say something like this:
h2xs -AX -n Net::Acme
The "-A" omits the Autoloader code, "-X" omits XS ele
ments, and "-n" specifies the name of the module.
Use strict and warnings
A module's code has to be warning and strict-clean,
since you can't guarantee the conditions that it'll be
used under. Besides, you wouldn't want to distribute
code that wasn't warning or strict-clean anyway, right?
Use Carp
The Carp module allows you to present your error mes
sages from the caller's perspective; this gives you a
way to signal a problem with the caller and not your
module. For instance, if you say this:
warn "No hostname given";
the user will see something like this:
No hostname given at /usr/local/lib/perl5/site_perl/5.6.0/Net/Acme.pm
line 123.
which looks like your module is doing something wrong.
Instead, you want to put the blame on the user, and say
this:
No hostname given at bad_code, line 10.
You do this by using Carp and replacing your "warn"s
with "carp"s. If you need to "die", say "croak"
instead. However, keep "warn" and "die" in place for
your sanity checks - where it really is your module at
fault.
Use Exporter - wisely!
"h2xs" provides stubs for Exporter, which gives you a
standard way of exporting symbols and subroutines from
your module into the caller's namespace. For instance,
saying "use Net::Acme qw(&frob)" would import the
"frob" subroutine.
The package variable "@EXPORT" will determine which
symbols will get exported when the caller simply says
"use Net::Acme" - you will hardly ever want to put any
thing in there. "@EXPORT_OK", on the other hand, speci
fies which symbols you're willing to export. If you do
want to export a bunch of symbols, use the
"%EXPORT_TAGS" and define a standard export set - look
at the Exporter manpage for more details.
Use plain old documentation
The work isn't over until the paperwork is done, and
you're going to need to put in some time writing some
documentation for your module. "h2xs" will provide a
stub for you to fill in; if you're not sure about the
format, look at the perlpod manpage for an introduc
tion. Provide a good synopsis of how your module is
used in code, a description, and then notes on the
syntax and function of the individual subroutines or
methods. Use Perl comments for developer notes and POD
for end-user notes.
Write tests
You're encouraged to create self-tests for your module
to ensure it's working as intended on the myriad plat
forms Perl supports; if you upload your module to CPAN,
a host of testers will build your module and send you
the results of the tests. Again, "h2xs" provides a test
framework which you can extend - you should do some
thing more than just checking your module will compile.
Write the README
If you're uploading to CPAN, the automated gremlins
will extract the README file and place that in your
CPAN directory. It'll also appear in the main by-module
and by-category directories if you make it onto the
modules list. It's a good idea to put here what the
module actually does in detail, and the user-visible
changes since the last release.
Step-by-step: Distributing your module
Get a CPAN user ID
Every developer publishing modules on CPAN needs a CPAN
ID. See the instructions at "http://www.cpan.org/mod
ules/04pause.html" (or equivalent on your nearest mir
ror) to find out how to do this.
""perl Makefile.PL; make test; make dist""
Once again, "h2xs" has done all the work for you. It
produces the standard "Makefile.PL" you'll have seen
when you downloaded and installs modules, and this pro
duces a Makefile with a "dist" target.
Once you've ensured that your module passes its own
tests - always a good thing to make sure - you can
"make dist", and the Makefile will hopefully produce
you a nice tarball of your module, ready for upload.
Upload the tarball
The email you got when you received your CPAN ID will
tell you how to log in to PAUSE, the Perl Authors
Upload SErver. From the menus there, you can upload
your module to CPAN.
Announce to the modules list
Once uploaded, it'll sit unnoticed in your author
directory. If you want it connected to the rest of the
CPAN, you'll need to tell the modules list about it.
The best way to do this is to email them a line in the
style of the modules list, like this:
Net::Acme bdpO Interface to Acme Frobnicator servers FOOBAR
^ ^^^^ ^ ^
| |||| Module description Your ID
| ||||
| |||\- Interface: (O)OP, (r)eferences, (h)ybrid, (f)unctions
| |||
| ||\-- Language: (p)ure Perl, C(+)+, (h)ybrid, (C), (o)ther
| ||
Module |\--- Support: (d)eveloper, (m)ailing list, (u)senet, (n)one
Name |
\---- Maturity: (i)dea, (c)onstructions, (a)lpha, (b)eta,
(R)eleased, (M)ature, (S)tandard
plus a description of the module and why you think it
should be included. If you hear nothing back, that
means your module will probably appear on the modules
list at the next update. Don't try subscribing to "mod
ules@perl.org"; it's not another mailing list. Just
have patience.
Announce to clpa
If you have a burning desire to tell the world about
your release, post an announcement to the moderated
"comp.lang.perl.announce" newsgroup.
Fix bugs!
Once you start accumulating users, they'll send you bug
reports. If you're lucky, they'll even send you
patches. Welcome to the joys of maintaining a software
project...
AUTHOR
Simon Cozens, "simon@cpan.org"
SEE ALSO
the perlmod manpage, the perlmodlib manpage, the
perlmodinstall manpage, the h2xs manpage, the strict man
page, the Carp manpage, the Exporter manpage, the perlpod
manpage, the Test manpage, the ExtUtils::MakeMaker man
page, http://www.cpan.org/
2001-03-18 perl v5.6.1 PERLNEWMOD(1)
