lib/local/lib.pm

   1 use strict;
   2 use warnings;
   3
   4 package local::lib;
   5
   6 use 5.006;
   7
   8 use File::Spec ();
   9 use Config;
  10
  11 our $VERSION = '1.008026'; # 1.8.26
  12 $VERSION = eval $VERSION;
  13
  14 sub import {
  15   my ($class, @args) = @_;
  16
  17   my @steps;
  18   my %opts;
  19
  20   while (@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 =~ /−/) {
  25       die <<'DEATH';
  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.
  32 DEATH
  33     }
  34     elsif ($arg eq '--self-contained') {
  35       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";
  36     }
  37     elsif( $arg =~ /^--deactivate(?:=(.*))?$/ ) {
  38       my $path = defined $1 ? $1 : shift @args;
  39       push @steps, ['deactivate', $path];
  40     }
  41     elsif ( $arg eq '--deactivate-all' ) {
  42       push @steps, ['deactivate_all'];
  43     }
  44     elsif ( $arg =~ /^--shelltype(?:=(.*))?$/ ) {
  45       my $shell = defined $1 ? $1 : shift @args;
  46       $opts{shelltype} = $shell;
  47     }
  48     elsif ( $arg eq '--no-create' ) {
  49       $opts{no_create} = 1;
  50     }
  51     elsif ( $arg =~ /^--/ ) {
  52       die "Unknown import argument: $arg";
  53     }
  54     else {
  55       push @steps, ['activate', $arg];
  56     }
  57   }
  58   if (!@steps) {
  59     push @steps, ['activate', undef];
  60   }
  61
  62   my $self = $class->new(%opts);
  63
  64   for (@steps) {
  65     my ($method, @args) = @$_;
  66     $self = $self->$method(@args);
  67   }
  68
  69   if ($0 eq '-') {
  70     $self->print_environment_vars_for;
  71     exit 0;
  72   }
  73   else {
  74     $self->setup_local_lib_for;
  75   }
  76 }
  77
  78 sub new {
  79   my $class = shift;
  80   bless {@_}, $class;
  81 }
  82
  83 sub clone {
  84   my $self = shift;
  85   bless {%$self, @_}, ref $self;
  86 }
  87
  88 sub inc { $_[0]->{inc}     ||= \@INC }
  89 sub libs { $_[0]->{libs}   ||= [ \'PERL5LIB' ] }
  90 sub bins { $_[0]->{bins}   ||= [ \'PATH' ] }
  91 sub roots { $_[0]->{roots} ||= [ \'PERL_LOCAL_LIB_ROOT' ] }
  92 sub extra { $_[0]->{extra} ||= {} }
  93 sub shelltype { $_[0]->{shelltype} ||= $_[0]->guess_shelltype }
  94 sub no_create { $_[0]->{no_create} }
  95
  96 my $_archname = $Config{archname};
  97 my $_version  = $Config{version};
  98 my @_inc_version_list = reverse split / /, $Config{inc_version_list};
  99 my $_path_sep = $Config{path_sep};
 100
 101 sub _as_list {
 102   my $list = shift;
 103   grep length, map {
 104     !(ref $_ && ref $_ eq 'SCALAR') ? $_ : (
 105       defined $ENV{$$_} ? split(/\Q$_path_sep/, $ENV{$$_})
 106                         : ()
 107     )
 108   } ref $list ? @$list : $list;
 109 }
 110 sub _remove_from {
 111   my ($list, @remove) = @_;
 112   return @$list
 113     if !@remove;
 114   my %remove = map { $_ => 1 } @remove;
 115   grep !$remove{$_}, _as_list($list);
 116 }
 117
 118 my @_lib_subdirs = (
 119   [$_version, $_archname],
 120   [$_version],
 121   [$_archname],
 122   (@_inc_version_list ? \@_inc_version_list : ()),
 123   [],
 124 );
 125
 126 sub install_base_bin_path {
 127   my ($class, $path) = @_;
 128   return File::Spec->catdir($path, 'bin');
 129 }
 130 sub install_base_perl_path {
 131   my ($class, $path) = @_;
 132   return File::Spec->catdir($path, 'lib', 'perl5');
 133 }
 134 sub install_base_arch_path {
 135   my ($class, $path) = @_;
 136   File::Spec->catdir($class->install_base_perl_path($path), $_archname);
 137 }
 138
 139 sub lib_paths_for {
 140   my ($class, $path) = @_;
 141   my $base = $class->install_base_perl_path($path);
 142   return map { File::Spec->catdir($base, @$_) } @_lib_subdirs;
 143 }
 144
 145 sub _mm_escape_path {
 146   my $path = shift;
 147   $path =~ s/\\/\\\\\\\\/g;
 148   if ($path =~ s/ /\\ /g) {
 149     $path = qq{"\\"$path\\""};
 150   }
 151   return $path;
 152 }
 153
 154 sub _mb_escape_path {
 155   my $path = shift;
 156   $path =~ s/\\/\\\\/g;
 157   return qq{"$path"};
 158 }
 159
 160 sub installer_options_for {
 161   my ($class, $path) = @_;
 162   return {
 163     PERL_MM_OPT => defined $path ? "INSTALL_BASE="._mm_escape_path($path) : undef,
 164     PERL_MB_OPT => defined $path ? "--install_base "._mb_escape_path($path) : undef,
 165   };
 166 }
 167
 168 sub active_paths {
 169   my ($self) = @_;
 170   $self = ref $self ? $self : $self->new;
 171
 172   return grep {
 173     # screen out entries that aren't actually reflected in @INC
 174     my $active_ll = $self->install_base_perl_path($_);
 175     grep { $_ eq $active_ll } @{$self->inc};
 176   } _as_list($self->roots);
 177 }
 178
 179
 180 sub deactivate {
 181   my ($self, $path) = @_;
 182   $self = $self->new unless ref $self;
 183   $path = $self->resolve_path($path);
 184   $path = $self->normalize_path($path);
 185
 186   my @active_lls = $self->active_paths;
 187
 188   if (!grep { $_ eq $path } @active_lls) {
 189     warn "Tried to deactivate inactive local::lib '$path'\n";
 190     return $self;
 191   }
 192
 193   my %args = (
 194     bins  => [ _remove_from($self->bins,  $self->install_base_bin_path($path)) ],
 195     libs  => [ _remove_from($self->libs,  $self->install_base_perl_path($path)) ],
 196     inc   => [ _remove_from($self->inc,   $self->lib_paths_for($path)) ],
 197     roots => [ _remove_from($self->roots, $path) ],
 198   );
 199
 200   $args{extra} = $self->installer_options_for($args{roots}[0]);
 201
 202   $self->clone(%args);
 203 }
 204
 205 sub deactivate_all {
 206   my ($self) = @_;
 207   $self = $self->new unless ref $self;
 208
 209   my @active_lls = $self->active_paths;
 210
 211   my %args;
 212   if (@active_lls) {
 213     %args = (
 214       bins => [ _remove_from($self->bins,
 215         map $self->install_base_bin_path($_), @active_lls) ],
 216       libs => [ _remove_from($self->libs,
 217         map $self->install_base_perl_path($_), @active_lls) ],
 218       inc => [ _remove_from($self->inc,
 219         map $self->lib_paths_for($_), @active_lls) ],
 220       roots => [ _remove_from($self->roots, @active_lls) ],
 221     );
 222   }
 223
 224   $args{extra} = $self->installer_options_for(undef);
 225
 226   $self->clone(%args);
 227 }
 228
 229 sub activate {
 230   my ($self, $path) = @_;
 231   $self = $self->new unless ref $self;
 232   $path = $self->resolve_path($path);
 233   $self->ensure_dir_structure_for($path)
 234     unless $self->no_create;
 235
 236   $path = $self->normalize_path($path);
 237
 238   my @active_lls = $self->active_paths;
 239
 240   if (grep { $_ eq $path } @active_lls[1 .. $#active_lls]) {
 241     $self = $self->deactivate($path);
 242   }
 243
 244   my %args;
 245   if (!@active_lls || $active_lls[0] ne $path) {
 246     %args = (
 247       bins  => [ $self->install_base_bin_path($path), @{$self->bins} ],
 248       libs  => [ $self->install_base_perl_path($path), @{$self->libs} ],
 249       inc   => [ $self->lib_paths_for($path), @{$self->inc} ],
 250       roots => [ $path, @{$self->roots} ],
 251     );
 252   }
 253
 254   $args{extra} = $self->installer_options_for($path);
 255
 256   $self->clone(%args);
 257 }
 258
 259 sub normalize_path {
 260   my ($self, $path) = @_;
 261   $path = ( Win32::GetShortPathName($path) || $path )
 262     if $^O eq 'MSWin32';
 263   return $path;
 264 }
 265
 266 sub _legacy {
 267   my ($self, $path) = @_;
 268   $self = $self->new unless ref $self;
 269   if (defined $path) {
 270     $self = $self->activate($path);
 271   }
 272   $self;
 273 }
 274
 275 sub build_environment_vars_for {
 276   my ($self) = _legacy(@_);
 277   (
 278     PATH                => join($_path_sep, _as_list($self->bins)),
 279     PERL5LIB            => join($_path_sep, _as_list($self->libs)),
 280     PERL_LOCAL_LIB_ROOT => join($_path_sep, _as_list($self->roots)),
 281     %{$self->extra},
 282   );
 283 }
 284
 285 sub setup_local_lib_for {
 286   my ($self) = _legacy(@_);
 287   $self->setup_env_hash_for;
 288   @INC = @{$self->inc};
 289 }
 290
 291 sub setup_env_hash_for {
 292   my $self = shift;
 293   my %env = $self->build_environment_vars_for(@_);
 294   for my $key (keys %env) {
 295     if (defined $env{$key}) {
 296       $ENV{$key} = $env{$key};
 297     }
 298     else {
 299       delete $ENV{$key};
 300     }
 301   }
 302 }
 303
 304 sub print_environment_vars_for {
 305   my $self = shift;
 306   print $self->environment_vars_string_for(@_);
 307 }
 308
 309 sub environment_vars_string_for {
 310   my $self = _legacy(@_);
 311
 312   my $build_method = 'build_' . $self->shelltype . '_env_declaration';
 313
 314   my @envs = (
 315     PATH                => $self->bins,
 316     PERL5LIB            => $self->libs,
 317     PERL_LOCAL_LIB_ROOT => $self->roots,
 318     %{$self->extra},
 319   );
 320   my $out = '';
 321   while (@envs) {
 322     my ($name, $value) = (shift(@envs), shift(@envs));
 323     if (
 324         ref $value
 325         && @$value == 1
 326         && ref $value->[0]
 327         && ref $value->[0] eq 'SCALAR'
 328         && ${$value->[0]} eq $name) {
 329       next;
 330     }
 331     if (
 332         !ref $value
 333         and defined $value
 334           ? (defined $ENV{$name} && $value eq $ENV{$name})
 335           : !defined $ENV{$name}
 336     ) {
 337       next;
 338     }
 339     $out .= $self->$build_method($name, $value);
 340   }
 341   my $wrap_method = 'wrap_' . $self->shelltype . '_output';
 342   if ($self->can($wrap_method)) {
 343     return $self->$wrap_method($out);
 344   }
 345   return $out;
 346 }
 347
 348 sub build_bourne_env_declaration {
 349   my ($class, $name, $args) = @_;
 350   my $value = $class->_interpolate($args, '$%s', '"', '\\%s');
 351
 352   if (!defined $value) {
 353     return qq{unset $name;\n};
 354   }
 355
 356   $value =~ s/(^|\G|$_path_sep)\$$name$_path_sep/$1\$$name\${$name+$_path_sep}/g;
 357   $value =~ s/$_path_sep\$$name$/\${$name+$_path_sep}\$$name/;
 358
 359   qq{export ${name}="$value";\n}
 360 }
 361
 362 sub build_csh_env_declaration {
 363   my ($class, $name, $args) = @_;
 364   my ($value, @vars) = $class->_interpolate($args, '$%s', '"', '"\\%s"');
 365   if (!defined $value) {
 366     return qq{unsetenv $name;\n};
 367   }
 368
 369   my $out = '';
 370   for my $var (@vars) {
 371     $out .= qq{if ! \$?$name setenv $name '';\n};
 372   }
 373
 374   my $value_without = $value;
 375   if ($value_without =~ s/(?:^|$_path_sep)\$$name(?:$_path_sep|$)//g) {
 376     $out .= qq{if "\$$name" != '' setenv $name "$value";\n};
 377     $out .= qq{if "\$$name" == '' };
 378   }
 379   $out .= qq{setenv $name "$value_without";\n};
 380   return $out;
 381 }
 382
 383 sub build_cmd_env_declaration {
 384   my ($class, $name, $args) = @_;
 385   my $value = $class->_interpolate($args, '%%%s%%', qr([()!^"<>&|]), '^%s');
 386   if (!$value) {
 387     return qq{\@set $name=\n};
 388   }
 389
 390   my $out = '';
 391   my $value_without = $value;
 392   if ($value_without =~ s/(?:^|$_path_sep)%$name%(?:$_path_sep|$)//g) {
 393     $out .= qq{\@if not "%$name%"=="" set $name=$value\n};
 394     $out .= qq{\@if "%$name%"=="" };
 395   }
 396   $out .= qq{\@set $name=$value_without\n};
 397   return $out;
 398 }
 399
 400 sub build_powershell_env_declaration {
 401   my ($class, $name, $args) = @_;
 402   my $value = $class->_interpolate($args, '$env:%s', '"', '`%s');
 403
 404   if (!$value) {
 405     return qq{Remove-Item Env:\\$name;\n};
 406   }
 407
 408   my $maybe_path_sep = qq{\$(if("\$env:$name"-eq""){""}else{"$_path_sep"})};
 409   $value =~ s/(^|\G|$_path_sep)\$env:$name$_path_sep/$1\$env:$name"+$maybe_path_sep+"/g;
 410   $value =~ s/$_path_sep\$env:$name$/"+$maybe_path_sep+\$env:$name+"/;
 411
 412   qq{\$env:$name = \$("$value");\n};
 413 }
 414 sub wrap_powershell_output {
 415   my ($class, $out) = @_;
 416   return $out || " \n";
 417 }
 418
 419 sub _interpolate {
 420   my ($class, $args, $var_pat, $escape, $escape_pat) = @_;
 421   return
 422     unless defined $args;
 423   my @args = ref $args ? @$args : $args;
 424   return
 425     unless @args;
 426   my @vars = map { $$_ } grep { ref $_ eq 'SCALAR' } @args;
 427   my $string = join $_path_sep, map {
 428     ref $_ eq 'SCALAR' ? sprintf($var_pat, $$_) : do {
 429       s/($escape)/sprintf($escape_pat, $1)/ge; $_;
 430     };
 431   } @args;
 432   return wantarray ? ($string, \@vars) : $string;
 433 }
 434
 435 sub pipeline;
 436
 437 sub pipeline {
 438   my @methods = @_;
 439   my $last = pop(@methods);
 440   if (@methods) {
 441     \sub {
 442       my ($obj, @args) = @_;
 443       $obj->${pipeline @methods}(
 444         $obj->$last(@args)
 445       );
 446     };
 447   } else {
 448     \sub {
 449       shift->$last(@_);
 450     };
 451   }
 452 }
 453
 454 =begin testing
 455
 456 #:: test pipeline
 457
 458 package local::lib;
 459
 460 { package Foo; sub foo { -$_[1] } sub bar { $_[1]+2 } sub baz { $_[1]+3 } }
 461 my $foo = bless({}, 'Foo');
 462 Test::More::ok($foo->${pipeline qw(foo bar baz)}(10) == -15);
 463
 464 =end testing
 465
 466 =cut
 467
 468 sub resolve_path {
 469   my ($class, $path) = @_;
 470
 471   $path = $class->${pipeline qw(
 472     resolve_relative_path
 473     resolve_home_path
 474     resolve_empty_path
 475   )}($path);
 476
 477   $path;
 478 }
 479
 480 sub resolve_empty_path {
 481   my ($class, $path) = @_;
 482   if (defined $path) {
 483     $path;
 484   } else {
 485     '~/perl5';
 486   }
 487 }
 488
 489 =begin testing
 490
 491 #:: test classmethod setup
 492
 493 my $c = 'local::lib';
 494
 495 =end testing
 496
 497 =begin testing
 498
 499 #:: test classmethod
 500
 501 is($c->resolve_empty_path, '~/perl5');
 502 is($c->resolve_empty_path('foo'), 'foo');
 503
 504 =end testing
 505
 506 =cut
 507
 508 sub resolve_home_path {
 509   my ($class, $path) = @_;
 510   return $path unless ($path =~ /^~/);
 511   my ($user) = ($path =~ /^~([^\/]+)/); # can assume ^~ so undef for 'us'
 512   my $homedir = do {
 513     if (!defined $user && defined $ENV{HOME}) {
 514       $ENV{HOME}
 515     }
 516     else {
 517       require File::Glob;
 518       File::Glob::bsd_glob("~$user", File::Glob::GLOB_TILDE());
 519     }
 520   };
 521   unless (defined $homedir) {
 522     require Carp;
 523     Carp::croak(
 524       "Couldn't resolve homedir for "
 525       .(defined $user ? $user : 'current user')
 526     );
 527   }
 528   $path =~ s/^~[^\/]*/$homedir/;
 529   $path;
 530 }
 531
 532 sub resolve_relative_path {
 533   my ($class, $path) = @_;
 534   $path = File::Spec->rel2abs($path);
 535 }
 536
 537 =begin testing
 538
 539 #:: test classmethod
 540
 541 local *File::Spec::rel2abs = sub { shift; 'FOO'.shift; };
 542 is($c->resolve_relative_path('bar'),'FOObar');
 543
 544 =end testing
 545
 546 =cut
 547
 548 sub ensure_dir_structure_for {
 549   my ($class, $path) = @_;
 550   unless (-d $path) {
 551     warn "Attempting to create directory ${path}\n";
 552   }
 553   require File::Basename;
 554   my @dirs;
 555   while(!-d $path) {
 556     push @dirs, $path;
 557     $path = File::Basename::dirname($path);
 558   }
 559   mkdir $_ for reverse @dirs;
 560   return;
 561 }
 562
 563 =begin testing
 564
 565 #:: test classmethod
 566
 567 File::Path::rmtree('t/var/splat');
 568
 569 $c->ensure_dir_structure_for('t/var/splat');
 570
 571 ok(-d 't/var/splat');
 572
 573 =end testing
 574
 575 =cut
 576
 577 sub guess_shelltype {
 578   my $shellbin
 579     = defined $ENV{SHELL}
 580       ? (File::Spec->splitpath($ENV{SHELL}))[-1]
 581     : ( $^O eq 'MSWin32' && exists $ENV{'!EXITCODE'} )
 582       ? 'bash'
 583     : ( $^O eq 'MSWin32' && $ENV{PROMPT} && $ENV{COMSPEC} )
 584       ? (File::Spec->splitpath($ENV{COMSPEC}))[-1]
 585     : ( $^O eq 'MSWin32' && !$ENV{PROMPT} )
 586       ? 'powershell.exe'
 587     : 'sh';
 588
 589   for ($shellbin) {
 590     return
 591         /csh/              ? 'csh'
 592       : /command\.com/i    ? 'cmd'
 593       : /cmd\.exe/i        ? 'cmd'
 594       : /4nt\.exe/i        ? 'cmd'
 595       : /powershell\.exe/i ? 'powershell'
 596                            : 'bourne';
 597   }
 598 }
 599
 600 1;
 601 __END__
 602
 603 =encoding utf8
 604
 605 =head1 NAME
 606
 607 local::lib - create and use a local lib/ for perl modules with PERL5LIB
 608
 609 =head1 SYNOPSIS
 610
 611 In code -
 612
 613   use local::lib; # sets up a local lib at ~/perl5
 614
 615   use local::lib '~/foo'; # same, but ~/foo
 616
 617   # Or...
 618   use FindBin;
 619   use local::lib "$FindBin::Bin/../support";  # app-local support library
 620
 621 From the shell -
 622
 623   # Install LWP and its missing dependencies to the '~/perl5' directory
 624   perl -MCPAN -Mlocal::lib -e 'CPAN::install(LWP)'
 625
 626   # Just print out useful shell commands
 627   $ perl -Mlocal::lib
 628   export PERL_MB_OPT='--install_base /home/username/perl5'
 629   export PERL_MM_OPT='INSTALL_BASE=/home/username/perl5'
 630   export PERL5LIB="/home/username/perl5/lib/perl5"
 631   export PATH="/home/username/perl5/bin:$PATH"
 632
 633 =head2 The bootstrapping technique
 634
 635 A typical way to install local::lib is using what is known as the
 636 "bootstrapping" technique.  You would do this if your system administrator
 637 hasn't already installed local::lib.  In this case, you'll need to install
 638 local::lib in your home directory.
 639
 640 Even if you do have administrative privileges, you will still want to set up your
 641 environment variables, as discussed in step 4. Without this, you would still
 642 install the modules into the system CPAN installation and also your Perl scripts
 643 will not use the lib/ path you bootstrapped with local::lib.
 644
 645 By default local::lib installs itself and the CPAN modules into ~/perl5.
 646
 647 Windows users must also see L</Differences when using this module under Win32>.
 648
 649 1. Download and unpack the local::lib tarball from CPAN (search for "Download"
 650 on the CPAN page about local::lib).  Do this as an ordinary user, not as root
 651 or administrator.  Unpack the file in your home directory or in any other
 652 convenient location.
 653
 654 2. Run this:
 655
 656   perl Makefile.PL --bootstrap
 657
 658 If the system asks you whether it should automatically configure as much
 659 as possible, you would typically answer yes.
 660
 661 In order to install local::lib into a directory other than the default, you need
 662 to specify the name of the directory when you call bootstrap, as follows:
 663
 664   perl Makefile.PL --bootstrap=~/foo
 665
 666 3. Run this: (local::lib assumes you have make installed on your system)
 667
 668   make test && make install
 669
 670 4. Now we need to setup the appropriate environment variables, so that Perl
 671 starts using our newly generated lib/ directory. If you are using bash or
 672 any other Bourne shells, you can add this to your shell startup script this
 673 way:
 674
 675   echo 'eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)' >>~/.bashrc
 676
 677 If you are using C shell, you can do this as follows:
 678
 679   /bin/csh
 680   echo $SHELL
 681   /bin/csh
 682   echo 'eval `perl -I$HOME/perl5/lib/perl5 -Mlocal::lib`' >> ~/.cshrc
 683
 684 If you passed to bootstrap a directory other than default, you also need to
 685 give that as import parameter to the call of the local::lib module like this
 686 way:
 687
 688   echo 'eval $(perl -I$HOME/foo/lib/perl5 -Mlocal::lib=$HOME/foo)' >>~/.bashrc
 689
 690 After writing your shell configuration file, be sure to re-read it to get the
 691 changed settings into your current shell's environment. Bourne shells use
 692 C<. ~/.bashrc> for this, whereas C shells use C<source ~/.cshrc>.
 693
 694 If you're on a slower machine, or are operating under draconian disk space
 695 limitations, you can disable the automatic generation of manpages from POD when
 696 installing modules by using the C<--no-manpages> argument when bootstrapping:
 697
 698   perl Makefile.PL --bootstrap --no-manpages
 699
 700 To avoid doing several bootstrap for several Perl module environments on the
 701 same account, for example if you use it for several different deployed
 702 applications independently, you can use one bootstrapped local::lib
 703 installation to install modules in different directories directly this way:
 704
 705   cd ~/mydir1
 706   perl -Mlocal::lib=./
 707   eval $(perl -Mlocal::lib=./)  ### To set the environment for this shell alone
 708   printenv                      ### You will see that ~/mydir1 is in the PERL5LIB
 709   perl -MCPAN -e install ...    ### whatever modules you want
 710   cd ../mydir2
 711   ... REPEAT ...
 712
 713 If you are working with several C<local::lib> environments, you may want to
 714 remove some of them from the current environment without disturbing the others.
 715 You can deactivate one environment like this (using bourne sh):
 716
 717   eval $(perl -Mlocal::lib=--deactivate,~/path)
 718
 719 which will generate and run the commands needed to remove C<~/path> from your
 720 various search paths. Whichever environment was B<activated most recently> will
 721 remain the target for module installations. That is, if you activate
 722 C<~/path_A> and then you activate C<~/path_B>, new modules you install will go
 723 in C<~/path_B>. If you deactivate C<~/path_B> then modules will be installed
 724 into C<~/pathA> -- but if you deactivate C<~/path_A> then they will still be
 725 installed in C<~/pathB> because pathB was activated later.
 726
 727 You can also ask C<local::lib> to clean itself completely out of the current
 728 shell's environment with the C<--deactivate-all> option.
 729 For multiple environments for multiple apps you may need to include a modified
 730 version of the C<< use FindBin >> instructions in the "In code" sample above.
 731 If you did something like the above, you have a set of Perl modules at C<<
 732 ~/mydir1/lib >>. If you have a script at C<< ~/mydir1/scripts/myscript.pl >>,
 733 you need to tell it where to find the modules you installed for it at C<<
 734 ~/mydir1/lib >>.
 735
 736 In C<< ~/mydir1/scripts/myscript.pl >>:
 737
 738   use strict;
 739   use warnings;
 740   use local::lib "$FindBin::Bin/..";  ### points to ~/mydir1 and local::lib finds lib
 741   use lib "$FindBin::Bin/../lib";     ### points to ~/mydir1/lib
 742
 743 Put this before any BEGIN { ... } blocks that require the modules you installed.
 744
 745 =head2 Differences when using this module under Win32
 746
 747 To set up the proper environment variables for your current session of
 748 C<CMD.exe>, you can use this:
 749
 750   C:\>perl -Mlocal::lib
 751   set PERL_MB_OPT=--install_base C:\DOCUME~1\ADMINI~1\perl5
 752   set PERL_MM_OPT=INSTALL_BASE=C:\DOCUME~1\ADMINI~1\perl5
 753   set PERL5LIB=C:\DOCUME~1\ADMINI~1\perl5\lib\perl5
 754   set PATH=C:\DOCUME~1\ADMINI~1\perl5\bin;%PATH%
 755
 756   ### To set the environment for this shell alone
 757   C:\>perl -Mlocal::lib > %TEMP%\tmp.bat && %TEMP%\tmp.bat && del %TEMP%\tmp.bat
 758   ### instead of $(perl -Mlocal::lib=./)
 759
 760 If you want the environment entries to persist, you'll need to add them to the
 761 Control Panel's System applet yourself or use L<App::local::lib::Win32Helper>.
 762
 763 The "~" is translated to the user's profile directory (the directory named for
 764 the user under "Documents and Settings" (Windows XP or earlier) or "Users"
 765 (Windows Vista or later)) unless $ENV{HOME} exists. After that, the home
 766 directory is translated to a short name (which means the directory must exist)
 767 and the subdirectories are created.
 768
 769 =head3 PowerShell
 770
 771 local::lib also supports PowerShell, and an be used with the
 772 C<Invoke-Expression> cmdlet.
 773
 774   Invoke-Expression "$(perl -Mlocal::lib)"
 775
 776 =head1 RATIONALE
 777
 778 The version of a Perl package on your machine is not always the version you
 779 need.  Obviously, the best thing to do would be to update to the version you
 780 need.  However, you might be in a situation where you're prevented from doing
 781 this.  Perhaps you don't have system administrator privileges; or perhaps you
 782 are using a package management system such as Debian, and nobody has yet gotten
 783 around to packaging up the version you need.
 784
 785 local::lib solves this problem by allowing you to create your own directory of
 786 Perl packages downloaded from CPAN (in a multi-user system, this would typically
 787 be within your own home directory).  The existing system Perl installation is
 788 not affected; you simply invoke Perl with special options so that Perl uses the
 789 packages in your own local package directory rather than the system packages.
 790 local::lib arranges things so that your locally installed version of the Perl
 791 packages takes precedence over the system installation.
 792
 793 If you are using a package management system (such as Debian), you don't need to
 794 worry about Debian and CPAN stepping on each other's toes.  Your local version
 795 of the packages will be written to an entirely separate directory from those
 796 installed by Debian.
 797
 798 =head1 DESCRIPTION
 799
 800 This module provides a quick, convenient way of bootstrapping a user-local Perl
 801 module library located within the user's home directory. It also constructs and
 802 prints out for the user the list of environment variables using the syntax
 803 appropriate for the user's current shell (as specified by the C<SHELL>
 804 environment variable), suitable for directly adding to one's shell
 805 configuration file.
 806
 807 More generally, local::lib allows for the bootstrapping and usage of a
 808 directory containing Perl modules outside of Perl's C<@INC>. This makes it
 809 easier to ship an application with an app-specific copy of a Perl module, or
 810 collection of modules. Useful in cases like when an upstream maintainer hasn't
 811 applied a patch to a module of theirs that you need for your application.
 812
 813 On import, local::lib sets the following environment variables to appropriate
 814 values:
 815
 816 =over 4
 817
 818 =item PERL_MB_OPT
 819
 820 =item PERL_MM_OPT
 821
 822 =item PERL5LIB
 823
 824 =item PATH
 825
 826 =back
 827
 828 When possible, these will be appended to instead of overwritten entirely.
 829
 830 These values are then available for reference by any code after import.
 831
 832 =head1 CREATING A SELF-CONTAINED SET OF MODULES
 833
 834 See L<lib::core::only> for one way to do this - but note that
 835 there are a number of caveats, and the best approach is always to perform a
 836 build against a clean perl (i.e. site and vendor as close to empty as possible).
 837
 838 =head1 OPTIONS
 839
 840 Options are values that can be passed to the C<local::lib> import besides the
 841 directory to use. They are specified as C<use local::lib '--option'[, path];>
 842 or C<perl -Mlocal::lib=--option[,path]>.
 843
 844 =head2 --deactivate
 845
 846 Remove the chosen path (or the default path) from the module search paths if it
 847 was added by C<local::lib>, instead of adding it.
 848
 849 =head2 --deactivate-all
 850
 851 Remove all directories that were added to search paths by C<local::lib> from the
 852 search paths.
 853
 854 =head2 --shelltype
 855
 856 Specify the shell type to use for output.  By default, the shell will be
 857 detected based on the environment.  Should be one of: C<bourne>, C<csh>,
 858 C<cmd>, or C<powershell>.
 859
 860 =head2 --no-create
 861
 862 Prevents C<local::lib> from creating directories when activating dirs.  This is
 863 likely to cause issues on Win32 systems.
 864
 865 =head1 METHODS
 866
 867 =head2 ensure_dir_structure_for
 868
 869 =over 4
 870
 871 =item Arguments: $path
 872
 873 =item Return value: None
 874
 875 =back
 876
 877 Attempts to create the given path, and all required parent directories. Throws
 878 an exception on failure.
 879
 880 =head2 print_environment_vars_for
 881
 882 =over 4
 883
 884 =item Arguments: $path
 885
 886 =item Return value: None
 887
 888 =back
 889
 890 Prints to standard output the variables listed above, properly set to use the
 891 given path as the base directory.
 892
 893 =head2 build_environment_vars_for
 894
 895 =over 4
 896
 897 =item Arguments: $path
 898
 899 =item Return value: %environment_vars
 900
 901 =back
 902
 903 Returns a hash with the variables listed above, properly set to use the
 904 given path as the base directory.
 905
 906 =head2 setup_env_hash_for
 907
 908 =over 4
 909
 910 =item Arguments: $path
 911
 912 =item Return value: None
 913
 914 =back
 915
 916 Constructs the C<%ENV> keys for the given path, by calling
 917 L</build_environment_vars_for>.
 918
 919 =head2 active_paths
 920
 921 =over 4
 922
 923 =item Arguments: None
 924
 925 =item Return value: @paths
 926
 927 =back
 928
 929 Returns a list of active C<local::lib> paths, according to the
 930 C<PERL_LOCAL_LIB_ROOT> environment variable and verified against
 931 what is really in C<@INC>.
 932
 933 =head2 install_base_perl_path
 934
 935 =over 4
 936
 937 =item Arguments: $path
 938
 939 =item Return value: $install_base_perl_path
 940
 941 =back
 942
 943 Returns a path describing where to install the Perl modules for this local
 944 library installation. Appends the directories C<lib> and C<perl5> to the given
 945 path.
 946
 947 =head2 install_base_bin_path
 948
 949 =over 4
 950
 951 =item Arguments: $path
 952
 953 =item Return value: $install_base_bin_path
 954
 955 =back
 956
 957 Returns a path describing where to install the executable programs for this
 958 local library installation. Appends the directory C<bin> to the given path.
 959
 960 =head2 resolve_empty_path
 961
 962 =over 4
 963
 964 =item Arguments: $path
 965
 966 =item Return value: $base_path
 967
 968 =back
 969
 970 Builds and returns the base path into which to set up the local module
 971 installation. Defaults to C<~/perl5>.
 972
 973 =head2 resolve_home_path
 974
 975 =over 4
 976
 977 =item Arguments: $path
 978
 979 =item Return value: $home_path
 980
 981 =back
 982
 983 Attempts to find the user's home directory. If installed, uses C<File::HomeDir>
 984 for this purpose. If no definite answer is available, throws an exception.
 985
 986 =head2 resolve_relative_path
 987
 988 =over 4
 989
 990 =item Arguments: $path
 991
 992 =item Return value: $absolute_path
 993
 994 =back
 995
 996 Translates the given path into an absolute path.
 997
 998 =head2 resolve_path
 999
1000 =over 4
1001
1002 =item Arguments: $path
1003
1004 =item Return value: $absolute_path
1005
1006 =back
1007
1008 Calls the following in a pipeline, passing the result from the previous to the
1009 next, in an attempt to find where to configure the environment for a local
1010 library installation: L</resolve_empty_path>, L</resolve_home_path>,
1011 L</resolve_relative_path>. Passes the given path argument to
1012 L</resolve_empty_path> which then returns a result that is passed to
1013 L</resolve_home_path>, which then has its result passed to
1014 L</resolve_relative_path>. The result of this final call is returned from
1015 L</resolve_path>.
1016
1017 =head1 A WARNING ABOUT UNINST=1
1018
1019 Be careful about using local::lib in combination with "make install UNINST=1".
1020 The idea of this feature is that will uninstall an old version of a module
1021 before installing a new one. However it lacks a safety check that the old
1022 version and the new version will go in the same directory. Used in combination
1023 with local::lib, you can potentially delete a globally accessible version of a
1024 module while installing the new version in a local place. Only combine "make
1025 install UNINST=1" and local::lib if you understand these possible consequences.
1026
1027 =head1 LIMITATIONS
1028
1029 =over 4
1030
1031 =item * Directory names with spaces in them are not well supported by the perl
1032 toolchain and the programs it uses.  Pure-perl distributions should support
1033 spaces, but problems are more likely with dists that require compilation. A
1034 workaround you can do is moving your local::lib to a directory with spaces
1035 B<after> you installed all modules inside your local::lib bootstrap. But be
1036 aware that you can't update or install CPAN modules after the move.
1037
1038 =item * Rather basic shell detection. Right now anything with csh in its name is
1039 assumed to be a C shell or something compatible, and everything else is assumed
1040 to be Bourne, except on Win32 systems. If the C<SHELL> environment variable is
1041 not set, a Bourne-compatible shell is assumed.
1042
1043 =item * Kills any existing PERL_MM_OPT or PERL_MB_OPT.
1044
1045 =item * Should probably auto-fixup CPAN config if not already done.
1046
1047 =back
1048
1049 Patches very much welcome for any of the above.
1050
1051 =over 4
1052
1053 =item * On Win32 systems, does not have a way to write the created environment
1054 variables to the registry, so that they can persist through a reboot.
1055
1056 =back
1057
1058 =head1 TROUBLESHOOTING
1059
1060 If you've configured local::lib to install CPAN modules somewhere in to your
1061 home directory, and at some point later you try to install a module with C<cpan
1062 -i Foo::Bar>, but it fails with an error like: C<Warning: You do not have
1063 permissions to install into /usr/lib64/perl5/site_perl/5.8.8/x86_64-linux at
1064 /usr/lib64/perl5/5.8.8/Foo/Bar.pm> and buried within the install log is an
1065 error saying C<'INSTALL_BASE' is not a known MakeMaker parameter name>, then
1066 you've somehow lost your updated ExtUtils::MakeMaker module.
1067
1068 To remedy this situation, rerun the bootstrapping procedure documented above.
1069
1070 Then, run C<rm -r ~/.cpan/build/Foo-Bar*>
1071
1072 Finally, re-run C<cpan -i Foo::Bar> and it should install without problems.
1073
1074 =head1 ENVIRONMENT
1075
1076 =over 4
1077
1078 =item SHELL
1079
1080 =item COMSPEC
1081
1082 local::lib looks at the user's C<SHELL> environment variable when printing out
1083 commands to add to the shell configuration file.
1084
1085 On Win32 systems, C<COMSPEC> is also examined.
1086
1087 =back
1088
1089 =head1 SEE ALSO
1090
1091 =over 4
1092
1093 =item * L<Perl Advent article, 2011|http://perladvent.org/2011/2011-12-01.html>
1094
1095 =back
1096
1097 =head1 SUPPORT
1098
1099 IRC:
1100
1101     Join #local-lib on irc.perl.org.
1102
1103 =head1 AUTHOR
1104
1105 Matt S Trout <mst@shadowcat.co.uk> http://www.shadowcat.co.uk/
1106
1107 auto_install fixes kindly sponsored by http://www.takkle.com/
1108
1109 =head1 CONTRIBUTORS
1110
1111 Patches to correctly output commands for csh style shells, as well as some
1112 documentation additions, contributed by Christopher Nehren <apeiron@cpan.org>.
1113
1114 Doc patches for a custom local::lib directory, more cleanups in the english
1115 documentation and a L<german documentation|POD2::DE::local::lib> contributed by
1116 Torsten Raudssus <torsten@raudssus.de>.
1117
1118 Hans Dieter Pearcey <hdp@cpan.org> sent in some additional tests for ensuring
1119 things will install properly, submitted a fix for the bug causing problems with
1120 writing Makefiles during bootstrapping, contributed an example program, and
1121 submitted yet another fix to ensure that local::lib can install and bootstrap
1122 properly. Many, many thanks!
1123
1124 pattern of Freenode IRC contributed the beginnings of the Troubleshooting
1125 section. Many thanks!
1126
1127 Patch to add Win32 support contributed by Curtis Jewell <csjewell@cpan.org>.
1128
1129 Warnings for missing PATH/PERL5LIB (as when not running interactively) silenced
1130 by a patch from Marco Emilio Poleggi.
1131
1132 Mark Stosberg <mark@summersault.com> provided the code for the now deleted
1133 '--self-contained' option.
1134
1135 Documentation patches to make win32 usage clearer by
1136 David Mertens <dcmertens.perl@gmail.com> (run4flat).
1137
1138 Brazilian L<portuguese translation|POD2::PT_BR::local::lib> and minor doc
1139 patches contributed by Breno G. de Oliveira <garu@cpan.org>.
1140
1141 Improvements to stacking multiple local::lib dirs and removing them from the
1142 environment later on contributed by Andrew Rodland <arodland@cpan.org>.
1143
1144 Patch for Carp version mismatch contributed by Hakim Cassimally
1145 <osfameron@cpan.org>.
1146
1147 =head1 COPYRIGHT
1148
1149 Copyright (c) 2007 - 2010 the local::lib L</AUTHOR> and L</CONTRIBUTORS> as
1150 listed above.
1151
1152 =head1 LICENSE
1153
1154 This is free software; you can redistribute it and/or modify it under
1155 the same terms as the Perl 5 programming language system itself.
1156
1157 =cut