Additional install tests from Hans Dieter Pearcey (hdp@cpan.org). Thanks!
[p5sagit/local-lib.git] / lib / local / lib.pm
index b4a3841..d2e5269 100644 (file)
@@ -11,7 +11,7 @@ use File::Path ();
 use Carp ();
 use Config;
 
-our $VERSION = '1.003002'; # 1.3.2
+our $VERSION = '1.003004'; # 1.3.4
 
 sub import {
   my ($class, @args) = @_;
@@ -368,6 +368,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
@@ -402,6 +428,138 @@ PATH is appended to, rather than clobbered.
 
 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".
@@ -455,6 +613,9 @@ documentation additions, contributed by Christopher Nehren <apeiron@cpan.org>.
 Doc patches for a custom local::lib patch contributed by Torsten Raudssus
 <torsten@raudssus.de>.
 
+Hans Dieter Pearcey <hdp@cpan.org> sent in some additional tests for ensuring
+things will install properly.
+
 =head1 LICENSE
 
 This library is free software under the same license as perl itself