Installing Perl Modules (Practical mod

0.9. Installing Perl Modules

mod_perl and all the various Perl modules and helper utilities mentioned in this book are available via FTP and HTTP from any of the sites on the Comprehensive Perl Archive Network (CPAN) at http://cpan.org/. This is a list of several hundred public FTP and HTTP sites that mirror each others' contents on a regular basis.

You can search for and install Perl modules in two ways:

Manually, by going to http://search.cpan.org/, finding the module, then downloading, building, and installing it. You can also browse the modules by categories or authors at http://cpan.org/.
Automatically, by using Andreas Koenig's CPAN shell or (on MS Windows systems) the Perl Package Manager (PPM). These tools allow you to search for available modules and install them with a single command.

9.1. Manual Installation

When you download a module manually, it's best to find the one closest to you. You can find a list of CPAN mirrors at http://mirror.cpan.org/.

You can download the source packages with your browser, or, if you know the URL of the package, you can use any command tool to do that for you. In this book, we usually use the lwp-download perl script (which is bundled with the libwww-perl package, by Gisle Aas) as a client. You can use any other utility to download the files from the Internet.

Once you've downloaded the Perl module you want, you'll need to build and install it. Some modules are 100% Perl and can just be copied to the Perl library directory. Others contain some components written in C and need to be compiled.

Let's download the CPAN shell package, which we will use shortly:

panic% lwp-download http://www.cpan.org/authors/id/ANDK/CPAN-1.60.tar.gz
Saving to 'CPAN-1.60.tar.gz'...
115 KB received in 2 seconds (56.3 KB/sec)

9.2. Prerequisites Needed to Install Perl Modules on Windows

While Unix operating systems include standard utilities such as tar, gzip, and make, Windows systems don't. For this reason, you will have to go through some extra steps to ensure that you can install modules from the CPAN under Windows.

We assume here that you are using the ActivePerl distribution from ActiveState.

The first utility needed is make. On Windows, such a utility (called nmake) is distributed by Microsoft for free. You can download a self-extracting archive from ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe. When you run this executable, you will have three files: readme.txt, nmake.err, and nmake.exe. Copy these files into a directory in your PATH,[1] such as C:\Windows\System, C:\Windows, or even C:\Perl\bin. You will now be able to replace any use of make in the examples in this book with nmake.

[1]To see your PATH, run echo %PATH% from the command line.

Some examples, and the use of CPAN.pm, also require command-line utilities such as tar or gzip. There are a number of projects that have ported such tools to Windows—for example, GnuWin32 (http://gnuwin32.sourceforge.net/) and UnixUtils (http://unxutils.sourceforge.net/). These toolkits allow you to use standard Unix utilities from your Windows command line.

Another option is Cygwin (http://www.cygwin.com/), which puts a Unix layer on top of Windows. This allows you to use many Unix-specific applications, but these must run from the Cygwin shell. If you use Cygwin, you should use the normal Unix steps discussed in this book, not any Windows-specific ones.

There is another downside of Windows: compilation tools aren't included. This means that some modules that use C extensions (e.g., mod_perl) can't be installed in the normal way, and you have to get precompiled distributions of them. In such cases, it is a good idea to follow the PPM instructions given later in this Preface, which should allow you to install binary versions of some of the modules discussed here.

9.3. Building a Perl Module

Building a Perl module and installing it is simple and usually painless. Perl modules are distributed as gzipped tar archives. You can unpack them like this:

panic% gunzip -c CPAN-1.60.tar.gz  | tar xvf -
 CPAN-1.60/
 CPAN-1.60/lib/
 CPAN-1.60/lib/CPAN/
 CPAN-1.60/lib/CPAN/Nox.pm
 CPAN-1.60/lib/CPAN/Admin.pm
 CPAN-1.60/lib/CPAN/FirstTime.pm
 CPAN-1.60/lib/Bundle/
 CPAN-1.60/lib/Bundle/CPAN.pm
 CPAN-1.60/lib/CPAN.pm
 CPAN-1.60/Todo
 CPAN-1.60/ChangeLog
 CPAN-1.60/t/
 CPAN-1.60/t/loadme.t
 CPAN-1.60/t/vcmp.t
 CPAN-1.60/MANIFEST
 CPAN-1.60/Makefile.PL
 CPAN-1.60/cpan
 CPAN-1.60/README

Or, if you are using a GNU tar utility, you can unpack the package in one command:

panic% tar zxvf CPAN-1.59.tzr.gz

Once the archive has been unpacked, you'll have to enter the newly created directory and issue the perl Makefile.PL, make, make test, and make install commands. Together, these will build, test, and install the module:

panic% cd CPAN-1.60
panic% perl Makefile.PL
Checking if your kit is complete...
Looks good
Writing Makefile for CPAN

panic% make 
cp lib/CPAN/Nox.pm blib/lib/CPAN/Nox.pm
cp lib/Bundle/CPAN.pm blib/lib/Bundle/CPAN.pm
cp lib/CPAN/Admin.pm blib/lib/CPAN/Admin.pm
cp lib/CPAN.pm blib/lib/CPAN.pm
cp lib/CPAN/FirstTime.pm blib/lib/CPAN/FirstTime.pm
cp cpan blib/script/cpan
/usr/bin/perl -I/usr/lib/perl5/5.6.1/i386-linux 
              -I/usr/lib/perl5/5.6.1 -MExtUtils::MakeMaker
              -e "MY->fixin(shift)" blib/script/cpan
Manifying blib/man3/CPAN::Nox.3
Manifying blib/man3/Bundle::CPAN.3
Manifying blib/man3/CPAN::Admin.3
Manifying blib/man3/CPAN.3
Manifying blib/man3/CPAN::FirstTime.3

panic% make test
PERL_DL_NONLAZY=1 /usr/bin/perl -Iblib/arch -Iblib/lib 
-I/usr/lib/perl5/5.6.1/i386-linux -I/usr/lib/perl5/5.6.1 
-e 'use Test::Harness qw(&runtests $verbose);
   $verbose=0; runtests @ARGV;' 
t/*.t
t/loadme............ok
t/vcmp..............ok
All tests successful.
Files=2, Tests=31,  3 wallclock secs ( 1.22 cusr +  0.91 csys =  2.13 CPU)

Become root if you need to install the module on the whole system:

panic% su
<root password>

panic# make install
Installing /usr/lib/perl5/man/man3/CPAN::Nox.3
Installing /usr/lib/perl5/man/man3/Bundle::CPAN.3
Installing /usr/lib/perl5/man/man3/CPAN::Admin.3
Installing /usr/lib/perl5/man/man3/CPAN.3
Installing /usr/lib/perl5/man/man3/CPAN::FirstTime.3
Writing /usr/lib/perl5/5.6.1/i386-linux/auto/CPAN/.packlist
Appending installation info to /usr/lib/perl5/5.6.1/i386-linux/perllocal.pod

9.4. Using the CPAN Shell

A simpler way to do the same thing is to use Andreas Koenig's wonderful CPAN shell (recent Perl versions come bundled with this module). With it, you can download, build, and install Perl modules from a simple command-line shell. The following illustrates a typical session in which we install the Apache::VMonitor module:

panic% perl -MCPAN -e shell

cpan shell -- CPAN exploration and modules installation (v1.60)
ReadLine support enabled

cpan> install Apache::VMonitor
Running install for module Apache::VMonitor
Running make for S/ST/STAS/Apache-VMonitor-0.6.tar.gz
Fetching with LWP:
  http://cpan.org/authors/id/S/ST/STAS/Apache-VMonitor-0.6.tar.gz
Fetching with LWP:
  http://cpan.org/authors/id/S/ST/STAS/CHECKSUMS
Checksum for /root/.cpan/sources/authors/id/S/ST/STAS/Apache-VMonitor-0.6.tar.gz ok
Apache-VMonitor-0.6/
Apache-VMonitor-0.6/README
Apache-VMonitor-0.6/Makefile.PL
Apache-VMonitor-0.6/MANIFEST
Apache-VMonitor-0.6/CHANGES
Apache-VMonitor-0.6/VMonitor.pm

CPAN.pm: Going to build S/ST/STAS/Apache-VMonitor-0.6.tar.gz

Checking for Apache::Scoreboard...ok
Checking for GTop...ok
Checking for Time::HiRes...ok
Checking for mod_perl...ok
Checking if your kit is complete...
Looks good
Writing Makefile for Apache::VMonitor
cp VMonitor.pm blib/lib/Apache/VMonitor.pm
Manifying blib/man3/Apache::VMonitor.3
  /usr/bin/make  -- OK
Running make test
No tests defined for Apache::VMonitor extension.
  /usr/bin/make test -- OK
Running make install
Installing /usr/lib/perl5/site_perl/5.6.1/Apache/VMonitor.pm
Installing /usr/lib/perl5/man/man3/Apache::VMonitor.3
Writing /usr/lib/perl5/site_perl/5.6.1/i386-linux/auto/Apache/VMonitor/.packlist
Appending installation info to /usr/lib/perl5/5.6.1/i386-linux/perllocal.pod
  /usr/bin/make install UNINST=1 -- OK

cpan> exit

Notice that the CPAN shell fetches the CHECKSUMS file and verifies that the package hasn't been tampered with.

The latest CPAN module comes with a small utility called cpan, which you can use to start the CPAN shell:

panic% cpan

cpan shell -- CPAN exploration and modules installation (v1.60)
ReadLine support enabled

9.5. Using the Perl Package Manager

If you are using ActivePerl on Windows, or the Perl/Apache/mod_perl binary distribution discussed in Chapter 2, you will have access to a handy utility called ppm. This program installs Perl modules from archives separate from the CPAN that contain precompiled versions of certain modules.

For first-time configuration, do the following:

C:\> ppm
PPM interactive shell (2.1.5) - type 'help' for available commands.
PPM> set repository theoryx5 http://theoryx5.uwinnipeg.ca/cgi-bin/ppmserver?urn:/PPMServer
PPM> set repository oi http://openinteract.sourceforge.net/ppmpackages/
PPM> set save
PPM> quit
C:\>

These steps will allow you to access a number of interesting packages not available from the ActiveState archive (including mod_perl). To see a list of these packages, type search in the PPM interactive shell, or visit http://openinteract.sourceforge.net/ppmpackages/ and http://theoryx5.uwinnipeg.ca/ppmpackages/.

Now, when you want to install a module, issue the following commands:

C:\> ppm
PPM> install Some::Module
PPM> quit
C:\>

It's as easy as that! Alternatively, you might want to do it directly:

C:\> ppm install Some::Module

This will have the same effect.