lib/local/lib.pm

   1 use strict;
   2 use warnings;
   3
   4 package local::lib;
   5
   6 use 5.008001; # probably works with earlier versions but I'm not supporting them
   7               # (patches would, of course, be welcome)
   8
   9 use File::Spec ();
  10 use File::Path ();
  11 use Carp ();
  12 use Config;
  13
  14 our $VERSION = '1.008001'; # 1.8.1
  15
  16 our @KNOWN_FLAGS = qw(--self-contained);
  17
  18 sub import {
  19   my ($class, @args) = @_;
  20
  21   # Remember what PERL5LIB was when we started
  22   my $perl5lib = $ENV{PERL5LIB} || '';
  23
  24   my %arg_store;
  25   for my $arg (@args) {
  26     # check for lethal dash first to stop processing before causing problems
  27     if ($arg =~ /−/) {
  28       die <<'DEATH';
  29 WHOA THERE! It looks like you've got some fancy dashes in your commandline!
  30 These are *not* the traditional -- dashes that software recognizes. You
  31 probably got these by copy-pasting from the perldoc for this module as
  32 rendered by a UTF8-capable formatter. This most typically happens on an OS X
  33 terminal, but can happen elsewhere too. Please try again after replacing the
  34 dashes with normal minus signs.
  35 DEATH
  36     }
  37     elsif(grep { $arg eq $_ } @KNOWN_FLAGS) {
  38       (my $flag = $arg) =~ s/--//;
  39       $arg_store{$flag} = 1;
  40     }
  41     elsif($arg =~ /^--/) {
  42       die "Unknown import argument: $arg";
  43     }
  44     else {
  45       # assume that what's left is a path
  46       $arg_store{path} = $arg;
  47     }
  48   }
  49
  50   if($arg_store{'self-contained'}) {
  51     die "FATAL: The local::lib --self-contained flag has never worked reliably and the original author, Mark Stosberg, was unable or unwilling to maintain it. As such, this flag has been removed from the local::lib codebase in order to prevent misunderstandings and potentially broken builds. The local::lib authors recommend that you look at the lib::core::only module shipped with this distribution in order to create a more robust environment that is equivalent to what --self-contained provided (although quite possibly not what you originally thought it provided due to the poor quality of the documentation, for which we apologise).\n";
  52   }
  53
  54   $arg_store{path} = $class->resolve_path($arg_store{path});
  55   $class->setup_local_lib_for($arg_store{path});
  56
  57   for (@INC) { # Untaint @INC
  58     next if ref; # Skip entry if it is an ARRAY, CODE, blessed, etc.
  59     m/(.*)/ and $_ = $1;
  60   }
  61 }
  62
  63 sub pipeline;
  64
  65 sub pipeline {
  66   my @methods = @_;
  67   my $last = pop(@methods);
  68   if (@methods) {
  69     \sub {
  70       my ($obj, @args) = @_;
  71       $obj->${pipeline @methods}(
  72         $obj->$last(@args)
  73       );
  74     };
  75   } else {
  76     \sub {
  77       shift->$last(@_);
  78     };
  79   }
  80 }
  81
  82 =begin testing
  83
  84 #:: test pipeline
  85
  86 package local::lib;
  87
  88 { package Foo; sub foo { -$_[1] } sub bar { $_[1]+2 } sub baz { $_[1]+3 } }
  89 my $foo = bless({}, 'Foo');
  90 Test::More::ok($foo->${pipeline qw(foo bar baz)}(10) == -15);
  91
  92 =end testing
  93
  94 =cut
  95
  96 sub _uniq {
  97     my %seen;
  98     grep { ! $seen{$_}++ } @_;
  99 }
 100
 101 sub resolve_path {
 102   my ($class, $path) = @_;
 103   $class->${pipeline qw(
 104     resolve_relative_path
 105     resolve_home_path
 106     resolve_empty_path
 107   )}($path);
 108 }
 109
 110 sub resolve_empty_path {
 111   my ($class, $path) = @_;
 112   if (defined $path) {
 113     $path;
 114   } else {
 115     '~/perl5';
 116   }
 117 }
 118
 119 =begin testing
 120
 121 #:: test classmethod setup
 122
 123 my $c = 'local::lib';
 124
 125 =end testing
 126
 127 =begin testing
 128
 129 #:: test classmethod
 130
 131 is($c->resolve_empty_path, '~/perl5');
 132 is($c->resolve_empty_path('foo'), 'foo');
 133
 134 =end testing
 135
 136 =cut
 137
 138 sub resolve_home_path {
 139   my ($class, $path) = @_;
 140   return $path unless ($path =~ /^~/);
 141   my ($user) = ($path =~ /^~([^\/]+)/); # can assume ^~ so undef for 'us'
 142   my $tried_file_homedir;
 143   my $homedir = do {
 144     if (eval { require File::HomeDir } && $File::HomeDir::VERSION >= 0.65) {
 145       $tried_file_homedir = 1;
 146       if (defined $user) {
 147         File::HomeDir->users_home($user);
 148       } else {
 149         File::HomeDir->my_home;
 150       }
 151     } else {
 152       if (defined $user) {
 153         (getpwnam $user)[7];
 154       } else {
 155         if (defined $ENV{HOME}) {
 156           $ENV{HOME};
 157         } else {
 158           (getpwuid $<)[7];
 159         }
 160       }
 161     }
 162   };
 163   unless (defined $homedir) {
 164     Carp::croak(
 165       "Couldn't resolve homedir for "
 166       .(defined $user ? $user : 'current user')
 167       .($tried_file_homedir ? '' : ' - consider installing File::HomeDir')
 168     );
 169   }
 170   $path =~ s/^~[^\/]*/$homedir/;
 171   $path;
 172 }
 173
 174 sub resolve_relative_path {
 175   my ($class, $path) = @_;
 176   $path = File::Spec->rel2abs($path);
 177 }
 178
 179 =begin testing
 180
 181 #:: test classmethod
 182
 183 local *File::Spec::rel2abs = sub { shift; 'FOO'.shift; };
 184 is($c->resolve_relative_path('bar'),'FOObar');
 185
 186 =end testing
 187
 188 =cut
 189
 190 sub setup_local_lib_for {
 191   my ($class, $path) = @_;
 192   $path = $class->ensure_dir_structure_for($path);
 193   if ($0 eq '-') {
 194     $class->print_environment_vars_for($path);
 195     exit 0;
 196   } else {
 197     $class->setup_env_hash_for($path);
 198     @INC = _uniq(split($Config{path_sep}, $ENV{PERL5LIB}), @INC);
 199   }
 200 }
 201
 202 sub install_base_bin_path {
 203   my ($class, $path) = @_;
 204   File::Spec->catdir($path, 'bin');
 205 }
 206
 207 sub install_base_perl_path {
 208   my ($class, $path) = @_;
 209   File::Spec->catdir($path, 'lib', 'perl5');
 210 }
 211
 212 sub install_base_arch_path {
 213   my ($class, $path) = @_;
 214   File::Spec->catdir($class->install_base_perl_path($path), $Config{archname});
 215 }
 216
 217 sub ensure_dir_structure_for {
 218   my ($class, $path) = @_;
 219   unless (-d $path) {
 220     warn "Attempting to create directory ${path}\n";
 221   }
 222   File::Path::mkpath($path);
 223   # Need to have the path exist to make a short name for it, so
 224   # converting to a short name here.
 225   $path = Win32::GetShortPathName($path) if $^O eq 'MSWin32';
 226
 227   return $path;
 228 }
 229
 230 sub INTERPOLATE_ENV () { 1 }
 231 sub LITERAL_ENV     () { 0 }
 232
 233 sub guess_shelltype {
 234   my $shellbin = 'sh';
 235   if(defined $ENV{'SHELL'}) {
 236       my @shell_bin_path_parts = File::Spec->splitpath($ENV{'SHELL'});
 237       $shellbin = $shell_bin_path_parts[-1];
 238   }
 239   my $shelltype = do {
 240       local $_ = $shellbin;
 241       if(/csh/) {
 242           'csh'
 243       } else {
 244           'bourne'
 245       }
 246   };
 247
 248   # Both Win32 and Cygwin have $ENV{COMSPEC} set.
 249   if (defined $ENV{'COMSPEC'} && $^O ne 'cygwin') {
 250       my @shell_bin_path_parts = File::Spec->splitpath($ENV{'COMSPEC'});
 251       $shellbin = $shell_bin_path_parts[-1];
 252          $shelltype = do {
 253                  local $_ = $shellbin;
 254                  if(/command\.com/) {
 255                          'win32'
 256                  } elsif(/cmd\.exe/) {
 257                          'win32'
 258                  } elsif(/4nt\.exe/) {
 259                          'win32'
 260                  } else {
 261                          $shelltype
 262                  }
 263          };
 264   }
 265   return $shelltype;
 266 }
 267
 268 sub print_environment_vars_for {
 269   my ($class, $path) = @_;
 270   print $class->environment_vars_string_for($path);
 271 }
 272
 273 sub environment_vars_string_for {
 274   my ($class, $path) = @_;
 275   my @envs = $class->build_environment_vars_for($path, LITERAL_ENV);
 276   my $out = '';
 277
 278   # rather basic csh detection, goes on the assumption that something won't
 279   # call itself csh unless it really is. also, default to bourne in the
 280   # pathological situation where a user doesn't have $ENV{SHELL} defined.
 281   # note also that shells with funny names, like zoid, are assumed to be
 282   # bourne.
 283
 284   my $shelltype = $class->guess_shelltype;
 285
 286   while (@envs) {
 287     my ($name, $value) = (shift(@envs), shift(@envs));
 288     $value =~ s/(\\")/\\$1/g;
 289     $out .= $class->${\"build_${shelltype}_env_declaration"}($name, $value);
 290   }
 291   return $out;
 292 }
 293
 294 # simple routines that take two arguments: an %ENV key and a value. return
 295 # strings that are suitable for passing directly to the relevant shell to set
 296 # said key to said value.
 297 sub build_bourne_env_declaration {
 298   my $class = shift;
 299   my($name, $value) = @_;
 300   return qq{export ${name}="${value}"\n};
 301 }
 302
 303 sub build_csh_env_declaration {
 304   my $class = shift;
 305   my($name, $value) = @_;
 306   return qq{setenv ${name} "${value}"\n};
 307 }
 308
 309 sub build_win32_env_declaration {
 310   my $class = shift;
 311   my($name, $value) = @_;
 312   return qq{set ${name}=${value}\n};
 313 }
 314
 315 sub setup_env_hash_for {
 316   my ($class, $path) = @_;
 317   my %envs = $class->build_environment_vars_for($path, INTERPOLATE_ENV);
 318   @ENV{keys %envs} = values %envs;
 319 }
 320
 321 sub build_environment_vars_for {
 322   my ($class, $path, $interpolate) = @_;
 323   return (
 324     PERL_LOCAL_LIB_ROOT => join($Config{path_sep},
 325               (($ENV{PERL_LOCAL_LIB_ROOT}||()) ?
 326                 ($interpolate == INTERPOLATE_ENV
 327                   ? ($ENV{PERL_LOCAL_LIB_ROOT}||())
 328                   : (($^O ne 'MSWin32') ? '$PERL_LOCAL_LIB_ROOT'
 329                     : '%PERL_LOCAL_LIB_ROOT%' ))
 330                 : ()),
 331                 $path
 332             ),
 333     PERL_MB_OPT => "--install_base ${path}",
 334     PERL_MM_OPT => "INSTALL_BASE=${path}",
 335     PERL5LIB => join($Config{path_sep},
 336                   $class->install_base_arch_path($path),
 337                   $class->install_base_perl_path($path),
 338                   (($ENV{PERL5LIB}||()) ?
 339                     ($interpolate == INTERPOLATE_ENV
 340                       ? ($ENV{PERL5LIB})
 341                       : (($^O ne 'MSWin32') ? '$PERL5LIB' : '%PERL5LIB%' ))
 342                     : ())
 343                 ),
 344     PATH => join($Config{path_sep},
 345               $class->install_base_bin_path($path),
 346               ($interpolate == INTERPOLATE_ENV
 347                 ? ($ENV{PATH}||())
 348                 : (($^O ne 'MSWin32') ? '$PATH' : '%PATH%' ))
 349              ),
 350   )
 351 }
 352
 353 =begin testing
 354
 355 #:: test classmethod
 356
 357 File::Path::rmtree('t/var/splat');
 358
 359 $c->ensure_dir_structure_for('t/var/splat');
 360
 361 ok(-d 't/var/splat');
 362
 363 =end testing
 364
 365 =encoding utf8
 366
 367 =head1 NAME
 368
 369 local::lib - create and use a local lib/ for perl modules with PERL5LIB
 370
 371 =head1 SYNOPSIS
 372
 373 In code -
 374
 375   use local::lib; # sets up a local lib at ~/perl5
 376
 377   use local::lib '~/foo'; # same, but ~/foo
 378
 379   # Or...
 380   use FindBin;
 381   use local::lib "$FindBin::Bin/../support";  # app-local support library
 382
 383 From the shell -
 384
 385   # Install LWP and its missing dependencies to the '~/perl5' directory
 386   perl -MCPAN -Mlocal::lib -e 'CPAN::install(LWP)'
 387
 388   # Just print out useful shell commands
 389   $ perl -Mlocal::lib
 390   export PERL_MB_OPT='--install_base /home/username/perl5'
 391   export PERL_MM_OPT='INSTALL_BASE=/home/username/perl5'
 392   export PERL5LIB='/home/username/perl5/lib/perl5/i386-linux:/home/username/perl5/lib/perl5'
 393   export PATH="/home/username/perl5/bin:$PATH"
 394
 395 =head2 The bootstrapping technique
 396
 397 A typical way to install local::lib is using what is known as the
 398 "bootstrapping" technique.  You would do this if your system administrator
 399 hasn't already installed local::lib.  In this case, you'll need to install
 400 local::lib in your home directory.
 401
 402 If you do have administrative privileges, you will still want to set up your
 403 environment variables, as discussed in step 4. Without this, you would still
 404 install the modules into the system CPAN installation and also your Perl scripts
 405 will not use the lib/ path you bootstrapped with local::lib.
 406
 407 By default local::lib installs itself and the CPAN modules into ~/perl5.
 408
 409 Windows users must also see L</Differences when using this module under Win32>.
 410
 411 1. Download and unpack the local::lib tarball from CPAN (search for "Download"
 412 on the CPAN page about local::lib).  Do this as an ordinary user, not as root
 413 or administrator.  Unpack the file in your home directory or in any other
 414 convenient location.
 415
 416 2. Run this:
 417
 418   perl Makefile.PL --bootstrap
 419
 420 If the system asks you whether it should automatically configure as much
 421 as possible, you would typically answer yes.
 422
 423 In order to install local::lib into a directory other than the default, you need
 424 to specify the name of the directory when you call bootstrap, as follows:
 425
 426   perl Makefile.PL --bootstrap=~/foo
 427
 428 3. Run this: (local::lib assumes you have make installed on your system)
 429
 430   make test && make install
 431
 432 4. Now we need to setup the appropriate environment variables, so that Perl
 433 starts using our newly generated lib/ directory. If you are using bash or
 434 any other Bourne shells, you can add this to your shell startup script this
 435 way:
 436
 437   echo 'eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)' >>~/.bashrc
 438
 439 If you are using C shell, you can do this as follows:
 440
 441   /bin/csh
 442   echo $SHELL
 443   /bin/csh
 444   perl -I$HOME/perl5/lib/perl5 -Mlocal::lib >> ~/.cshrc
 445
 446 If you passed to bootstrap a directory other than default, you also need to give that as
 447 import parameter to the call of the local::lib module like this way:
 448
 449   echo 'eval $(perl -I$HOME/foo/lib/perl5 -Mlocal::lib=$HOME/foo)' >>~/.bashrc
 450
 451 After writing your shell configuration file, be sure to re-read it to get the
 452 changed settings into your current shell's environment. Bourne shells use
 453 C<. ~/.bashrc> for this, whereas C shells use C<source ~/.cshrc>.
 454
 455 If you're on a slower machine, or are operating under draconian disk space
 456 limitations, you can disable the automatic generation of manpages from POD when
 457 installing modules by using the C<--no-manpages> argument when bootstrapping:
 458
 459   perl Makefile.PL --bootstrap --no-manpages
 460
 461 To avoid doing several bootstrap for several Perl module environments on the
 462 same account, for example if you use it for several different deployed
 463 applications independently, you can use one bootstrapped local::lib
 464 installation to install modules in different directories directly this way:
 465
 466   cd ~/mydir1
 467   perl -Mlocal::lib=./
 468   eval $(perl -Mlocal::lib=./)  ### To set the environment for this shell alone
 469   printenv                      ### You will see that ~/mydir1 is in the PERL5LIB
 470   perl -MCPAN -e install ...    ### whatever modules you want
 471   cd ../mydir2
 472   ... REPEAT ...
 473
 474 For multiple environments for multiple apps you may need to include a modified
 475 version of the C<< use FindBin >> instructions in the "In code" sample above.
 476 If you did something like the above, you have a set of Perl modules at C<<
 477 ~/mydir1/lib >>. If you have a script at C<< ~/mydir1/scripts/myscript.pl >>,
 478 you need to tell it where to find the modules you installed for it at C<<
 479 ~/mydir1/lib >>.
 480
 481 In C<< ~/mydir1/scripts/myscript.pl >>:
 482
 483   use strict;
 484   use warnings;
 485   use local::lib "$FindBin::Bin/..";  ### points to ~/mydir1 and local::lib finds lib
 486   use lib "$FindBin::Bin/../lib";     ### points to ~/mydir1/lib
 487
 488 Put this before any BEGIN { ... } blocks that require the modules you installed.
 489
 490 =head2 Differences when using this module under Win32
 491
 492 To set up the proper environment variables for your current session of
 493 C<CMD.exe>, you can use this:
 494
 495   C:\>perl -Mlocal::lib
 496   set PERL_MB_OPT=--install_base C:\DOCUME~1\ADMINI~1\perl5
 497   set PERL_MM_OPT=INSTALL_BASE=C:\DOCUME~1\ADMINI~1\perl5
 498   set PERL5LIB=C:\DOCUME~1\ADMINI~1\perl5\lib\perl5;C:\DOCUME~1\ADMINI~1\perl5\lib\perl5\MSWin32-x86-multi-thread
 499   set PATH=C:\DOCUME~1\ADMINI~1\perl5\bin;%PATH%
 500
 501   ### To set the environment for this shell alone
 502   C:\>perl -Mlocal::lib > %TEMP%\tmp.bat && %TEMP%\tmp.bat && del %TEMP%\temp.bat
 503   ### instead of $(perl -Mlocal::lib=./)
 504
 505 If you want the environment entries to persist, you'll need to add then to the
 506 Control Panel's System applet yourself or use L<App::local::lib::Win32Helper>.
 507
 508 The "~" is translated to the user's profile directory (the directory named for
 509 the user under "Documents and Settings" (Windows XP or earlier) or "Users"
 510 (Windows Vista or later)) unless $ENV{HOME} exists. After that, the home
 511 directory is translated to a short name (which means the directory must exist)
 512 and the subdirectories are created.
 513
 514 =head1 RATIONALE
 515
 516 The version of a Perl package on your machine is not always the version you
 517 need.  Obviously, the best thing to do would be to update to the version you
 518 need.  However, you might be in a situation where you're prevented from doing
 519 this.  Perhaps you don't have system administrator privileges; or perhaps you
 520 are using a package management system such as Debian, and nobody has yet gotten
 521 around to packaging up the version you need.
 522
 523 local::lib solves this problem by allowing you to create your own directory of
 524 Perl packages downloaded from CPAN (in a multi-user system, this would typically
 525 be within your own home directory).  The existing system Perl installation is
 526 not affected; you simply invoke Perl with special options so that Perl uses the
 527 packages in your own local package directory rather than the system packages.
 528 local::lib arranges things so that your locally installed version of the Perl
 529 packages takes precedence over the system installation.
 530
 531 If you are using a package management system (such as Debian), you don't need to
 532 worry about Debian and CPAN stepping on each other's toes.  Your local version
 533 of the packages will be written to an entirely separate directory from those
 534 installed by Debian.
 535
 536 =head1 DESCRIPTION
 537
 538 This module provides a quick, convenient way of bootstrapping a user-local Perl
 539 module library located within the user's home directory. It also constructs and
 540 prints out for the user the list of environment variables using the syntax
 541 appropriate for the user's current shell (as specified by the C<SHELL>
 542 environment variable), suitable for directly adding to one's shell
 543 configuration file.
 544
 545 More generally, local::lib allows for the bootstrapping and usage of a
 546 directory containing Perl modules outside of Perl's C<@INC>. This makes it
 547 easier to ship an application with an app-specific copy of a Perl module, or
 548 collection of modules. Useful in cases like when an upstream maintainer hasn't
 549 applied a patch to a module of theirs that you need for your application.
 550
 551 On import, local::lib sets the following environment variables to appropriate
 552 values:
 553
 554 =over 4
 555
 556 =item PERL_MB_OPT
 557
 558 =item PERL_MM_OPT
 559
 560 =item PERL5LIB
 561
 562 =item PATH
 563
 564 PATH is appended to, rather than clobbered.
 565
 566 =back
 567
 568 These values are then available for reference by any code after import.
 569
 570 =head1 CREATING A SELF-CONTAINED SET OF MODULES
 571
 572 See L<lib::core::only> for one way to do this - but note that
 573 there are a number of caveats, and the best approach is always to perform a
 574 build against a clean perl (i.e. site and vendor as close to empty as possible).
 575
 576 =head1 METHODS
 577
 578 =head2 ensure_dir_structure_for
 579
 580 =over 4
 581
 582 =item Arguments: $path
 583
 584 =item Return value: None
 585
 586 =back
 587
 588 Attempts to create the given path, and all required parent directories. Throws
 589 an exception on failure.
 590
 591 =head2 print_environment_vars_for
 592
 593 =over 4
 594
 595 =item Arguments: $path
 596
 597 =item Return value: None
 598
 599 =back
 600
 601 Prints to standard output the variables listed above, properly set to use the
 602 given path as the base directory.
 603
 604 =head2 build_environment_vars_for
 605
 606 =over 4
 607
 608 =item Arguments: $path, $interpolate
 609
 610 =item Return value: \%environment_vars
 611
 612 =back
 613
 614 Returns a hash with the variables listed above, properly set to use the
 615 given path as the base directory.
 616
 617 =head2 setup_env_hash_for
 618
 619 =over 4
 620
 621 =item Arguments: $path
 622
 623 =item Return value: None
 624
 625 =back
 626
 627 Constructs the C<%ENV> keys for the given path, by calling
 628 L</build_environment_vars_for>.
 629
 630 =head2 install_base_perl_path
 631
 632 =over 4
 633
 634 =item Arguments: $path
 635
 636 =item Return value: $install_base_perl_path
 637
 638 =back
 639
 640 Returns a path describing where to install the Perl modules for this local
 641 library installation. Appends the directories C<lib> and C<perl5> to the given
 642 path.
 643
 644 =head2 install_base_arch_path
 645
 646 =over 4
 647
 648 =item Arguments: $path
 649
 650 =item Return value: $install_base_arch_path
 651
 652 =back
 653
 654 Returns a path describing where to install the architecture-specific Perl
 655 modules for this local library installation. Based on the
 656 L</install_base_perl_path> method's return value, and appends the value of
 657 C<$Config{archname}>.
 658
 659 =head2 install_base_bin_path
 660
 661 =over 4
 662
 663 =item Arguments: $path
 664
 665 =item Return value: $install_base_bin_path
 666
 667 =back
 668
 669 Returns a path describing where to install the executable programs for this
 670 local library installation. Based on the L</install_base_perl_path> method's
 671 return value, and appends the directory C<bin>.
 672
 673 =head2 resolve_empty_path
 674
 675 =over 4
 676
 677 =item Arguments: $path
 678
 679 =item Return value: $base_path
 680
 681 =back
 682
 683 Builds and returns the base path into which to set up the local module
 684 installation. Defaults to C<~/perl5>.
 685
 686 =head2 resolve_home_path
 687
 688 =over 4
 689
 690 =item Arguments: $path
 691
 692 =item Return value: $home_path
 693
 694 =back
 695
 696 Attempts to find the user's home directory. If installed, uses C<File::HomeDir>
 697 for this purpose. If no definite answer is available, throws an exception.
 698
 699 =head2 resolve_relative_path
 700
 701 =over 4
 702
 703 =item Arguments: $path
 704
 705 =item Return value: $absolute_path
 706
 707 =back
 708
 709 Translates the given path into an absolute path.
 710
 711 =head2 resolve_path
 712
 713 =over 4
 714
 715 =item Arguments: $path
 716
 717 =item Return value: $absolute_path
 718
 719 =back
 720
 721 Calls the following in a pipeline, passing the result from the previous to the
 722 next, in an attempt to find where to configure the environment for a local
 723 library installation: L</resolve_empty_path>, L</resolve_home_path>,
 724 L</resolve_relative_path>. Passes the given path argument to
 725 L</resolve_empty_path> which then returns a result that is passed to
 726 L</resolve_home_path>, which then has its result passed to
 727 L</resolve_relative_path>. The result of this final call is returned from
 728 L</resolve_path>.
 729
 730 =head1 A WARNING ABOUT UNINST=1
 731
 732 Be careful about using local::lib in combination with "make install UNINST=1".
 733 The idea of this feature is that will uninstall an old version of a module
 734 before installing a new one. However it lacks a safety check that the old
 735 version and the new version will go in the same directory. Used in combination
 736 with local::lib, you can potentially delete a globally accessible version of a
 737 module while installing the new version in a local place. Only combine "make
 738 install UNINST=1" and local::lib if you understand these possible consequences.
 739
 740 =head1 LIMITATIONS
 741
 742 The perl toolchain is unable to handle directory names with spaces in it,
 743 so you cant put your local::lib bootstrap into a directory with spaces. What
 744 you can do is moving your local::lib to a directory with spaces B<after> you
 745 installed all modules inside your local::lib bootstrap. But be aware that you
 746 cant update or install CPAN modules after the move.
 747
 748 Rather basic shell detection. Right now anything with csh in its name is
 749 assumed to be a C shell or something compatible, and everything else is assumed
 750 to be Bourne, except on Win32 systems. If the C<SHELL> environment variable is
 751 not set, a Bourne-compatible shell is assumed.
 752
 753 Bootstrap is a hack and will use CPAN.pm for ExtUtils::MakeMaker even if you
 754 have CPANPLUS installed.
 755
 756 Kills any existing PERL5LIB, PERL_MM_OPT or PERL_MB_OPT.
 757
 758 Should probably auto-fixup CPAN config if not already done.
 759
 760 Patches very much welcome for any of the above.
 761
 762 On Win32 systems, does not have a way to write the created environment variables
 763 to the registry, so that they can persist through a reboot.
 764
 765 =head1 TROUBLESHOOTING
 766
 767 If you've configured local::lib to install CPAN modules somewhere in to your
 768 home directory, and at some point later you try to install a module with C<cpan
 769 -i Foo::Bar>, but it fails with an error like: C<Warning: You do not have
 770 permissions to install into /usr/lib64/perl5/site_perl/5.8.8/x86_64-linux at
 771 /usr/lib64/perl5/5.8.8/Foo/Bar.pm> and buried within the install log is an
 772 error saying C<'INSTALL_BASE' is not a known MakeMaker parameter name>, then
 773 you've somehow lost your updated ExtUtils::MakeMaker module.
 774
 775 To remedy this situation, rerun the bootstrapping procedure documented above.
 776
 777 Then, run C<rm -r ~/.cpan/build/Foo-Bar*>
 778
 779 Finally, re-run C<cpan -i Foo::Bar> and it should install without problems.
 780
 781 =head1 ENVIRONMENT
 782
 783 =over 4
 784
 785 =item SHELL
 786
 787 =item COMSPEC
 788
 789 local::lib looks at the user's C<SHELL> environment variable when printing out
 790 commands to add to the shell configuration file.
 791
 792 On Win32 systems, C<COMSPEC> is also examined.
 793
 794 =back
 795
 796 =head1 SUPPORT
 797
 798 IRC:
 799
 800     Join #local-lib on irc.perl.org.
 801
 802 =head1 AUTHOR
 803
 804 Matt S Trout <mst@shadowcat.co.uk> http://www.shadowcat.co.uk/
 805
 806 auto_install fixes kindly sponsored by http://www.takkle.com/
 807
 808 =head1 CONTRIBUTORS
 809
 810 Patches to correctly output commands for csh style shells, as well as some
 811 documentation additions, contributed by Christopher Nehren <apeiron@cpan.org>.
 812
 813 Doc patches for a custom local::lib directory, more cleanups in the english
 814 documentation and a L<german documentation|POD2::DE::local::lib> contributed by Torsten Raudssus
 815 <torsten@raudssus.de>.
 816
 817 Hans Dieter Pearcey <hdp@cpan.org> sent in some additional tests for ensuring
 818 things will install properly, submitted a fix for the bug causing problems with
 819 writing Makefiles during bootstrapping, contributed an example program, and
 820 submitted yet another fix to ensure that local::lib can install and bootstrap
 821 properly. Many, many thanks!
 822
 823 pattern of Freenode IRC contributed the beginnings of the Troubleshooting
 824 section. Many thanks!
 825
 826 Patch to add Win32 support contributed by Curtis Jewell <csjewell@cpan.org>.
 827
 828 Warnings for missing PATH/PERL5LIB (as when not running interactively) silenced
 829 by a patch from Marco Emilio Poleggi.
 830
 831 Mark Stosberg <mark@summersault.com> provided the code for the now deleted
 832 '--self-contained' option.
 833
 834 Documentation patches to make win32 usage clearer by
 835 David Mertens <dcmertens.perl@gmail.com> (run4flat).
 836
 837 Brazilian L<portuguese translation|POD2::PT_BR::local::lib> and minor doc patches contributed by Breno
 838 G. de Oliveira <garu@cpan.org>.
 839
 840 =head1 COPYRIGHT
 841
 842 Copyright (c) 2007 - 2010 the local::lib L</AUTHOR> and L</CONTRIBUTORS> as
 843 listed above.
 844
 845 =head1 LICENSE
 846
 847 This library is free software and may be distributed under the same terms
 848 as perl itself.
 849
 850 =cut
 851
 852 1;