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.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:

• ?
• !
• a
• autobundle
• b
• clean
• d
• force
• h
• i
• install
• look
• m
• make
• o
• q
• r
• readme
• recompile
• reload
• test
• u