Using CPAN with a non-root account

CPAN can be configured differently for each user, and can install modules to custom areas on a system. The sample configuration below installs modules under ~/lib/perl5, man pages under ~/share/man and (hopefully) everything else under the home directory. This approach also works for individual software trees required for special applications that run as non-privileged accounts: simply adjust the installation paths to suit the software depot in question.

Consult Life with CPAN for more information about the Comprehensive Perl Archive Network (CPAN). Consider also local::lib to bootsrap custom Perl module installation directories.

Configuration

1. Download the sample MyConfig.pm, and move it to ~/.cpan/CPAN/MyConfig.pm.

   $ mkdir -p ~/.cpan/CPAN
   $ mv MyConfig.pm ~/.cpan/CPAN

2. Customize the MyConfig.pm file.
   

   1. Change all occurences of HOMEDIRFIX to your home directory, for example /home/username.
      
   2. Review the makepl_arg arguments. For more information on the arguments, see ExtUtils::MakeMaker.
      

   3. Check the paths to various commands (e.g. wget), proxy settings for your environment, the urllist, and the shell.

      Be sure to remove the UNINST=1 option on make_install_arg for any non-system-wide configuration as otherwise CPAN will attempt to remove “shadowing” versions of the module installed for the site perl, leading to error messages involving forceunlink.

   4. Test MyConfig.pm for problems.

      $ perl -c MyConfig.pm
      MyConfig.pm syntax OK

3. See below for the required PERL5LIB settings to customize @INC, if installing modules that depend on previously installed modules. Be sure to load the changes into your shell environment before running cpan, or to close and reopen your shell.
   

4. Test the new configuration.

   To ensure Makefile are being generated with the proper paths, make a module from the CPAN shell, then review at the paths set in the resulting Makefile.

   cpan> make Text::Autoformat
   …
   cpan> look Text::Autoformat
   …
   $ less Makefile
   $ grep /home/username Makefile
   SITELIBEXP = /home/username/lib/perl5
   PREFIX = /home/username/
   INSTALLPRIVLIB = /home/username/lib/perl5
   INSTALLSITELIB = /home/username/lib/perl5
   INSTALLVENDORLIB = /home/username/lib/perl5
   INSTALLARCHLIB = /home/username/lib/perl5/darwin-thread-multi-2level
   INSTALLSITEARCH = /home/username/lib/perl5/darwin-thread-multi-2level
   INSTALLVENDORARCH = /home/username/lib/perl5/darwin-thread-multi-2level
   INSTALLMAN1DIR = /home/username/share/man/man1
   INSTALLSITEMAN1DIR = /home/username/share/man/man1
   INSTALLMAN3DIR = /home/username/share/man/man3
   INSTALLSITEMAN3DIR = /home/username/share/man/man3
   $ exit

   If the Makefile has the wrong path set for any variables, update the makepl_arg arguments in MyConfig.pm to set these variables to install to the proper custom location.

Customize @INC

Perl must be made aware of the custom /home/username/lib/perl5 library directory. Perl uses the @INC variable to hold library directories, though this varible must not be edited directly. For more information on @INC, consult perlvar (overview of variable), perlrun (command line arguments and environment variables), or lib (use lib pragma). Under a Bourne shell (such as zsh), use the following to set PERL5LIB and MANPATH environment variables.

if [ -d $HOME/lib/perl5 ]; then
PERL5LIB=${PERL5LIB:+$PERL5LIB:}$HOME/lib/perl5
fi
MANPATH=${MANPATH:+$MANPATH:}$HOME/share/man
export MANPATH PERL5LIB

Code running under Taint mode may require the use lib statement: see perlsec for details. Other applications may include different methods of setting custom environment setting, such as SetEnv under Apache:

SetEnv PERL5LIB /home/username/lib/perl5:/sw/lib/perl5