If using local::lib, consult its documentation. Otherwise, Perl must be made aware of any custom library directories. Perl uses the @INC variable (perldoc perlvar) to list these directories, though this array should not be edited directly. To change @INC, use lib (perldoc lib) or use the -I option to perl (perldoc perlrun) or set the PERLLIB or PERL5LIB environment variable (perldoc perlrun) or recompile perl. The most common methods are to either specify a use lib statement in each program:
$ perl -E 'use lib qw{/some/path /elsewhere}; say for @INC' | head -2
/some/path
/elsewhere
Or to set the PERL5LIB environment variable, which accepts a colon delimited list of paths.
$ env PERL5LIB=/a:/b perl -E 'say for @INC' | head -2
/a
/b
Testing PERL5LIB
For Perl 5, under a Bourne shell, set the PERL5LIB environment variable, and test whether perl can find and use a module verified to be installed under the custom install path:
# Confirm nothing else has set PERL5LIB first
$ echo $PERL5LIB
$ export PERL5LIB=~/lib/perl5
# Check that the shell and perl are aware of the new setting
$ echo $PERL5LIB
/home/username/lib/perl5
$ perl -V | grep $PERL5LIB
PERL5LIB="/home/username/lib/perl5"
/home/username/lib/perl5/darwin-thread-multi-2level
/home/username/lib/perl5
# Find a Perl module to test with (if none, install something!)
$ find ~/lib/perl5 -type f -name "*.pm" | head -1
/home/username/lib/perl5/Bundle/LWP.pm
# See if the module can load, and if so, from where
$ perl -MBundle::LWP -le 'print $INC{"Bundle/LWP.pm"}'
/home/username/lib/perl5/Bundle/LWP.pm
The final command confirms that Bundle::LWP is actually being read from under /home/username/lib/perl5 by perl, and not some other directory in @INC. Note how module names are converted to filesystem paths by replacing all the :: with / on Unix, plus a suffix of .pm. If a module cannot be used as expected, causes would include permissions problems, or perhaps other environment variables and settings altering the results. Unix Debugging Tips covers how to delve through Unix systems, and the various external documents referenced above detail other environment variables and settings that also influence @INC. Additional points:
- The perldoc -l Module::Name command is a shorter method of printing the path to a module file. However, perl is a more accurate test:
- Older flavors of Bourne shells did not support the ~ abbreviation for home directories, and instead must use $HOME.
$ perl -MPod::Perldoc -le 'print $INC{"Pod/Perldoc.pm"}'
/usr/share/perl/5.10/Pod/Perldoc.pm
$ perldoc -l Pod::Perldoc
No documentation found for "Pod::Perldoc".
Shell Configuration for PERL5LIB
The custom PERL5LIB should be made permanent, for example by adding the lines:
PERL5LIB=$HOME/lib/perl5
export PERL5LIB
MANPATH=$HOME/share/man
export MANPATH
To the ~/.profile shell startup file (or as appropriate for the shell in question). Then, create a new shell and echo $PERL5LIB to confirm that the setting is available. Consult the shell documentation (for example STARTUP/SHUTDOWN FILES under zsh(1)), or learn from a book such as Learning the BASH Shell to understand the various startup files and when they are evaluated by the shell. One method to cleanly replace the currently running shell is to simply exec the shell, which replaces the current shell process with a newly launched instance:
$ echo $SHELL
/bin/zsh
$ exec $SHELL
Note that under cron(8), the environment may be different than set in the shell. Ensure that the crontab(5) file sets appropriate environment variables to find any required perl modules.
Perl code running under Taint mode may require the use lib statement: see perlsec for details. Certain programs may require custom configuration to set PERL5LIB. Consult the documentation to see whether any options to adjust environment variables are offered, or experiment to see whether the program will inherit them from the parent process. Apache, for example, offers the SetEnv configuration option under mod_env:
SetEnv PERL5LIB /home/username/lib/perl5:/some/other/perl/lib
Some programs, such as sudo, may strip environment variables. This may delete PERL5LIB or other necessary settings. Workaround programs that do this via a wrapper script that then sets all the necessary variables, then runs the original program:
#!/bin/sh
export PERL5LIB=…
exec /path/to/the/real_program "$@"
