CPAN

POSSIBLE OUTDATED INFORMATION!

  • DreamHost does not directly support any of the features described on this page. Use at your own risk!
  • Support for these instructions is not available from DreamHost tech support.
  • Server changes performed by DreamHost may break your modifications. You, as the user, are responsible for troubleshooting and resolving issues with your customizations.
  • If you require root/sudo access to run a command, you must upgrade to a Dedicated server and add an admin user.

The Comprehensive Perl Archive Network (CPAN) allows you to use an extensive library of pre-made modules available at http://search.cpan.org.

CPAN normally requires root access, but this article shows you how to set up CPAN as a non-root user.

Setting up CPAN

  1. Log into 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, then 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 click 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. Click 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:
    
    export PERL_LOCAL_LIB_ROOT="$PERL_LOCAL_LIB_ROOT:/home/username/perl5";
    export PERL_MB_OPT="--install_base /home/username/perl5";
    export PERL_MM_OPT="INSTALL_BASE=/home/username/perl5";
    export PERL5LIB="/home/username/perl5/lib/perl5:$PERL5LIB";
    export PATH="/home/username/perl5/bin:$PATH";
    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.

Installing modules

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
    

Viewing modules

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.24
    CPAN_FILE    G/GR/GRANTM/XML-Simple-2.24.tar.gz
    MANPAGE      XML::Simple - An API for simple XML files
    INST_FILE    /home/username/perl5/lib/perl5/XML/Simple.pm
    INST_VERSION 2.24

Making your FastCGI / CGI scripts work

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

Installing Module::Build and many other modules

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 .profile (or .bash_profile), otherwise anything you build won't know how to read the Module::Build Build script.

Other modules

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 say:
    INSTALLARCHLIB = $(SITEPREFIX)/lib/perl/5.10
  4. Proceed with your make/make test/make install.

Configuring CPAN

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

Using CPAN Minus and local::lib

Tatsuhiko Miyagawa's CPAN Minus (github cpan) 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.

Killed

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

 

Did this article answer your questions?

Article last updated PST.