integrate changes#3105,3130,3154 from maint-5.005

p4raw-link: @3154 on //depot/maint-5.005/perl: 60a22511b32234c359f6a1235f7273a596f8edcb
p4raw-link: @3130 on //depot/maint-5.005/perl: 08c9aea58d52024cd45844ac23e957399bbc0340
p4raw-link: @3105 on //depot/maint-5.005/perl: 412383e48358b00907bbb438802caa8caf7f67cf

p4raw-id: //depot/perl@3158
p4raw-integrated: from //depot/maint-5.005/perl@3157 'ignore' Configure
	(@3057..) 'merge in' hints/dec_osf.sh (@2702..) hints/netbsd.sh
	(@2714..) INSTALL (@3059..)

1 files changed, 25 insertions, 6 deletions

diff --git a/INSTALL b/INSTALL
index fc2890d57d..fccc4f141a 100644
--- a/INSTALL
+++ b/INSTALL
@@ -685,9 +685,24 @@ You can elect to build a shared libperl by
 
 	sh Configure -Duseshrplib
 
-To actually build perl, you must add the current working directory to your
-LD_LIBRARY_PATH environment variable before running make.  You can do
-this with
+To build a shared libperl, the environment variable controlling shared
+library search (LD_LIBRARY_PATH in most systems, DYLD_LIBRARY_PATH for
+NeXTSTEP/OPENSTEP, LIBRARY_PATH for BeOS) must be set up to include
+the Perl build directory because that's where the shared libperl will
+be created.   Configure arranges Makefile to have the correct shared
+library search settings.
+
+However, there are some special cases where manually setting the
+shared library path might be required.  For example, if you want to run
+something like the following with the newly-built but not-yet-installed
+./perl:
+
+        cd t; ./perl misc/failing_test.t
+or
+        ./perl -Ilib ~/my_mission_critical_test
+
+then you need to set up the shared library path explicitly.
+You can do this with
 
    LD_LIBRARY_PATH=`pwd`:$LD_LIBRARY_PATH; export LD_LIBRARY_PATH
 
@@ -695,9 +710,13 @@ for Bourne-style shells, or
 
    setenv LD_LIBRARY_PATH `pwd`
 
-for Csh-style shells.  You *MUST* do this before running make.
-Folks running NeXT OPENSTEP must substitute DYLD_LIBRARY_PATH for
-LD_LIBRARY_PATH above.
+for Csh-style shells.  (This procedure may also be needed if for some
+unexpected reason Configure fails to set up Makefile correctly.)
+
+You can often recognize failures to build/use a shared libperl from error
+messages complaining about a missing libperl.so (or libperl.sl in HP-UX),
+for example:
+18126:./miniperl: /sbin/loader: Fatal Error: cannot map libperl.so
 
 There is also an potential problem with the shared perl library if you
 want to have more than one "flavor" of the same version of perl (e.g.