Using CPAN Modules (Programming Perl)

22.2. Using CPAN Modules

Most modules that you'll find on CPAN are in "tarball" form. That is, they have a file extension ending in .tar.gz, and expand into a directory with the module code and any auxiliary files, usually including a README and a Makefile.PL file.

There are four steps for making CPAN modules available to your programs: decompression, unpacking, building, and installation. How each of those steps work depend on your operating system and the module being installed, so we can't give you a foolproof recipe that will work all the time. When in doubt, read the README and INSTALL files that were hopefully distributed with the module. Also read the perlmodinstall manpage.

But you may never have to think about the installation procedure if you use the CPAN module (bundled with the Perl distribution) or PPM (the Perl Package Manager, bundled with the ActiveState distribution of Perl). To use the CPAN module (not to be confused with CPAN itself), type:

% perl -MCPAN -e "shell"

at your command line to begin the configuration process. After you've answered a variety of questions about how you'd like to retrieve files, you can install a module by typing:

install Some::Module

in the CPAN module's shell, or by typing:

% perl -MCPAN -e "install 'Some::Module'"

from your normal command line.

If you don't have the convenience of either the CPAN module or PPM, you'll need to go through the steps in the following sections by hand. Instructions are provided for Unix, Windows, and Macintosh; for other operating systems, consult the perlmodinstall manpage.

22.2.1. Decompressing and Unpacking CPAN Modules

Most of the thousands of utilities on CPAN are compressed so that they take up less space. Once you've retrieved a module tarball, you first need to turn it into a directory tree on your system by decompressing ("unzipping") and unpacking the tarball. On Unix, you can use gzip and tar to do this. (On many systems, tar will do both.) On Windows, WinZip will both decompress and unpack tarballs. On a Macintosh, you can either use StuffIt and DropStuff, MacGzip, or suntar.

22.2.2. Building CPAN Modules

A minority of CPAN modules come with C code that you'll need to compile for your system, which is naturally a problem for systems that lack a C compiler. The standard procedure for building a CPAN module (with or without C code) is the following three commands, executed from the command line. (If you don't have a command line, or a make-equivalent, you'll need to resort to more drastic, system-dependent measures. Windows users have a command line but might need to use the nmake utility instead of make.)

% perl Makefile.PL

% make

% make test

The perl Makefile.PL command will try to create a Makefile, which the subsequent make command uses to determine what utilities need to be built and in what order. The final command, make test, runs the test suite that the module author hopefully included.

22.2.3. Installing CPAN Modules into the Perl Library

Presuming you've followed the previous steps, you now have a module that has been built and tested, but not yet installed into Perl's library. When Perl was installed on your system, a lib directory was created to hold modules, pragmas, and related files. That's the Perl library, which is usually something like /usr/local/lib/perl5 on Unix systems and C:\PERL\LIB by default on Windows systems. Modules installed after Perl was built are stored in the site_perl subdirectory of the Perl library. You can see the names of all your library directories (and a bunch of other stuff) by saying:

% perl -V

To install the module, type:

% make install

Superuser access is normally required, even for installing modules into your site-specific Perl library directories.

With a little work, you can install the module in a directory outside your Perl library (such as your home directory). If you would normally have typed perl Makefile.PL to create a Makefile, you could instead use this incantation:

% perl Makefile.PL LIB=/my/dir/perllib  \
        INSTALLMAN1DIR=/my/dir/man/man1 \
        INSTALLMAN3DIR=/my/dir/man/man3 \
            INSTALLBIN=/my/dir/bin      \
         INSTALLSCRIPT=/my/dir/scripts

This will install the modules somewhere in the /my/dir/perllib directory and any remaining files where they need to go. (If you find yourself typing this a lot, you could even write a little Perl program to do it for you. Perl is good for things like that.)

Then you can have Perl search your special directory for modules by adding:

use lib "/my/dir/perllib";

before your program attempts to load in the module. You may also set the PERL5LIB environment variable to that directory, or use Perl's -I switch. See the use lib pragma in Chapter 31, "Pragmatic Modules" for examples of doing this.