How is use local::lib different from use lib?

Question

I don't understand what use local::lib does that regular use lib doesn't. Could someone explain it?

Answer 1

local::lib

1. Defaults to ~/perl5 if you don't specify a directory (while use lib; is a no-op).

2. Resolves relative paths to absolute paths before adding them to @INC. (lib just adds the relative path as-is.)

3. Expands ~ and ~user in the directory name.

4. Appends /lib/perl5 to the directory you specify. (So use local::lib '/foo'; is somewhat equivalent to use lib '/foo/lib/perl5';.)

5. Prepends DIR/bin to your PATH, so you can use scripts installed by local modules.

Answer 2

Regular use lib foo is almost as simple as:

BEGIN { unshift(@INC, foo) }

Whereas use local::lib sets many other Perl environment variables to make sure you can install modules locally, see the source.

Answer 3

use lib adds a directory to your module search path (@INC). It has no effect on anything outside of the program or module which contains the use lib directive.

local::lib is intended to be used to enable a private module installation directory and, if you configure your shell environment in the way that it recommends, this private directory will be used for all Perl module installations (whether via CPAN or manual make install) and modules installed there will be made available to all Perl programs/modules run from within your local::lib-aware shell environment.