How to build your own perl module distribution

I enjoy every time I have the chance of programming in Perl, since it's a language that adapts to my needs very easily. Sometimes I want to create a module to reuse the functionality that repeats over and over in my Perl scripts. Still, until not long ago, I have never known how to configure my Perl modules to build and install them easily in my computers.

Recently I have finished reading the O'Reilly book Intermediate Perl, which contains a specific chapter on how to build your modules to distribute them and another one on how to publish your package in CPAN. I want to summarize here what I have learned in order both to have my own notes and don't forget about it and to share my experience with you.

The first thing to do when you want to build your own Perl module distribution is to initialize the first module you want to develop. For that, you can use module-starter, which is a simple starter kit for any module. To install it CPAN is your friend:
cpan -i Module::Starter
cpan -i Module::Starter::AddModule
cpan -i Module::Build


Once installed you can use the command module-starter to create the basic structure of the module:
module-starter --mb --module="ModuleName"


This command creates a new subdirectory called ModuleName with the basic structure of the module, including the t directory for tests, the lib directory with the module file ModuleName.pm, the Perl script Build.PL with configurations to generate the module distribution (something like a Makefile) and the script Build to generate the module distribution. To build the module itself, you usually use the following commands are:
Perl Build.PL
./Build
./Build test
./Build disttest
./Build dist
./Build install


The first command, perl Build.PL, is going to update the Build script when any configuration changes (if you add a new module or change the version number, for example). After the Build script is updated, you can use it to build the module, test it, run the tests for the distribution package, generate a distribution package or install it in your system.

The module generated with module-starter has the default structure for any Perl module, including the perldoc documentation section, the code that the module includes and the end of the module itself, so it's ready for you to add the code and put the proper documentation.

If you want to add a new module to the distribution, you can add it with the next command:
module-starter --module="ModuleName2" --dist=.


As you see, the command is pretty similar to the first one used to generate the distribution, but with a new argument, --dist=., which indicates that the module is going to be added to the distribution located in the current directory. If you want to see more documentation on the building process, you can check the module::Build documentation, including the configuration options for Build.PL.

Once you are happy with your distribution, you can publish it to CPAN, which is the subject for a next blog entry.

Happy Hacking!