Now, let's assume the following scenario. We have installed the LWP package in our local repository. Now we want to install another module (e.g., mod_perl), and it has LWP listed in its prerequisites list. We know that we have LWP installed, but when we run perl Makefile.PL for the module we're about to install, we're told that we don't have LWP installed.

There is no way for Perl to know that we have some locally installed modules. All it does is search the directories listed in @INC, and because @INC contains only the default four directories (plus the . directory), it cannot find the locally installed LWP package. We cannot solve this problem by adding code to modify @INC, but changing the PERL5LIB environment variable will do the trick.

How to define an environment variable varies according to which shell you use. Bourne-style shell users can split a long line using the backslash (\):

panic% export PERL5LIB=/home/stas/lib/perl5/5.6.1:\
/home/stas/lib/perl5/site_perl/5.6.1:\
/home/stas/lib/perl5/site_perl

In the C-style shells, however, you'll have to make sure that the value of the PERL5LIB environment variable is specified as one continuous line with no newlines or spaces:

panic% setenv PERL5LIB /home/stas/lib/perl5/5.6.1:
/home/stas/lib/perl5/site_perl/5.6.1:
/home/stas/lib/perl5/site_perl

(In this example, the lines were split to make them fit on the page.)

As with use lib, Perl automatically prepends the architecture-specific directories to @INC if those exist.

When you have done this, verify the value of the newly configured @INC by executing perl -V as before. You should see the modified value of @INC:

panic% perl -V

Characteristics of this binary (from libperl): 
Built under linux
Compiled at Apr  6 1999 23:34:07
%ENV:
  PERL5LIB="/home/stas/lib/perl5/5.6.1:
  /home/stas/lib/perl5/site_perl/5.6.1:
  /home/stas/lib/perl5/site_perl"
@INC:
  /home/stas/lib/perl5/5.6.1/i386-linux
  /home/stas/lib/perl5/5.6.1
  /home/stas/lib/perl5/site_perl/5.6.1/i386-linux
  /home/stas/lib/perl5/site_perl/5.6.1
  /home/stas/lib/perl5/site_perl
  /usr/lib/perl5/5.6.1/i386-linux
  /usr/lib/perl5/5.6.1
  /usr/lib/perl5/site_perl/5.6.1/i386-linux
  /usr/lib/perl5/site_perl/5.6.1
  /usr/lib/perl5/site_perl
  .

When everything works as you want it to, add these commands to your .tcshrc, .bashrc, C:\autoexec.bat or another equivalent file.[21] The next time you start a shell, the environment will be ready for you to work with the new Perl directories.

[21]These files are run by the shell at startup and allow you to set environment variables that might be useful every time you use your shell.

Note that if you have a PERL5LIBsetting, you don't need to alter the @INC value in your scripts. But if someone else (who doesn't have this setting in the shell) tries to execute your scripts, Perl will fail to find your locally installed modules. This includes cron scripts, which might use a different shell environment (in which case the PERL5LIBsetting won't be available).

The best approach is to have both the PERL5LIB environment variable and the explicit @INC extension code at the beginning of the scripts, as described above.