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.
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.
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.
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:PERLLIB 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 Glossary for examples of doing
this.