Starting modules with h2xs

[ Perl tips index ]
[ Subscribe to Perl tips ]

Using h2xs to start your modules is deprecated. Use something like Module::Starter instead.

Bundling code into modules can make your project easier to test, develop, and maintain. However while many developers are familiar with the concept and requirements of a module, not everyone is sure of the best way to lay these out on the filesystem.

If your business or project does not already have existing guidelines for module development, then you may wish to consider starting with Perl's h2xs command.

The original use of h2xs was building Perl extensions form C header files, and it is still used extensively for this purpose. However h2xs can also be used to provide the skeleton for ordinary Perl modules, and we will investigate that in today's perl-tip.

The easiest way to start a pure Perl module with h2xs is with the command:

        h2xs -XA -n Acme::Example

The -n Acme::Example switch specifies our module name. This is used in generating the directory (Acme-Example), skeleton code, and is used in generating the Makefile.PL.

The -XA switches simply omit the sections that would have been used if we were building our module on the top of existing C header files. As a pure Perl module, these are simply going to get in the way.

By default, h2xs will use the latest and greatest Perl features when creating our code skeleton. If we want to ensure backwards compatibility, we can do so using the -b switch. In the example below we ensure that our code will still work under Perl 5.6.0, which is still seen in many environments:

        h2xs -b 5.6.0 -XA -n Acme::Example

Files inside a module distribution

After running h2xs, a number of files will exist in our distribution. These are skeleton files, and are intended to be checked and edited by the developer.

Changes
The Changes file exists to track changes to the module. This is not a required file for a module distribution, but it is recommended. For CPAN and other distributed modules it can help developers make more informed choices about upgrading; for internally used modules it can be used to track major feature changes and releases.
Makefile.PL
The Makefile.PL is used to generate a makefile for building, testing, and installing your module. It can be used to check that the correct version of Perl and supporting modules are installed, as well as doing any special work required to ensure your module is built correctly.

The Makefile.PL files generated by h2xs use ExtUtils::MakeMaker to generate the final makefiles. You can use perldoc ExtUtils::MakeMaker to learn more about the options that can be passed to this module.

To build, test, and install your module, use:

        perl Makefile.PL
        make
        make test
        make install
MANIFEST
The MANIFEST file contains a list of all files that should be contained in your module distribution. This is used when building an archive for distribution, and also by clients and automated tools to ensure the distribution is intact.

The MANIFEST file allows for additional notes, tests, directories, design documents, and other files to live in your development environment, without the requirement that these included in the final distribution.

You should ensure that your MANIFEST file lists all the files essential for your distribution, including both Perl modules, tests, and special files such as Makefile.PL. You can check to see which files are missing from your MANIFEST by using:

        perl Makefile.PL
        make distcheck

Likewise, if you wish to automatically update your manifest to include all new files found in your distribution, you can do so with:

        perl Makefile.PL
        make manifest

To actually build a distribution from your module, use:

        perl Makefile.PL
        make tardist

It's highly recommended that you ensure that the generated file (in the form Acme-Example-0.01.tar.gz) can be used to correctly build and install your module before you distribute it. There is also a make zipdist command to build a .zip file rather than a .tar.gz file.

README
The README file contains a short description of the module, and any information that should be known to developers before installing it. It is not required for your module to work correctly, but is often considered useful. The README file is considered special as it is unpacked and displayed by CPAN and other archives; it can be read by developers without downloading or examining the rest of the module.
t/
The t/ directory contains tests for your module. A good module has plenty of tests try and ensure the code is working correctly, and to catch any bugs before they reach production. You can learn more about testing by reading perldoc Test::Tutorial.
lib/
The lib/ directory houses your code. In our example, we would find the /lib/Acme/Example.pm file already created and with sample code and documentation in-place. If our distribution will contain many modules, they should also be added under the lib/ directory, and we should also ensure they are added to the MANIFEST file above.

When creating any new module, it's highly recommended that you also use a revision control system, such as CVS or subversion. The use of a revision control system is recommended for all development work, not just Perl modules, and is an important part of the change management process.

[ Perl tips index ]
[ Subscribe to Perl tips ]


This Perl tip and associated text is copyright Perl Training Australia. You may freely distribute this text so long as it is distributed in full with this Copyright noticed attached.

If you have any questions please don't hesitate to contact us:

Email: contact@perltraining.com.au
Phone: 03 9354 6001 (Australia)
International: +61 3 9354 6001

Valid XHTML 1.0 Valid CSS