From Deep Thought

From CPAN's "perlnewmod"...

Contents 1 Preparation 1.1 Module::Starter 1.2 Create the directory 2 Creativity 2.1 Create your module 3 Production 3.1 Tweak Makefile.PL 3.2 Tests 3.3 README File 4 Packaging 4.1 Create the Distro 5 Distribute 5.1 PAUSE 6 Links

Preparation

Module::Starter

Make sure Module::Starter is installed on your system. If not...

 cpan -i Module::Starter

Create the directory

Creates the directory and file skeleton for your new module:

    module-starter --module=Foo::Bar \
      --author="Your Name" --email=yourname@cpan.org

Creativity

Create your module

 insert creative coding here including inline perldoc format comments

Production

Tweak Makefile.PL

Edit the Makefile.PL that controls your tests, build information, etc.

A virgin skeleton of Makefile.PL will look something like this:

use strict;
use warnings;
use ExtUtils::MakeMaker;

WriteMakefile(
    NAME                => 'Postgres::Handler::HTML',
    AUTHOR              => 'Cyber Sprocket Labs <info@cybersprocket.com>',
    VERSION_FROM        => 'lib/Postgres/Handler/HTML.pm',
    ABSTRACT_FROM       => 'lib/Postgres/Handler/HTML.pm',
    PL_FILES            => {},
    PREREQ_PM => {
        'Test::More' => 0,
    },
    dist                => { COMPRESS => 'gzip -9f', SUFFIX => 'gz', },
    clean               => { FILES => 'Postgres-Handler-HTML-*' },
);

Tests

You're encouraged to create self-tests for your module to ensure it's working as intended on the myriad platforms 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, module-starter and h2xs provide a test framework which you can extend - you should do something more than just checking your module will compile. Test::Simple and Test::More are good places to start when writing a test suite.

README File

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.

Packaging

Create the Distro

perl Makefile.PL; make test; make dist

Once again, module-starter or h2xs has done all the work for you. They produce the standard Makefile.PL you see when you download and install modules, and this produces 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.

Distribute

PAUSE

PAUSE is the official Perl package sharing site. Once you have your PAUSE account you can upload the file there.

At Cyber Sprocket we prefer to keep the final packaged tarzip file linked to our public web server and tell PAUSE to go fetch the distribution there. Our repos are at http://www.cybersprocket.com/cpandistros/<package-dir>/<tarzip name>.

Links

• CPAN Outline For Creating A New Module
• CPAN Makefile.PL Details
• CPAN Test::More Details
• PAUSE, Perl Author's Upload Server