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