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 lib
LIST
is almost the
same as saying BEGIN { unshift(@INC
,
LIST
) }
, but
use lib
LIST
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.
# 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 for more
about using -I
from the command line.