use lib (Programming Perl)

31.13. use lib

use lib "$ENV{HOME}/libperl";   # add ~/libperl
no lib ".";                     # remove cwd

This pragma simplifies the manipulation of @INC at compile time. It is typically used to add extra directories to Perl's search path so that later do, require, and use statements will find library files that aren't located in Perl's default search path. It's especially important with use, since that happens at compile time too, and setting @INC normally (that is, at run time) would be too late.

Parameters to use lib are prepended to the beginning of Perl's search path. Saying use libLIST is almost the same as saying BEGIN { unshift(@INC,LIST) }, but use libLIST includes support for platform-specific directories. For each given directory $dir in its argument list, the lib pragma also checks to see whether a directory named $dir/$archname/auto exists. If so, the $dir/$archname directory is assumed to be a corresponding platform-specific directory, so is added to @INC (in front of $dir).

To avoid redundant additions that slow access time and waste a small amount of memory, trailing duplicate entries in @INC are removed when entries are added.

Normally, you should only add directories to @INC. If you do need to delete directories from @INC, take care to delete only those that you yourself added, or those that you're somehow certain aren't needed by other modules in your program. Other modules may have added directories to your @INC that they need for correct operation.

The no lib pragma deletes all instances of each named directory from @INC. It also deletes any corresponding platform-specific directory as described earlier.

When the lib pragma is loaded, it saves the current value of @INC to the array @lib::ORIG_INC, so to restore the original, just copy that array to the real @INC.

Even though @INC typically includes dot ("."), the current directory, this really isn't as useful as you'd think. For one thing, the dot entry comes at the end, not the start, so that modules installed in the current directory don't suddenly override system versions. You could say use lib "." if that's what you really want. More annoyingly, it's the current directory of the Perl process, not the directory that the script was installed into, which makes it completely unreliable. If you create a program plus some modules for that program to use, it will work while you're developing, but it won't work when you aren't running in the directory the files live in.

One solution for this is to use the standard FindBin module:

use FindBin;                # where was script installed?
use lib $FindBin::Bin;      # use that dir for libs, too

The FindBin module tries to guess the full path to the directory in which the running process's program was installed. Don't use this for security purposes, because malicious programs can usually deceive it if they try hard enough. But unless you're intentionally trying to break the module, it should work as intended. The module provides a $FindBin::Bin variable (which you may import) that contains the module's guess of where the program was installed. You can then use the lib pragma to add that directory to your @INC, thus producing an executable-relative path.

Some programs expect to be installed in a bin directory and then find their library modules in "cousin" files installed in a lib directory at the same level as bin. For example, programs might go in /usr/local/apache/bin or /opt/perl/bin, and libraries go in /usr/local/apache/lib and /opt/perl/lib. This code takes care of that neatly:

use FindBin qw($Bin);
use lib "$Bin/../lib";

If you find yourself specifying the same use lib in several unrelated programs, you might consider setting the PERL5LIB environment variable instead. See the description of the PERL5LIB environment variable in Chapter 19, "The Command-Line Interface".

# syntax for sh, bash, ksh, or zsh
$ PERL5LIB=$HOME/perllib; export PERL5LIB

# syntax for csh or tcsh
% setenv PERL5LIB ~/perllib

If you want to use optional directories on just this program without changing its source, look into the -I command-line switch:

% perl -I ~/perllib program-path args

See the Chapter 19, "The Command-Line Interface" for more about using -I from the command line.