This document assumes that you:

• you probably don't have root access
• know basic Unix/Linux commands, and that you're using BASH as your shell
• know how to use a Unix/Linux text editor
• know how to read Unix/Linux path names
• know basic Perl

Why install CPAN?

Quite simply CPAN.pm takes care of those piddling details which can make perl module installation so painful - it will find, ftp, decompress, install and make any module you want, as well as checking you also have any modules further up the chain of inheritance, stopping runtime errors on scripts which are trying to USE modules which themselves USE modules that you didn't know you needed to install (Net::FTP is a good example of this fish hook behavior as it basically inherits from Net::cmd, and without that you get nothing but a nice cascade display).

However if you don't have, or don't want to use the disk space (10Mb approx), installing any perl module is basically the same:

1. make a site_perl folder somewhere in your user account :
   [SHELL PROMPT ]$ mkdir site_perl
2. set the environment variable PERL5LIB:

   [SHELL PROMPT ]$ cd ~

   [SHELL PROMPT ]$ vim .bashrc

   [VIM PROMPT ]$ PERL5LIB=/path/to/my/site_perl

   [VIM PROMPT ]$ export PERL5LIB

   This only affects the Environment variables of the shell so you may have to logout and re-login in before the new path will become active, you can check if it's set correctly by typing:

   [SHELL PROMPT ]$ echo $PERL5LIB

   if this command doesn't seem to print anything, or, if it prints something different from what you typed, the variable hasn't been set correctly. Repeat the last few steps again)

3. FTP the module into your site_perl folder

[SHELL PROMPT ]$ cd /path/to/your/site_perl

[SHELL PROMPT ]$ ftp ftp.your.fave.ftp.site

ftp> get /path/to/yourmodule.tar.gz [space]/path/to/your/site_perl/yourmodule.tar.gz

ftp> quit

221 Goodbye.

4. *DECOMPRESS the file:
   

   [SHELL PROMPT ]$ gzip -d yourmodule.tar.gz

5. *UNPACK the file :

   [SHELL PROMPT ]$ tar -xvf yourmodule.tar

   *Note:
   these last two steps can be compacted into 1 line, with the added bonus of saving of disk space by not ending up with a copy of 'file.tar' sitting in the install directory:

   gunzip -c file.tar.gz | tar xvf -

   gzcat examples.tar.gz | gnutar xf -

   gnutar xvfz filename.tar.gz -C archive_name

6. BUILD the module (sometimes unnecessary):
   

   [SHELL PROMPT ]$ perl Makefile.PL LIB=/path/to/my/site_perl \
   INSTALLMAN1DIR=/path/to/my/man/man1 \
   INSTALLMAN3DIR=/path/to/my/man/man3

   [SHELL PROMPT ]$ make

   [SHELL PROMPT ]$ make test

7. INSTALL the module:
   

   [SHELL PROMPT ]$ make install

8. At this point you may get some errors:
   

   If the error is about a file not being created:
   

   1. create the path to the file as indicated
   2. install again.

   If the error says a module may is missing:
   

   1. FTP the module into your site_perl folder
   2. go through the installation process as described above with the missing module.

In your scripts and cgis, insert the line (perl versions 5.002 and later): use lib '/path/to/my/site_perl';

or for earlier perls (5.001 and before):BEGIN { unshift(@INC, "/path/to/my/site_perl") }

so the perl interpreter will know to check your site_perl dir for modules.

CPAN specifics

Before getting into the nuts and bolts of CPAN, there's one caveat you should be aware of:

If you install a newer CPAN bundle (version 1.60 and above), it will automatically try to install the latest version of perl (currently 5.8.0).

That said, this is more of an annoyance than a threat - CPAN can't install the perl interpreter without asking you for configuration information, but it can be pretty scary the first time it happens - so until this 'feature' is removed from the cpan mod (yes it's quite unpopular with a lot of people), if you have a perl version number lower than 5.8.0, expect this to happen everytime you run CPAN. The first thing you should do then is check what version of perl is on the system, so you know what you're dealing with:

Untarred and unzipped the latest perl bundle is around 24Mb, if that doesn't worry you then just leave it where it is (or even placate CPAN and go ahead and install it). If you have a set disk quota however, you can delete it - you'll find the bundle archive inside a directory called 'build' in the CPAN directory - (see the instructions below on configuring CPAN for how to get this path)

Installing CPAN.pm

[SHELL PROMPT ]$ perl -MCPAN -e shell

the first time you run it you'll be prompted for config info, in most cases the default values are fine (just press enter without writing anything), but you must make sure you set the following two correctly for either CPAN.pm, or any modules it installs, to work correctly:

cpan> cpan_home: /path/to/my/site_perl/ANY_NAME_YOU_WANT

cpan> makepl_arg: LIB=/path/to/my/site_perl

cpan> o conf

CPAN::Config options:
*commit	Commit changes to disk
*defaults	Reload defaults from disk
*init	Interactive setting of all options
build_cache	10
build_dir	/path/to/my/site_perl/ANY_NAME_YOU_WANT/build
cpan_home	/path/to/my/site_perl/ANY_NAME_YOU_WANT
ftp	/usr/bin/ftp
ftp_proxy
getcwd	cwd
gzip	/usr/bin/gzip
http_proxy
inactivity_timeout	0
index_expire	1
inhibit_startup_message	0
keep_source_where	/path/to/my/site_perl/ANY_NAME_YOU_WANT/sources
lynx	/usr/bin/lynx
make	/usr/bin/make
make_arg
make_install_arg
makepl_arg	PREFIX=/path/to/my/site_perl
ncftp	/usr/bin/ncftp
no_proxy
pager	/usr/bin/less
shell	/bin/bash
tar	/bin/tar
unzip	/bin/unzip
urllist	ftp://cpan.nas.nasa.gov/ pub/perl/CPAN/
wait_list	wait://ls6.informatik.uni-dortmund.de:1404

*note: the first 3 are commands

see the relevant MAN page or PODs for more information on how to set or unset these variables, do this by typing

either:

[SHELL PROMPT]$ perldoc CPAN

or:

[SHELL PROMPT]$ man CPAN

Once installed correctly, adding other modules to your site_perl becomes a breeze - just type:

[SHELL PROMPT ]$ perl -MCPAN -e shell

cpan> install MODULE

and CPAN.pm does the rest. Maintaining existing modules becomes a lot easier too, through CPAN you can check for newer releases. For a brief summary of CPAN.pm's commands use the CPAN shell's own internal help function: