home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam  

Book HomeJava and XSLTSearch this book

2.4. Getting and Installing Modules

As you'll see when you look at the lists of modules and their authors on CPAN, many users have made their modules freely available. If you find an interesting problem and are thinking of writing a module to solve it, check the modules directory on CPAN first to see if there is a module there that you can use. The chances are good that there is a module that does what you need, or perhaps one that you can extend, rather than starting from scratch.[4]

[4]If you are interested in writing and contributing modules, there are several good starting points for learning to do so—see the perlmodlib manpage, the "Perl 5 Module List," and the "Perl Authors Upload Server" (http://www.perl.com/CPAN/modules/04pause.html).

Before you download a module, you might also check your system to see if it's already installed. The following command searches the libraries in the @INC array and prints the names of all modules it finds:

find `perl -e 'print "@INC"'` -name '*.pm' -print

2.4.1. Locating Modules

If you start from the modules directory on CPAN, you'll see that the modules are categorized into three subdirectories:

by-authors       Modules by author's registered CPAN name
by-category      Modules by subject matter (see below)
by-module        Modules by namespace (i.e., MIME)

If you know what module you want, you can go directly to it by clicking on the by-module entry. If you are looking for a module in a particular category, you can find it in the by-category subdirectory. If you know the author, click on by-author. However, if you aren't familiar with the categories and want to find a module that performs a certain task, you might want to get the file 00modlist.long.html, also in the modules directory. This file is the "Perl 5 Modules List." It contains a list of all the modules, by category, with a brief description of the purpose of each module and a link to the author's CPAN directory for downloading.

Here is a list of the Perl Module categories, plus two for modules that don't fit anywhere else:


If you are in the by-categories subdirectory and have selected an area from which you'd like to download a module, you'll find a list of the files in the directory. tar files have a .tar.gz extension, and README files have a .readme extension. You'll generally find a README file for each module; take a look at it before you decide to download the file.

Here's a sample directory listing from category 14, under the MD5 directory:


You'll notice that multiple versions are sometimes listed—for example, the MD5 module has Versions 1.5.3 through 1.7 available. Generally, this is to facilitate the transition to a new version of the module.

Select the .readme file of the most current archive and review its contents carefully. README files often give special instructions about building the module; they warn you about other modules needed for proper functioning and if the module can't be built under certain versions of Perl. If you're satisfied with what you read, download the file.

2.4.2. Module Installation

If you're running the standard distribution of Perl, on either a Unix or Win32 system, and you want to install a module, this section explains how to do it. If you are running the ActiveState Win32 port, you can follow the instructions covered in this section, unless you're running on a system without a development toolkit; if this is the case, see the next section.

Before installing modules, you should understand at least a little about make. make is a command designed to automate compilations; it guarantees that programs are compiled with the correct options and are linked to the current version of program modules and libraries. But it's not just for programmers—make is useful for any situation in which there are dependencies among a group of related files.

make uses a file known as a Makefile, which is a text file that describes the dependencies and contains instructions that tell make what to do. A Perl programmer who writes a module creates a file called Makefile.PL that comes with the module when you download it. Makefile.PL is a Perl script that uses another module, ExtUtils::MakeMaker (generally referred to as simply MakeMaker), to generate a Makefile specific to that module on your system.

Before you can actually install the module, you need to decide where it should go. Modules can be installed either globally, for everyone to use, or locally, for your own use. Most system administrators install popular software, including Perl modules, to be globally available. In that case, the modules are generally installed in a branch of the lib directory with the rest of the Perl libraries.

If you have root privileges or write access to the locations where Perl modules are installed on your system, you can proceed by moving the downloaded module file to the correct directory and running gunzip and tar to unpack it. Then cd to the module directory and check any README or INSTALL files, check the MANIFEST file to be sure everything is there. If all is well, you can run the following to complete the installation:

% perl Makefile.PL
% make
% make test
% make install

If you're on a Win32 platform and are using Mingw32, do the following:

C:\modulename-version> perl Makefile.PL
C:\modulename-version> dmake
C:\modulename-version> dmake test
C:\modulename-version> dmake install

It's possible that you'll need to customize Makefile.PL before running it. If so, see the discussion of ExtUtils::MakeMaker in Chapter 8, "Standard Modules". Or, if you know the MakeMaker options that you'd like to add to Makefile.PL, you can add these options on the command line. A typical scenario would be on a system where you've installed a precompiled version of Perl, and the CC and LD options in Config.pm don't match your programming environment; thus, Perl modules won't build correctly. To solve this problem, you can do the following:

% perl Makefile.PL CC=gcc LD=gcc

If you are going to install the module locally (for example, if you don't have permission to install globally or you want to test it locally before installing it for general use), you need to pass a PREFIX argument to Perl when you run Makefile.PL to generate the Makefile. This argument tells MakeMaker to use the directory following PREFIX as the base directory when installing the module.

For example, to install a module in the directory /home/mydir/Perl/Modules, the PREFIX argument would look like this:

% perl Makefile.PL PREFIX=/home/mydir/Perl/Modules

Then follow the remaining steps, as above:

% make
% make test
% make install

The module is now available, but when you write Perl code to use the module, there's another detail to take care of. Since Perl looks in system-wide directories as specified in the special array @INC, it won't find local modules unless you tell it where they are. Instead, you'll receive an error message such as the following:

Can't locate <ModuleName>.pm in @INC.
BEGIN failed--compilation aborted.

Thus, if you installed the module in /home/mydir/Perl/Modules, you need to tell Perl to look in that location with the command use lib 'path':

#!/usr/local/bin/perl -w
use lib '/home/mydir/Perl/Modules';
use ModuleName;

2.4.3. Installing Modules with ActiveState Perl

Prior to Perl 5.005, ActiveState's Perl for Win32 did not support MakeMaker. If you are running Perl 5.004 (or earlier), you should upgrade because the absense of MakeMaker prevents you from installing and using most current Perl modules. While some modules can be installed manually, this is not suggested, since it's likely that something will be forgotten, and the module won't work correctly! You should follow all module documentation to determine which installation technique is the proper one, so that everything will be okay.

With 5.6 and later, you can use MakeMaker to install the modules, or you can use the Perl Package Manager that comes with ActivePerl.

2.4.4. Installing Modules with the CPAN Module

If you are just getting and installing one or a few modules, it's not a big problem to download the module's tarball and run through the build process manually. But if you don't want to cope with the brute-force approach when dealing with large module installations (such as LWP and the CPAN bundle), there is an easier way—you can use the CPAN module. The CPAN module (CPAN.pm) can be used interactively from the command line to locate, download, and install Perl modules and their dependencies, or to identify modules and authors. CPAN.pm was designed to automate the installation of Perl modules; it includes searching capabilities and the ability to retrieve files from one or more of the mirrored CPAN sites and unpack them in a dedicated directory.

To run the CPAN module interactively, enter:

% perl -MCPAN -e shell

The first time you use the CPAN module, it takes you through a series of setup questions and writes CPAN::Config if you run the above as root or your administrative user. If the above is run as a user who does not have administrative permissions, CPAN.pm determines who you are and writes MyConfig.pm in a subdirectory of your home directory (defaults to ~/.cpan/CPAN/MyConfig.pm). After that, whenever you use the CPAN module for downloading other modules, it uses the .cpan directory as the general build and cache directory, saved as cpan_home in the configuration file. If ReadLine support is available (i.e., Term::ReadKey and Term::ReadLine are installed), you can use command history and command completion as you enter commands.

When the module runs and is ready for commands to be entered, you'll see the prompt:


You can then enter h to get a brief help message, or just start entering commands. The commands are all methods in the CPAN::Shell package. For commands that can operate on modules, bundles, authors, or distributions, CPAN.pm treats arguments containing a slash (/) as distributions, arguments beginning with Bundle:: as bundles, and everything else as modules or authors. The following is a listing of the interactive CPAN commands.



Displays brief help message. Same as h command.


o type [option] [value]

Sets and queries options. Takes the following arguments:

Type of options to set or query. The possible values are:

Debugging options. Prints CPAN module options for debugging the package.

Configuration options. Lists or sets values for CPAN module configuration variables kept in the hash %CPAN::Config. These configuration variables are:




Size of cache for directories to build modules


Locally accessible directory to build modules


Number of days before refetching index files


Local directory reserved for this package


Location of external program gzip


Breaks an interactive Makefile.PL after inactivity_timeout seconds of inactivity (set to 0 to never break)


If true, does not print startup message


If set, keeps source in local directory


Where to keep source


Location of external make program


Arguments to always pass to make


Same as make_arg for make install


Arguments to always pass to perl Makefile.PL


Location of external more program (or other pager)


Location of external tar program


Location of external unzip program


Arrayref to nearby CPAN sites (or equivalent locations, such as CD-ROM)


Uses serializer to cache metadata


Sets behavior for handling module dependencies; options are follow, automatically, ask, and ignore


Controls the cache-scanning behavior; options are atstart and never


An arrayref that contains the wait server(s) to try

The CPAN module configuration option or options; used with conf. Can be one or more scalar or list options from the table above.

Value to be set for a configuration option. The possibilities for o conf are:

o conf scalaropt
Prints current value of scalar option

o conf scalaropt value
Sets scalar option to value

o conf listopt
Prints current value of list option in MakeMaker format

o conf listopt [shift|pop]
Shifts or pops the array in listoptvariable

o conf listopt [unshift|push|splice] list
Works like the corresponding Perl functions to modify the array in listopt based on list

o conf commit
Wites CPAN::Config with updated options

Library Navigation Links

Copyright © 2002 O'Reilly & Associates. All rights reserved.