CPAN

1. Log in to your server via SSH.
2. Create the following directories:

   [server] mkdir ~/perl5/man
   [server] mkdir ~/perl5/man/man1
   [server] mkdir ~/perl5/man/man3

3. Set up CPAN to install the modules. If this is the first time you run it, it goes directly into configuration mode:

   [server]$ cpan
   

   You must use the cpan command, rather than perl -MCPAN. The latter command is not recognized as an installer, and is subject to more stringent memory limits.

4. If the CPAN setup doesn't appear, enter o conf init at the cpan> prompt:

   CPAN.pm requires configuration, but most of it can be done automatically.
   If you answer 'no' below, then enter an interactive dialog for each
   configuration option instead.
   
   Would you like to configure as much as possible automatically? [yes] yes
   

5. Type yes and then press the Enter key:

   Warning: You do not have write permission for Perl library directories.
   
   To install modules, you need to configure a local Perl library directory or
   escalate your privileges.  CPAN can help you by bootstrapping the local::lib
   module or by configuring itself to use 'sudo' (if available).  You may also
   resolve this problem manually if you need to customize your setup.
   
   What approach do you want?  (Choose 'local::lib', 'sudo' or 'manual')
    [local::lib]

6. Press the Enter key to accept local::lib:

   Now you need to choose your CPAN mirror sites.  You can let me
   pick mirrors for you, you can select them from a list or you
   can enter them by hand.
   
   Would you like me to automatically choose some CPAN mirror
   sites for you? (This means connecting to the Internet) [yes] yes

7. Type yes and then click the Enter key. Let the script run until you see the following:

   local::lib is installed. You must now add the following environment variables
   to your shell configuration files (or registry, if you are on Windows) and
   then restart your command line shell and CPAN before installing modules:
   
   PATH="/home/username/perl5/bin${PATH:+:${PATH}}"; export PATH;
   PERL5LIB="/home/username/perl5/lib/perl5${PERL5LIB:+:${PERL5LIB}}"; export PERL5LIB;
   PERL_LOCAL_LIB_ROOT="/home/username/perl5${PERL_LOCAL_LIB_ROOT:+:${PERL_LOCAL_LIB_ROOT}}"; export PERL_LOCAL_LIB_ROOT;
   PERL_MB_OPT="--install_base \"/home/username/perl5\""; export PERL_MB_OPT;
   PERL_MM_OPT="INSTALL_BASE=/home/username/perl5"; export PERL_MM_OPT;
   
   Would you like me to append that to /home/username/.bashrc now? [yes] yes

8. Type yes and then click the Enter key:

   commit: wrote '/home/username/.cpan/CPAN/MyConfig.pm'
   
   You can re-run configuration any time with 'o conf init' in the CPAN shell

   Your prompt changes to the following:

   cpan[1] 

9. Run the following. Make sure to change the username to your actual Shell username:

   cpan[1] o conf makepl_arg "install_base=/home/username/perl5 \
       LIB=/home/username/perl5/lib \
       INSTALLMAN1DIR=/home/username/perl5/man/man1 \
       INSTALLMAN3DIR=/home/username/perl5/man/man3"

10. Commit the changes:

    cpan[1] o conf commit

11. Type exit to quit CPAN:

    cpan[1] exit

    This puts you back in your normal shell.

Now that everything is set up, you can install the modules.

1. Open CPAN again:

   [server] cpan

2. Type install Some::Module, where Some::Module is the name of the module you are trying to install:

   [cpan[1] install XML:Simple
   

You can also check if and where modules are installed within CPAN. Type in the letter i followed by the module name. For example:

[cpan[1] i XML::Simple
Module id = XML::Simple
    CPAN_USERID  GRANTM (Grant McLean <grantm@cpan.org>)
    CPAN_VERSION 2.25
    CPAN_FILE    G/GR/GRANTM/XML-Simple-2.25.tar.gz
    UPLOAD_DATE  2024-04-08
    MANPAGE      XML::Simple - An API for simple XML files
    INST_FILE    /usr/share/perl5/XML/Simple.pm
    INST_VERSION 2.22

Any CGI or Fast CGI scripts must have the following at the top in order to use the locally installed modules:

use lib qw( /home/username/perlmods/lib/perl/5.x /home/username/perlmods/lib/perl/5.x.x 
            /home/username/perlmods/share/perl/5.x /home/username/perlmods/share/perl/5.x.x
            /home/username/perlmods/local/share/perl/5.x.x 
            /home/username/perlmods/local/lib/perl/5.x.x );

where username is your shell name, perlmods is what you chose above as the local CPAN install directory, and 5.x and 5.x.x refer to the currently installed Perl version determined by perl -v.

What if I see an error?

If the above cpan command generates an error like the following:

Your configuration suggests that CPAN.pm should use a working
directory of
    /root/.cpan
Unfortunately we could not create the lock file
    /root/.cpan/.lock
due to permission problems.

Please make sure that the configuration variable
    $CPAN::Config->{cpan_home}
points to a directory where you can write a .lock file. You can set
this variable in either
    /etc/perl/CPAN/Config.pm
or
    /home/username/.cpan/CPAN/MyConfig.pm

Could not open >/root/.cpan/.lock: Permission denied

then you must manually create a ~/.cpan/CPAN/MyConfig.pm file before proceeding to the next step (this is because root already configured cpan in your host.)

You can do this by entering the following:

mkdir -pv ${HOME}/.cpan/CPAN
cat > ${HOME}/.cpan/CPAN/MyConfig.pm <<eof

\$CPAN::Config = {
  'auto_commit' => q[0],
  'build_cache' => q[10],
  'build_dir' => q[\$ENV{HOME}/.cpan/build],
  'cache_metadata' => q[1],
  'commandnumber_in_prompt' => q[1],
  'cpan_home' => q[\$ENV{HOME}/.cpan],
  'dontload_hash' => {  },
  'ftp' => q[/usr/bin/ftp],
  'ftp_passive' => q[1],
  'ftp_proxy' => q[],
  'getcwd' => q[cwd],
  'gpg' => q[/usr/bin/gpg],
  'gzip' => q[/bin/gzip],
  'histfile' => q[\$ENV{HOME}/.cpan/histfile],
  'histsize' => q[100],
  'http_proxy' => q[],
  'inactivity_timeout' => q[0],
  'index_expire' => q[1],
  'inhibit_startup_message' => q[0],
  'keep_source_where' => q[\$ENV{HOME}/.cpan/sources],
  'lynx' => q[/usr/bin/lynx],
  'make' => q[/usr/bin/make],
  'make_arg' => q[],
  'make_install_arg' => q[],
  'make_install_make_command' => q[/usr/bin/make],
  'makepl_arg' => q[PREFIX=\$ENV{HOME}/perlmods],
  'mbuild_arg' => q[],
  'mbuild_install_arg' => q[],
  'mbuild_install_build_command' => q[./Build],
  'mbuildpl_arg' => q[],
  'ncftpget' => q[/usr/bin/ncftpget],
  'no_proxy' => q[],
  'pager' => q[less],
  'prerequisites_policy' => q[follow],
  'scan_cache' => q[atstart],
  'shell' => q[/bin/bash],
  'tar' => q[/bin/tar],
  'term_is_latin' => q[0],
  'term_ornaments' => q[1],
  'unzip' => q[/usr/bin/unzip],
  'urllist' => [q[ftp://cpan.cse.msu.edu/], q[ftp://cpan-du.viaverio.com/pub/CPAN/], q[ftp://cpan.mirrors.redwire.net/pub/CPAN/], q[ftp://cpan.hostrack.net/pub/CPAN]],
  'use_sqlite' => q[0],
  'wget' => q[/usr/bin/wget],
};
1;
__END__
eof

If you're installing Module::Build or others which use Module::Build in their installation, it might help to add the above PERL5LIB lines to your .bash_profile, otherwise, anything you build won't know how to read the Module::Build Build script.

Please note that some modules do not install correctly from CPAN as non-root and to a non-standard path. They must be built and installed manually (that is, using the build scripts provided with the modules). Two specifically are:

DateTime

DateTime (as of 0.68) requires the install step to be executed like so using the --install_base option:

[server]$ ./Build install --install_base ~/perlmods

IO:Compress

IO::Compress (as of 2.034) requires tweaking the Makefile because one of the target paths ignores the PREFIX environment variable.

1. Generate the Makefile using:

   [server]$ perl Makefile.PL PREFIX=~/perlmods
   

2. Open up the Makefile and look for this line:

   INSTALLARCHLIB = /usr/lib/perl/5.10

3. Change it to:

   INSTALLARCHLIB = $(SITEPREFIX)/lib/perl/5.10

4. Run make, make test, and make install.

If you need to manually configure settings, you can access your configuration in the file:

~/.cpan/CPAN/MyConfig.pm

If specifying PREFIX as above, then use the full path to your perlmods directory:

PREFIX=/home/username/perlmods

Use perldoc to get a listing of CPAN settings that you can edit:

[server]$ perldoc CPAN

Tatsuhiko Miyagawa's CPAN Minus (github ) makes it even easier to add support for your own Perl modules. Use

[server]$ cpanm -L ~/perlmod module ...

to install modules into ~/perlmod. In your script, enter the following:

use local::lib '~/perlmod';

to use these modules.

There is a monitor service running that may kill your perl installs. Visit the following article for more information.

• Why were my processes killed on my shared server?