[ 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
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
-n Acme::Example switch specifies our module name. This is used in
generating the directory (
Acme-Example), skeleton code, and is used in
-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
-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
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.
Changesfile 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.PLis 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.
Makefile.PL files generated by
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
MANIFESTfile 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.
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
.zip file rather than a
READMEfile 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
READMEfile 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/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
lib/directory houses your code. In our example, we would find the
/lib/Acme/Example.pmfile 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
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:
|Phone:||03 9354 6001 (Australia)|
|International:||+61 3 9354 6001|
Copyright Perl Training Australia. Contact us at firstname.lastname@example.org