Help File Library: Installing and Using CPAN.pm

Written By: Robin McFarlane

This document assumes that you:

• know basic Unix/Linux commands
• 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 the disk space, 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. Repeat the last few steps again)

3. FTP the module 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

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

To install CPAN.pm - follow the installation procedure as above, once installed and you've checked that the path to your site_perl folder is set correctly in the ENVIRONMENT variables you can start up the CPAN shell by typing:

[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

you can check these values in the CPAN shell at any time by typing:

cpan> o conf

which outputs a listing of all the config variables like this:

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:

cpan> ?

Or for a sharper learning curve read the pods in HTML format http://theoryx5.uwinnipeg.ca/CPAN/perl/CPAN.html">here.

Robin McFarlane robinmcf@altern.org