package local::lib;
-use 5.8.1; # probably works with earlier versions but I'm not supporting them
- # (patches would, of course, be welcome)
+use 5.008001; # probably works with earlier versions but I'm not supporting them
+ # (patches would, of course, be welcome)
use File::Spec ();
use File::Path ();
use Carp ();
use Config;
-our $VERSION = '1.000000'; # 1.0.0
+our $VERSION = '1.002000'; # 1.2.0
sub import {
- my ($class, $path) = @_;
+ my ($class, @args) = @_;
+
+ # The path is required, but last in the list, so we pop, not shift here.
+ my $path = pop @args;
$path = $class->resolve_path($path);
$class->setup_local_lib_for($path);
+
+ # Handle the '--self-contained' option
+ my $flag = shift @args;
+ no warnings 'uninitialized'; # the flag is optional
+ if ($flag eq '--self-contained') {
+ # The only directories that remain are those that we just defined and those where core modules are stored.
+ @INC = ($Config::Config{privlibexp}, $Config::Config{archlibexp}, split ':', $ENV{PERL5LIB});
+ }
+ elsif (defined $flag) {
+ die "unrecognized import argument: $flag";
+ }
+
}
sub pipeline;
}
}
-sub INTERPOLATE_PATH () { 1 }
-sub LITERAL_PATH () { 0 }
+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_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.
my @shell_bin_path_parts = File::Spec->splitpath($ENV{'SHELL'});
$shellbin = $shell_bin_path_parts[-1];
}
+ my $shelltype = do {
+ local $_ = $shellbin;
+ if(/csh/) {
+ 'csh'
+ } else {
+ 'bourne'
+ }
+ };
+
while (@envs) {
my ($name, $value) = (shift(@envs), shift(@envs));
$value =~ s/(\\")/\\$1/g;
-
- if($shellbin =~ /csh/) {
- $out .= qq{setenv ${name} "${value}"\n};
- }
- else {
- $out .= qq{export ${name}="${value}"\n};
- }
+ $out .= $class->${\"build_${shelltype}_env_declaration"}($name, $value);
}
print $out;
}
+# simple routines that take two arguments: an %ENV key and a value. return
+# strings that are suitable for passing directly to the relevant shell to set
+# said key to said value.
+sub build_bourne_env_declaration {
+ my $class = shift;
+ my($name, $value) = @_;
+ return qq{export ${name}="${value}"\n};
+}
+
+sub build_csh_env_declaration {
+ my $class = shift;
+ my($name, $value) = @_;
+ return qq{setenv ${name} "${value}"\n};
+}
+
sub setup_env_hash_for {
my ($class, $path) = @_;
- my %envs = $class->build_environment_vars_for($path, INTERPOLATE_PATH);
+ my %envs = $class->build_environment_vars_for($path, INTERPOLATE_ENV);
@ENV{keys %envs} = values %envs;
}
PERL5LIB => join(':',
$class->install_base_perl_path($path),
$class->install_base_arch_path($path),
+ ($ENV{PERL5LIB} ?
+ ($interpolate == INTERPOLATE_ENV
+ ? ($ENV{PERL5LIB})
+ : ('$PERL5LIB'))
+ : ())
),
PATH => join(':',
$class->install_base_bin_path($path),
- ($interpolate == INTERPOLATE_PATH
+ ($interpolate == INTERPOLATE_ENV
? $ENV{PATH}
: '$PATH')
),
use local::lib '~/foo'; # same, but ~/foo
+ # Or...
+ use FindBin;
+ use local::lib "$FindBin::Bin/../support"; # app-local support library
+
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)'
+
+ # Just print out useful shell commands
$ perl -Mlocal::lib
export MODULEBUILDRC=/home/username/perl/.modulebuildrc
export PERL_MM_OPT='INSTALL_BASE=/home/username/perl'
To bootstrap if you don't have local::lib itself installed -
- $ perl -MCPAN -eshell # you only need to do this if you don't have a ~/.cpan
- cpan> exit
<download local::lib tarball from CPAN, unpack and cd into dir>
+
$ perl Makefile.PL --bootstrap
$ make test && make install
+
$ echo 'eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)' >>~/.bashrc
+
# Or for C shells...
+
$ /bin/csh
% echo $SHELL
/bin/csh
environment variable), suitable for directly adding to one's shell configuration
file.
+More generally, local::lib allows for the bootstrapping and usage of a directory
+containing Perl modules outside of Perl's C<@INC>. This makes it easier to ship
+an application with an app-specific copy of a Perl module, or collection of
+modules. Useful in cases like when an upstream maintainer hasn't applied a patch
+to a module of theirs that you need for your application.
+
+On import, local::lib sets the following environment variables to appropriate
+values:
+
+=over 4
+
+=item MODULEBUILDRC
+
+=item PERL_MM_OPT
+
+=item PERL5LIB
+
+=item PATH
+
+PATH is appended to, rather than clobbered.
+
+=back
+
+These values are then available for reference by any code after import.
+
+=head1 A WARNING ABOUT UNINST=1
+
+Be careful about using local::lib in combination with "make install UNINST=1".
+The idea of this feature is that will uninstall an old version of a module
+before installing a new one. However it lacks a safety check that the old
+version and the new version will go in the same directory. Used in combination
+with local::lib, you can potentially delete a globally accessible version of a
+module while installing the new version in a local place. Only combine if "make
+install UNINST=1" and local::lib if you understand these possible consequences.
+
=head1 LIMITATIONS
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.
+to be Bourne. 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
have CPANPLUS installed.
auto_install fixes kindly sponsored by http://www.takkle.com/
+=head1 CONTRIBUTORS
+
+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>.
+
=head1 LICENSE
This library is free software under the same license as perl itself
projects / p5sagit/local-lib.git / blobdiff