Dusting off README.threads.

p4raw-id: //depot/cfgperl@3779

diff --git a/README.threads b/README.threads
index 136b156..4ae2f37 100644 (file)
--- a/README.threads
+++ b/README.threads
@@ -5,34 +5,62 @@ few race conditions that show up under high contention on SMP
 machines.  Internal implementation is still subject to changes.
 It is not recommended for production use at this time.
 
+---------------------------------------------------------------------------
+
 Building
 
-If you want to build with multi-threading support and you are
-running one of the following:
+If your system is in the following list you should be able to just:
 
-  * Linux 2.x (with the LinuxThreads library installed: that's
-    the linuxthreads and linuxthreads-devel RPMs for RedHat)
+    ./Configure -Dusethreads -des
+    make
 
-  * Digital UNIX 4.x
+and ignore the rest of this "Building" section.  If not, continue
+from the "Problems" section.
 
-  * Digital UNIX 3.x (Formerly DEC OSF/1), see additional note below
+       * Linux 2.* (with the LinuxThreads library installed:
+         that's the linuxthreads and linuxthreads-devel RPMs
+         for RedHat)
 
-  * Solaris 2.x for recentish x (2.5 is OK)
+       * Tru64 UNIX (formerly Digital UNIX formerly DEC OSF/1)
+         (see additional note below)
 
-  * IRIX 6.2 or newer. 6.2 will require a few os patches.
-    IMPORTANT: Without patch 2401, a kernel bug in IRIX 6.2 will
-    cause your machine to panic and crash when running threaded perl.
-    IRIX 6.3 and up should be OK. See lower down for patch details.
+       * Solaris 2.* for recentish x (2.5 is OK)
 
-then you should be able to use
+       * IRIX 6.2 or newer. 6.2 will require a few OS patches.
+         IMPORTANT: Without patch 2401 (or its replacement),
+         a kernel bug in IRIX 6.2 will cause your machine to
+         panic and crash when running threaded perl.
+         IRIX 6.3 and up should be OK. See lower down for patch details.
 
-    ./Configure -Dusethreads -des
-    make
+       * AIX 4.1.5 or newer.
+
+       * FreeBSD 2.2.8 or newer.
+
+       * OpenBSD
+
+       * NeXTstep, OpenStep (Rhapsody?)
 
-and ignore the rest of this "Building" section. If it doesn't
-work or you are using another platform which you believe supports
-POSIX.1c threads then read on.  Additional information may be in
-a platform-specific "hints" file in the hints/ subdirectory.
+       * OS/2
+
+       * DOS DJGPP
+
+       * VM/ESA
+
+---------------------------------------------------------------------------
+
+Problems
+
+If the simple way doesn't work or you are using another platform which
+you believe supports POSIX.1c threads then read on.  Additional
+information may be in a platform-specific "hints" file in the hints/
+subdirectory.
+
+First of all, because threads are such an experimentral feature
+there's a failsafe in Configure that stops unknown platforms
+from using threads.  Search for "is not known to support threads". 
+About five lines above that is a line that has a list of operating
+system names separated with |-signs.  Append your operating system
+(perl -le 'print $^O') to that list.
 
 On other platforms that use Configure to build perl, omit the -d
 from your ./Configure arguments. For example, use:
@@ -43,11 +71,12 @@ When Configure prompts you for ccflags, insert any other arguments in
 there that your compiler needs to use POSIX threads. When Configure
 prompts you for linking flags, include any flags required for
 threading (usually nothing special is required here).  Finally, when
-COnfigure prompts you for libraries, include any necessary libraries
+Configure prompts you for libraries, include any necessary libraries
 (e.g. -lpthread).  Pay attention to the order of libraries.  It is
 probably necessary to specify your threading library *before* your
 standard C library, e.g.  it might be necessary to have -lpthread -lc,
-instead of -lc -lpthread.
+instead of -lc -lpthread.  You may also need to use -lc_r instead
+of -lc.
 
 Once you have specified all your compiler flags, you can have Configure
 accept all the defaults for the remainder of the session by typing  &-d
@@ -71,7 +100,7 @@ For Digital Unix 4.x:
 
 For Digital Unix 3.x (Formerly DEC OSF/1):
     Add -DOLD_PTHREADS_API to ccflags
-    If compiling with the GNU cc compiler, remove -thread from ccflags
+    If compiling with the GNU cc compiler, remove -threads from ccflags
 
     (The following should be done automatically if you call Configure
       with the -Dusethreads option).
@@ -93,6 +122,7 @@ For IRIX:
     For IRIX 6.3 and 6.4 the pthreads should work out of the box.
     Thanks to Hannu Napari <Hannu.Napari@hut.fi> for the IRIX
     pthreads patches information.
+
 For AIX:
     (This should all be done automatically by the hint file).
     Change cc to xlc_r or cc_r.
@@ -107,6 +137,12 @@ For Win32:
 Now you can do a
     make
 
+When you succeed in compiling and testing ("make test" after your
+build) a threaded Perl in a platform previosuly unknown to support
+threaded perl, please let perlbug@perl.com know about your victory.
+Explain what you did in painful detail.
+
+---------------------------------------------------------------------------
 
 O/S specific bugs
 
@@ -155,6 +191,7 @@ Try running the main perl test suite too. There are known
 failures for some of the DBM/DB extensions (if their underlying
 libraries were not compiled to be thread-aware).
 
+---------------------------------------------------------------------------
 
 Bugs
 
@@ -164,8 +201,7 @@ tested at all in recent times.)
 
 * There may still be races where bugs show up under contention.
 
-* Need to document "lock", Thread.pm, Queue.pm, ...
-
+---------------------------------------------------------------------------
 
 Debugging
 
@@ -178,6 +214,7 @@ have to delete the lines in perl.c which say
         DEBUG_S(signal(SIGSEGV, (void(*)(int))catch_sigsegv););
     #endif
 
+---------------------------------------------------------------------------
 
 Background
 
@@ -287,3 +324,6 @@ Andy Dougherty <doughera@lafayette.edu>
 
 Other minor updates 10 Feb 1999 by
 Gurusamy Sarathy
+
+More platforms added 26 Jul 1999 by
+Jarkko Hietaniemi