use File::Spec ();
use File::Path ();
-use Carp ();
use Config;
-our $VERSION = '1.004008'; # 1.4.7
-my @KNOWN_FLAGS = (qw/--self-contained/);
+our $VERSION = '1.008008'; # 1.8.8
+
+our @KNOWN_FLAGS = qw(--self-contained --deactivate --deactivate-all);
+
+sub DEACTIVATE_ONE () { 1 }
+sub DEACTIVATE_ALL () { 2 }
+
+sub INTERPOLATE_ENV () { 1 }
+sub LITERAL_ENV () { 0 }
sub import {
my ($class, @args) = @_;
- @args <= 1 + @KNOWN_FLAGS or die <<'DEATH';
-Please see `perldoc local::lib` for directions on using this module.
-DEATH
# Remember what PERL5LIB was when we started
- my $perl5lib = $ENV{PERL5LIB};
+ my $perl5lib = $ENV{PERL5LIB} || '';
my %arg_store;
for my $arg (@args) {
}
if($arg_store{'self-contained'}) {
- # The only directories that remain are those that we just defined and those
- # where core modules are stored. We put PERL5LIB first, so it'll be favored
- # over privlibexp and archlibexp
-
- @INC = _uniq(
- $class->install_base_perl_path($arg_store{path}),
- $class->install_base_arch_path($arg_store{path}),
- split( $Config{path_sep}, $perl5lib ),
- $Config::Config{privlibexp},
- $Config::Config{archlibexp}
- );
+ 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";
+ }
- # We explicitly set PERL5LIB here to the above de-duped list to prevent
- # @INC from growing with each invocation
- $ENV{PERL5LIB} = join( $Config{path_sep}, @INC );
+ my $deactivating = 0;
+ if ($arg_store{deactivate}) {
+ $deactivating = DEACTIVATE_ONE;
+ }
+ if ($arg_store{'deactivate-all'}) {
+ $deactivating = DEACTIVATE_ALL;
}
$arg_store{path} = $class->resolve_path($arg_store{path});
- $class->setup_local_lib_for($arg_store{path});
+ $class->setup_local_lib_for($arg_store{path}, $deactivating);
for (@INC) { # Untaint @INC
next if ref; # Skip entry if it is an ARRAY, CODE, blessed, etc.
}
};
unless (defined $homedir) {
+ require Carp;
Carp::croak(
"Couldn't resolve homedir for "
.(defined $user ? $user : 'current user')
=cut
sub setup_local_lib_for {
- my ($class, $path) = @_;
- $path = $class->ensure_dir_structure_for($path);
+ my ($class, $path, $deactivating) = @_;
+
+ my $interpolate = LITERAL_ENV;
+ my @active_lls = $class->active_paths;
+
+ $class->ensure_dir_structure_for($path);
+
+ # On Win32 directories often contain spaces. But some parts of the CPAN
+ # toolchain don't like that. To avoid this, GetShortPathName() gives us
+ # an alternate representation that has none.
+ # This only works if the directory already exists.
+ $path = Win32::GetShortPathName($path) if $^O eq 'MSWin32';
+
+ if (! $deactivating) {
+ if (@active_lls && $active_lls[-1] eq $path) {
+ exit 0 if $0 eq '-';
+ return; # Asked to add what's already at the top of the stack
+ } elsif (grep { $_ eq $path} @active_lls) {
+ # Asked to add a dir that's lower in the stack -- so we remove it from
+ # where it is, and then add it back at the top.
+ $class->setup_env_hash_for($path, DEACTIVATE_ONE);
+ # Which means we can no longer output "PERL5LIB=...:$PERL5LIB" stuff
+ # anymore because we're taking something *out*.
+ $interpolate = INTERPOLATE_ENV;
+ }
+ }
+
if ($0 eq '-') {
- $class->print_environment_vars_for($path);
+ $class->print_environment_vars_for($path, $deactivating, $interpolate);
exit 0;
} else {
- $class->setup_env_hash_for($path);
- @INC = _uniq(split($Config{path_sep}, $ENV{PERL5LIB}), @INC);
+ $class->setup_env_hash_for($path, $deactivating);
+ my $arch_dir = $Config{archname};
+ @INC = _uniq(
+ (
+ # Inject $path/$archname for each path in PERL5LIB
+ map { ( File::Spec->catdir($_, $arch_dir), $_ ) }
+ split($Config{path_sep}, $ENV{PERL5LIB})
+ ),
+ @INC
+ );
}
}
-sub modulebuildrc_path {
- my ($class, $path) = @_;
- File::Spec->catfile($path, '.modulebuildrc');
-}
-
sub install_base_bin_path {
my ($class, $path) = @_;
File::Spec->catdir($path, 'bin');
warn "Attempting to create directory ${path}\n";
}
File::Path::mkpath($path);
- # Need to have the path exist to make a short name for it, so
- # converting to a short name here.
- $path = Win32::GetShortPathName($path) if $^O eq 'MSWin32';
- my $modulebuildrc_path = $class->modulebuildrc_path($path);
- if (-e $modulebuildrc_path) {
- unless (-f _) {
- Carp::croak("${modulebuildrc_path} exists but is not a plain file");
- }
- } else {
- warn "Attempting to create file ${modulebuildrc_path}\n";
- open MODULEBUILDRC, '>', $modulebuildrc_path
- || Carp::croak("Couldn't open ${modulebuildrc_path} for writing: $!");
- print MODULEBUILDRC qq{install --install_base ${path}\n}
- || Carp::croak("Couldn't write line to ${modulebuildrc_path}: $!");
- close MODULEBUILDRC
- || Carp::croak("Couldn't close file ${modulebuildrc_path}: $@");
- }
-
- return $path;
+ return
}
-sub INTERPOLATE_ENV () { 1 }
-sub LITERAL_ENV () { 0 }
-
-sub print_environment_vars_for {
- my ($class, $path) = @_;
- my @envs = $class->build_environment_vars_for($path, LITERAL_ENV);
- my $out = '';
-
- # rather basic csh detection, goes on the assumption that something won't
- # call itself csh unless it really is. also, default to bourne in the
- # pathological situation where a user doesn't have $ENV{SHELL} defined.
- # note also that shells with funny names, like zoid, are assumed to be
- # bourne.
+sub guess_shelltype {
my $shellbin = 'sh';
if(defined $ENV{'SHELL'}) {
my @shell_bin_path_parts = File::Spec->splitpath($ENV{'SHELL'});
}
};
}
+ return $shelltype;
+}
+
+sub print_environment_vars_for {
+ my ($class, $path, $deactivating, $interpolate) = @_;
+ print $class->environment_vars_string_for($path, $deactivating, $interpolate);
+}
+
+sub environment_vars_string_for {
+ my ($class, $path, $deactivating, $interpolate) = @_;
+ my @envs = $class->build_environment_vars_for($path, $deactivating, $interpolate);
+ my $out = '';
+
+ # rather basic csh detection, goes on the assumption that something won't
+ # call itself csh unless it really is. also, default to bourne in the
+ # pathological situation where a user doesn't have $ENV{SHELL} defined.
+ # note also that shells with funny names, like zoid, are assumed to be
+ # bourne.
+
+ my $shelltype = $class->guess_shelltype;
while (@envs) {
my ($name, $value) = (shift(@envs), shift(@envs));
- $value =~ s/(\\")/\\$1/g;
+ $value =~ s/(\\")/\\$1/g if defined $value;
$out .= $class->${\"build_${shelltype}_env_declaration"}($name, $value);
}
- print $out;
+ return $out;
}
# simple routines that take two arguments: an %ENV key and a value. return
sub build_bourne_env_declaration {
my $class = shift;
my($name, $value) = @_;
- return qq{export ${name}="${value}"\n};
+ return defined($value) ? qq{export ${name}="${value}";\n} : qq{unset ${name};\n};
}
sub build_csh_env_declaration {
my $class = shift;
my($name, $value) = @_;
- return qq{setenv ${name} "${value}"\n};
+ return defined($value) ? qq{setenv ${name} "${value}"\n} : qq{unsetenv ${name}\n};
}
sub build_win32_env_declaration {
my $class = shift;
my($name, $value) = @_;
- return qq{set ${name}=${value}\n};
+ return defined($value) ? qq{set ${name}=${value}\n} : qq{set ${name}=\n};
}
sub setup_env_hash_for {
- my ($class, $path) = @_;
- my %envs = $class->build_environment_vars_for($path, INTERPOLATE_ENV);
+ my ($class, $path, $deactivating) = @_;
+ my %envs = $class->build_environment_vars_for($path, $deactivating, INTERPOLATE_ENV);
@ENV{keys %envs} = values %envs;
}
sub build_environment_vars_for {
+ my ($class, $path, $deactivating, $interpolate) = @_;
+
+ if ($deactivating == DEACTIVATE_ONE) {
+ return $class->build_deactivate_environment_vars_for($path, $interpolate);
+ } elsif ($deactivating == DEACTIVATE_ALL) {
+ return $class->build_deact_all_environment_vars_for($path, $interpolate);
+ } else {
+ return $class->build_activate_environment_vars_for($path, $interpolate);
+ }
+}
+
+# Build an environment value for a variable like PATH from a list of paths.
+# References to existing variables are given as references to the variable name.
+# Duplicates are removed.
+#
+# options:
+# - interpolate: INTERPOLATE_ENV/LITERAL_ENV
+# - exists: paths are included only if they exist (default: interpolate == INTERPOLATE_ENV)
+# - filter: function to apply to each path do decide if it must be included
+# - empty: the value to return in the case of empty value
+my %ENV_LIST_VALUE_DEFAULTS = (
+ interpolate => INTERPOLATE_ENV,
+ exists => undef,
+ filter => sub { 1 },
+ empty => undef,
+);
+sub _env_list_value {
+ my $options = shift;
+ die(sprintf "unknown option '$_' at %s line %u\n", (caller)[1..2])
+ for grep { !exists $ENV_LIST_VALUE_DEFAULTS{$_} } keys %$options;
+ my %options = (%ENV_LIST_VALUE_DEFAULTS, %{ $options });
+ $options{exists} = $options{interpolate} == INTERPOLATE_ENV
+ unless defined $options{exists};
+
+ my %seen;
+
+ my $value = join($Config{path_sep}, map {
+ ref $_ ? ($^O eq 'MSWin32' ? "%${$_}%" : "\$${$_}") : $_
+ } grep {
+ ref $_ || (defined $_
+ && length($_) > 0
+ && !$seen{$_}++
+ && $options{filter}->($_)
+ && (!$options{exists} || -e $_))
+ } map {
+ if (ref $_ eq 'SCALAR' && $options{interpolate} == INTERPOLATE_ENV) {
+ exists $ENV{${$_}} ? (split /\Q$Config{path_sep}/, $ENV{${$_}}) : ()
+ } else {
+ $_
+ }
+ } @_);
+ return length($value) ? $value : $options{empty};
+}
+
+sub build_activate_environment_vars_for {
my ($class, $path, $interpolate) = @_;
return (
- MODULEBUILDRC => $class->modulebuildrc_path($path),
+ PERL_LOCAL_LIB_ROOT =>
+ _env_list_value(
+ { interpolate => $interpolate, exists => 0, empty => '' },
+ \'PERL_LOCAL_LIB_ROOT',
+ $path,
+ ),
+ PERL_MB_OPT => "--install_base ${path}",
PERL_MM_OPT => "INSTALL_BASE=${path}",
- PERL5LIB => join($Config{path_sep},
- $class->install_base_perl_path($path),
- $class->install_base_arch_path($path),
- ($ENV{PERL5LIB} ?
- ($interpolate == INTERPOLATE_ENV
- ? ($ENV{PERL5LIB})
- : (($^O ne 'MSWin32') ? '$PERL5LIB' : '%PERL5LIB%' ))
- : ())
- ),
- PATH => join($Config{path_sep},
- $class->install_base_bin_path($path),
- ($interpolate == INTERPOLATE_ENV
- ? $ENV{PATH}
- : (($^O ne 'MSWin32') ? '$PATH' : '%PATH%' ))
- ),
+ PERL5LIB =>
+ _env_list_value(
+ { interpolate => $interpolate, exists => 0, empty => '' },
+ $class->install_base_perl_path($path),
+ \'PERL5LIB',
+ ),
+ PATH => _env_list_value(
+ { interpolate => $interpolate, exists => 0, empty => '' },
+ $class->install_base_bin_path($path),
+ \'PATH',
+ ),
)
}
+sub active_paths {
+ my ($class) = @_;
+
+ return () unless defined $ENV{PERL_LOCAL_LIB_ROOT};
+ return grep { $_ ne '' } split /\Q$Config{path_sep}/, $ENV{PERL_LOCAL_LIB_ROOT};
+}
+
+sub build_deactivate_environment_vars_for {
+ my ($class, $path, $interpolate) = @_;
+
+ my @active_lls = $class->active_paths;
+
+ if (!grep { $_ eq $path } @active_lls) {
+ warn "Tried to deactivate inactive local::lib '$path'\n";
+ return ();
+ }
+
+ my $perl_path = $class->install_base_perl_path($path);
+ my $arch_path = $class->install_base_arch_path($path);
+ my $bin_path = $class->install_base_bin_path($path);
+
+
+ my %env = (
+ PERL_LOCAL_LIB_ROOT => _env_list_value(
+ {
+ exists => 0,
+ },
+ grep { $_ ne $path } @active_lls
+ ),
+ PERL5LIB => _env_list_value(
+ {
+ exists => 0,
+ filter => sub {
+ $_ ne $perl_path && $_ ne $arch_path
+ },
+ },
+ \'PERL5LIB',
+ ),
+ PATH => _env_list_value(
+ {
+ exists => 0,
+ filter => sub { $_ ne $bin_path },
+ },
+ \'PATH',
+ ),
+ );
+
+ # If removing ourselves from the "top of the stack", set install paths to
+ # correspond with the new top of stack.
+ if ($active_lls[-1] eq $path) {
+ my $new_top = $active_lls[-2];
+ $env{PERL_MB_OPT} = defined($new_top) ? "--install_base ${new_top}" : undef;
+ $env{PERL_MM_OPT} = defined($new_top) ? "INSTALL_BASE=${new_top}" : undef;
+ }
+
+ return %env;
+}
+
+sub build_deact_all_environment_vars_for {
+ my ($class, $path, $interpolate) = @_;
+
+ my @active_lls = $class->active_paths;
+
+ my %perl_paths = map { (
+ $class->install_base_perl_path($_) => 1,
+ $class->install_base_arch_path($_) => 1
+ ) } @active_lls;
+ my %bin_paths = map { (
+ $class->install_base_bin_path($_) => 1,
+ ) } @active_lls;
+
+ my %env = (
+ PERL_LOCAL_LIB_ROOT => undef,
+ PERL_MM_OPT => undef,
+ PERL_MB_OPT => undef,
+ PERL5LIB => _env_list_value(
+ {
+ exists => 0,
+ filter => sub {
+ ! scalar grep { exists $perl_paths{$_} } $_[0]
+ },
+ },
+ \'PERL5LIB'
+ ),
+ PATH => _env_list_value(
+ {
+ exists => 0,
+ filter => sub {
+ ! scalar grep { exists $bin_paths{$_} } $_[0]
+ },
+ },
+ \'PATH'
+ ),
+ );
+
+ return %env;
+}
+
=begin testing
#:: test classmethod
ok(-d 't/var/splat');
-ok(-f 't/var/splat/.modulebuildrc');
-
=end testing
+=encoding utf8
+
=head1 NAME
local::lib - create and use a local lib/ for perl modules with PERL5LIB
From the shell -
- # Install LWP and it's missing dependencies to the 'my_lwp' directory
- perl -MCPAN -Mlocal::lib=my_lwp -e 'CPAN::install(LWP)'
-
- # Install LWP and *all non-core* dependencies to the 'my_lwp' directory
- perl -MCPAN -Mlocal::lib=--self-contained,my_lwp -e 'CPAN::install(LWP)'
+ # Install LWP and its missing dependencies to the '~/perl5' directory
+ perl -MCPAN -Mlocal::lib -e 'CPAN::install(LWP)'
# Just print out useful shell commands
$ perl -Mlocal::lib
- export MODULEBUILDRC=/home/username/perl/.modulebuildrc
- export PERL_MM_OPT='INSTALL_BASE=/home/username/perl'
- export PERL5LIB='/home/username/perl/lib/perl5:/home/username/perl/lib/perl5/i386-linux'
- export PATH="/home/username/perl/bin:$PATH"
+ export PERL_MB_OPT='--install_base /home/username/perl5'
+ export PERL_MM_OPT='INSTALL_BASE=/home/username/perl5'
+ export PERL5LIB='/home/username/perl5/lib/perl5/i386-linux:/home/username/perl5/lib/perl5'
+ export PATH="/home/username/perl5/bin:$PATH"
=head2 The bootstrapping technique
A typical way to install local::lib is using what is known as the
"bootstrapping" technique. You would do this if your system administrator
hasn't already installed local::lib. In this case, you'll need to install
-local::lib in your home directory.
+local::lib in your home directory.
+
+If you do have administrative privileges, you will still want to set up your
+environment variables, as discussed in step 4. Without this, you would still
+install the modules into the system CPAN installation and also your Perl scripts
+will not use the lib/ path you bootstrapped with local::lib.
+
+By default local::lib installs itself and the CPAN modules into ~/perl5.
+
+Windows users must also see L</Differences when using this module under Win32>.
1. Download and unpack the local::lib tarball from CPAN (search for "Download"
on the CPAN page about local::lib). Do this as an ordinary user, not as root
If the system asks you whether it should automatically configure as much
as possible, you would typically answer yes.
-3. Run this:
+In order to install local::lib into a directory other than the default, you need
+to specify the name of the directory when you call bootstrap, as follows:
+
+ perl Makefile.PL --bootstrap=~/foo
+
+3. Run this: (local::lib assumes you have make installed on your system)
make test && make install
-4. Arrange for Perl to use your own packages instead of the system
-packages. If you are using bash, you can do this as follows:
+4. Now we need to setup the appropriate environment variables, so that Perl
+starts using our newly generated lib/ directory. If you are using bash or
+any other Bourne shells, you can add this to your shell startup script this
+way:
echo 'eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)' >>~/.bashrc
/bin/csh
perl -I$HOME/perl5/lib/perl5 -Mlocal::lib >> ~/.cshrc
-You can also pass --bootstrap=~/foo to get a different location -
-
- perl Makefile.PL --bootstrap=~/foo
- make test && make install
+If you passed to bootstrap a directory other than default, you also need to give that as
+import parameter to the call of the local::lib module like this way:
echo 'eval $(perl -I$HOME/foo/lib/perl5 -Mlocal::lib=$HOME/foo)' >>~/.bashrc
After writing your shell configuration file, be sure to re-read it to get the
-changed settings into your current shell's environment. Bourne shells use C<.
-~/.bashrc> for this, whereas C shells use C<source ~/.cshrc>. Replace .bashrc or
-.cshrc with the name of the file you wrote above with the echo command.
+changed settings into your current shell's environment. Bourne shells use
+C<. ~/.bashrc> for this, whereas C shells use C<source ~/.cshrc>.
If you're on a slower machine, or are operating under draconian disk space
limitations, you can disable the automatic generation of manpages from POD when
perl Makefile.PL --bootstrap --no-manpages
-If you want to install multiple Perl module environments, say for application evelopment,
-install local::lib globally and then:
+To avoid doing several bootstrap for several Perl module environments on the
+same account, for example if you use it for several different deployed
+applications independently, you can use one bootstrapped local::lib
+installation to install modules in different directories directly this way:
cd ~/mydir1
perl -Mlocal::lib=./
eval $(perl -Mlocal::lib=./) ### To set the environment for this shell alone
- printenv ### You will see that ~/mydir1 is in the PERL5LIB
+ printenv ### You will see that ~/mydir1 is in the PERL5LIB
perl -MCPAN -e install ... ### whatever modules you want
cd ../mydir2
... REPEAT ...
+If you are working with several C<local::lib> environments, you may want to
+remove some of them from the current environment without disturbing the others.
+You can deactivate one environment like this (using bourne sh):
+
+ eval $(perl -Mlocal::lib=--deactivate,~/path)
+
+which will generate and run the commands needed to remove C<~/path> from your
+various search paths. Whichever environment was B<activated most recently> will
+remain the target for module installations. That is, if you activate
+C<~/path_A> and then you activate C<~/path_B>, new modules you install will go
+in C<~/path_B>. If you deactivate C<~/path_B> then modules will be installed
+into C<~/pathA> -- but if you deactivate C<~/path_A> then they will still be
+installed in C<~/pathB> because pathB was activated later.
+
+You can also ask C<local::lib> to clean itself completely out of the current
+shell's environment with the C<--deactivate-all> option.
For multiple environments for multiple apps you may need to include a modified
version of the C<< use FindBin >> instructions in the "In code" sample above.
If you did something like the above, you have a set of Perl modules at C<<
=head2 Differences when using this module under Win32
+To set up the proper environment variables for your current session of
+C<CMD.exe>, you can use this:
+
C:\>perl -Mlocal::lib
- set MODULEBUILDRC=C:\DOCUME~1\ADMINI~1\perl5\.modulebuildrc
+ set PERL_MB_OPT=--install_base C:\DOCUME~1\ADMINI~1\perl5
set PERL_MM_OPT=INSTALL_BASE=C:\DOCUME~1\ADMINI~1\perl5
set PERL5LIB=C:\DOCUME~1\ADMINI~1\perl5\lib\perl5;C:\DOCUME~1\ADMINI~1\perl5\lib\perl5\MSWin32-x86-multi-thread
set PATH=C:\DOCUME~1\ADMINI~1\perl5\bin;%PATH%
- ### To set the environment for this shell alone
- C:\>perl -Mlocal::lib > %TEMP%\tmp.bat && %TEMP%\tmp.bat && del %TEMP%\temp.bat
+ ### To set the environment for this shell alone
+ C:\>perl -Mlocal::lib > %TEMP%\tmp.bat && %TEMP%\tmp.bat && del %TEMP%\tmp.bat
### instead of $(perl -Mlocal::lib=./)
If you want the environment entries to persist, you'll need to add then to the
-Control Panel's System applet yourself at the moment.
+Control Panel's System applet yourself or use L<App::local::lib::Win32Helper>.
The "~" is translated to the user's profile directory (the directory named for
the user under "Documents and Settings" (Windows XP or earlier) or "Users"
-(Windows Vista or later) unless $ENV{HOME} exists. After that, the home
+(Windows Vista or later)) unless $ENV{HOME} exists. After that, the home
directory is translated to a short name (which means the directory must exist)
and the subdirectories are created.
=over 4
-=item MODULEBUILDRC
+=item PERL_MB_OPT
=item PERL_MM_OPT
These values are then available for reference by any code after import.
+=head1 CREATING A SELF-CONTAINED SET OF MODULES
+
+See L<lib::core::only> for one way to do this - but note that
+there are a number of caveats, and the best approach is always to perform a
+build against a clean perl (i.e. site and vendor as close to empty as possible).
+
+=head1 OPTIONS
+
+Options are values that can be passed to the C<local::lib> import besides the
+directory to use. They are specified as C<use local::lib '--option'[, path];>
+or C<perl -Mlocal::lib=--option[,path]>.
+
+=head2 --deactivate
+
+Remove the chosen path (or the default path) from the module search paths if it
+was added by C<local::lib>, instead of adding it.
+
+=head2 --deactivate-all
+
+Remove all directories that were added to search paths by C<local::lib> from the
+search paths.
+
=head1 METHODS
-=head2 ensure_directory_structure_for
+=head2 ensure_dir_structure_for
=over 4
-=item Arguments: path
+=item Arguments: $path
+
+=item Return value: None
=back
=over 4
-=item Arguments: path
+=item Arguments: $path
+
+=item Return value: None
=back
Prints to standard output the variables listed above, properly set to use the
given path as the base directory.
+=head2 build_environment_vars_for
+
+=over 4
+
+=item Arguments: $path, $interpolate
+
+=item Return value: \%environment_vars
+
+=back
+
+Returns a hash with the variables listed above, properly set to use the
+given path as the base directory.
+
=head2 setup_env_hash_for
=over 4
-=item Arguments: path
+=item Arguments: $path
+
+=item Return value: None
=back
Constructs the C<%ENV> keys for the given path, by calling
-C<build_environment_vars_for>.
+L</build_environment_vars_for>.
+
+=head2 active_paths
+
+=over 4
+
+=item Arguments: None
+
+=item Return value: @paths
+
+=back
+
+Returns a list of active C<local::lib> paths, according to the
+C<PERL_LOCAL_LIB_ROOT> environment variable.
=head2 install_base_perl_path
=over 4
-=item Arguments: path
+=item Arguments: $path
+
+=item Return value: $install_base_perl_path
=back
=over 4
-=item Arguments: path
+=item Arguments: $path
+
+=item Return value: $install_base_arch_path
=back
=over 4
-=item Arguments: path
+=item Arguments: $path
+
+=item Return value: $install_base_bin_path
=back
local library installation. Based on the L</install_base_perl_path> method's
return value, and appends the directory C<bin>.
-=head2 modulebuildrc_path
-
-=over 4
-
-=item Arguments: path
-
-=back
-
-Returns a path describing where to install the C<.modulebuildrc> file, based on
-the given path.
-
=head2 resolve_empty_path
=over 4
-=item Arguments: path
+=item Arguments: $path
+
+=item Return value: $base_path
=back
=over 4
-=item Arguments: path
+=item Arguments: $path
+
+=item Return value: $home_path
=back
=over 4
-=item Arguments: path
+=item Arguments: $path
+
+=item Return value: $absolute_path
=back
=over 4
-=item Arguments: path
+=item Arguments: $path
+
+=item Return value: $absolute_path
=back
=head1 LIMITATIONS
+The perl toolchain is unable to handle directory names with spaces in it,
+so you cant put your local::lib bootstrap into a directory with spaces. What
+you can do is moving your local::lib to a directory with spaces B<after> you
+installed all modules inside your local::lib bootstrap. But be aware that you
+cant update or install CPAN modules after the move.
+
Rather basic shell detection. Right now anything with csh in its name is
assumed to be a C shell or something compatible, and everything else is assumed
to be Bourne, except on Win32 systems. If the C<SHELL> environment variable is
Bootstrap is a hack and will use CPAN.pm for ExtUtils::MakeMaker even if you
have CPANPLUS installed.
-Kills any existing PERL5LIB, PERL_MM_OPT or MODULEBUILDRC.
+Kills any existing PERL5LIB, PERL_MM_OPT or PERL_MB_OPT.
Should probably auto-fixup CPAN config if not already done.
=back
+=head1 SUPPORT
+
+IRC:
+
+ Join #local-lib on irc.perl.org.
+
=head1 AUTHOR
Matt S Trout <mst@shadowcat.co.uk> http://www.shadowcat.co.uk/
Patches to correctly output commands for csh style shells, as well as some
documentation additions, contributed by Christopher Nehren <apeiron@cpan.org>.
-'--self-contained' feature contributed by Mark Stosberg <mark@summersault.com>.
-
-Ability to pass '--self-contained' without a directory inspired by frew on
-irc.perl.org/#catalyst.
-
-Doc patches for a custom local::lib directory contributed by Torsten Raudssus
+Doc patches for a custom local::lib directory, more cleanups in the english
+documentation and a L<german documentation|POD2::DE::local::lib> contributed by Torsten Raudssus
<torsten@raudssus.de>.
Hans Dieter Pearcey <hdp@cpan.org> sent in some additional tests for ensuring
Patch to add Win32 support contributed by Curtis Jewell <csjewell@cpan.org>.
+Warnings for missing PATH/PERL5LIB (as when not running interactively) silenced
+by a patch from Marco Emilio Poleggi.
+
+Mark Stosberg <mark@summersault.com> provided the code for the now deleted
+'--self-contained' option.
+
+Documentation patches to make win32 usage clearer by
+David Mertens <dcmertens.perl@gmail.com> (run4flat).
+
+Brazilian L<portuguese translation|POD2::PT_BR::local::lib> and minor doc patches contributed by Breno
+G. de Oliveira <garu@cpan.org>.
+
+Improvements to stacking multiple local::lib dirs and removing them from the
+environment later on contributed by Andrew Rodland <arodland@cpan.org>.
+
+Patch for Carp version mismatch contributed by Hakim Cassimally <osfameron@cpan.org>.
+
=head1 COPYRIGHT
-Copyright (c) 2007 - 2009 the local::lib L</AUTHOR> and L</CONTRIBUTORS> as
+Copyright (c) 2007 - 2010 the local::lib L</AUTHOR> and L</CONTRIBUTORS> as
listed above.
=head1 LICENSE