use Carp ();
use Config;
-our $VERSION = '1.001000'; # 1.1.0
+our $VERSION = '1.003003'; # 1.3.3
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
+ # make sure fancy dashes cause an error
+ if ($flag =~ /−/) {
+ 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
+probably got these by copy-pasting from the perldoc for this module as
+rendered by a UTF8-capable formatter. This most typically happens on an OS X
+terminal, but can happen elsewhere too. Please try again after replacing the
+dashes with normal minus signs.
+DEATH
+ }
+ 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;
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'
/bin/csh
% perl -I$HOME/perl5/lib/perl5 -Mlocal::lib >> ~/.cshrc
-You can also pass --boostrap=~/foo to get a different location (adjust the
-bashrc / cshrc line appropriately)
+You can also pass --boostrap=~/foo to get a different location -
+
+ $ perl Makefile.PL --bootstrap=~/foo
+ $ make test && make install
+
+ $ echo 'eval $(perl -I$HOME/foo/lib/perl5 -Mlocal::lib=$HOME/foo)' >>~/.bashrc
+
+If you want to install multiple Perl module environments, say for application evelopment,
+install local::lib globally and then:
+
+ $ 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
+ $ perl -MCPAN -e install ... ### whatever modules you want
+ $ cd ../mydir2
+ ... REPEAT ...
+
+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<< ~/mydir1/lib >>. If you have a script at
+C<< ~/mydir1/scripts/myscript.pl >>, you need to tell it where to find the modules you installed
+for it at C<< ~/mydir1/lib>>.
+
+In C<< ~/mydir1/scripts/myscript.pl >>:
+
+ use strict;
+ use warnings;
+ use local::lib "$FindBin::Bin/.."; ### points to ~/mydir1 and local::lib finds lib
+ use lib "$FindBin::Bin/../lib"; ### points to ~/mydir1/lib
+
+Put this before any BEGIN { ... } blocks that require the modules you installed.
=head1 DESCRIPTION
These values are then available for reference by any code after import.
+=head1 METHODS
+
+=head2 ensure_directory_structure_for
+
+=over 4
+
+=item Arguments: path
+
+=back
+
+Attempts to create the given path, and all required parent directories. Throws
+an exception on failure.
+
+=head2 print_environment_vars_for
+
+=over 4
+
+=item Arguments: path
+
+=back
+
+Prints to standard output 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
+
+=back
+
+Constructs the C<%ENV> keys for the given path, by calling
+C<build_environment_vars_for>.
+
+=head2 install_base_perl_path
+
+=over 4
+
+=item Arguments: path
+
+=back
+
+Returns a path describing where to install the Perl modules for this local
+library installation. Appends the directories C<lib> and C<perl5> to the given
+path.
+
+=head2 install_base_arch_path
+
+=over 4
+
+=item Arguments: path
+
+=back
+
+Returns a path describing where to install the architecture-specific Perl
+modules for this local library installation. Based on the
+L</install_base_perl_path> method's return value, and appends the value of
+C<$Config{archname}>.
+
+=head2 install_base_bin_path
+
+=over 4
+
+=item Arguments: path
+
+=back
+
+Returns a path describing where to install the executable programs for this
+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
+
+=back
+
+Builds and returns the base path into which to set up the local module
+installation. Defaults to C<~/perl5>.
+
+=head2 resolve_home_path
+
+=over 4
+
+=item Arguments: path
+
+=back
+
+Attempts to find the user's home directory. If installed, uses C<File::HomeDir>
+for this purpose. If no definite answer is available, throws an exception.
+
+=head2 resolve_relative_path
+
+=over 4
+
+=item Arguments: path
+
+=back
+
+Translates the given path into an absolute path.
+
+=head2 resolve_path
+
+=over 4
+
+=item Arguments: path
+
+=back
+
+Calls the following in a pipeline, passing the result from the previous to the
+next, in an attempt to find where to configure the environment for a local
+library installation: L</resolve_empty_path>, L</resolve_home_path>,
+L</resolve_relative_path>. Passes the given path argument to
+L</resolve_empty_path> which then returns a result that is passed to
+L</resolve_home_path>, which then has its result passed to
+L</resolve_relative_path>. The result of this final call is returned from
+L</resolve_path>.
+
+=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 "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
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>.
+
+Doc patches for a custom local::lib patch contributed by Torsten Raudssus
+<torsten@raudssus.de>.
+
=head1 LICENSE
This library is free software under the same license as perl itself