13.2 Looking at the Templates

You'll create some subdirectories below the current directory and a bunch of files in the lowest of those directories. Let's look at them to see what they are. First, cd into the directory:

$ cd Island/Plotting/Maps

Now, let's examine the MANIFEST file:

$ cat MANIFEST
Changes
Makefile.PL
MANIFEST
Maps.pm
README
t/1.t

The MANIFEST file resembles a table of contents for the distribution. When you eventually bundle up everything and ship it off to the CPAN or the ultimate recipient, the bundling tool looks at MANIFEST to know what to include, and the unpacking tool verifies that everything in MANIFEST is present at the destination. Of course, MANIFEST lists MANIFEST, but it also lists everything else created by h2xs automatically.

While maintaining a MANIFEST sounds like it might be painful, you can be assured that you won't accidentally include your "notes to self" in the distribution just because the file happened to be in the wrong directory. Specific steps discussed later keep the MANIFEST up to date.

The next, mostly uninteresting, file is README, which is self-describing:

$ cat README
Island/Plotting/Maps version 0.01
=  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==  ==

The README is used to introduce the module and provide instructions on
how to install the module, any machine dependencies it may have (for
example C compilers and installed libraries) and any other information
that should be provided before the module is installed.

A README file is required for CPAN modules since CPAN extracts the
README file from a module distribution so that people browsing the
archive can use it get an idea of the modules uses. It is usually a
good idea to provide version information here so that people can
decide whether fixes for the module are worth downloading.

INSTALLATION

To install this module type the following:

   perl Makefile.PL
   make
   make test
   make install

DEPENDENCIES

This module requires these other modules and libraries:

  blah blah blah

COPYRIGHT AND LICENCE

Put the correct copyright and licence information here.

Copyright (C) 2002 Ginger Grant

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

Obviously, you will want to edit this file to be whatever you want it to be. The phrase "blah blah blah" is often used in the templates to indicate things that must be changed.^[4] If you leave unchanged the blah blah blah and other notes from h2xs to you, potential users will suspect that bugs in the code have also escaped your scrutiny, so proofread this stuff (and your code) before you distribute your module.

^[4] When you're bored, you might find it amusing to do a search of the current CPAN for all places in which blah blah blah occurs.

Pay special attention to the copyright and license section. (It should have your name in place of Ginger's name, unless your machine is very confused about who is sitting at the keyboard.) Your employer may require you to change the copyright notice to include your company name rather than your name, for example. Or, if you're including someone else's code in your module, you may need to mention their copyright (or lack thereof) as well.

The README file also has a special responsibility: the master CPAN archiving tools pull out the README file as a separate entry automatically, permitting the file to be indexed by search engines on the various worldwide archives, and to be downloaded and read trivially by the CPAN installation tools. In the CPAN.pm shell, for example, you can say:^[5]

^[5] Well, you would be able to do this, if there were actually a module on CPAN named Island::Plotting::Maps.

$ perl -MCPAN -eshell
cpan> readme Island::Plotting::Maps

and the contents of the README file will be shown without having to download and unpack the entire distribution.

Another file created as a template is Changes:

$ cat Changes
Revision history for Perl extension Island::Plotting::Maps.

0.01  Wed Oct 16 15:53:23 2002
        - original version; created by h2xs 1.22 with options
                -XAn Island::Plotting::Maps

You'll need to maintain this file manually, unless your interactive development environment has automated tools for such maintenance. Most people will expect to be able to look here to see what has been updated in new releases of your module. Try not to disappoint them. One of the main purposes of the Changes file is debugging: if you realize that a certain bug turned up three releases back, you can look here to remind yourself of new features or bug fixes that were introduced in that release.