Today we'll have a glance at how to run the Catalyst server under local::lib for development use and also how to use local::lib as a build environment for putting your application into production.

local::lib provides an easy way to localize a perl module library to a particular user's environment. It can be advantageous on shared hosts for full control over non-root installations and a powerful tool for building and deploying Catalyst applications.

The prerequisites for local::lib simply require a toolchain (make, C compiler, etc) and an outbound connection (to connect with CPAN). This tutorial was written from the perspective that the user is familiar with Catalyst and working on a Linux based system.

This article follows the bootstrap instructions for installing local::lib.

If your user does not have a ~/.cpan directory, then run this command, accept the defaults and quit when its done setup

 % perl -MCPAN -eshell 
 % cpan> exit 

The first step is to download local::lib from CPAN. As of this writing, the current version is 1.001000 so we'll grab that

  % wget http://search.cpan.org/CPAN/authors/id/A/AP/APEIRON/local-lib-1.001000.tar.gz

and unpack it

 % tar xvzf local-lib-1.001000.tar.gz

The typical installation process is very straightforward, barring any system oddities

 % cd ~/local-lib-1.001000
 % perl Makefile.PL --bootstrap
 % make test
 % make install

Note: If any of the above steps hang for any reason, you may need to go into the build directory (~/.cpan/build/CPAN-1.92) and run make install.

You should now be setup with a ~/perl5 directory, which will be used for further module installations via CPAN. To complete installation, setup your environment by adding it to your .bashrc for subsequent logins and reload the file for this session

 % echo 'eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)' >> ~/.bashrc
 % source .bashrc

You can now check that MODULEBUILDRC, PERL5LIB, PERL_MM_OPT and PATH all mention your new setup under ~/perl5 using the 'set' command

 set | egrep "MODULEBUILDRC|PERL5LIB|PERL_MM_OPT|PATH"

Now you are safe to install a few basic modules for faster downloading, checksum checking, and stopping persistant state warnings, respectively

 % perl -MCPAN -e 'install(LWP)'
 % perl -MCPAN -e 'install Digest::SHA'
 % perl -MCPAN -e 'install(YAML)'

There is really nothing new to getting a basic Catalyst application working at this point, except to understand that you are now using the modules under ~/perl5 so you can install anything you please. There is no need for root privileges as everything will install cleanly into your local directory. There are several suggestions here for getting Catalyst installed. For development all you need is to install Catalyst::Devel like so

 % perl -MCPAN -e 'install Catalyst::Devel'

Then you can create an app and fire it up

 % catalyst.pl MyApp
 % cd MyApp
 % script/myapp_server.pl

You are now running your Catalyst application under local::lib

If you start with an empty site_perl (only core modules) and a fresh local::lib installation, you can actually build your application, test it works, and use the modules in the deployment of your app (Note: a fresh perl installation requires root). Your options here are to compile perl from scratch, or to use your package management system to install only core perl packages and possibly a perl database driver. For a clean local::lib install, just move your old directory out of the way and redo the tarball installation steps above.

This also requires that you have been adding the application dependencies to your Makefile.PL. For example, you would probably have a dependency that looks like this, along with the other modules the app is using

 requires 'Catalyst' => '5.7010';

For more info see Module::Install. Once you've added all of your dependencies, build the Makefile

 % cd MyApp
 % perl Makefile.PL 

Assuming you have a fresh perl and local::lib installation, the following command will show each module as 'missing' which makes it build all of the dependencies into your ~/perl5/lib/perl5 directory

 % make installdeps 

For testing, just verify your application starts up. You can then take this set of modules, tar, and deploy them with your application on another box, knowing that this set of modules works with this version of the application that you've compiled your modules against.

Installing deps with Makefile.PL is also useful in an environment with multiple developers. If a dependency is added, it has to go into Makefile.PL. Making sure modules are only installed with make installdeps verifies that when the code is committed that uses a new module, other developers can easily install it into their local::lib (with perl Makefile.PL && make installdeps) and thus becomes a new dependecy in the build process.

One more useful thing about local::lib is that you can use it to test patches to code that you are working on. For example, if you've made a patch or just want to test out a branch of code, you can install it to your local::lib in the typical way

 % cd My-Module-branch
 % perl Makefile.PL && make install

Then later if you want to rollback to the current version of the module fire up cpan and drop into the shell of the current module

 % cpan
 cpan> look My::Module

You should now be in a shell in which you can install the module in the usual way to overwrite your version

 Working directory is /home/user/.cpan/build/My-Module-0.00000-NvZbRI
 % perl Makefile.PL && make install 

We have seen where you can use local::lib as a development environment and touched on how you can use it to build modules for deploying on other hosts. It can be handy for control over your modules on shared hosts and in a multi-developer setting as well as an easy way to work on external code.

John Goulah, <jgoulah@gmail.com>