local::lib

Official Website: CPAN

Why

Most Perl web apps have CPAN dependencies. Your shared hosting account probably comes with access to many pre-installed CPAN modules, but chances are your webapp depends on one or more CPAN modules that aren’t installed. Or perhaps a required module is installed, but it’s an old version.

local::lib is the preferred way of installing custom CPAN modules.

How

# get rid of any existing cpan configuration

mv ~/.cpan ~/.cpan_original

# if you can run wget

wget -O - http://cpanmin.us/ | perl - local::lib App::cpanminus && echo 'eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)' >> ~/.bashrc && . ~/.bashrc

# or if you can run curl

curl -L http://cpanmin.us/ | perl - local::lib App::cpanminus && echo 'eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)' >> ~/.bashrc && . ~/.bashrc

# otherwise, FTP up the contents of http://cpanmin.us to a file called cpanmin.us, make it executable and then run:

./cpanmin.us local::lib App::cpanminus && echo 'eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)' >> ~/.bashrc && . ~/.bashrc

Or failing all of that, follow the “bootstrapping technique” on the local::lib CPAN page.

As a bonus, we also installed installed cpanminus along the way.

Watch the output while the above commands are running to make sure that your perl process doesn’t get killed mid-way through. If that happens, remove the ~/perl5 directory and try again.

If everything worked, you now have a ~/perl5 directory where custom CPAN modules get installed. We modified your .bashrc so that your shell environment gets automatically configured in such a way that CPAN clients such as cpan and cpanminus automatically install new CPAN modules into your local lib.

Remember to tell Perl!

It’s all very well to have your custom CPAN modules nicely installed in ~/perl5, but you have to make sure your web server knows where to find them. When you run perl from the command line, your shell environment is configured such that Perl knows where to find your local lib. However when, say, Apache runs your script in CGI mode, it’s not going to know to look in ~/perl5. It will only use the system Perl INC paths, and chances are your server doesn’t even have local::lib installed!

So it’s vitally important that you put a “use lib …” line at the top of all of your Perl scripts, giving Perl enough information to find the location of local::lib, followed by a “use local::lib” so that local::lib can do its thing and make sure all your INC paths are correct before your script actually does anything.

For example, assuming the home dir of your shared hosting account is “/home/patrick“, you would put the following two lines at the top of your Perl script, right below the shebang line:

use lib "/home/patrick/perl5/lib/perl5";
use local::lib;