Learning Perl Objects, References amp;amp; Modules [Electronic resources] نسخه متنی

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.