[Bast-commits] r9073 - in local-lib/1.000/trunk/lib: lib/core local

[matthewt at dev.catalyst.perl.org]

Author: matthewt
Date: 2010-03-31 19:10:38 +0100 (Wed, 31 Mar 2010)
New Revision: 9073

Modified:
   local-lib/1.000/trunk/lib/lib/core/only.pm
   local-lib/1.000/trunk/lib/local/lib.pm
Log:
doc cleanup

Modified: local-lib/1.000/trunk/lib/lib/core/only.pm
===================================================================
--- local-lib/1.000/trunk/lib/lib/core/only.pm	2010-03-31 16:23:40 UTC (rev 9072)
+++ local-lib/1.000/trunk/lib/lib/core/only.pm	2010-03-31 18:10:38 UTC (rev 9073)
@@ -17,15 +17,19 @@
 
   use lib::core::only; # now @INC contains only the two core directories
 
-  # To get only the core directories plus the ones for the local::lib in
-  # scope
+To get only the core directories plus the ones for the local::lib in scope:
 
   $ perl -Mlib::core::only -Mlocal::lib=~/perl5 myscript.pl
 
+To attempt to do a self-contained build (but note this will not reliably
+propagate into subprocesses, see the CAVEATS below):
+
+  $ PERL5OPT='-Mlib::core::only -Mlocal::lib=~/perl5' cpan
+
 =head1 DESCRIPTION
 
 lib::core::only is simply a shortcut to say "please reduce my @INC to only
-the core lib and archlib directories of this perl".
+the core lib and archlib (architecture-specific lib) directories of this perl".
 
 You might want to do this to ensure a local::lib contains only the code you
 need, or to test an L<App::FatPacker|App::FatPacker> tree, or to avoid known

Modified: local-lib/1.000/trunk/lib/local/lib.pm
===================================================================
--- local-lib/1.000/trunk/lib/local/lib.pm	2010-03-31 16:23:40 UTC (rev 9072)
+++ local-lib/1.000/trunk/lib/local/lib.pm	2010-03-31 18:10:38 UTC (rev 9073)
@@ -384,9 +384,6 @@
   # 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)'
-
   # Just print out useful shell commands
   $ perl -Mlocal::lib
   export MODULEBUILDRC=/home/username/perl/.modulebuildrc
@@ -553,24 +550,10 @@
 
 =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.
+See L<lib::core::only|lib::core::only> for one way to do this - but note that
+there are a number of caveats, and the best approach is always to perform a
+build against a clean perl (i.e. site and vendor as close to empty as possible).
 
-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