12.3. Modules from CPAN

CPAN (the Comprehensive Perl Archive Network) is the central repository for a collection of hundreds of Perl modules. To find the CPAN mirror closest to you, go to http://www.perl.com/CPAN. (In Chapter 16, we show you how to download database modules from CPAN and how to use those modules in a program.)

Perl modules that depend on each other are bundled together by name, author, and category. These modules can be found under the CPAN modules directory or by using the CPAN search engine under http://search.cpan.org. If you need to install these modules, the CPAN documentation gives you easy-to-follow instructions. The Web page shown here displays how the information is catalogued and gives a partial list of the modules.

Figure 12.5. The Perl 5 module list at the CPAN Web site.

[View full size image]

ActivePerl, available for the Linux, Solaris, Mac OS, and Windows operating systems, contains the Perl Package Manager (for installing packages of CPAN modules) and complete online help. PPM allows you to access package repositories and install new packages or update old ones you already have with relative ease.

Go to www.activestate.com/ppmpackages/5.6 to access the ActiveState Package repository.

The Cpan.pm Module

The Cpan.pm module allows you to query, download, and build Perl modules from CPAN sites. It runs in both interactive and batch mode and is designed to automate the installation of Perl modules and extensions. The modules are fetched from one or more of the mirrored CPAN sites and unpacked in a dedicated directory. To learn more about this module, at your system command line type

$ perldoc Cpan

to read the following:

NAME
    CPAN - query, download and build perl modules from CPAN sites

SYNOPSIS

   Interactive mode:

      perl -MCPAN -e shell;

   Batch mode:

      use CPAN;

      autobundle, clean, install, make, recompile, test

DESCRIPTION
    The CPAN module is designed to automate the make and install of perl
    modules and extensions. It includes some searching capabilities and
    knows how to use Net::FTP or LWP (or lynx or an external ftp client) to
    fetch the raw data from the net.

    Modules are fetched from one or more of the mirrored CPAN
    (Comprehensive Perl Archive Network) sites and unpacked in a
    dedicated directory.

    The CPAN module also supports the concept of named and versioned
    *bundles* of modules. Bundles simplify the handling of sets of related
    modules. See Bundles below.

    The package contains a session manager and a cache manager. There is no
    status retained between sessions. The session manager keeps track of
    what has been fetched, built and installed in the current session. The
    cache manager keeps track of the disk space occupied by the make
    processes and deletes excess space according to a simple FIFO
    mechanism.

    For extended searching capabilities there's a plugin for CPAN available,
    the CPAN::WAIT manpage. 'CPAN::WAIT' is a full-text search engine that
    indexes all documents available in CPAN authors directories. If
    'CPAN::WAIT' is installed on your system, the interactive shell of
    <CPAN.pm> will enable the 'wq', 'wr', 'wd', 'wl', and 'wh' commands
    which send queries to the WAIT server that has been configured for your
    installation.
                          <continues>

					  

Example 12.14.

Code View: 1 $ h2xs -A -n Exten.dir Writing Exten.dir/Exten.dir.pm Writing Exten.dir/Exten.dir.xs Writing Exten.dir/Makefile.PL Writing Exten.dir/test.pl Writing Exten.dir/Changes Writing Exten.dir/MANIFEST 2 $ cd Exten.dir 3 $ ls 4 $ more Exten.dir.pm package Exten.dir; require 5.005_62; use strict; use warnings; require Exporter; require DynaLoader; our @ISA = qw(Exporter DynaLoader); # Items to export into callers namespace by default. # Note: do not export names by default without # a very good reason. Use EXPORT_OK instead. # Do not simply export all your public # functions/methods/constants. # This allows declaration use Exten.dir ':all'; # If you do not need this, moving things directly # into @EXPORT or @EXPORT_OK will save memory. perl -MCPAN -e shell cpan shell -- CPAN exploration and modules installation (v1.7602) ReadLine support enabled cpan> h Display Information command argument description a,b,d,m WORD or /REGEXP/ about authors, bundles, distributions, modules i WORD or /REGEXP/ about anything of above r NONE reinstall recommendations ls AUTHOR about files in the author's directory Download, Test, Make, Install... get download make make (implies get) test MODULES, make test (implies make) install DISTS, BUNDLES make install (implies test) clean make clean look open subshell in these dists' directories readme display these dists' README files Other h,? display this menu ! perl-code eval a perl command o conf [opt] set and query options q quit the cpan shell reload cpan load CPAN.pm again reload index load newer indices autobundle Snapshot force cmd unconditionally do cmd cpan>

12.3.1. Using PPM

PPM is a program manager that comes with ActivePerl (www.activestate.com). It is very easy to use and runs on Linux, Windows, and Mac OS. It comes in both a GUI and command-line interface. When the Perl Package Manager is activated, it brings up a window with all the currently installed packages. You can search for specific modules and install, upgrade, and remove modules using this graphical interface. For everyday use, this is much easier than using CPAN.

Figure 12.6. PPM GUI.

[View full size image]

Figure 12.7. What the icons mean in the PPM window.

[View full size image]

Figure 12.8. Searching for a Perl module to Sendmail.

[View full size image]

Creating Extensions and Modules for CPAN with the h2xs Tool

The h2xs tool is a standard application that comes with the regular Perl distribution. It creates a directory and a set of skeleton files to use when creating a module or adding C language extensions. To get a full description, type at your system prompt

$ perldoc h2xs

Example 12.15.

Code View: 1 $ h2xs -A -n Exten.dir Writing Exten.dir/Exten.dir.pm Writing Exten.dir/Exten.dir.xs Writing Exten.dir/Makefile.PL Writing Exten.dir/test.pl Writing Exten.dir/Changes Writing Exten.dir/MANIFEST 2 $ cd Exten.dir 3 $ ls 4 $ more Exten.dir.pm package Exten.dir; require 5.005_62; use strict; use warnings; require Exporter; require DynaLoader; our @ISA = qw(Exporter DynaLoader); # Items to export into callers namespace by default. # Note: do not export names by default without # a very good reason. Use EXPORT_OK instead. # Do not simply export all your public # functions/methods/constants. # This allows declaration use Exten.dir ':all'; # If you do not need this, moving things directly # into @EXPORT or @EXPORT_OK will save memory. our %EXPORT_TAGS = ( 'all' => [ qw() ] ); our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } ); our @EXPORT = qw( ); our $VERSION = '0.01'; bootstrap Exten.dir $VERSION; # Preloaded methods go here. 1; _ _END_ _ # Below is stub documentation for your module. # You'd better edit it! =head1 NAME Exten.dir - Perl extension for blah blah blah =head1 SYNOPSIS use Exten.dir; blah blah blah =head1 DESCRIPTION Stub documentation for Exten.dir, created by h2xs. It looks like the author of the extension was negligent enough to leave the stub unedited. Blah blah blah. =head2 EXPORT None by default. =head1 AUTHOR A. U. Thor, a.u.thor@a.galaxy.far.far.away =head1 SEE ALSO perl(1). =cut Explanation The h2xs tool creates a subdirectory (this one is called Exten.dir) consisting of six files that will be used in the creation of a CPAN-style module. Before creating a module for CPAN, you should go to www.cpan.org/modules/00modlist.long.html to make sure someone else hasn't already written it, which could save you some work. We change into the new directory created by h2xs. This is a listing of the files created by h2xs (not shown). The MANIFEST file contains a list of all files just created in this directory and where any additional files should be listed that will be distributed with the module. The Makefile.PL file generates a Makefile. Exten.dir.pm is the skeletal module, which will contain extensions, and Exten.dir.xs will contain the XSUB routines for loading C extensions. This is the skeleton module used to help set up the module correctly.