 |  |
| |
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
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.
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;
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.
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 CPAN and type:
perl ppm.pl
The PPM prompt appears, and you can begin to enter PPM commands. The available commands are:
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.
| a |
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 [email protected]
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 |
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 |
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.
| i |
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 |
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 |
o type [option] [value]
Sets and queries options. Takes the following arguments:
|
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 |
| r |
r
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.
| 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:
|  | |
| 2.3. Installing Perl |  | 2.5. Documentation |
Copyright © 2002 O'Reilly & Associates. All rights reserved.