How to install Perl modules - Printer Friendly

From Apply Now,Your Guide to Perl / PHP.

Introduction

One of the most important things Perl programmers have to learn is how to install Perl modules on Unix and Windows. There are two basic methods for installing modules. You can go directly to CPAN, download the module, and install it manually. Or you can use one of the automated methods, such as the CPAN module for Unix or the Perl Package Manager (PPM) for Windows.

In this tutorial we'll first cover the standard installation procedure for modules available from CPAN. Next we'll learn how to use the CPAN module for Unix. Then we'll look at how to use PPM for Windows.

What is CPAN?

The Comprehensive Perl Archive Network, or CPAN, is the main repository of all the available modules for Perl. The stated goal for the site is "to contain all the Perl material you will need", and this is certainly true for the Perl Ports (Binary Distributions of Perl) and Perl Modules. They do have some scripts, but this isn't one of the premiere script listings available. However, it's the starting point for finding the module you need.

Finding the Perl modules you need

If you know what you want, the easiest way to find it is to use one of the search links from the CPAN home page. You'll find what you need from any of them, but the one I use most is the "CPAN modules, distributions, and authors " link. I like it because it makes modules really easy to find.

For instance, if you want to see the available modules for a specific category, such as Security, click the link and there they are. If the category isn't listed, use the search box. The listing will provide you with the list of modules, their documentation, and a file to download. For instance, if you do a search for "SMTP", you'll find all the modules that use it to send email. It's a really nice way to see what's available.

If you're interested in browsing through all the modules just to see what's available, click on the modules link from the CPAN home page. You'll see a menu that will let you choose how to view the list of modules (the complete list, by author, category, etc.). Also, there is an article detailing How To Install Modules, which is a comprehensive explanation of how to install modules on specific platforms. We're only covering Unix and Windows in this tutorial, but if you're on another platform you'll find the information you need in the CPAN article.

How to build and install Perl modules

Once you find a module go ahead and download it, and you're ready for the next step. Standard module installation involves four steps: Decompressing, Unpacking, Building, and Installing. Let's look at each step.

Decompressing and Unpacking the module

The files you'll download from CPAN are all nicely packaged in files most commonly ending in .tar.gz, and less commonly in .zip. On Unix, you can decompress by typing

=======
gzip -d module.tar.gz
=======

To unpack type

=======
tar -xof module.tar
=======

Or you can decompress and unpack in one step by typing

=======
gzip -dc module.tar.gz | tar -xof -
=======

If you're using Windows, you can decompress and unpack the file by using WinZip. Note that your browser may have renamed the .tar.gz file to" _tar.tar". For example, if you downloaded "module.tar.gz" it may show up on your computer as "module_tar.tar". Just rename it "module.tar.gz" before trying to open it with WinZip.

Once you decompress and unpack the module files, you're ready to build them. However, be sure and read both the README and INSTALL files that come with your module, because this step isn't always necessary.

If you're on Unix type

=======
perl Makefile.PL
make make test
=======

If you're on Windows, type

=======
perl Makefile.PL
nmake nmake test
=======

If you don't have nmake on your system, it is freely available from Microsoft.

Installing the module

The final step is to install the module by typing

=======
make install (for Unix)
=======

=======
nmake install (for Windows)
=======

It didn't work, now what?

OK, the install failed. It may be that you don't have root access or you aren't allowed to install modules into the standard Perl directories. That's all right, you can still install and use your module, and here's how.

When you build a module, the first command is usually

=======
perl Makefile.pl
=======

But if you don't have permission to install the module in the standard directories, you can specify a directory by typing

=======
perl Makefile.PL PREFIX=/module_directory
=======

That way you can install the module into a directory of your choosing. This works well if your ISP won't let you install the module in the standard Perl directories, and won't do the installation for you. Just create the directory in your account space and specify it when you build. When you type make install, it will install the files into that directory.

Automating Module Installation

If you're on Unix, you can automate the installation process by using the CPAN module (CPAN.pm). This module is designed to query, download, and install modules from CPAN. You'll have to download and install it manually, and once you're done type

=======
perl -MCPAN -e shell
=======

If it's the first time you've used it, then you will be asked a series of questions that will configure the program. After that you can use it interactively to automate module installation. The process is self-explanatory, but you can type 'h' to get help. It's very simple to use, for instance installing a module is as easy as typing

=======
cpan> install <module>
=======

If the module is already installed, CPAN.pm will check to see if it's up to date. If it isn't, then the module is updated. If it is, it will print "module up to date" and it won't try to reinstall it.

Do read the documentation, since there's more you can do with CPAN.pm that we aren't going to cover in this tutorial.

Automated installation with PPM

Those of you using Windows can also automate module installation by using the Perl Package Manager (PPM) that is part of the Perl for Win32 installation. PPM doesn't connect to CPAN, but uses package repositories instead. For a current list, please see the PPM FAQ.

To use PPM make sure you're connected to the Internet and type

=======
PPM
=======

at the command line.

To find out what packages are available type search <pattern>. For example, to find out what modules are available to read email using POP3, type

=======
search POP3
=======

and you should see something like

=======
Mail-POP3 Client
=======

When you're ready to install type

=======
install <packagename>
=======

As with CPAN.pm, be sure and read the documentation. There's more you can do with PPM, but we're not going to go into the details in this tutorial.

What if the Perl script can't find the module?

If your script fails because it can't find the module, here is a little debugging script you can use to try and solve the problem. It will direct error messages to your browser so that you can see what is going on. The most likely problem will be that there's an incorrect path, and the message will help you see what path is being used.

#!/path/to/perl
#===============================
# How to send debugging messages to a browser
# Copyright, Emmie P. Lewis
#===============================
# This script is designed to help debug module
# installation problems.
#===============================

use strict ;

print "Content-type: text/plain", "\n\n" ;

# This will send fatal error messages to your browser
# Use it whenever you are seeing the "Internal Server Error" message
# in your scripts
use CGI::Carp qw(fatalsToBrowser) ;

# This should be the path to the directory
# you used when you installed the module
# Modify this path when you run the script
use lib '/path/to/module/directory' ;

# Change this name to your module name
# Check the module documentation for
# the correct way to include it in a script

use "ChangeMe" ;

# This line will print the contents of Perl's @INC variable
# If you see something like "@INC is [... a bunch of pathnames ...]",
# then you'll be able to use your module

print "\@INC is @INC\n" ;

Summary

Although the idea of installing modules can be daunting the first time you try, it's gets to be fairly routine after you've done it a few times.

I encourage you to spend some time browsing CPAN and the ActiveState Repository, just to see what's available. Your programming jobs are so much easier if you can use code that is readily available.

Why spend time writing code when you can download it for free? You don't have to be an expert to use modules. They'll broaden your horizons, help you accomplish something you might not know how to do, and maybe teach you something about programming in Perl. Not a bad deal, huh?