Maintenance releace 3 of perl5.005. Includes support for threads.

1 files changed, 111 insertions, 30 deletions

diff --git a/contrib/perl5/INSTALL b/contrib/perl5/INSTALL
index a892e7d..c5e04cb 100644
--- a/contrib/perl5/INSTALL
+++ b/contrib/perl5/INSTALL
@@ -64,6 +64,23 @@ In a related issue, old extensions may possibly be affected by the
 changes in the Perl language in the current release.  Please see
 pod/perldelta.pod for a description of what's changed.
 
+=head1 WARNING:  This version requires a compiler that supports ANSI C.
+
+If you find that your C compiler is not ANSI-capable, try obtaining
+GCC, available from GNU mirrors worldwide (e.g. ftp://ftp.gnu.org/pub/gnu).
+Another alternative may be to use a tool like C<ansi2knr> to convert the
+sources back to K&R style, but there is no guarantee this route will get
+you anywhere, since the prototypes are not the only ANSI features used
+in the Perl sources.  C<ansi2knr> is usually found as part of the freely
+available C<Ghostscript> distribution.  Another similar tool is
+C<unprotoize>, distributed with GCC.  Since C<unprotoize> requires GCC to
+run, you may have to run it on a platform where GCC is available, and move
+the sources back to the platform without GCC.
+
+If you succeed in automatically converting the sources to a K&R compatible
+form, be sure to email perlbug@perl.com to let us know the steps you
+followed.  This will enable us to officially support this option.
+
 =head1 Space Requirements
 
 The complete perl5 source tree takes up about 10 MB of disk space.  The
@@ -167,6 +184,9 @@ put (symlinks to) perl and its accompanying utilities, such as perldoc,
 into a directory typically found along a user's PATH, or in another
 obvious and convenient place.
 
+You can use "Configure -Uinstallusrbinperl" which causes installperl
+to skip installing perl also as /usr/bin/perl.
+
 By default, Configure will compile perl to use dynamic loading if
 your system supports it.  If you want to force perl to be compiled
 statically, you can either choose this when Configure prompts you or
@@ -472,23 +492,26 @@ that problem.
 
 If you need to install perl on many identical systems, it is
 convenient to compile it once and create an archive that can be
-installed on multiple systems.  Here's one way to do that:
+installed on multiple systems.  Suppose, for example, that you want to
+create an archive that can be installed in /opt/perl.
+Here's one way to do that:
 
     # Set up config.over to install perl into a different directory,
     # e.g. /tmp/perl5 (see previous part).
-    sh Configure -des
+    sh Configure -Dprefix=/opt/perl -des
     make
     make test
-    make install
+    make install   # This will install everything into /tmp/perl5.
     cd /tmp/perl5
-    # Edit $archlib/Config.pm to change all the
+    # Edit $archlib/Config.pm and $archlib/.packlist to change all the
     # install* variables back to reflect where everything will
-    # really be installed.
-    # Edit any of the scripts in $scriptdir to have the correct
+    # really be installed.  (That is, change /tmp/perl5 to /opt/perl
+    # everywhere in those files.)
+    # Check the scripts in $scriptdir to make sure they have the correct
     # #!/wherever/perl line.
     tar cvf ../perl5-archive.tar .
     # Then, on each machine where you want to install perl,
-    cd /usr/local  # Or wherever you specified as $prefix
+    cd /opt/perl # Or wherever you specified as $prefix
     tar xvf perl5-archive.tar
 
 =head2 Site-wide Policy settings
@@ -518,8 +541,9 @@ some of the main things you can change.
 
 =head2 Threads
 
-On some platforms, perl5.005 can be compiled to use threads.  To
-enable this, read the file README.threads, and then try
+On some platforms, perl5.005 can be compiled with experimental support
+for threads.  To enable this, read the file README.threads, and then
+try:
 
 	sh Configure -Dusethreads
 
@@ -653,9 +677,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
 
@@ -663,9 +702,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.
@@ -771,21 +814,6 @@ you can change a number of factors in the way perl is built
 by adding appropriate -D directives to your ccflags variable in
 config.sh.
 
-For example, you can replace the rand() and srand() functions in the
-perl source by any other random number generator by a trick such as the
-following (this should all be on one line):
-
-	sh Configure -Dccflags='-Dmy_rand=random -Dmy_srand=srandom' \
-		-Drandbits=31
-
-or you can use the drand48 family of functions with
-
-	sh Configure -Dccflags='-Dmy_rand=lrand48 -Dmy_srand=srand48' \
-		-Drandbits=31
-
-or by adding the -D flags to your ccflags at the appropriate Configure
-prompt.  (Read pp.c to see how this works.)
-
 You should also run Configure interactively to verify that a hint file
 doesn't inadvertently override your ccflags setting.  (Hints files
 shouldn't do that, but some might.)
@@ -920,6 +948,42 @@ to config.h and edit the config.h to reflect your system's peculiarities.
 You'll probably also have to extensively modify the extension building
 mechanism.
 
+=item Environment variable clashes
+
+Configure uses a CONFIG variable that is reported to cause trouble on
+ReliantUnix 5.44.  If your system sets this variable, you can try
+unsetting it before you run Configure.  Configure should eventually
+be fixed to avoid polluting the namespace of the environment.
+
+=item Digital UNIX/Tru64 UNIX and BIN_SH
+
+In Digital UNIX/Tru64 UNIX Configure might abort with
+
+Build a threading Perl? [n]
+Configure[2437]: Syntax error at line 1 : `config.sh' is not expected.
+
+This indicates that Configure is being run with a broken Korn shell
+(even though you think you are using a Bourne shell by using
+"sh Configure" or "./Configure").  The Korn shell bug has been reported
+to Compaq as of February 1999 but in the meanwhile, the reason ksh is
+being used is that you have the environment variable BIN_SH set to
+'xpg4'.  This causes /bin/sh to delegate its duties to /bin/posix/sh
+(a ksh).  Unset the environment variable and rerun Configure.
+
+=item HP-UX 11, pthreads, and libgdbm
+
+If you are running Configure with -Dusethreads in HP-UX 11, be warned
+that POSIX threads and libgdbm (the GNU dbm library) compiled before
+HP-UX 11 do not mix.  This will cause a basic test run by Configure to
+fail
+
+Pthread internal error: message: __libc_reinit() failed, file: ../pthreads/pthread.c, line: 1096
+Return Pointer is 0xc082bf33
+sh: 5345 Quit(coredump)
+
+and Configure will give up.  The cure is to recompile and install
+libgdbm under HP-UX 11.
+
 =item Porting information
 
 Specific information for the OS/2, Plan9, VMS and Win32 ports is in the
@@ -1218,6 +1282,17 @@ ones (which ones these are depends on your system and applications)
 with "ipcrm -s SEMAPHORE_ID_HERE" or configure more semaphores to your
 system.
 
+=item GNU binutils
+
+If you mix GNU binutils (nm, ld, ar) with equivalent vendor-supplied
+tools you may be in for some trouble.  For example creating archives
+with an old GNU 'ar' and then using a new current vendor-supplied 'ld'
+may lead into linking problems.  Either recompile your GNU binutils
+under your current operating system release, or modify your PATH not
+to include the GNU utils before running Configure, or specify the
+vendor-supplied utilities explicitly to Configure, for example by
+Configure -Dar=/bin/ar.
+
 =item Miscellaneous
 
 Some additional things that have been reported for either perl4 or perl5:
@@ -1236,6 +1311,12 @@ If you get syntax errors on '(', try -DCRIPPLED_CC.
 
 Machines with half-implemented dbm routines will need to #undef I_ODBM
 
+HP-UX 11 Y2K patch "Y2K-1100 B.11.00.B0125 HP-UX Core OS Year 2000
+Patch Bundle" has been reported to break the io/fs test #18 which
+tests whether utime() can change timestamps.  The Y2K patch seems to
+break utime() so that over NFS the timestamps do not get changed
+(on local filesystems utime() still works).
+ 
 =back
 
 =head1 make test