Item 41: Don t reinvent the wheeluse Perl modules.

Item 41: Don't reinvent the wheeluse Perl modules.

Modules are Perl's " Software ICs." Perl modules provide a versatile, clean means of adding functionality to Perl. At their simplest, modules define ordinary functions that can be used in Perl programs. They also can add objects and methods (see Item 49). Modules can be written entirely in Perl, as is usually the case, or they can be written with a mixture of C or C++ and Perl (see Item 47). Modules also can be written to modify the behavior of Perl's compile- or run-time phase itself, as with pragma modules like strict (see Item 36).

There are many, many different modules available to Perl programmers. A wide variety of common programming chores have been encapsulated in freely distributed modules available from the Comprehensive Perl Archive Network (CPAN). What's available includes e-mail, netnews, FTP, and World Wide Web (WWW) utilities; graphical and character user interface tools; Perl language extensions; and database, text-processing, mathematical, and image-processing utilities. The list goes on from thereand for quite a while!

Getting modules from the CPAN

The CPAN is a replicated archive, mirrored on many different FTP and WWW servers worldwide. One way to get modules from the CPAN is to download and install them yourself. If you know of a CPAN site "near" you (meaning one to which you have good connectivity), you can retrieve files directly from that site via FTP. On the other hand, if you don't know where to find a CPAN site, you can use the CPAN multiplexer at www.perl.com to find one for you. Just access the following URL from your favorite web browser:

http://www.perl.com/CPAN/

A site will be automatically selected for you. If you omit the trailing slash, you will be presented with a list of sites to choose from. Another way to get modules from the CPAN is to use the CPAN module. The CPAN module is part of the Perl distribution as of version 5.004 and can be installed for earlier versions of the language. If you have the CPAN module installed, you can use it interactively by typing the following at a command line:

 %  perl -MCPAN -e shell  

If this is the first time you have used the module, you will be asked a number of configuration questions. The default answers will be fine for most of them. Toward the end, you will be asked for the URL of your preferred CPAN site. You would ordinarily answer with something like:

 We need to know the URL of your favorite CPAN site.  Please enter it here:  ftp://your.site.here.com/pub/perl/CPAN/  

If you are lucky enough to have a CPAN mirror on your own machine (not all that hard to set up, really, but beyond the scope of this book), you can use a file URL:

 Please enter it here:  file:///home/joseph/CPAN/  

Now you will enter the interactive mode of the CPAN module. Here you can list and explore the modules that are available. You can also download, build, and install them. For example, to build and install a new version of the CPAN module, and assuming that you have the correct permissions, just type:

 cpan>  install CPAN  Running make  CPAN-1.28/  CPAN-1.28/lib/ 

. . . etc.

You can even restart the new version without exiting:

 cpan>  reload CPAN  Subroutine AUTOLOAD redefined at (eval 8) line 61, <GEN8> chunk  1.  Value of $term will not stay shared at (eval 8) line 92, <GEN8>  chunk 1. 

. . . blah blah blah . . .

Installing Perl modules

If you are running an older version of Perl and don't have the CPAN module installed, or if you want to install a module that is not part of the CPAN (e.g., one that you are writing yourself), you need to make and install the module manually. Fortunately, the procedure is straightforward.

The module should be supplied in a tar-ed, compressed archive. It should have a name that looks something like File-Magic-1.03.tar.Z if it doesn't, it may have been created without using h2xs and MakeMaker (see Item 45), and all bets as to how to install it are off. Fortunately, although "funky" modules were commonplace in the early days of Perl 5, they are rare now.

There is no File::Magic module (not that I'm aware of, anyway), so the example below is for illustration only. Replace File-Magic with the name of the module you actually want to install. Also, the output you see while building and installing a module may be somewhat different than what follows .

Note

If you follow the steps below, you will install a module into your existing Perl installation . If you do not want to do that, or do not have the necessary permissions, see later in this Item for ways to install and use a module in a different directory.

The first step is to uncompress and un-tar the package. Depending on your version of Unix, you will do something like this:

 %  uncompress File-Magic-1.03.tar.Z  %  tar xvf File-Magic-1.03.tar  File-Magic-1.03/  File-Magic-1.03/Makefile.PL  File-Magic-1.03/Changes  File-Magic-1.03/test.pl  File-Magic-1.03/Magic.pm  File-Magic-1.03/MANIFEST 

Next, cd to the newly created directory and create the module's makefile:

 %  cd File-Magic-1.03  %  perl Makefile.PL  Checking if your kit is complete...  Looks good  Writing Makefile for File::Magic 

You can now make and test the module:

 %  make  cp Magic.pm ./blib/lib/File/Magic.pm  Manifying ./blib/man3/File::Magic.3  %  make test  PERL_DL_NONLAZY=1 /usr/local/bin/perl -I./blib/arch  -I./blib/lib -I/usr/local/lib/perl5/sun4-solaris/5.004  -I/usr/local/lib/perl5 test.pl  1..2  ok 1  ok 2 

If everything went smoothly, go ahead and install the module:

 %  make install  Installing /usr/local/lib/perl5/site_perl/./File/Magic.pm 

. . . etc.

For more about using Perl modules, see Item 42.

Installing Perl modules in private or alternative directories

If you aren't the official Perl administrator on your system, or if you don't want to install a new version module into the main distribution without trying it out first, you will have to install new modules into a different directory than the default. There are several ways to install a module into a nonstandard place, but we will discuss only the one that is most straightforward: the LIB variable.

To change the place where a module is installed, you need to modify the makefile that installs it. The way you do this is by setting the value of the LIB variable when you run the Makefile.PL script. For example, say you want to cause the module to be installed in /home/joseph/perllib :

 %  perl Makefile.PL LIB=/home/joseph/perllib  

Now, when you make, test, and install the module, it will wind up in /home/joseph/perllib rather than in the Perl tree.

To use a module installed in a nonstandard place, you will generally need to modify the module include path , @INC . The best way to do this is with the use lib pragma:

use lib '/home/joseph/perllib';	Add this directory to the include path.
use File::Magic qw(WaveWand); WaveWand glob "*.h";	Now we can get to File::Magic .

For more about the module include path, see Item 43.