bump version
[p5sagit/local-lib.git] / lib / local / lib.pm
index 32ba4ad..ceee4aa 100644 (file)
@@ -8,7 +8,7 @@ use 5.006;
 use File::Spec ();
 use Config;
 
-our $VERSION = '1.008026'; # 1.8.26
+our $VERSION = '2.000_000'; # 2.0.0
 $VERSION = eval $VERSION;
 
 sub import {
@@ -169,12 +169,12 @@ sub _mb_escape_path {
 
 sub installer_options_for {
   my ($class, $path) = @_;
-  return {
+  return (
     PERL_MM_OPT =>
       defined $path ? "INSTALL_BASE="._mm_escape_path($path) : undef,
     PERL_MB_OPT =>
       defined $path ? "--install_base "._mb_escape_path($path) : undef,
-  };
+  );
 }
 
 sub active_paths {
@@ -212,7 +212,7 @@ sub deactivate {
     roots => [ _remove_from($self->roots, $path) ],
   );
 
-  $args{extra} = $self->installer_options_for($args{roots}[0]);
+  $args{extra} = { $self->installer_options_for($args{roots}[0]) };
 
   $self->clone(%args);
 }
@@ -236,7 +236,7 @@ sub deactivate_all {
     );
   }
 
-  $args{extra} = $self->installer_options_for(undef);
+  $args{extra} = { $self->installer_options_for(undef) };
 
   $self->clone(%args);
 }
@@ -266,7 +266,7 @@ sub activate {
     );
   }
 
-  $args{extra} = $self->installer_options_for($path);
+  $args{extra} = { $self->installer_options_for($path) };
 
   $self->clone(%args);
 }
@@ -654,6 +654,10 @@ From the shell -
   export PERL5LIB="/home/username/perl5/lib/perl5"
   export PATH="/home/username/perl5/bin:$PATH"
 
+From a .bashrc file -
+
+  [ $SHLVL -eq 1 ] && eval "$(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)"
+
 =head2 The bootstrapping technique
 
 A typical way to install local::lib is using what is known as the
@@ -670,12 +674,18 @@ By default local::lib installs itself and the CPAN modules into ~/perl5.
 
 Windows users must also see L</Differences when using this module under Win32>.
 
-1. Download and unpack the local::lib tarball from CPAN (search for "Download"
+=over 4
+
+=item 1.
+
+Download and unpack the local::lib tarball from CPAN (search for "Download"
 on the CPAN page about local::lib).  Do this as an ordinary user, not as root
 or administrator.  Unpack the file in your home directory or in any other
 convenient location.
 
-2. Run this:
+=item 2.
+
+Run this:
 
   perl Makefile.PL --bootstrap
 
@@ -687,16 +697,20 @@ to specify the name of the directory when you call bootstrap, as follows:
 
   perl Makefile.PL --bootstrap=~/foo
 
-3. Run this: (local::lib assumes you have make installed on your system)
+=item 3.
+
+Run this: (local::lib assumes you have make installed on your system)
 
   make test && make install
 
-4. Now we need to setup the appropriate environment variables, so that Perl
+=item 4.
+
+Now we need to setup the appropriate environment variables, so that Perl
 starts using our newly generated lib/ directory. If you are using bash or
 any other Bourne shells, you can add this to your shell startup script this
 way:
 
-  echo 'eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)' >>~/.bashrc
+  echo '[ $SHLVL -eq 1 ] && eval "$(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)"' >>~/.bashrc
 
 If you are using C shell, you can do this as follows:
 
@@ -709,12 +723,14 @@ If you passed to bootstrap a directory other than default, you also need to
 give that as import parameter to the call of the local::lib module like this
 way:
 
-  echo 'eval $(perl -I$HOME/foo/lib/perl5 -Mlocal::lib=$HOME/foo)' >>~/.bashrc
+  echo '[ $SHLVL -eq 1 ] && eval "$(perl -I$HOME/foo/lib/perl5 -Mlocal::lib=$HOME/foo)"' >>~/.bashrc
 
 After writing your shell configuration file, be sure to re-read it to get the
 changed settings into your current shell's environment. Bourne shells use
 C<. ~/.bashrc> for this, whereas C shells use C<source ~/.cshrc>.
 
+=back
+
 If you're on a slower machine, or are operating under draconian disk space
 limitations, you can disable the automatic generation of manpages from POD when
 installing modules by using the C<--no-manpages> argument when bootstrapping:
@@ -734,6 +750,12 @@ installation to install modules in different directories directly this way:
   cd ../mydir2
   ... REPEAT ...
 
+When used in a C<.bashrc> file, it is recommended that you protect against
+re-activating a directory in a sub-shell.  This can be done by checking the
+C<$SHLVL> variable as shown in synopsis.  Without this, sub-shells created by
+the user or other programs will override changes made to the parent shell's
+environment.
+
 If you are working with several C<local::lib> environments, you may want to
 remove some of them from the current environment without disturbing the others.
 You can deactivate one environment like this (using bourne sh):
@@ -792,7 +814,7 @@ and the subdirectories are created.
 
 =head3 PowerShell
 
-local::lib also supports PowerShell, and an be used with the
+local::lib also supports PowerShell, and can be used with the
 C<Invoke-Expression> cmdlet.
 
   Invoke-Expression "$(perl -Mlocal::lib)"
@@ -1003,11 +1025,11 @@ local library installation. Appends the directory C<bin> to the given path.
 
 =item Arguments: $path
 
-=item Return value: \%installer_env_vars
+=item Return value: %installer_env_vars
 
 =back
 
-Returns a hashref of environment variables that should be set to cause
+Returns a hash of environment variables that should be set to cause
 installation into the given path.
 
 =head2 resolve_empty_path
@@ -1232,6 +1254,12 @@ not set, a Bourne-compatible shell is assumed.
 
 =item * Should probably auto-fixup CPAN config if not already done.
 
+=item * local::lib loads L<File::Spec>.  When used to set shell variables,
+this isn't a problem.  When used inside a perl script, any L<File::Spec>
+version inside the local::lib will be ignored.  A workaround for this is using
+C<use lib "$ENV{HOME}/perl5/lib/perl5";> inside the script instead of using
+C<local::lib> directly.
+
 =back
 
 Patches very much welcome for any of the above.
@@ -1332,9 +1360,12 @@ environment later on contributed by Andrew Rodland <arodland@cpan.org>.
 Patch for Carp version mismatch contributed by Hakim Cassimally
 <osfameron@cpan.org>.
 
+Rewrite of internals and numerous bug fixes and added features contributed by
+Graham Knop <haarg@haarg.org>.
+
 =head1 COPYRIGHT
 
-Copyright (c) 2007 - 2010 the local::lib L</AUTHOR> and L</CONTRIBUTORS> as
+Copyright (c) 2007 - 2013 the local::lib L</AUTHOR> and L</CONTRIBUTORS> as
 listed above.
 
 =head1 LICENSE