From: Graham Knop <haarg@haarg.org>
Date: Mon, 23 Dec 2013 01:57:50 +0000 (-0500)
Subject: document recommended use of $SHLVL
X-Git-Tag: v2.000_000~10
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=p5sagit%2Flocal-lib.git;a=commitdiff_plain;h=a19f7fe948183357a1de04e8ce57b3f92c47fc05

document recommended use of $SHLVL
---

diff --git a/lib/local/lib.pm b/lib/local/lib.pm
index 632c4a3..6f607d6 100644
--- a/lib/local/lib.pm
+++ b/lib/local/lib.pm
@@ -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
@@ -706,7 +710,7 @@ 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:
 
@@ -719,7 +723,7 @@ 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
@@ -746,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):