Perl Cookbook

Preparing a Module for Distribution

Problem

You want to prepare your module in standard distribution format so you can easily send your module to a friend. Better yet, you plan to contribute your module to CPAN so everyone can use it.

Solution

It’s best to start with Perl’s standard h2xs tool. Let’s say you want to make a Planets module or an Astronomy::Orbits module. You’d type:

% h2xs -XA -n Planets
% h2xs -XA -n Astronomy::Orbits

These commands make subdirectories called . /Planets/ and . /Astronomy/Orbits/ respectively, where you will find all the components you need to get you started. The -n flag names the module you want to make, -X suppresses creation of XS (external subroutine) components, and -A means the module won’t use the AutoLoader.

Discussion

Writing modules is easy—once you know how. Writing a proper module is like filling out a legal contract: it’s full of places to initial, sign, and date exactly right. If you miss any, it’s not valid. Instead of hiring a contract lawyer, you can get a quick start on writing modules using the h2xs program. This tool gives you a skeletal module file with all the right parts filled in, and it also gives you the other files needed to correctly install your module and its documentation or to bundle it up for inclusion in CPAN or sending off to a friend.

h2xs is something of a misnomer because XS is Perl’s external subroutine interface for linking with C or C ++. But the h2xs tool is also extremely convenient for preparing a distribution ...