[Bast-commits] r8706 - in local-lib/1.000/trunk: . lib/local

[apeiron at dev.catalyst.perl.org]

Author: apeiron
Date: 2010-02-14 11:25:32 +0000 (Sun, 14 Feb 2010)
New Revision: 8706

Modified:
   local-lib/1.000/trunk/Changes
   local-lib/1.000/trunk/lib/local/lib.pm
Log:
Beginning of better docs for --self-contained courtesy of markstos at cpan.org.
Also bump the version number immediately so I don't forget to when I release it.

Modified: local-lib/1.000/trunk/Changes
===================================================================
--- local-lib/1.000/trunk/Changes	2010-02-14 11:25:26 UTC (rev 8705)
+++ local-lib/1.000/trunk/Changes	2010-02-14 11:25:32 UTC (rev 8706)
@@ -1,5 +1,8 @@
 Revision history for local::lib
 
+        - Start of better docs for C<--self-contained> thanks to
+          markstos at cpan.org.
+
 1.004009 2009-11-07
 
         - Fix warning if your $ENV{PERL5LIB} is undef

Modified: local-lib/1.000/trunk/lib/local/lib.pm
===================================================================
--- local-lib/1.000/trunk/lib/local/lib.pm	2010-02-14 11:25:26 UTC (rev 8705)
+++ local-lib/1.000/trunk/lib/local/lib.pm	2010-02-14 11:25:32 UTC (rev 8706)
@@ -11,7 +11,7 @@
 use Carp ();
 use Config;
 
-our $VERSION = '1.004009'; # 1.4.9
+our $VERSION = '1.005000'; # 1.5.0
 my @KNOWN_FLAGS = (qw/--self-contained/);
 
 sub import {
@@ -567,6 +567,26 @@
 
 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