Jon Orwant has a good tutorial about installing Perl modules, called perlmodinstall - http://perldoc.perl.org/perlmodinstall.html - which is distributed with Perl. It is more detailed than this document, and has probably been updated more recently. I wrote this back when that doc was fairly sparse. This document is not actively maintained.
This document describes the procedure for installing Perl modules, on Unix and NT. It covers CPAN.pm for Unix, the PPM for NT, and a variety of methods of installing 'manually'. Unless specifically stated, when I refer to NT, I really mean all Win32 platforms, including Win95 and Win98. I don't have Windows 2000 installed yet, but I have no particular reason to think that these procedures won't work there.
This document, or any subsequent revision of this document, should always be available at http://www.rcbowen.com/imho/perl/modules.html
Before you install a module, you need to get it. Both Unix and NT have an automated method of getting and installing modules (CPAN.pm and PPM, respectively) but if you are not using those, for whatever reason, you will need to go to CPAN to retrieve the module files.
The first thing that you will need to do is to get the module from CPAN. You can find a CPAN mirror by looking at the file called MIRRORED-BY. You can find a copy of that file at http://www.cpan.org/MIRRORED.BY You can search CPAN for a module that does a particular thing by going to http://search.cpan.org/
The various modules are in .tar.gz format, which is a compressed archive
format.
The file will have a name something like File-Archive-0.53.tar.gz,
indicating that the module is called File::Archive and the version
number is 0.53.
The instructions will tell you to decompress, or unpack, the file.
On a Unix machine, this can be done with the tar and gzip programs,
which are almost certainly installed on your machine.
gunzip File-Archive-0.53.tar.gz
tar -xf File-Archive-0.53.tar
With some versions of tar, you can do this all in one command:
tar -zxf File-Archive-0.53.tar.gz
This will create a subdirectory called (in this case) File-Archive-0.53.
On Windows, you can unpack a .tar.gz file with WinZip, or other similar unzip program. You can get WinZip from http://www.winzip.com/
Most people working with Perl are using one variety or another of Unix. That's just the way that the community is made up. So when you read the instructions in the README file that comes with every module, it will make the assumption (in most cases) that you are running Unix. There are 3 normal ways to install a Perl module on a Unix machine. Which one you use will depend on a number of factors, the most important one being whether you have root privileges on the machine.
The standard way to install a Perl module on Unix is to change into the directory that was created when you unpacked the .tar.gz file, and then type the following sequence of commands:
perl Makefile.PL
make
make test
make install
This will create a makefile for you, then compile the module, test it, and put it in the correct location for you. This requires that you are logged in as root, so that you can copy files to the Perl library directory, and various other places on your system where the installation will put files.
If you do not have root permissions on the machine where you want to install the module, such as if you wish to install a module in your home directory, just change one of those commands. Instead of
perl Makefile.PL
type
perl Makefile.PL PREFIX=/path/to/where/you/want/it
That will put all the files in that directory. In order to use modules that are stored in that location, you will need to add the following like to your Perl programs:
use lib /path/to/where/you/want/it
Perl comes with a very handy module called CPAN.pm that automates the process of downloading and installing a Perl module. There are some modules that are really helpful to have installed before you use CPAN.pm. They are not absolutely required, but they make life a lot easier. These modules are:
Digest::MD5
HTML::Parser
MIME::Base64
URI
libnet
libwww
You can download and install those modules as described in the section above. Then you can load the CPAN.pm shell with the following command:
perl -MCPAN -e shell
This also requires that you are root.
The first time that you run the CPAN shell, you will need to make some configurations. It's usually OK to select all the defaults. When you come to the section about choosing a CPAN mirror, try to choose one that is located near to you.
Once you have typed the above command, you will be at an interactive prompt with a huge number of options to make your life easier. The only ones that I will talk about here are the search feature, and the installation feature.
To find a particular module, use the i command, followed by an expression
that you want to search for:
cpan> i /Time/
CPAN.pm will go out to the CPAN mirrror that you selected, download the list of modules, and tell you which ones match the search word.
To install a module, just type:
cpan> install Time::CTime
CPAN.pm takes care of the whole process. It downloads the compressed file, unpacks it, builds it, and installs it all for you, unless there is a problem with the installation process. If there are other modules on which this module relies, it will also download and install those.
Occasionally, you will not be able to use any of the methods above to install modules. This may be the case if you are a particularly under-privileged user - perhaps you are renting web space on a server, where you are not given rights to do anything.
It is possible, for some modules, to install the module without compiling
anything, and so you can just drop the file in place and have it work. Without
going into a lot of the detail, some Perl modules contain a portion written in
some other language (such as C or C++) and some are written in just in Perl.
It is the latter type that this method will work for. How will you know? Well,
if there are no files called something.c and something.h in the package,
chances are that it is a module that contains only Perl code.
In these cases, you can just unpack the file, and then copy just the *.pm files to a directory from which you will run the modules. Two examples of this should suffice to illustrate how this is done.
IniConf.pm is a wonderful little module that allows you to read configuration
information out of a .ini-style config file. IniConf.pm is written only
in Perl, and has no C portion. When you unpack the .tar.gz file that you got
from CPAN, you will find several files in there, and one of them is called
IniConf.pm. This is the only file that you are actually interested in.
Copy that file to the directory where you have the Perl programs that will
be using this module. You can then use the module as you would if it was installed
"correctly," with just the line:
use IniConf;
Time::CTime is another very handy module that lets you print times in any format
that strikes your fancy. It is written just in Perl, without a C component.
You will install it just the same way as you did with IniConf, except that the
file, called CTime.pm, must be placed in a subdirectory called Time. The colons,
as well as indicating an organization of modules, also indicates a directory
structure on your file system.
As mentioned above, the instructions that come with most Perl modules assume that you are installing the module on a Unix system. So, the following methods should make things reasonably easy on Windows.
ActiveState Perl comes with a command-line tool called PPM - the Perl Package Manager - that simplifies the process of installing Perl modules on NT. To get into the PPM, go to a DOS prompt, and type
ppm
You should now see a prompt that looks like:
PPM>
at which you can type commands. There are a large number of commands that you can use, and there is very good documentation for PPM that comes with your distribution of Perl, so I'll just talk about two of the functions - searching for a module, and installing that module.
To search for a module, use the search function:
search Time
The search should, by default, be case-insensitive, although you can configure this.
This will return a list of all the modules that matched this search, and the file that the module is contained in. You can then install the module with the install command
install Time-modules
PPM will take care of downloading and installing the module for you.
Unfortunately, there are a limited number of modules available for installation via PPM. This number is growing, and you can request a particular module by going to the ActiveState web site and sending someone a note. However, if you need a module right now, you might be able to install it manually, as described above in the section about installing modules manually on Unix.
There are several available documents about writing and maintaining modules, as well as some about using modules. perlmod talks about what modules are. perlmodinstall talks about installing modules, but, as mentioned earler, it is a little dated.
At http://www.iserver.com/support/addonhelp/proglang/perl5/modules.html you will find a very detailed description of how to install Perl modules somewhere other than the default locations.
This document is entirely the fault of Rich Bowen <rbowen@rcbowen.com>. All questions, comments, and complaints should be directed to him.