[Chapter 2] 2.4 Getting and Installing Modules

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 either a module already that does what you need, or perhaps one that you can extend, rather than starting from scratch.[ 2 ]

[2] If you are interested in writing and contributing modules, there are several places that serve as good starting points for learning to do that - 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 through the by-category subdirectory. If you know the author, click on by-author . However, if you aren't familiar with the categories and you want to find out if there is a module that performs a certain task, you might want to get the file 00modlist.long.html , also in the modules directory. That 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 categories; there are currently 22 categories, plus one for modules that don't fit anywhere else:

02_Perl_Core_Modules
03_Development_Support
04_Operating_System_Interfaces
05_Networking_Devices_Inter_Process
06_Data_Type_Utilities
07_Database_Interfaces
08_User_Interfaces   
09_Interfaces_to_Other_Languages
10_File_Names_Systems_Locking  
11_String_Processing_Language_Text_Process
12_Option_Argument_Parameter_Processing
13_Internationalization_and_Locale     
14_Authentication_Security_Encryption  
15_World_Wide_Web_HTML_HTTP_CGI
16_Server_and_Daemon_Utilities
17_Archiving_and_Compression  
18_Images_Pixmap_Bitmap_Manipulation
19_Mail_and_Usenet_News
20_Control_Flow_Utilities
21_File_Handle_Input_Output
22_Microsoft_Windows_Modules
23_Miscellaneous_Modules
99_Not_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 15:

ANDK                           
CGI-Out-96.081401.readme       
CGI-Out-96.081401.tar.gz       
CGI-Response-0.03.readme       
CGI-Response-0.03.tar.gz       
CGI-modules-2.75.readme        
CGI-modules-2.75.tar.gz        
CGI-modules-2.76.readme        
CGI-modules-2.76.tar.gz   
CGI.pm-2.32.readme        
CGI.pm-2.33.readme        
CGI.pm-2.34.readme        
CGI.pm-2.35.readme
CGI.pm-2.35.tar.gz
CGI.pm-2.36.readme
CGI.pm-2.36.tar.gz
CGI_Imagemap-1.00.readme
CGI_Imagemap-1.00.tar.gz
CGI_Lite-1.62.pm.gz
DOUGM
LDS
MGH
MIKEH
MUIR
SHGUN

You'll notice that multiple versions are sometimes listed - for example, CGI.pm has versions 2.35 and 2.36 available. Generally this is to ease 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, either on 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, 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 where 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 just referred to as 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 to move the downloaded module file to the correct directory and run gunzip and tar to unpack it. Then cd to the module directory and check any README or INSTALL files, and check the MANIFEST file to be sure everything is there. If all is well, you can then run the following to complete the installation:

% perl Makefile.PL
% make
% make test
% make 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 .

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 like 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 the use of MakeMaker. If you are running Perl 5.004 (or earlier), this prevents you from installing some modules. Others can be installed manually by making sure all the files that come in the module distribution are placed in the correct libraries. The documentation that comes with the module may help you determine if you can install it and what you need to do.

With 5.005, you can now 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 the site (such as CPAN or the CD that comes with the Perl Resource Kit for Win32 ) that contains the modules you are interested in, 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 the Perl Package Manager.
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 do it manually. But if you don't want to deal with doing it all manually, or if you are maintaining an entire Perl installation, 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, 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 -eshell

The first time you use the CPAN module, it takes you through a series of setup questions and writes a file called MyConfig.pm in a subdirectory of your home directory that 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 you to enter commands, 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 modules: