Last week we built a simple module the defined and exported (on demand) one function. We also tested using the module with a test script in the same directory. This week we will look at how to install the module so we can use it from anywhere (well, within reason).

The first thing to know is where perl looks for modules when it wants to load them — and we can find out by looking at the special @INC (include) array. If you type ‘perl -V’ at the command prompt you will see a bunch of configuration information, at the of which you will see the contents of the @INC. You can also just view the @INC array with this command-line invocation (you might have to fiddle with the quoting depending on your shell):

    perl -le 'print join "\n", @INC'

On my machine it says:

    [jandrew]$ perl -le 'print join "\n",@INC'
    /usr/local/lib/perl5/5.6.0/i586-linux
    /usr/local/lib/perl5/5.6.0
    /usr/local/lib/perl5/site_perl/5.6.0/i586-linux
    /usr/local/lib/perl5/site_perl/5.6.0
    /usr/local/lib/perl5/site_perl/5.005/i586-linux
    /usr/local/lib/perl5/site_perl/5.005
    /usr/local/lib/perl5/site_perl
    .

These are the search paths perl uses to find modules. Notice, that last line is just a dot — meaning current directory, which is why our test script was able to work.

So, if we want to be able to use our Cool.pm module we can place it in one of those directories, and we usually use the sit_perl directory for our current version of Perl. My version here is 5.6.0 so I would place the Cool module at:

    /usr/local/lib/perl5/site_perl/5.6.0/Cool.pm

Now, you may not have permissions to install into these directories. In this case you have two options for using a private installation directory. First create a directory where you will install your private modules — I might use /home/jandrew/perl5lib or something — and put your module there. Now we have to tell Perl where to find it (or rather, we have to get this directory into the @INC array). The ‘use lib’ pragma can be used on a script by script basis to install extra directories in @INC:

    #!/usr/bin/perl -w
    use strict;
    use lib '/home/jandrew/perl5lib';
    use Cool;

That ‘use lib’ line tells perl to install that directory at the beginning of the @INC array (so it will be searched first). The problem with this is that we have to use this line in every script that needs to use one of our private modules — and if we share our module and scripts with someone else, they’ll need to install the module in their own private directory and change that line in ever script we give them. The alternative is to use the PERL5LIB environment variable. Setting this variable (by whatever means your platform or shell uses) gives us a way to tell Perl where to look without our having to specify it in each script:

    [jandrew]$ export PERL5LIB=/home/jandrew/myperlib
    [jandrew]$ perl -le 'print join "\n", @INC'
    /home/jandrew/myperlib
    /usr/local/lib/perl5/5.6.0/i586-linux
    /usr/local/lib/perl5/5.6.0
    /usr/local/lib/perl5/site_perl/5.6.0/i586-linux
    /usr/local/lib/perl5/site_perl/5.6.0
    /usr/local/lib/perl5/site_perl/5.005/i586-linux
    /usr/local/lib/perl5/site_perl/5.005
    /usr/local/lib/perl5/site_perl
    .

Here we see that once the environment variable is set, that directory is then automatically prepended to the @INC array. Now we can decide to change our private directory and move all of our modules and we only have to change this environment variable to point to the new location rather than each of our scripts. Next week we will look at packaging up our module so we can conveniently distribute it to others.

*****