perltutorial
cog
<ul>
<li><a href="#name">NAME</a></li>
<li><a href="#synopsis">SYNOPSIS</a></li>
<li><a href="#description">DESCRIPTION</a></li>
<ul>
<li><a href="#before_you_start">Before you start</a></li>
<li><a href="#picking_a_good">Picking a good name for your module</a></li>
<li><a href="#start_your_module">Start your module</a></li>
<li><a href="#h2xs">h2xs</a></li>
<li><a href="#module-starter">module-starter</a></li>
<li><a href="#extutils">ExtUtils::ModuleMaker</a></li>
</ul>
<li><a href="#step_by_step">Step by step: what to do</a></li>
<ul>
<li><a href="#document_first">Document first</a></li>
<li><a href="#create_tests">Create tests</a></li>
<li><a href="#use_strict">Use strict</a></li>
<li><a href="#use_warnings">Use warnings</a></li>
<li><a href="#exports">Exports</a></li>
<ul>
<li><a href="#how_it_works">How it works</a></li>
<li><a href="#what_to_export">What to export</a></li>
</ul>
<li><a href="#inside_your_distribution">Inside your distribution</a></li>
<ul>
<li><a href="#keep_the_changes">Keep the Changes up to date</a></li>
<li><a href="#don_t_forget_the_readme">Don't forget the README</a></li>
<li><a href="#the_manifest">The MANIFEST</a></li>
<li><a href="#makefile_pl">Makefile.PL</a></li>
<li><a href="#version_numbers">Version numbers</a></li>
</ul>
<li><a href="#almost_done">Almost done</a></li>
<ul>
<li><a href="#test_it_yourself">Test it yourself</a></li>
</ul>
<li><a href="#before_uploading">Before uploading</a></li>
<li><a href="#uploading">Uploading</a></li>
</ul>
<li><a href="#other_good_practices">Other good practices</a></li>
<ul>
<li><a href="#release_early_release_often">Release early, release often</a></li>
<li><a href="#good_style">Good style</a></li>
<li><a href="#source_control">Source control</a></li>
<li><a href="#me_got_kwalitee">Me got Kwalitee</a></li>
<li><a href="#other_things_you_should_know">Other things you should know</a></li>
<ul>
<li><a href="#cpan_testers">CPAN Testers</a></li>
<li><a href="#registering_modules">Registering modules</a></li>
</ul>
</ul>
<li><a href="#so_i_have_a_module">So I have a module. Now what?</a></li>
<li><a href="#final_words">Final words</a></li>
<li><a href="#see_also">SEE ALSO</a></li>
<ul>
<li><a href="#books">Books</a></li>
<li><a href="#links">Links</a></li>
<li><a href="#modules">Modules</a></li>
<li><a href="#documentation">Documentation</a></li>
</ul>
<li><a href="#acknowledgements">ACKNOWLEDGEMENTS</a></li>
<li><a href="#author">AUTHOR</a></li>
<li><a href="#copyright">COPYRIGHT</a></li>
</ul>
<hr>
<h3><a name="name">NAME</h3>
José's Guide for creating Perl modules
<h3><a name="synopsis">SYNOPSIS</h3>
Follow this guide to create good Perl distributions
<h3><a name="description">DESCRIPTION</h3>
From time to time, someone with little experience comes to me and
asks: "I'd like to create a module. What do I do?"
<p>In order to answer that question to as many people as possible at the
same time, I decided to write this guide.
<h4><a name="before_you_start">Before you start</h4>
Before creating a module, use <a href="http://search.cpan.org">CPAN Search</a> to
see if it already exists. If you don't find it at first, search for it
under different names; search for its functionality, rather than the
name you'd be giving it.
<p>You should do this exhaustively so you don't waste your time
duplicating effort.
<p>If your search on CPAN doesn't satisfy you, you can also search
Google. A lot of times, the right keywords are in the messages people
post about the module but not in the documentation.
<p>Just because a namespace exists doesn't mean you should abandon your
module. See if it is any good, if it has everything you'd like it to
have, and if it's being maintained. A good alternative is to contact
the author and ask him what he thinks about it. Maybe he'll give you
the namespace or you can also submit patches for the existing module.
<p>If you need help with any of this, you can ask the PAUSE admins at
<a href="http://lists.perl.org/showlist.cgi?name=modules">modules@perl.org</a>.
They will gladly help you with that, and sometimes they even have
different means to contact the person.
<h4><a name="picking a good">Picking a good name for your module</h4>
A module needs a good name that's intuitive, something that people
search for, and describes the functionality it provides.
<p>If you're having trouble deciding on a name for your module, send an
e-mail to
<a href="http://lists.perl.org/showlist.cgi?name=module-authors">module-authors@perl.org</a>
and
<a href="http://lists.perl.org/showlist.cgi?name=modules">modules@perl.org</a>.
The readers can help you figure out a good
name.
<p>If you have a name you're not sure about, keep that name in your mind
for a couple of days. If you don't think of anything better, it's
probably a good name. If the name is really bad, you'll probably think
of another one during this time.
<h4><a name="start_your_module">Start your module</h4>
Sure, you can create your *.pm file, but don't forget the Makefile.PL,
decent tests and the MANIFEST, along with META.yml and... wait a
minute, you're not actually thinking of doing this all by yourself,
are you?
<p>As with several other tasks that people do on a daily basis, starting
a module from scratch is a task that has been automated... several
times! This means you have a range of module creation tools to help you.
<h4><a name="h2xs">h2xs</h4>
A simple execution of h2xs is enough to create a module; here's an
example:
<p><code> h2xs -XAn My::New::Module</code>
<p>The resulting structure is something like this (depending on your
version of h2xs).
<p><code> .
`-- My-New-Module
|-- Changes
|-- MANIFEST
|-- Makefile.PL
|-- README
|-- lib
| `-- My
| `-- New
| `-- Module.pm
`-- t
`-- My-New-Module.t</code>
<p>You're left with a directory with the name of your module, containing
a Changes, MANIFEST, Makefile.PL, README, lib/ directory for your
modules and a t/ directory for your tests. Not bad...
<p>Without the -b switch, h2xs assumes your module requires your current
version of Perl. If your module doesn't have any particular needs for
that version, change that! I have been a victim of this in the past,
with people sending me e-mails saying "Hey, your module requires Perl
5.8.4, but it would run in 5.6.0. Could you please change that?" Save
yourselves that trouble and check that.
<h4><a name="module-starter">module-starter</h4>
The module-starter script from [cpan://Module::Starter] asks for a few more
parameters to start with. Here's an example:
<p><code> module-starter --module=My::New::Module --author="Me, Myself" \
--email=myself@cpan.org</code>
<p>Here's the resulting structure from this:
<p><code> `-- My-New-Module
|-- Changes
|-- MANIFEST
|-- Makefile.PL
|-- README
|-- lib
| `-- My
| `-- New
| `-- Module.pm
`-- t
|-- 00.load.t
|-- pod-coverage.t
`-- pod.t</code>
<p>Looks pretty much the same as the result of h2xs, right? But don't let
that fool you! Apart from the new files that test your POD
documentation, the contents of those files are different from the ones
generated with h2xs. Give a try to both systems and check out the
differences.
<p>Currently, I use module-starter to start my own modules.
<h4><a name="extutils">ExtUtils::ModuleMaker</h4>
[cpan://ExtUtils::ModuleMaker] is another tool for creating modules. Using the
command <code>modulemaker</code> you are taken throught a menu. The resulting
structure would be something like this:
<p><code> `-- My
`-- New
`-- Module
|-- Changes
|-- LICENSE
|-- MANIFEST
|-- Makefile.PL
|-- README
|-- Todo
|-- lib
| `-- My
| `-- New
| `-- Module.pm
|-- scripts
`-- t
`-- 001_load.t</code>
<p>You can see some resemblances to the two other systems, right? Notice
the Todo and LICENSE files, as well as the scripts directory.
<h3><a name="step_by_step">Step by step: what to do</h3>
<h4><a name="document_first">Document first</h4>
Now that you've created the skeleton of your module, you should
move on to its guts, to its code, right?
<p><b>Wrong!</b>
<p>My personal opinion is that you should always start by thinking about
what you're doing. This will save time in the long run.
<p>Start with the documentation. My experience tells me that coding gets much
easier after you've documented every single one of your functions.
<p>Before actually coding, write down the description of what every
function in the module should do. This gives you a chance to figure
out what you are doing.
<p>I usually keep a list of modules I'd like to create. Rather than
create them when I think about them, I take notes on them
from time to time. When the right time comes, I use that list and
pick one of the modules with the most notes. Then, I write the
documentation.
<h4><a name="create_tests">Create tests</h4>
Make tests <i>before</i> your code. I usually make mine at the same time
I'm coding. I code a function, write its tests and test it.
<p>Tests find things your eye wouldn't catch. As your module evolves,
things you left behind can suddenly break. Tests will warn you about
them. You should test as much as you can. No test is a test too many.
<p>Test for basic cases, but you should also test the extreme ones. Don't
forget to test your functions with and without parameters, and even
with parameters in excess, or wrong ones. You should know what those
functions return in each of those cases.
<p>You should also test your documentation, but module-starter will
automatically create those tests for that, using [cpan://Test::Pod::Coverage]
and [cpan://Test::Pod].
<h4><a name="use_strict">Use strict</h4>
Use strict! "Strictures" can warn you about things that otherwise
you'd be unaware of, like uninitialized variables and so on. Just
put it at the top of all of your code files.
<p><code> use strict;</code>
<h4><a name="use_warnings">Use warnings</h4>
Warnings are good for your code and your sanity.
<p><code> use warnings;</code>
<p>Use <code>warnings</code> and <code>strict</code> at the very beginning of
scripts or modules.
<p>But there is a downside to using warnings, though: they're
not backwards compatible! If your code uses warnings, it
won't work with versions of Perl prior to 5.6. You can,
however, use warnings while developing and remove them when
releasing.
<p>The latest version of [cpan://Test::Harness] turns on warnings while
you test, so you might as well make your code warning free.
<h4><a name="exports">Exports</h4>
<h5><a name="how_it_works">How it works</h5>
When you have a module, you probably have functions. When a user uses
your module, he has to import your functions into his program.
<p>You're the one who chooses what he's able to import (that is, you can
choose not to let a particular function be imported) and how.
<p>Here's an example, to make things easier:
<p><code> require Exporter;
our @ISA = qw(Exporter);
our %EXPORT_TAGS = (
'all' => [ qw(
function_make
function_remove
activate_all
deactivate_all
) ],
'action' => [ qw(
function_make
function_remove
) ],
'manipulation' => [ qw(
activate_all
deactivate_all
) ],
);
our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
our @EXPORT = qw(
function1
);</code>
<p>Here's a brief explanation of what is going on in that code:
<p>The last instruction (yes, we're starting by the end) states that
whoever uses the module will always get <code>function1</code>. The user gets
everything in the @EXPORT array automatically.
<p>The %EXPORT_TAGS hash is kind of an 'alias maker'. In the example, the
tag <code>action</code> is mapped into <code>function_make</code> and
<code>function_remove</code>,
<code>manipulation</code> is mapped into <code>activate_all</code> and
<code>deactivate_all</code>,
and <code>all</code> is mapped in the four functions. When using a module like
this:
<p><code> use The::Module qw/:action/;</code>
<p>The current package is importing <code>function_make</code> and
<code>function_remove</code>.
<p>The @EXPORT_OK is also very important. Things that are not in the
@EXPORT variable can only be imported if they are included in
@EXPORT_OK.
<p>In this particular example, it's OK to import any of the four
functions comprised in the <code>all</code> tag. This means one can do something
like this:
<p><code> use The::Module qw/:action activate_all/;</code>
<p>He will get <code>function_make</code>,
<code>function_remove</code>, <code>activate_all</code> and
<code>function1</code> loaded in his package.
<h5><a name="what_to_export">What to export</h5>
So now that you have a couple of functions / methods implemented, you
should think on what to export...
<p>If your module is purely object oriented, then you probably won't
export anything.
<p>However, if you have functions, you might feel a sudden urge to export
some of them.
<p>Don't!!!
<p>Do not export functions just because. Instead, make them available to
be exported, but let the user select what he wants to use (but don't
forget to document the possibilities, of course).
<p>Plus, people HATE changes in the API, so think deeply about it. By not
exporting anything, your API will remain the same when you add new
functionalities to your module.
<p>So, instead of adding those functions to @EXPORT, try adding them to
@EXPORT_OK.
<h4><a name="inside_your_distribution">Inside your distribution</h4>
<h5><a name="keep_the_changes">Keep the Changes up to date</h5>
The Changes file is there for a reason, right? Keep it up to date! It
will help users know what you have changed (and therefore choosing
whether to download and install the new version or not); it will help
you in case something gets broken from one version to the next one
(because you'll know what you have changed); plus, you (and everybody
else, for that matter) will be able to keep track of your work.
<h5><a name="don_t_forget_the_readme">Don't forget the README</h5>
The README file is really important. Not everybody reads it, but they
should. That's why it is named README; because you're supposed to READ
IT!
<p>Anyway, browsing a module on the CPAN, people will often look at the
README, and if it isn't much, they will very likely take that as a
sign that your module isn't really finished.
<p>Both h2xs and module-starter create a standard README file, which you
should change and add sections to as you feel the necessity for. I
usually copy the POD documentation of my main module to it.
<h5><a name="the_manifest">The MANIFEST</h5>
The MANIFEST file contains the list of all files to include in the
distribution (and only those get into it).
<p>Whenever you add an extra file, don't forget to include it on the
MANIFEST file, or your distribution will be incomplete (and,
probably, broken).
<h5><a name="makefile_pl">Makefile.PL</h5>
There is a file called Makefile.PL. By looking at it, you might think
that you actually don't need to do anything to it; and that might be
true, most of the times.
<p>If you used h2xs, you should check its parameters. Otherwise, you
should be fine.
<p>However, there is one situation when you absolutely should update
Makefile.PL: when you use other modules. That is, when your module has
dependencies.
<p>Just go there and add something like this:
<p><code> PREREQ_PM => {
'Another::Module' => 0.01,
},</code>
<p>That, for instance, states that your module depends on the existence
of at least version 0.01 of Another::Module.
<p>This makes life easier for everybody. The user who's downloading and
installing your module automatically doesn't have to spend time
figuring out the dependencies, for instance; and CPANPLUS will test
your module correctly (hopefully).
<p>When testing, [cpan://Test::Prereq] might be a good option to check whether
there are any modules you should add to PREREQ_PM (see section "Make
tests", down below).
<h5><a name="version_numbers">Version numbers</h5>
Whenever you release a new version, change the version number in your
module... and in the README... and be sure to include it in the
Changes file too. It's really depressing when you upload a module and
afterwards notice you got the version number wrong... (and it's even
more depressing when you release the module again to get rid of that
annoyance and you do it again).
<p>Do not go from version 0.01 to 1.00 and then to 2.00, because that
really looks bad and you'll be in version 20.00 in no time. Instead,
go from 0.01 to 0.02, and from there to 0.03, and so on.
<p>Also, there isn't really the necessity of going to 1.00 just from
0.99; people often change the integer part of the version (if one may
call it the integer part, given that it is usually a string) when they
do major changes in the design of the system, not when they run out of
numbers.
<p>Versions which are still being implemented usually have the current
version number with an underscore and a number, like 0.04_01 and are
called "developer releases"; the underscore makes it clear that the
distribution is not yet ready for the general public. You should
follow that practice. You can even upload a developer's release to the
CPAN. When people look at your module they will see that version, with
a red sign stating it's a developer's release and a link to the last
ready-to-take version.
<h4><a name="almost_done">Almost done</h4>
<h5><a name="test_it_yourself">Test it yourself</h5>
Before uploading your module, you should test it yourself. Use this to
make your distribution:
<p><code> make dist</code>
<p>Suppose you had forgotten about including something in the MANIFEST,
for instance. Just because your module passed all your tests in your
specific directory doesn't mean it's working.
<p><code> make disttest</code>
<p>That should do it.
<h4><a name="before_uploading">Before uploading</h4>
Check your distribution before you upload it.
<ul>
<li>Are the tests OK? Are they enough? Do they cover everything? Did I test after I last changed something?</li>
<li>Did I get the version number right in three different places?</li>
<li>Did I change the default documentation both on the module and on the README?</li>
<li>Are all files in the MANIFEST?</li>
<li>Did I include all the dependencies in Makefile.PL?</li>
</ul>
<h4><a name="uploading">Uploading</h4>
The <a href="http://pause.perl.org">PAUSE</a> is the Perl's Authors Uploading Server. In order
to upload something to the CPAN, you need a PAUSE account.
Get an account at <a href="http://pause.perl.org">PAUSE</a>.
<p>If you don't like the PAUSE web interface or you want to
automate it, or find it boring or whatever, you can take a
look at <code>release</code> and [cpan://Module::Release], which are tools
that automatically upload files to the CPAN and
SourceForge.net.
<h3><a name="other_good_practices">Other good practices</h3>
<h4><a name="release_early_release_often">Release early, release often</h4>
You don't have to wait until your module is completed to release it.
"Release early, release often!" You'll be more
motivated to do your work, people will be able to track your
progress and might even give you some very important feedback on it.
<h4><a name="good_style">Good style</h4>
In the CPAN, good coding style might be the difference
between you receiving patches or not, or even between people
actually using your modules or not (because some programmers
are too suspicious and feel the urge to understand every
little piece of code they use).
<p>Read <code>perlstyle</code> and Perl::Tidy which show very good
ways to tidy up your Perl code.
<h4><a name="source_control">Source control</h4>
Keep your code under a source control system, such as CVS,
Subversion, or Perforce. You get backups, version control
and lots of other advantages. Others who want to help can also
access it if you make it public.
<h4><a name="me_got_kwalitee">Me got Kwalitee</h4>
The Kwalitee of your modules is not really Quality, but as
close as possible as an automatic Quality-measurer can be.
<p>The Kwalitee project examines distributions on the CPAN for
good Perl coding practices, such as the use of strict,
existence of tests, and so on. It assigns a score to each
distribution, and therefore an average mean to the authors.
<p>Strive for a high Kwalitee score is good for you, your
modules, and its users. The higher Kwalitee you get, the
bigger your ego becomes, and people consider your modules to
be higher quality.
<h4><a name="other_things_you_should_know">Other things you should know</h4>
<h5><a name="cpan_testers">CPAN Testers</h5>
One of the best things about the CPAN is that your releases are
actually tested by other people.
<p>As a module author, you don't have to bother about it; you simply
upload your modules to the CPAN and wait to see if anything happens.
<p>If your module's tests fail somewhere, you'll receive a report
(actually, you're likely to receive quite a few, given that your
module will probably fail on other systems too).
<p>Don't take it too hard if you receive an email with a subject starting
with "FAIL Your::Module". It's nothing personal! You screwed up, but
it's no big deal, because thanks to the CPAN Testers you are now
informed of the problem and you can easily (hopefully) correct it and
release a new version.
<p>There, no harm done.
<h5><a name="registering_modules">Registering modules</h5>
Another thing you can do is to register the namespace of
your module.
<p>To do that, go to your PAUSE account and use the "Register
namespace" option, which is pretty simple to use. You'll
have to elaborate on how and why is your module
important, but it's not that difficult, really.
<p>When people look at your home node on CPAN Search
(http://search.cpan.org/~yourusername), they will see all
your modules and a list of the registered ones, along with
some information on those.
<p>A registered module was approved by PAUSE admins.
Therefore, it's not simply a product of some delusional
visionist with headaches and is probably something good,
unless, of course, some PAUSE admin that day was a
delusional visionist and had an headache.
<h3><a name="so_i_have_a_module">So I have a module. Now what?</h3>
If you're thinking "Time for another one", hold your horses there,
pal! Creating module after module really isn't that hard; the hard
thing is to maintain them all and keep them useful. Loads of modules
on their 0.01 versions that really don't do much and do have a list of
"promises" don't do anyone much good, do they? Keep
in mind that you should take all your modules to a stable version of
them.
<p>There's nothing wrong in having a bunch of modules you haven't
completed yet, but there <b>is</b> something wrong in having a bunch of
modules you will <b>never</b> complete.
<h3><a name="final_words">Final words</h3>
That said, I hope you now know a bit more than when you started
reading this document, and I hope it helps the Kwalitee... er...
Quality of the CPAN modules around.
<p>If you still have doubts (or maybe even more than when you started),
there are lots of people willing to help (and of course I'm one of
them).
<p>Check out the
<a href="http://lists.perl.org/showlist.cgi?name=modules">modules@perl.org</a> mailing list.
<p>For anything else, I'm cog at cpan dot org.
<h3><a name="see_also">SEE ALSO</h3>
<h4><a name="books">Books</h4>
<ul>
<li><a href="http://apress.com/book/bookDisplay.html?bID=14">Writing Perl Modules for CPAN, by Sam Tregar</a></li>
</ul>
<h4><a name="links">Links</h4>
<ul>
<li><a href="http://langworth.com/PerlTestCard">Perl Testing Reference Card</a></li>
<li><a href="http://www.steve.gb.com/perl/lesson08.html">Perl tutorial Lesson 8</a></li>
<li><a href="http://cpants.dev.zsi.at/">Kwalitee</a></li>
<li><a href="http://domm.zsi.at/talks/cpants/">CPAN Testing Service (CPANTS)</a></li>
<li><a href="http://magnonel.guild.net/~schwern/talks/CPANTS/full_slides/">http://magnonel.guild.net/~schwern/talks/CPANTS/full_slides/</a></li>
<li><a href="http://lists.perl.org/showlist.cgi?name=module-authors">Perl module author's mailing list, module-authors@perl.org</a></li>
<li><a href="http://lists.perl.org/showlist.cgi?name=modules">Perl authors upload server (PAUSE) mailing list, modules@perl.org</a></li>
</ul>
<h4><a name="modules">Modules</h4>
<ul>
<li>[cpan://Exporter]</li>
<li>[cpan://ExtUtils::ModuleMaker]</li>
<li>[cpan://Module::Release]</li>
<li>[cpan://Module::Starter]</li>
<li>[cpan://Perl::Tidy]</li>
<li>[cpan://Test::More]</li>
<li>[cpan://Test::Prereq]</li>
</ul>
<h4><a name="documentation">Documentation</h4>
<ul>
<li>[doc://perlmodlib]</li>
<li>[doc://perlmodstyle]</li>
<li>[doc://perlnewmod]</li>
<li>[doc://perlstyle]</li>
</ul>
<h3><a name="acknowledgements">ACKNOWLEDGEMENTS</h3>
This guide was loosely based on [id://376075] (which you should read, too).
<p><a href="http://alfarrabio.di.uminho.pt/~albie/">Alberto Simões</a> and <a href="http://www.panix.com/~comdog/">brian d foy</a> made really good suggestions for sections to add to this document, as well as some changes to the existing ones.
<h3><a name="author">AUTHOR</h3>
José Castro, cog at cpan dot org
<h3><a name="copyright">COPYRIGHT</h3>
Copyright 2004, José Castro, Creative Commons license.