Installing Perl modules on BinAC

This tutorial describes the installation of Perl modules in your $HOME directory without root privileges. The underlying idea is to install the module local::lib in your $HOME first, which then configures your working directory to place all modules installed by cpanm in $HOME.

Installing local::lib

First of all Perl 5.26 has to be loaded with module load. This version of Perl comes with cpanm installed.

$ module load devel/perl/5.26

After that you have to change into $HOME and install local::lib.

$ cd $HOME
$ wget cpan.metacpan.org/authors/id/H/HA/HAARG/local-lib-2.000024.tar.gz
$ tar xvf local-lib-2.000024.tar.gz
$ cd local-lib-2.000024
$ perl Makefile.PL --bootstrap
$ make test && make install
$ rm ~/local-lib-2.000024.tar.gz

Visit https://metacpan.org/pod/local::lib to learn more about local::lib.

Configuring the working environment

Having a properly configured working environment is crucial to the execution of programs. For instance, it determines the availability of programs and their versions. Therefore we will take a look at the environment variables that are relevant for a Perl environemnt. You don't have to touch them just to install new modules but they help in understanding how Perl searches for installed modules.

By default, Perl looks for a module in a number of specific directories. If it cannot find the module it returns an error message like the following:

Can't locate My/Module.pm in @INC (@INC contains: /usr/local/lib64/perl5 /usr/local/share/perl5 /usr/lib64/perl5/vendor_perl /usr/share/perl5/vendor_perl /usr/lib64/perl5 /usr/share/perl5

You can list the search paths used with

$ perl -e "print \"@INC\""

which shows these paths by default:

/usr/local/lib64/perl5
/usr/local/share/perl5
/usr/lib64/perl5/vendor_perl
/usr/share/perl5/vendor_perl
/usr/lib64/perl5 /usr/share/perl5

If you load the Perl module on BinAC these paths change:

$ module load devel/perl/5.26
$ perl -e "print \"@INC\""

and should now list:

/opt/bwhpc/common/devel/perl/5.26/lib/site_perl/5.26.1/x86_64-linux-thread-multi
/opt/bwhpc/common/devel/perl/5.26/lib/site_perl/5.26.1 /opt/bwhpc/common/devel/perl/5.26/lib/5.26.1/x86_64-linux-thread-multi
/opt/bwhpc/common/devel/perl/5.26/lib/5.26.1 /opt/bwhpc/common/devel/perl/5.26/lib
/opt/bwhpc/common/devel/perl/5.26/lib/site_perl/5.26.1/x86_64-linux-thread-multi
/opt/bwhpc/common/devel/perl/5.26/lib/site_perl/5.26.1
/opt/bwhpc/common/devel/perl/5.26/lib/5.26.1/x86_64-linux-thread-multi
/opt/bwhpc/common/devel/perl/5.26/lib/5.26.1

. Perl is now using completely different directories to find modules. We are simply going to add $HOME to that list. Furthermore we use local::lib to tell cpanm to install new modules in $HOME.

Use the following lines to temporarily (until you logout) modify your environment:

$ perl -I ~/perl5/lib/perl5/ -Mlocal::lib
PATH="~/perl5/bin${PATH:+:${PATH}}"; export PATH;
PERL5LIB="~/perl5/lib/perl5${PERL5LIB:+:${PERL5LIB}}"; export PERL5LIB;
PERL_LOCAL_LIB_ROOT="~/perl5${PERL_LOCAL_LIB_ROOT:+:${PERL_LOCAL_LIB_ROOT}}"; export PERL_LOCAL_LIB_ROOT;
PERL_MB_OPT="--install_base \"~/perl5\""; export PERL_MB_OPT;
PERL_MM_OPT="INSTALL_BASE=~/perl5"; export PERL_MM_OPT;

The variables PERL_MB_OPT and PERL_MM_OPT tell Perl where new modules should be installed. In this case it is $HOME/perl5.

PERL5LIB defines the search path.

To install new modules you will also have to set PERL_CPANM_HOME to configure the installation location for cpanm, which is also $HOME/perl5.

$ eval $(perl -I ~/perl5/lib/perl5/ -Mlocal::lib)
$ export PERL_CPANM_HOME=/tmp/cpanm_$USER

You can also put all of the lines above in your ~/.bashrc to run them automatically whenever you log in.

Installing new modules

Finally we can install modules using cpanm, which offers dependency management and improved error messages compared to cpan. As an example we will install the module Path::Tiny.

Note that modules installed in $HOME won't be found automatically if you log in again and didn't put the environment modifications in your ~/.bashrc.

$ cpanm Path::Tiny

Removing modules

Cpanm can also be used to remove modules.

$ cpanm --uninstall Path::Tiny

Resetting your working environment

If you made a mistake while configuring your environment variables and didn't modify your ~/.bashrc, simply logging out and back in will restore the environment.

In case you modified ~/.bashrc you need to remove the lines you added first and then log out and back in again.

If you want to remove the files created during this tutorial run:

$ cd $HOME
$ rm -rf local-lib-2.000024
$ rm -rf perl5/
$ rm -rf .cpanm/