use File::Spec ();
use File::Path ();
-use Carp ();
use Config;
-our $VERSION = '1.008003'; # 1.8.3
+our $VERSION = '1.008_021'; # 1.8.21 development release
+$VERSION = eval $VERSION;
our @KNOWN_FLAGS = qw(--self-contained --deactivate --deactivate-all);
my %arg_store;
for my $arg (@args) {
# check for lethal dash first to stop processing before causing problems
- if ($arg =~ /−/) {
+ # the fancy dash is U+2212 or \xE2\x88\x92
+ if ($arg =~ /\xE2\x88\x92/ or $arg =~ /−/) {
die <<'DEATH';
WHOA THERE! It looks like you've got some fancy dashes in your commandline!
These are *not* the traditional -- dashes that software recognizes. You
package local::lib;
{ package Foo; sub foo { -$_[1] } sub bar { $_[1]+2 } sub baz { $_[1]+3 } }
-my $foo = bless({}, 'Foo');
+my $foo = bless({}, 'Foo');
Test::More::ok($foo->${pipeline qw(foo bar baz)}(10) == -15);
=end testing
}
};
unless (defined $homedir) {
+ require Carp;
Carp::croak(
"Couldn't resolve homedir for "
.(defined $user ? $user : 'current user')
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 '-';
}
}
- $path = $class->ensure_dir_structure_for($path);
-
if ($0 eq '-') {
$class->print_environment_vars_for($path, $deactivating, $interpolate);
exit 0;
} else {
$class->setup_env_hash_for($path, $deactivating);
- @INC = _uniq(split($Config{path_sep}, $ENV{PERL5LIB}), @INC);
+ 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
+ );
}
}
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';
-
- return $path;
+ return
}
sub guess_shelltype {
}
}
+# 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) {
+ defined $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 (
- PERL_LOCAL_LIB_ROOT => join($Config{path_sep},
- (($ENV{PERL_LOCAL_LIB_ROOT}||()) ?
- ($interpolate == INTERPOLATE_ENV
- ? ($ENV{PERL_LOCAL_LIB_ROOT}||())
- : (($^O ne 'MSWin32') ? '$PERL_LOCAL_LIB_ROOT'
- : '%PERL_LOCAL_LIB_ROOT%' ))
- : ()),
- $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_arch_path($path),
- $class->install_base_perl_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',
+ ),
)
}
my ($class) = @_;
return () unless defined $ENV{PERL_LOCAL_LIB_ROOT};
- return split /\Q$Config{path_sep}/, $ENV{PERL_LOCAL_LIB_ROOT};
+
+ return grep {
+ # screen out entries that aren't actually reflected in @INC
+ my $active_ll = $class->install_base_perl_path($_);
+ grep { $_ eq $active_ll } @INC
+ }
+ grep { $_ ne '' }
+ split /\Q$Config{path_sep}\E/, $ENV{PERL_LOCAL_LIB_ROOT};
}
sub build_deactivate_environment_vars_for {
return ();
}
- my @new_ll_root = grep { $_ ne $path } @active_lls;
- my @new_perl5lib = grep {
- $_ ne $class->install_base_arch_path($path) &&
- $_ ne $class->install_base_perl_path($path)
- } split /\Q$Config{path_sep}/, $ENV{PERL5LIB};
+ 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 => (@new_ll_root ?
- join($Config{path_sep}, @new_ll_root) : undef
+ PERL_LOCAL_LIB_ROOT => _env_list_value(
+ {
+ exists => 0,
+ },
+ grep { $_ ne $path } @active_lls
),
- PERL5LIB => (@new_perl5lib ?
- join($Config{path_sep}, @new_perl5lib) : undef
+ PERL5LIB => _env_list_value(
+ {
+ exists => 0,
+ filter => sub {
+ $_ ne $perl_path && $_ ne $arch_path
+ },
+ },
+ \'PERL5LIB',
),
- PATH => join($Config{path_sep},
- grep { $_ ne $class->install_base_bin_path($path) }
- split /\Q$Config{path_sep}/, $ENV{PATH}
+ 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) {
- if (@active_lls > 1) {
- my $new_top = $active_lls[-2];
- %env = (%env,
- PERL_MB_OPT => "--install_base ${new_top}",
- PERL_MM_OPT => "INSTALL_BASE=${new_top}",
- );
- } else {
- %env = (%env,
- PERL_MB_OPT => undef,
- PERL_MM_OPT => undef,
- );
- }
+ 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;
my @active_lls = $class->active_paths;
- my @new_perl5lib = split /\Q$Config{path_sep}/, $ENV{PERL5LIB};
- my @new_path = split /\Q$Config{path_sep}/, $ENV{PATH};
-
- for my $path (@active_lls) {
- @new_perl5lib = grep {
- $_ ne $class->install_base_arch_path($path) &&
- $_ ne $class->install_base_perl_path($path)
- } @new_perl5lib;
-
- @new_path = grep {
- $_ ne $class->install_base_bin_path($path)
- } @new_path;
- }
+ 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 => (@new_perl5lib ?
- join($Config{path_sep}, @new_perl5lib) : 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'
),
- PATH => join($Config{path_sep}, @new_path),
);
return %env;
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
+Even 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.
make test && make install
-4. Now we need to setup the appropriate environment variables, so that Perl
+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:
/bin/csh
perl -I$HOME/perl5/lib/perl5 -Mlocal::lib >> ~/.cshrc
-If you passed to bootstrap a directory other than default, you also need to give that as
+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
+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
perl Makefile.PL --bootstrap --no-manpages
-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
+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
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
+ 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
If you are using a package management system (such as Debian), you don't need to
worry about Debian and CPAN stepping on each other's toes. Your local version
of the packages will be written to an entirely separate directory from those
-installed by Debian.
+installed by Debian.
=head1 DESCRIPTION
=back
Returns a list of active C<local::lib> paths, according to the
-C<PERL_LOCAL_LIB_ROOT> environment variable.
+C<PERL_LOCAL_LIB_ROOT> environment variable and verified against
+what is really in C<@INC>.
=head2 install_base_perl_path
=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
+=over 4
+
+=item * The perl toolchain is unable to handle directory names with spaces in it,
+so you can't 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.
+can't update or install CPAN modules after the move.
-Rather basic shell detection. Right now anything with csh in its name is
+=item * 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
not set, a Bourne-compatible shell is assumed.
-Bootstrap is a hack and will use CPAN.pm for ExtUtils::MakeMaker even if you
+=item * 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 PERL_MB_OPT.
+=item * Kills any existing PERL5LIB, PERL_MM_OPT or PERL_MB_OPT.
-Should probably auto-fixup CPAN config if not already done.
+=item * Should probably auto-fixup CPAN config if not already done.
+
+=back
Patches very much welcome for any of the above.
-On Win32 systems, does not have a way to write the created environment variables
+=over 4
+
+=item * On Win32 systems, does not have a way to write the created environment variables
to the registry, so that they can persist through a reboot.
+=back
+
=head1 TROUBLESHOOTING
If you've configured local::lib to install CPAN modules somewhere in to your
=back
+=head1 SEE ALSO
+
+=over 4
+
+=item * L<Perl Advent article, 2011|http://perladvent.org/2011/2011-12-01.html>
+
+=back
+
=head1 SUPPORT
IRC:
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 - 2010 the local::lib L</AUTHOR> and L</CONTRIBUTORS> as
=head1 LICENSE
-This library is free software and may be distributed under the same terms
-as perl itself.
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.
=cut