Getting and Installing Modules (Perl in a Nutshell, 2nd Edition)

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:

02_Perl_Core_Modules
03_Development_Support
04_Operating_System_Interfaces
05_Networking_Devices_IPC
06_Data_Type_Utilities
07_Database_Interface
08_User_Interfaces
09_Language_Interfaces
10_File_Names_Systems_Locking
11_String_Lang_Text_Proc
12_Opt_Arg_Param_Proc
13_Internationalization_Locale
14_Security_and_Encryption
15_World_Wide_Web_HTML_HTTP_CGI
16_Server_and_Daemon_Utilities
17_Archiving_and_Compression
18_Images_Pixmaps_Bitmaps
19_Mail_and_Usenet_News
20_Control_Flow_Utilities
21_File_Handle_Input_Output
22_Microsoft_Windows_Modules
23_Miscellaneous_Modules
24_Commercial_Software_Interfaces
99_Not_In_Modulelist
99_Not_Yet_In_Modulelist

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:

Digest-MD5-2.09.readme
Digest-MD5-2.09.tar.gz
GAAS
GARY
MD5-1.5.3.readme
MD5-1.5.3.tar.gz
MD5-1.6.readme
MD5-1.6.tar.gz
MD5-1.7.readme
MD5-1.7.tar.gz
NWINT

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.3.1. Using MakeMaker

To install a module using MakeMaker, follow the procedure described earlier for installing when you are running the standard distribution, replacing make with nmake or dmake as appropriate.

2.4.3.2. Using the Perl Package Manager

The Perl Package Manager (PPM) provides a command-line interface for obtaining and installing Perl modules and extensions. To run PPM, connect to CPAN and type:

perl ppm.pl

The PPM prompt appears, and you can begin to enter PPM commands. The available commands are:

help [command]: Prints the list of commands and what they do, or help for a particular command.
install packages: Installs the specified packages.
quit: Leaves PPM.
remove packages: Removes the specified packages from the system.
search: Searches for information about available packages.
set: Sets or displays current options.
verify: Verifies that your current installation is up-to-date.

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:

cpan>

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.

! perl-code

evals a Perl command .

a [authorlist]

Searches for CPAN authors. Arguments can be strings that must be matched exactly or regular expressions, which must be enclosed in slashes and are matched in case-insensitive fashion. With no arguments, it returns a list of all authors, by CPAN ID. With arguments, it returns a list of authors if there is more than one that matches the criteria, or it returns additional information if a single author is returned. String and regular expression arguments can be combined in the same command.

cpan> a /^nv/ LWALL
Author          NVPAT (Nathan V. Patwardhan)
Author          LWALL (Larry Wall. Author of Perl. Busy man.)
cpan> a /^nv/
Author id = NVPAT
    EMAIL        nvp@ora.com
    FULLNAME     Nathan V. Patwardhan

autobundle

autobundle [bundlelist]

Writes a bundle file containing a list of all modules that are both available from CPAN and currently installed within @INC. The file is written to the Bundle subdirectory of cpan_home with a name that contains the current date and a counter—for example, Snapshot_1998_04_27_00.pm. You can use this file as input to the install command to install the latest versions of all the modules on your system:

perl -MCPAN -e 'install Bundle::Snapshot_1998_04_27_00'

b [bundlelist]

Searches for CPAN bundles. Arguments are the same as for the a command, except they specify bundles. With a single argument, b displays details about the bundle; with multiple arguments, it displays a list.

clean

clean [arglist]

Does a make clean in the distribution file's directory. arglistcan include one or more modules, bundles, distributions, or one of the values r or u to reinstall or uninstall.

d [distriblist]

Displays information about module distributions for the distribution(s) specified in distriblist. Arguments are the same as for the a command. Displays details for a single argument, or a list if the output consists of multiple distributions.

force

force method [arglist]

Takes as a first argument the method to invoke, which can be one of make, test, or install, and executes the command from scratch for each argument in arglist. The arguments may be modules or distributions.

Be warned that force also allows you to install modules that have failed some or all of the module tests. If installing modules that have failed their tests bothers you, then you shouldn't use force.

Displays brief help message. Same as ?.

i [arglist]

Displays information about the arguments specified in arglist, which can be an author, module, bundle, or distribution. Arguments and output are the same as for a.

install

install [arglist]

Installs the arguments specified in arglist, which can be modules or distributions. Implies test. For a distribution, install is run unconditionally. For a module, CPAN.pm checks to see if the module is up-to-date, and if so, prints a message to that effect and does not do the install. Otherwise, it finds and processes the distribution that contains the module.

look

look arg

Takes one argument, which is a module or distribution, gets and untars the distribution file if necessary, changes to the appropriate directory, and opens a subshell process in that directory.

m [arglist]

Displays information about modules. Arguments are the same as for the a command. Displays details for a single module, or a list if there is more than one in the output.

make

make [arglist]

Unconditionally runs a make on each argument in arglist, which can be a module or a distribution. For a module, CPAN.pm finds and processes the distribution that contains the module.

o type [option] [value]

Sets and queries options. Takes the following arguments:

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

debug

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

conf

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

Variable

Content

build_cache

Size of cache for directories to build modules

build_dir

Locally accessible directory to build modules

index_expire

Number of days before refetching index files

cpan_home

Local directory reserved for this package

gzip

Location of external program gzip

inactivity_timeout

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

inhibit_startup_message

If true, does not print startup message

keep_source

If set, keeps source in local directory

keep_source_where

Where to keep source

make

Location of external make program

make_arg

Arguments to always pass to make

make_install_arg

Same as make_arg for make install

makepl_arg

Arguments to always pass to perl Makefile.PL

pager

Location of external more program (or other pager)

tar

Location of external tar program

unzip

Location of external unzip program

urllist

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

cache_metadata

Uses serializer to cache metadata

prerequisites_policy

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

scan_cache

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

wait_list

An arrayref that contains the wait server(s) to try
option: The CPAN module configuration option or options; used with conf. Can be one or more scalar or list options from the table above.
value: 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

Quits the CPAN module shell subroutine.

Recommendations for reinstallation. With no argument, lists all distributions that are out-of-date. With an argument, tells you whether that module or distribution is out-of-date.

readme

readme arglist

Finds and displays the README file for modules or distributions in arglist.

recompile

recompile

Runs full make/test/install cycle over all installed dynamically loadable modules with force in effect. Useful for completing a network installation on systems after the first installation, in which the CPAN module would otherwise declare the modules already up-to-date.

reload

reload arg

Reloads index files or re-eval s CPAN.pm itself. arg may be:

cpan: Re-eval s CPAN.pm.
index: Reloads index of files.

test

test

Runs the make test command.

Lists all uninstalled distributions.