لطفا منتظر باشید ...
12.9. Preparing a Module for Distribution
12.9.1. Problem
You want to prepare your
module in standard distribution format so you can easily send your
module to a friend. Better yet, you plan to contribute your module to
CPAN so everyone can use it.
12.9.2. Solution
It's best to start with Perl's standard h2xs
tool. Let's say you want to make a Planets module or an
Astronomy::Orbits module. You'd type:
% h2xs -XA -n Planets
% h2xs -XA -n Astronomy::Orbits
These commands make subdirectories called
./Planets/ and
./Astronomy/Orbits/, respectively, where you
will find all the components you need to get you started. The
-n flag names the module you want to
make, -X suppresses creation of XS
(external subroutine) components, and -A means the module won't use the AutoLoader.
12.9.3. Discussion
Writing modules is easy—once you know how. Writing a proper
module is like filling out a legal contract: it's full of places to
initial, sign, and date exactly right. If you miss any, it's not
valid. Instead of hiring a contract lawyer, you can get a quick start
on writing modules using the h2xs program. This
tool gives you a skeletal module file with the right parts filled in,
and it also gives you the other files needed to correctly install
your module and its documentation or to bundle up for contributing to
CPAN or sending off to a friend.h2xs is something of a misnomer because XS is
Perl's external subroutine interface for linking with C or C ++. But
the h2xs tool is also extremely convenient for
preparing a distribution even when you aren't using the XS
interface.Let's look at the module file that h2xs has
made. Because the module is called Astronomy::Orbits, the user
specifies not use Orbits but
rather use Astronomy::Orbits.
Therefore an extra Astronomy subdirectory is
made, under which an Orbits subdirectory is
placed. Here is the first and perhaps most important line of
Orbit.pm:
package Astronomy::Orbits;
This sets the package—the default prefix—on all global
identifiers (variables, functions, filehandles, etc.) in the file.
Therefore a variable like @ISA is really the
global variable @Astronomy::Orbits::ISA.As we said in the Introduction, you must not make the mistake of
saying package Orbits because
it's in the file Orbits.pm. The
package statement in the module must be exactly
match the target of the use or
require statement, which means the leading
directory portion needs to be there and the characters' case must be
the same. Furthermore, it must be installed in an
Astronomy subdirectory. The
h2xs command will set this all up properly,
including the installation rule in the Makefile. But if you're doing
this by hand, you must keep this in mind. See Recipe 12.1 for that.If you plan to use autoloading, described in Recipe 12.11, omit the -A
flag to h2xs, which produces lines like this:
require Exporter;
require AutoLoader;
@ISA = qw(Exporter AutoLoader);
If your module is bilingual in Perl and C as described in Recipe 12.18, omit the -X flag to h2xs to
produce lines like this:
require Exporter;
require DynaLoader;
@ISA = qw(Exporter DynaLoader);
Following this is the Exporter's variables as explained in Recipe 12.1. If you're writing an object-oriented
module as described in Chapter 13, you probably
won't use the Exporter at all.That's all there is for setup. Now, write your module code. When
you're ready to ship it off, use the make
dist directive from your shell to bundle it all up
into a tar archive for easy distribution. (The name of the
make program may vary from system to system.)
% perl Makefile.PL
% make dist
This will leave you with a file whose name is something like
Astronomy-Orbits-1.03.tar.Z.To register as a CPAN developer, check out http://pause.cpan.org.
12.9.4. See Also
http://www.cpan.org to find a
mirror near you and directions for submission;
h2xs(1); the documentation for the standard
Exporter, AutoLoader, AutoSplit, and ExtUtils::MakeMaker modules,
also found in Chapter 32 of Programming
Perl
