This is a brief guide to installing modules. For some background on what a module is and where they live on the system see the Simple Module Tutorial

The Basics of Module Installation

Fixing common problems

• When I perl Makefile.PL I get a Warning: prerequisite Foo::Bar failed to load: Can't locate foo/bar.pm in @INC....
• I get an error saying "Can't find make"
• make/nmake reports missing files
• make test reports errors
• I don't have permission to install a module on the system!

Tools to make the job easier CPAN and PPM

• CPAN.pm
• PPM

Installing Modules that include elements coded in C

The Basics of Module Installation

Most modules are available from CPAN - the Comprehensive Perl Archive Network. They are supplied in what is known as a tarball. A tarball is a gzip compressed tar file. When a module is made the directory structure it lives in is converted to a single file that contains both the files and the directory information. A program called tar performs this function and the resultant file is called a tar file. Tar files have a .tar file extension. This tar file is then compressed using the gzip (GNU Zip) program. Gzipped files have a .gz extension thus a standard module will be called something like:

Some-Module-0.01.tar.gz

The first part is the name, the next part the version number and the last part the .tar.gz extension signifying that this is a tarball. You uncompress a tarball using the tar program like this (the $ represents the command prompt):

$ tar -zxvf Some-Module-0.01.tar.gz

All *nix systems will have a tar program. On windows you can use CYGWIN which is a set of UNIX tools ported to Win32 to get tar but programs like WinZip will handle extracting tarballs just fine.

Once your have extracted your tarball you then need to make and install your files. You do that like this. At the command prompt navigate your way to the directory created where you extracted the tarball.  Making your extractions in a /temp dir is a good idea in case of problems with badly made distributions. There may be several directories to move through. In our hypothetical example above we would expect the tarball to extract into a directory called "Some-Module-0.01", however it may extract to "Some" or even straight into the current working directory (this is not fun to clean up, thus the suggestion of using a /temp dir). Within this module directory we should find a file called "Makefile.PL" although it *may* be several dirs deep. Once you find the Makefile.PL you do the following:

$ perl Makefile.PL
$ make
$ make test
$ make install

This should all proceed smoothly and your module should be installed, if not see below. Note on Win32 you will need to use a program called nmake. You can get a copy from M$ here: nmake via FTP or here nmake via HTTP Once you have downloaded it you need to run the program (it self extracts) and make sure that you do this in a directory that is on your PATH. The PATH is a list of directories that Win32 will search for executable files. When you type nmake you want Windows to be able to find the program so it must be in one of the directories on the PATH. To see your current PATH type PATH at the command prompt. C:\WINDOWS or C:\WINNT will be a fairly safe bet.

Now that you have got nmake and extracted it in a directory on your PATH you just do this:

C:\> perl Makefile.PL
C:\> nmake
C:\> nmake test
C:\> nmake install

Ok either everything went fine or you got some errors. Note in the following read nmake for make if your are on Win32

Fixing common problems

When I perl Makefile.PL or make test I get a Warning: prerequisite Foo::Bar failed to load: Can't locate foo/bar.pm in @INC....

Some modules have dependencies. They depend on other modules to function. These are specified in the Makefile.PL in the line:

'PREREQ_PM' => { Foo::Bar => 1.5 }

This line specifies that the module you are trying to install require a module called Foo:Bar and that the version of this module must be 1.5 or greater. If you get these type of errors you will need to download and install these module(s) first. You should find details in the README file - did you READIT?

Some Authors forget to edit their Makefile.PL with dependencies - in this case you will generally get this error message when you run the tests as the new module tries to load non-existent modules on which it is dependent.

I get an error saying "Can't find make"

As noted before when you say make/nmake the operating system looks along the path for an executable by the right name. If it can't find one you get this error. To fix it simple modify your path or specify the full path to the executable such as:

$ ~/make

This tells the operating system to use the make executable in your home directory where you just put it OK

make/nmake reports missing files

When you run make/nmake it looks for a file called MANIFEST which lists all the files that should be present in the distribution. If some are missing you get an error like:

$ make
Checking if your kit is complete...
Warning: the following files are missing in your kit:
Foo.bar
Please inform the author.
$

This is slack on the authors part for producing a broken distribution. Get a good one!

make test reports errors

While modules should be portable across operating systems some are not. To ensure that a module is working correctly most authors develop a test suite of programs that ensure the module is behaving as expected. When you run:

$ make test

These scripts are all run. Some errors are trivial but some are significant. If you get errors consult the README and look at the results to see what is broken. The author will want to know about these and may be able to help fix them.

If you get a lot of errors it is probably wise not to make install and install the module.

I don't have permission to install a module on the system!

If you don't have root permission you will not be able to install a module in the usual place on a shared user system. If you do not have root access you may get errors like:

$ make install
Warning: You do not have permissions to install into 
/usr/local/lib/perl5/site_perl/5.005/i386-freebsd at 
/usr/libdata/perl/5.00503/ExtUtils/Install.pm line 62.
mkdir /usr/local/lib/perl5/site_perl/5.005/CGI/Simple: 
Permission denied at /usr/libdata/perl/5.00503/ExtUtils/Install.pm line 120
*** Error code 2

 This is easy to get around. You just install it locally in your home directory. Make a directory called say /lib in your home directory like this:

# first navigate to your home directory
$ cd ~

# now make a directory called lib
# on UNIX
$ mkdir lib
# on Win32
C:\> md lib

Now you have a directory called ~/lib where the ~ represents the path to your home dir. ~ literally means your home dir but you knew that already. All you need to do is add a modifier to your perl Makefile.PL command

$ perl Makefile.PL PREFIX=~/lib LIB=~/lib

This tell MakeMaker to install the files in the lib directory in your home directory. You then just make/nmake as before. To use the module you just need to add ~/lib to @INC. See Simple Module Tutorial for full details of how. In a nutshell the top of your scripts will look like this:

#!/usr/bin/perl -w
use strict;
# add your ~/lib dir to @INC
use lib '/usr/home/your_home_dir/lib/';
# proceed as usual
use Some::Module;

Tools to make the job easier CPAN and PPM

There are some tools to make installing modules even easier. They may be difficult to get working through firewalls or proxies. Read the docs for configuration hints.

CPAN.pm

CPAN.pm is a perl module that installs perl modules! It is part of the standard distribution so you should have a copy available. The easiest way to use it is like this (note the use of different quotes on different OSs):

# Win32
C:\> perl -MCPAN -e "shell"

# UNIX
$ perl -MCPAN -e 'shell'

This fires up the interactive shell. Follow the prompts and accept the defaults.

PPM

PPM is the Perl Package Manager from ActiveState. See A guide to installing modules for Win32 for full details. It installs special versions of CPAN modules wrapped in an XML format called a PPD file. To file up the shell:

C:\>PPM
PPM>

Type help at the prompt for commands and see the docs. If you can't get PPM to work through your proxy/firewall then download the .zip files of the PPD files from here, unzip them, navigate to the directory you unzipped them into and then run:

C:\>PPM install Some-Module.ppd

Installing Modules that include elements coded in C

The most difficult modules to install are generally those that include parts of the module written in C. These modules require that you have a *good* C compiler on your system - generally gcc is best. On most UNIX systems you will have a C compiler but on Win32 you will probably not have as it is not a part of Windows. If you do not have a C compiler you will need to install one. Get a copy of gcc direct from the source here:

http://www.gnu.org/software/gcc/gcc.html

Getting modules compiling on Win32 can be tricky. See A Practical Guide to Compiling C based Modules under ActiveState using Microsoft C++. Just getting cygwin/MinGW and gcc is not enough. The easiset solution is to try to find a precompiled binary version (try ActiveState for a PPM or the Author) or email the Author the tale of your woes. If you are using Win32 expect the author to suggest you get a real OS but.....

cheers

tachyon

Corrected a few technical inexactitudes (similar to issues ;-) thanks to Hanamaki