grink's fixes for --self-contained

[p5sagit/local-lib.git] / lib / local / lib.pm

diff --git a/lib/local/lib.pm b/lib/local/lib.pm
index 160ff33..1f7a33a 100644 (file)
--- a/lib/local/lib.pm
+++ b/lib/local/lib.pm
@@ -11,11 +11,14 @@ use File::Path ();
 use Carp ();
 use Config;
 
-our $VERSION = '1.003003'; # 1.3.3
+our $VERSION = '1.004001'; # 1.4.1
 
 sub import {
   my ($class, @args) = @_;
 
+  # Remember what PERL5LIB was when we started
+  my $perl5lib = $ENV{PERL5LIB};
+
   # The path is required, but last in the list, so we pop, not shift here. 
   my $path = pop @args;
   $path = $class->resolve_path($path);
@@ -37,12 +40,17 @@ 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});
+    # We put PERL5LIB first, so it'll be favored over privlibexp and archlibexp
+    @INC = ( $class->install_base_perl_path($path), $class->install_base_arch_path($path), split( ':', $perl5lib ), $Config::Config{privlibexp}, $Config::Config{archlibexp} );
+    
+    # We explicitly set PERL5LIB here (back to what it was originally) to prevent @INC from growing with each invocation 
+    $ENV{PERL5LIB} = $perl5lib;
   }
   elsif (defined $flag) {
       die "unrecognized import argument: $flag";
   }
 
+  m/(.*)/ and $_ = $1 for @INC; # Untaint @INC
 }
 
 sub pipeline;
@@ -368,6 +376,32 @@ You can also pass --boostrap=~/foo to get a different location -
 
   $ 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
 
 This module provides a quick, convenient way of bootstrapping a user-local Perl
@@ -560,6 +594,22 @@ Should probably auto-fixup CPAN config if not already done.
 
 Patches very much welcome for any of the above.
 
+=head1 TROUBLESHOOTING
+
+If you've configured local::lib to install CPAN modules somewhere in to your
+home directory, and at some point later you try to install a module with C<cpan
+-i Foo::Bar>, but it fails with an error like: C<Warning: You do not have
+permissions to install into /usr/lib64/perl5/site_perl/5.8.8/x86_64-linux at
+/usr/lib64/perl5/5.8.8/Foo/Bar.pm> and buried within the install log is an
+error saying C<'INSTALL_BASE' is not a known MakeMaker parameter name>, then
+you've somehow lost your updated ExtUtils::MakeMaker module.
+
+To remedy this situation, rerun the bootstrapping procedure documented above.
+
+Then, run C<rm -r ~/.cpan/build/Foo-Bar*>
+
+Finally, re-run C<cpan -i Foo::Bar> and it should install without problems.
+
 =head1 ENVIRONMENT
 
 =over 4
@@ -584,9 +634,18 @@ 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
+Doc patches for a custom local::lib directory contributed by Torsten Raudssus
 <torsten@raudssus.de>.
 
+Hans Dieter Pearcey <hdp@cpan.org> sent in some additional tests for ensuring
+things will install properly, submitted a fix for the bug causing problems with
+writing Makefiles during bootstrapping, contributed an example program, and
+submitted yet another fix to ensure that local::lib can install and bootstrap
+properly. Many, many thanks!
+
+pattern of Freenode IRC contributed the beginnings of the Troubleshooting
+section. Many thanks!
+
 =head1 LICENSE
 
 This library is free software under the same license as perl itself