11 our $VERSION = '1.008026'; # 1.8.26
12 $VERSION = eval $VERSION;
15 my ($class, @args) = @_;
21 my $arg = shift @args;
22 # check for lethal dash first to stop processing before causing problems
23 # the fancy dash is U+2212 or \xE2\x88\x92
24 if ($arg =~ /\xE2\x88\x92/ or $arg =~ /−/) {
26 WHOA THERE! It looks like you've got some fancy dashes in your commandline!
27 These are *not* the traditional -- dashes that software recognizes. You
28 probably got these by copy-pasting from the perldoc for this module as
29 rendered by a UTF8-capable formatter. This most typically happens on an OS X
30 terminal, but can happen elsewhere too. Please try again after replacing the
31 dashes with normal minus signs.
34 elsif ($arg eq '--self-contained') {
36 FATAL: The local::lib --self-contained flag has never worked reliably and the
37 original author, Mark Stosberg, was unable or unwilling to maintain it. As
38 such, this flag has been removed from the local::lib codebase in order to
39 prevent misunderstandings and potentially broken builds. The local::lib authors
40 recommend that you look at the lib::core::only module shipped with this
41 distribution in order to create a more robust environment that is equivalent to
42 what --self-contained provided (although quite possibly not what you originally
43 thought it provided due to the poor quality of the documentation, for which we
47 elsif( $arg =~ /^--deactivate(?:=(.*))?$/ ) {
48 my $path = defined $1 ? $1 : shift @args;
49 push @steps, ['deactivate', $path];
51 elsif ( $arg eq '--deactivate-all' ) {
52 push @steps, ['deactivate_all'];
54 elsif ( $arg =~ /^--shelltype(?:=(.*))?$/ ) {
55 my $shell = defined $1 ? $1 : shift @args;
56 $opts{shelltype} = $shell;
58 elsif ( $arg eq '--no-create' ) {
61 elsif ( $arg =~ /^--/ ) {
62 die "Unknown import argument: $arg";
65 push @steps, ['activate', $arg];
69 push @steps, ['activate', undef];
72 my $self = $class->new(%opts);
75 my ($method, @args) = @$_;
76 $self = $self->$method(@args);
80 $self->print_environment_vars;
84 $self->setup_local_lib;
95 bless {%$self, @_}, ref $self;
98 sub inc { $_[0]->{inc} ||= \@INC }
99 sub libs { $_[0]->{libs} ||= [ \'PERL5LIB' ] }
100 sub bins { $_[0]->{bins} ||= [ \'PATH' ] }
101 sub roots { $_[0]->{roots} ||= [ \'PERL_LOCAL_LIB_ROOT' ] }
102 sub extra { $_[0]->{extra} ||= {} }
103 sub shelltype { $_[0]->{shelltype} ||= $_[0]->guess_shelltype }
104 sub no_create { $_[0]->{no_create} }
106 my $_archname = $Config{archname};
107 my $_version = $Config{version};
108 my @_inc_version_list = reverse split / /, $Config{inc_version_list};
109 my $_path_sep = $Config{path_sep};
114 !(ref $_ && ref $_ eq 'SCALAR') ? $_ : (
115 defined $ENV{$$_} ? split(/\Q$_path_sep/, $ENV{$$_})
118 } ref $list ? @$list : $list;
121 my ($list, @remove) = @_;
124 my %remove = map { $_ => 1 } @remove;
125 grep !$remove{$_}, _as_list($list);
129 [$_version, $_archname],
132 (@_inc_version_list ? \@_inc_version_list : ()),
136 sub install_base_bin_path {
137 my ($class, $path) = @_;
138 return File::Spec->catdir($path, 'bin');
140 sub install_base_perl_path {
141 my ($class, $path) = @_;
142 return File::Spec->catdir($path, 'lib', 'perl5');
144 sub install_base_arch_path {
145 my ($class, $path) = @_;
146 File::Spec->catdir($class->install_base_perl_path($path), $_archname);
150 my ($class, $path) = @_;
151 my $base = $class->install_base_perl_path($path);
152 return map { File::Spec->catdir($base, @$_) } @_lib_subdirs;
155 sub _mm_escape_path {
157 $path =~ s/\\/\\\\\\\\/g;
158 if ($path =~ s/ /\\ /g) {
159 $path = qq{"\\"$path\\""};
164 sub _mb_escape_path {
166 $path =~ s/\\/\\\\/g;
170 sub installer_options_for {
171 my ($class, $path) = @_;
174 defined $path ? "INSTALL_BASE="._mm_escape_path($path) : undef,
176 defined $path ? "--install_base "._mb_escape_path($path) : undef,
182 $self = ref $self ? $self : $self->new;
185 # screen out entries that aren't actually reflected in @INC
186 my $active_ll = $self->install_base_perl_path($_);
187 grep { $_ eq $active_ll } @{$self->inc};
188 } _as_list($self->roots);
193 my ($self, $path) = @_;
194 $self = $self->new unless ref $self;
195 $path = $self->resolve_path($path);
196 $path = $self->normalize_path($path);
198 my @active_lls = $self->active_paths;
200 if (!grep { $_ eq $path } @active_lls) {
201 warn "Tried to deactivate inactive local::lib '$path'\n";
206 bins => [ _remove_from($self->bins,
207 $self->install_base_bin_path($path)) ],
208 libs => [ _remove_from($self->libs,
209 $self->install_base_perl_path($path)) ],
210 inc => [ _remove_from($self->inc,
211 $self->lib_paths_for($path)) ],
212 roots => [ _remove_from($self->roots, $path) ],
215 $args{extra} = $self->installer_options_for($args{roots}[0]);
222 $self = $self->new unless ref $self;
224 my @active_lls = $self->active_paths;
229 bins => [ _remove_from($self->bins,
230 map $self->install_base_bin_path($_), @active_lls) ],
231 libs => [ _remove_from($self->libs,
232 map $self->install_base_perl_path($_), @active_lls) ],
233 inc => [ _remove_from($self->inc,
234 map $self->lib_paths_for($_), @active_lls) ],
235 roots => [ _remove_from($self->roots, @active_lls) ],
239 $args{extra} = $self->installer_options_for(undef);
245 my ($self, $path) = @_;
246 $self = $self->new unless ref $self;
247 $path = $self->resolve_path($path);
248 $self->ensure_dir_structure_for($path)
249 unless $self->no_create;
251 $path = $self->normalize_path($path);
253 my @active_lls = $self->active_paths;
255 if (grep { $_ eq $path } @active_lls[1 .. $#active_lls]) {
256 $self = $self->deactivate($path);
260 if (!@active_lls || $active_lls[0] ne $path) {
262 bins => [ $self->install_base_bin_path($path), @{$self->bins} ],
263 libs => [ $self->install_base_perl_path($path), @{$self->libs} ],
264 inc => [ $self->lib_paths_for($path), @{$self->inc} ],
265 roots => [ $path, @{$self->roots} ],
269 $args{extra} = $self->installer_options_for($path);
275 my ($self, $path) = @_;
276 $path = ( Win32::GetShortPathName($path) || $path )
281 sub build_environment_vars_for {
282 my $self = $_[0]->new->activate($_[1]);
283 $self->build_environment_vars;
285 sub build_environment_vars {
288 PATH => join($_path_sep, _as_list($self->bins)),
289 PERL5LIB => join($_path_sep, _as_list($self->libs)),
290 PERL_LOCAL_LIB_ROOT => join($_path_sep, _as_list($self->roots)),
295 sub setup_local_lib_for {
296 my $self = $_[0]->new->activate($_[1]);
297 $self->setup_local_lib;
300 sub setup_local_lib {
302 $self->setup_env_hash;
303 @INC = @{$self->inc};
306 sub setup_env_hash_for {
307 my $self = $_[0]->new->activate($_[1]);
308 $self->setup_env_hash;
312 my %env = $self->build_environment_vars;
313 for my $key (keys %env) {
314 if (defined $env{$key}) {
315 $ENV{$key} = $env{$key};
323 sub print_environment_vars_for {
324 my $self = $_[0]->new->activate($_[1]);
325 $self->print_environment_vars;
327 sub print_environment_vars {
329 print $self->environment_vars_string;
332 sub environment_vars_string_for {
333 my $self = $_[0]->new->activate($_[1]);
334 $self->environment_vars_string;
336 sub environment_vars_string {
339 my $build_method = 'build_' . $self->shelltype . '_env_declaration';
343 PERL5LIB => $self->libs,
344 PERL_LOCAL_LIB_ROOT => $self->roots,
349 my ($name, $value) = (shift(@envs), shift(@envs));
354 && ref $value->[0] eq 'SCALAR'
355 && ${$value->[0]} eq $name) {
361 ? (defined $ENV{$name} && $value eq $ENV{$name})
362 : !defined $ENV{$name}
366 $out .= $self->$build_method($name, $value);
368 my $wrap_method = 'wrap_' . $self->shelltype . '_output';
369 if ($self->can($wrap_method)) {
370 return $self->$wrap_method($out);
375 sub build_bourne_env_declaration {
376 my ($class, $name, $args) = @_;
377 my $value = $class->_interpolate($args, '$%s', '"', '\\%s');
379 if (!defined $value) {
380 return qq{unset $name;\n};
383 $value =~ s/(^|\G|$_path_sep)\$$name$_path_sep/$1\$$name\${$name+$_path_sep}/g;
384 $value =~ s/$_path_sep\$$name$/\${$name+$_path_sep}\$$name/;
386 qq{export ${name}="$value";\n}
389 sub build_csh_env_declaration {
390 my ($class, $name, $args) = @_;
391 my ($value, @vars) = $class->_interpolate($args, '$%s', '"', '"\\%s"');
392 if (!defined $value) {
393 return qq{unsetenv $name;\n};
397 for my $var (@vars) {
398 $out .= qq{if ! \$?$name setenv $name '';\n};
401 my $value_without = $value;
402 if ($value_without =~ s/(?:^|$_path_sep)\$$name(?:$_path_sep|$)//g) {
403 $out .= qq{if "\$$name" != '' setenv $name "$value";\n};
404 $out .= qq{if "\$$name" == '' };
406 $out .= qq{setenv $name "$value_without";\n};
410 sub build_cmd_env_declaration {
411 my ($class, $name, $args) = @_;
412 my $value = $class->_interpolate($args, '%%%s%%', qr([()!^"<>&|]), '^%s');
414 return qq{\@set $name=\n};
418 my $value_without = $value;
419 if ($value_without =~ s/(?:^|$_path_sep)%$name%(?:$_path_sep|$)//g) {
420 $out .= qq{\@if not "%$name%"=="" set $name=$value\n};
421 $out .= qq{\@if "%$name%"=="" };
423 $out .= qq{\@set $name=$value_without\n};
427 sub build_powershell_env_declaration {
428 my ($class, $name, $args) = @_;
429 my $value = $class->_interpolate($args, '$env:%s', '"', '`%s');
432 return qq{Remove-Item Env:\\$name;\n};
435 my $maybe_path_sep = qq{\$(if("\$env:$name"-eq""){""}else{"$_path_sep"})};
436 $value =~ s/(^|\G|$_path_sep)\$env:$name$_path_sep/$1\$env:$name"+$maybe_path_sep+"/g;
437 $value =~ s/$_path_sep\$env:$name$/"+$maybe_path_sep+\$env:$name+"/;
439 qq{\$env:$name = \$("$value");\n};
441 sub wrap_powershell_output {
442 my ($class, $out) = @_;
443 return $out || " \n";
447 my ($class, $args, $var_pat, $escape, $escape_pat) = @_;
449 unless defined $args;
450 my @args = ref $args ? @$args : $args;
453 my @vars = map { $$_ } grep { ref $_ eq 'SCALAR' } @args;
454 my $string = join $_path_sep, map {
455 ref $_ eq 'SCALAR' ? sprintf($var_pat, $$_) : do {
456 s/($escape)/sprintf($escape_pat, $1)/ge; $_;
459 return wantarray ? ($string, \@vars) : $string;
466 my $last = pop(@methods);
469 my ($obj, @args) = @_;
470 $obj->${pipeline @methods}(
487 { package Foo; sub foo { -$_[1] } sub bar { $_[1]+2 } sub baz { $_[1]+3 } }
488 my $foo = bless({}, 'Foo');
489 Test::More::ok($foo->${pipeline qw(foo bar baz)}(10) == -15);
496 my ($class, $path) = @_;
498 $path = $class->${pipeline qw(
499 resolve_relative_path
507 sub resolve_empty_path {
508 my ($class, $path) = @_;
518 #:: test classmethod setup
520 my $c = 'local::lib';
528 is($c->resolve_empty_path, '~/perl5');
529 is($c->resolve_empty_path('foo'), 'foo');
535 sub resolve_home_path {
536 my ($class, $path) = @_;
537 return $path unless ($path =~ /^~/);
538 my ($user) = ($path =~ /^~([^\/]+)/); # can assume ^~ so undef for 'us'
540 if (!defined $user && defined $ENV{HOME}) {
545 File::Glob::bsd_glob("~$user", File::Glob::GLOB_TILDE());
548 unless (defined $homedir) {
551 "Couldn't resolve homedir for "
552 .(defined $user ? $user : 'current user')
555 $path =~ s/^~[^\/]*/$homedir/;
559 sub resolve_relative_path {
560 my ($class, $path) = @_;
561 $path = File::Spec->rel2abs($path);
568 local *File::Spec::rel2abs = sub { shift; 'FOO'.shift; };
569 is($c->resolve_relative_path('bar'),'FOObar');
575 sub ensure_dir_structure_for {
576 my ($class, $path) = @_;
578 warn "Attempting to create directory ${path}\n";
580 require File::Basename;
584 $path = File::Basename::dirname($path);
586 mkdir $_ for reverse @dirs;
594 File::Path::rmtree('t/var/splat');
596 $c->ensure_dir_structure_for('t/var/splat');
598 ok(-d 't/var/splat');
604 sub guess_shelltype {
606 = defined $ENV{SHELL}
607 ? (File::Spec->splitpath($ENV{SHELL}))[-1]
608 : ( $^O eq 'MSWin32' && exists $ENV{'!EXITCODE'} )
610 : ( $^O eq 'MSWin32' && $ENV{PROMPT} && $ENV{COMSPEC} )
611 ? (File::Spec->splitpath($ENV{COMSPEC}))[-1]
612 : ( $^O eq 'MSWin32' && !$ENV{PROMPT} )
619 : /command\.com/i ? 'cmd'
620 : /cmd\.exe/i ? 'cmd'
621 : /4nt\.exe/i ? 'cmd'
622 : /powershell\.exe/i ? 'powershell'
634 local::lib - create and use a local lib/ for perl modules with PERL5LIB
640 use local::lib; # sets up a local lib at ~/perl5
642 use local::lib '~/foo'; # same, but ~/foo
646 use local::lib "$FindBin::Bin/../support"; # app-local support library
650 # Install LWP and its missing dependencies to the '~/perl5' directory
651 perl -MCPAN -Mlocal::lib -e 'CPAN::install(LWP)'
653 # Just print out useful shell commands
655 export PERL_MB_OPT='--install_base /home/username/perl5'
656 export PERL_MM_OPT='INSTALL_BASE=/home/username/perl5'
657 export PERL5LIB="/home/username/perl5/lib/perl5"
658 export PATH="/home/username/perl5/bin:$PATH"
660 =head2 The bootstrapping technique
662 A typical way to install local::lib is using what is known as the
663 "bootstrapping" technique. You would do this if your system administrator
664 hasn't already installed local::lib. In this case, you'll need to install
665 local::lib in your home directory.
667 Even if you do have administrative privileges, you will still want to set up your
668 environment variables, as discussed in step 4. Without this, you would still
669 install the modules into the system CPAN installation and also your Perl scripts
670 will not use the lib/ path you bootstrapped with local::lib.
672 By default local::lib installs itself and the CPAN modules into ~/perl5.
674 Windows users must also see L</Differences when using this module under Win32>.
676 1. Download and unpack the local::lib tarball from CPAN (search for "Download"
677 on the CPAN page about local::lib). Do this as an ordinary user, not as root
678 or administrator. Unpack the file in your home directory or in any other
683 perl Makefile.PL --bootstrap
685 If the system asks you whether it should automatically configure as much
686 as possible, you would typically answer yes.
688 In order to install local::lib into a directory other than the default, you need
689 to specify the name of the directory when you call bootstrap, as follows:
691 perl Makefile.PL --bootstrap=~/foo
693 3. Run this: (local::lib assumes you have make installed on your system)
695 make test && make install
697 4. Now we need to setup the appropriate environment variables, so that Perl
698 starts using our newly generated lib/ directory. If you are using bash or
699 any other Bourne shells, you can add this to your shell startup script this
702 echo 'eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)' >>~/.bashrc
704 If you are using C shell, you can do this as follows:
709 echo 'eval `perl -I$HOME/perl5/lib/perl5 -Mlocal::lib`' >> ~/.cshrc
711 If you passed to bootstrap a directory other than default, you also need to
712 give that as import parameter to the call of the local::lib module like this
715 echo 'eval $(perl -I$HOME/foo/lib/perl5 -Mlocal::lib=$HOME/foo)' >>~/.bashrc
717 After writing your shell configuration file, be sure to re-read it to get the
718 changed settings into your current shell's environment. Bourne shells use
719 C<. ~/.bashrc> for this, whereas C shells use C<source ~/.cshrc>.
721 If you're on a slower machine, or are operating under draconian disk space
722 limitations, you can disable the automatic generation of manpages from POD when
723 installing modules by using the C<--no-manpages> argument when bootstrapping:
725 perl Makefile.PL --bootstrap --no-manpages
727 To avoid doing several bootstrap for several Perl module environments on the
728 same account, for example if you use it for several different deployed
729 applications independently, you can use one bootstrapped local::lib
730 installation to install modules in different directories directly this way:
734 eval $(perl -Mlocal::lib=./) ### To set the environment for this shell alone
735 printenv ### You will see that ~/mydir1 is in the PERL5LIB
736 perl -MCPAN -e install ... ### whatever modules you want
740 If you are working with several C<local::lib> environments, you may want to
741 remove some of them from the current environment without disturbing the others.
742 You can deactivate one environment like this (using bourne sh):
744 eval $(perl -Mlocal::lib=--deactivate,~/path)
746 which will generate and run the commands needed to remove C<~/path> from your
747 various search paths. Whichever environment was B<activated most recently> will
748 remain the target for module installations. That is, if you activate
749 C<~/path_A> and then you activate C<~/path_B>, new modules you install will go
750 in C<~/path_B>. If you deactivate C<~/path_B> then modules will be installed
751 into C<~/pathA> -- but if you deactivate C<~/path_A> then they will still be
752 installed in C<~/pathB> because pathB was activated later.
754 You can also ask C<local::lib> to clean itself completely out of the current
755 shell's environment with the C<--deactivate-all> option.
756 For multiple environments for multiple apps you may need to include a modified
757 version of the C<< use FindBin >> instructions in the "In code" sample above.
758 If you did something like the above, you have a set of Perl modules at C<<
759 ~/mydir1/lib >>. If you have a script at C<< ~/mydir1/scripts/myscript.pl >>,
760 you need to tell it where to find the modules you installed for it at C<<
763 In C<< ~/mydir1/scripts/myscript.pl >>:
767 use local::lib "$FindBin::Bin/.."; ### points to ~/mydir1 and local::lib finds lib
768 use lib "$FindBin::Bin/../lib"; ### points to ~/mydir1/lib
770 Put this before any BEGIN { ... } blocks that require the modules you installed.
772 =head2 Differences when using this module under Win32
774 To set up the proper environment variables for your current session of
775 C<CMD.exe>, you can use this:
777 C:\>perl -Mlocal::lib
778 set PERL_MB_OPT=--install_base C:\DOCUME~1\ADMINI~1\perl5
779 set PERL_MM_OPT=INSTALL_BASE=C:\DOCUME~1\ADMINI~1\perl5
780 set PERL5LIB=C:\DOCUME~1\ADMINI~1\perl5\lib\perl5
781 set PATH=C:\DOCUME~1\ADMINI~1\perl5\bin;%PATH%
783 ### To set the environment for this shell alone
784 C:\>perl -Mlocal::lib > %TEMP%\tmp.bat && %TEMP%\tmp.bat && del %TEMP%\tmp.bat
785 ### instead of $(perl -Mlocal::lib=./)
787 If you want the environment entries to persist, you'll need to add them to the
788 Control Panel's System applet yourself or use L<App::local::lib::Win32Helper>.
790 The "~" is translated to the user's profile directory (the directory named for
791 the user under "Documents and Settings" (Windows XP or earlier) or "Users"
792 (Windows Vista or later)) unless $ENV{HOME} exists. After that, the home
793 directory is translated to a short name (which means the directory must exist)
794 and the subdirectories are created.
798 local::lib also supports PowerShell, and an be used with the
799 C<Invoke-Expression> cmdlet.
801 Invoke-Expression "$(perl -Mlocal::lib)"
805 The version of a Perl package on your machine is not always the version you
806 need. Obviously, the best thing to do would be to update to the version you
807 need. However, you might be in a situation where you're prevented from doing
808 this. Perhaps you don't have system administrator privileges; or perhaps you
809 are using a package management system such as Debian, and nobody has yet gotten
810 around to packaging up the version you need.
812 local::lib solves this problem by allowing you to create your own directory of
813 Perl packages downloaded from CPAN (in a multi-user system, this would typically
814 be within your own home directory). The existing system Perl installation is
815 not affected; you simply invoke Perl with special options so that Perl uses the
816 packages in your own local package directory rather than the system packages.
817 local::lib arranges things so that your locally installed version of the Perl
818 packages takes precedence over the system installation.
820 If you are using a package management system (such as Debian), you don't need to
821 worry about Debian and CPAN stepping on each other's toes. Your local version
822 of the packages will be written to an entirely separate directory from those
827 This module provides a quick, convenient way of bootstrapping a user-local Perl
828 module library located within the user's home directory. It also constructs and
829 prints out for the user the list of environment variables using the syntax
830 appropriate for the user's current shell (as specified by the C<SHELL>
831 environment variable), suitable for directly adding to one's shell
834 More generally, local::lib allows for the bootstrapping and usage of a
835 directory containing Perl modules outside of Perl's C<@INC>. This makes it
836 easier to ship an application with an app-specific copy of a Perl module, or
837 collection of modules. Useful in cases like when an upstream maintainer hasn't
838 applied a patch to a module of theirs that you need for your application.
840 On import, local::lib sets the following environment variables to appropriate
855 When possible, these will be appended to instead of overwritten entirely.
857 These values are then available for reference by any code after import.
859 =head1 CREATING A SELF-CONTAINED SET OF MODULES
861 See L<lib::core::only> for one way to do this - but note that
862 there are a number of caveats, and the best approach is always to perform a
863 build against a clean perl (i.e. site and vendor as close to empty as possible).
867 Options are values that can be passed to the C<local::lib> import besides the
868 directory to use. They are specified as C<use local::lib '--option'[, path];>
869 or C<perl -Mlocal::lib=--option[,path]>.
873 Remove the chosen path (or the default path) from the module search paths if it
874 was added by C<local::lib>, instead of adding it.
876 =head2 --deactivate-all
878 Remove all directories that were added to search paths by C<local::lib> from the
883 Specify the shell type to use for output. By default, the shell will be
884 detected based on the environment. Should be one of: C<bourne>, C<csh>,
885 C<cmd>, or C<powershell>.
889 Prevents C<local::lib> from creating directories when activating dirs. This is
890 likely to cause issues on Win32 systems.
894 =head2 ensure_dir_structure_for
898 =item Arguments: $path
900 =item Return value: None
904 Attempts to create the given path, and all required parent directories. Throws
905 an exception on failure.
907 =head2 print_environment_vars_for
911 =item Arguments: $path
913 =item Return value: None
917 Prints to standard output the variables listed above, properly set to use the
918 given path as the base directory.
920 =head2 build_environment_vars_for
924 =item Arguments: $path
926 =item Return value: %environment_vars
930 Returns a hash with the variables listed above, properly set to use the
931 given path as the base directory.
933 =head2 setup_env_hash_for
937 =item Arguments: $path
939 =item Return value: None
943 Constructs the C<%ENV> keys for the given path, by calling
944 L</build_environment_vars_for>.
950 =item Arguments: None
952 =item Return value: @paths
956 Returns a list of active C<local::lib> paths, according to the
957 C<PERL_LOCAL_LIB_ROOT> environment variable and verified against
958 what is really in C<@INC>.
960 =head2 install_base_perl_path
964 =item Arguments: $path
966 =item Return value: $install_base_perl_path
970 Returns a path describing where to install the Perl modules for this local
971 library installation. Appends the directories C<lib> and C<perl5> to the given
974 =head2 install_base_bin_path
978 =item Arguments: $path
980 =item Return value: $install_base_bin_path
984 Returns a path describing where to install the executable programs for this
985 local library installation. Appends the directory C<bin> to the given path.
987 =head2 resolve_empty_path
991 =item Arguments: $path
993 =item Return value: $base_path
997 Builds and returns the base path into which to set up the local module
998 installation. Defaults to C<~/perl5>.
1000 =head2 resolve_home_path
1004 =item Arguments: $path
1006 =item Return value: $home_path
1010 Attempts to find the user's home directory. If installed, uses C<File::HomeDir>
1011 for this purpose. If no definite answer is available, throws an exception.
1013 =head2 resolve_relative_path
1017 =item Arguments: $path
1019 =item Return value: $absolute_path
1023 Translates the given path into an absolute path.
1029 =item Arguments: $path
1031 =item Return value: $absolute_path
1035 Calls the following in a pipeline, passing the result from the previous to the
1036 next, in an attempt to find where to configure the environment for a local
1037 library installation: L</resolve_empty_path>, L</resolve_home_path>,
1038 L</resolve_relative_path>. Passes the given path argument to
1039 L</resolve_empty_path> which then returns a result that is passed to
1040 L</resolve_home_path>, which then has its result passed to
1041 L</resolve_relative_path>. The result of this final call is returned from
1044 =head1 A WARNING ABOUT UNINST=1
1046 Be careful about using local::lib in combination with "make install UNINST=1".
1047 The idea of this feature is that will uninstall an old version of a module
1048 before installing a new one. However it lacks a safety check that the old
1049 version and the new version will go in the same directory. Used in combination
1050 with local::lib, you can potentially delete a globally accessible version of a
1051 module while installing the new version in a local place. Only combine "make
1052 install UNINST=1" and local::lib if you understand these possible consequences.
1058 =item * Directory names with spaces in them are not well supported by the perl
1059 toolchain and the programs it uses. Pure-perl distributions should support
1060 spaces, but problems are more likely with dists that require compilation. A
1061 workaround you can do is moving your local::lib to a directory with spaces
1062 B<after> you installed all modules inside your local::lib bootstrap. But be
1063 aware that you can't update or install CPAN modules after the move.
1065 =item * Rather basic shell detection. Right now anything with csh in its name is
1066 assumed to be a C shell or something compatible, and everything else is assumed
1067 to be Bourne, except on Win32 systems. If the C<SHELL> environment variable is
1068 not set, a Bourne-compatible shell is assumed.
1070 =item * Kills any existing PERL_MM_OPT or PERL_MB_OPT.
1072 =item * Should probably auto-fixup CPAN config if not already done.
1076 Patches very much welcome for any of the above.
1080 =item * On Win32 systems, does not have a way to write the created environment
1081 variables to the registry, so that they can persist through a reboot.
1085 =head1 TROUBLESHOOTING
1087 If you've configured local::lib to install CPAN modules somewhere in to your
1088 home directory, and at some point later you try to install a module with C<cpan
1089 -i Foo::Bar>, but it fails with an error like: C<Warning: You do not have
1090 permissions to install into /usr/lib64/perl5/site_perl/5.8.8/x86_64-linux at
1091 /usr/lib64/perl5/5.8.8/Foo/Bar.pm> and buried within the install log is an
1092 error saying C<'INSTALL_BASE' is not a known MakeMaker parameter name>, then
1093 you've somehow lost your updated ExtUtils::MakeMaker module.
1095 To remedy this situation, rerun the bootstrapping procedure documented above.
1097 Then, run C<rm -r ~/.cpan/build/Foo-Bar*>
1099 Finally, re-run C<cpan -i Foo::Bar> and it should install without problems.
1109 local::lib looks at the user's C<SHELL> environment variable when printing out
1110 commands to add to the shell configuration file.
1112 On Win32 systems, C<COMSPEC> is also examined.
1120 =item * L<Perl Advent article, 2011|http://perladvent.org/2011/2011-12-01.html>
1128 Join #local-lib on irc.perl.org.
1132 Matt S Trout <mst@shadowcat.co.uk> http://www.shadowcat.co.uk/
1134 auto_install fixes kindly sponsored by http://www.takkle.com/
1138 Patches to correctly output commands for csh style shells, as well as some
1139 documentation additions, contributed by Christopher Nehren <apeiron@cpan.org>.
1141 Doc patches for a custom local::lib directory, more cleanups in the english
1142 documentation and a L<german documentation|POD2::DE::local::lib> contributed by
1143 Torsten Raudssus <torsten@raudssus.de>.
1145 Hans Dieter Pearcey <hdp@cpan.org> sent in some additional tests for ensuring
1146 things will install properly, submitted a fix for the bug causing problems with
1147 writing Makefiles during bootstrapping, contributed an example program, and
1148 submitted yet another fix to ensure that local::lib can install and bootstrap
1149 properly. Many, many thanks!
1151 pattern of Freenode IRC contributed the beginnings of the Troubleshooting
1152 section. Many thanks!
1154 Patch to add Win32 support contributed by Curtis Jewell <csjewell@cpan.org>.
1156 Warnings for missing PATH/PERL5LIB (as when not running interactively) silenced
1157 by a patch from Marco Emilio Poleggi.
1159 Mark Stosberg <mark@summersault.com> provided the code for the now deleted
1160 '--self-contained' option.
1162 Documentation patches to make win32 usage clearer by
1163 David Mertens <dcmertens.perl@gmail.com> (run4flat).
1165 Brazilian L<portuguese translation|POD2::PT_BR::local::lib> and minor doc
1166 patches contributed by Breno G. de Oliveira <garu@cpan.org>.
1168 Improvements to stacking multiple local::lib dirs and removing them from the
1169 environment later on contributed by Andrew Rodland <arodland@cpan.org>.
1171 Patch for Carp version mismatch contributed by Hakim Cassimally
1172 <osfameron@cpan.org>.
1176 Copyright (c) 2007 - 2010 the local::lib L</AUTHOR> and L</CONTRIBUTORS> as
1181 This is free software; you can redistribute it and/or modify it under
1182 the same terms as the Perl 5 programming language system itself.