 |  |
Chapter 13. Writing a Distribution
Contents:
Starting with h2xs
Looking at the Templates
The Prototype Module Itself
Embedded Documentation
Controlling the Distribution with Makefile.PL
Alternate Installation Locations (PREFIX=...)
Trivial make test
Trivial make install
Trivial make dist
Using the Alternate Library Location
Exercise
In Chapter 12, you created a fictional Island::Plotting::Maps module, and built the right support for Exporter so that you could include use Island::Plotting::Maps in a program.
While the resulting .pm file is useful, it's not very practical. There's a lot more to building a real module than just creating the .pm file. You'll also need to consider and implement the following questions:
- Installation location
- How and where is the .pm file installed so a program can find the module in its @INC path?
- Documentation
- Where is the documentation for the module? How is the documentation installed so the user can read it?
- Archive completeness
- If there are any accompanying files, where are they? How can the end user know if any missing files are missing?
- Testing
- What test harnesses can the developer run to verify correct operation, including testing against older known bugs? Can these same tests be run by the installer to ensure proper operation in the target environment?
- C-language interfaces
- If the module contains C or C++ code (not covered here), how can the developer describe how to compile and link the code in the developer's environment, or the end user environment?
As Roy Scheider uttered in the movie Jaws: "You're gonna need a bigger boat." That "bigger boat" is the difference between a module and a distribution.
13.1. Starting with h2xs
A distribution contains the module (or collection of related modules), plus all the support files required to document, test, ship, and install the module. While you could potentially construct all these files by hand, it's much simpler to use a tool that comes with Perl, awkwardly called h2xs[76]
[76]The name h2xs has an interesting pedigree. Back in the early days of Perl 5, Larry invented the XS language to describe the glue code that Perl needs to talk to C-language functions and libraries. Originally, this code was written entirely by hand, but the h2xs tool was written to scan simple C-include header files (ending in .h) and generate most of the XS directly. Hence, h "2" (to) XS. Over time, more functions were added, including generating template files for the rest of the distribution. Now here we are, about to describe how to use h2xs for things that aren't either h or xs. Amazing.
The h2xs tool creates a series of template files that serve as a starting point for the distribution files. You simply need to say h2xs -XAn, followed by the name of the module—in this case, Island::Plotting::Maps.[77] Here's what the output looks like:[78]
[77]If there's more than one module in the distribution, it should be the name of the most important module. Others can be added later.
[78]The exact behavior and output of h2xs may vary depending upon your version of Perl.
$ h2xs -XAn Island::Plotting::Maps Defaulting to backwards compatibility with perl 5.8.0 If you intend this module to be compatible with earlier perl versions, please specify a minimum perl version with the -b option. Writing Island/Plotting/Maps/Maps.pm Writing Island/Plotting/Maps/Makefile.PL Writing Island/Plotting/Maps/README Writing Island/Plotting/Maps/t/1.t Writing Island/Plotting/Maps/Changes Writing Island/Plotting/Maps/MANIFEST
|  | |
| 12.12. Exercise |  | 13.2. Looking at the Templates |
Copyright © 2003 O'Reilly & Associates. All rights reserved.