delete broken --self-contained flag from core

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

diff --git a/lib/local/lib.pm b/lib/local/lib.pm
index 1b030b6..51c9ba7 100644 (file)
--- a/lib/local/lib.pm
+++ b/lib/local/lib.pm
@@ -11,14 +11,12 @@ use File::Path ();
 use Carp ();
 use Config;
 
-our $VERSION = '1.004008'; # 1.4.7
-my @KNOWN_FLAGS = (qw/--self-contained/);
+our $VERSION = '1.005001'; # 1.5.1
+
+our @KNOWN_FLAGS = qw(--self-contained);
 
 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} || '';
@@ -50,21 +48,7 @@ DEATH
   }
 
   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}
-    );
-
-    # 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 );
+    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";
   }
 
   $arg_store{path} = $class->resolve_path($arg_store{path});
@@ -350,7 +334,7 @@ sub build_environment_vars_for {
     PERL5LIB => join($Config{path_sep},
                   $class->install_base_perl_path($path),
                   $class->install_base_arch_path($path),
-                  ($ENV{PERL5LIB} ?
+                  (($ENV{PERL5LIB}||()) ?
                     ($interpolate == INTERPOLATE_ENV
                       ? ($ENV{PERL5LIB})
                       : (($^O ne 'MSWin32') ? '$PERL5LIB' : '%PERL5LIB%' ))
@@ -359,7 +343,7 @@ sub build_environment_vars_for {
     PATH => join($Config{path_sep},
               $class->install_base_bin_path($path),
               ($interpolate == INTERPOLATE_ENV
-                ? $ENV{PATH}
+                ? ($ENV{PATH}||())
                 : (($^O ne 'MSWin32') ? '$PATH' : '%PATH%' ))
              ),
   )
@@ -397,8 +381,8 @@ In code -
 
 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 its missing dependencies to the '~/perl5' directory
+  perl -MCPAN -Mlocal::lib -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)'
@@ -463,7 +447,7 @@ installing modules by using the C<--no-manpages> argument when bootstrapping:
 
   perl Makefile.PL --bootstrap --no-manpages
 
-If you want to install multiple Perl module environments, say for application evelopment, 
+If you want to install multiple Perl module environments, say for application development, 
 install local::lib globally and then:
 
   cd ~/mydir1
@@ -567,6 +551,26 @@ PATH is appended to, rather than clobbered.
 
 These values are then available for reference by any code after import.
 
+=head1 CREATING A SELF-CONTAINED SET OF MODULES
+
+You can use local::lib to prepare a directory which contains a module and all
+of its non-core dependencies.  The C<--self-contained> option ignores any
+globally installed modules when resolving dependencies, only considering
+modules installed in a "local::lib" directory or provided by core Perl.
+
+A use-case for this feature would be to prepare to deploy a whole "stack" of
+module dependencies on a new machine, even if you have copies of the same
+dependencies installed globally already.
+
+The C<--self-contained> option should be used like this: 
+
+  # Install LWP and *all non-core* dependencies to the 'my_lwp' directory 
+  perl -MCPAN -Mlocal::lib=--self-contained,my_lwp -e 'CPAN::install(LWP)'
+
+Note that some dependencies may involve C-based "XS" code even if your target
+module doesn't. The issue of dealing with XS vs Pure Perl code is beyond the scope
+of what local::lib provides. 
+
 =head1 METHODS
 
 =head2 ensure_directory_structure_for
@@ -770,11 +774,6 @@ auto_install fixes kindly sponsored by http://www.takkle.com/
 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
 <torsten@raudssus.de>.
 
@@ -789,6 +788,12 @@ section. Many thanks!
 
 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.
+
 =head1 COPYRIGHT
 
 Copyright (c) 2007 - 2009 the local::lib L</AUTHOR> and L</CONTRIBUTORS> as