 | Chapter 2 Installing Perl |  |
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
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.
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;
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.
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.
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 packagesInstalls the specified packages.
quitLeaves the Perl Package Manager.
remove packagesRemoves the specified packages from the system.
searchSearches for information about available packages.
setSets or displays current options.
verifyVerifies that your current installation is up-to-date.
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:
|  | |
| 2.3 Installing Perl |  | 2.5 Documentation |