Reflect recent changes

documentation/README.hpux

@@ -5,50 +5,88 @@ Please mail questions, comments, corrections, additional examples, etc.
 to Ralph.Lange@mail.bessy.de
 
 NOTE: 3.14 will ONLY compile on HPUX 11 systems. HPUX 10 does not have
-      the necessary thread support and will never ever be supported for
-      EPICS base versions >= 3.14.
+      the necessary posix thread support and will never ever be
+      supported for EPICS base versions >= 3.14.
 
 
 Tools needed
 ------------
 
- o HP's ANSI C compiler (cc)
+ o For compiling with HP native compilers
 
-For compiling with the HP C++ compiler (hpux-parisc)
- o Recent version of HP's aCC C++ compiler aCC (we use A.03.39)
+  - HP's ANSI C compiler (cc)
 
-For compiling with GNU g++
- o GNU g++ >= 2.95 (we use 3.2)
+  - Recent version of HP's aCC C++ compiler aCC (we use A.03.39)
+    HP's old frontend-based C++ compiler (CC) will not work.
+
+ o For compiling with the GNU compilers
+
+  - GNU assembler (part of the binutils package)
+
+  - GNU gcc/g++ >= 3 (I would suggest >= 3.2)
+    If you do not have GCC as a binary package, you can quite easily
+    build a GCC from scratch (aka "make bootstrap"). I was successful
+    using the following options to the configure script:
+    ../configure
+      --prefix=<compiler install location>
+      --enable-version-specific-runtime-libs
+      --enable-languages=c++
+      --with-gnu-as
+      --with-as=<location of GNU assembler executable>
+      --enable-shared
+      --enable-threads=posix
+    Remember to set the install location of your GCC package in the
+    configuration file ../configure/os/CONFIG_SITE.Common.hpux-parisc-gnu
+    to make the EPICS builds use it.
 
 
 Environment
 -----------
 
-Default is compiling with the generic HP aCC compiler. To use the GNU compiler,
-set the environment variable EPICS_HOST_ARCH to hpux-parisc-gnu before starting
-to compile base.
+Default is compiling with the generic HP aCC compiler. To use the GNU
+suite, set the environment variable EPICS_HOST_ARCH=hpux-parisc-gnu
+before starting to compile base.
 
 
 Shared Libraries
 ----------------
 
 Generating shared libraries is supported, suggested and the default.
-You have to set the appropriate search path variable in
-../configure/os/CONFIG_SITE.hpux-parisc.hpux-parisc to make shared
-libraries work properly. (You can always override with setting the
-SHLIB_PATH environment variable when executiong the binaries.)
+
+If you are planning to carry around your binaries to other machines, you
+have to set the shared library search path accordingly (i.e. to the
+generic location where you will install the shared libraries of EPICS
+base on the target machines). This is done in the configure area (in the
+file ../configure/os/CONFIG_SITE.Common.hpux-parisc).
+
+The setting of internal and external search paths for libraries is aimed
+at stability. The order of search is:
+ 1. Where the library was found at compile time.  (always)
+ 2. The INSTALL_LOCATION at compile time.         (convenient when developing)
+ 3. Any locations explicitly configured.          (generic location)
+ 4. The environment variable SHLIB_PATH.          (fallback)
+
+I changed the usual behaviour of "environment overrides default" to
+increase reliability: As long as the libraries are in the generic
+location, a user can set the environment wildly to anything without any
+impact on the reliable operation of EPICS applications.
+Still on systems where the libraries are not found at the generic place
+(and you don't have the root privilege to put them there), setting the
+environment you can point your client application to a fallback
+location.
 
 
 Known Problems
 --------------
 
+ o Caveat: To be compatible with HP-UX 10, GCC defaults to use the DCE
+   (user space) threads package. If you see messages like "errLogInit
+   failed" when running a Channel Access client, you are probably
+   linking against the old DCE threads library instead of libpthread.
+
  o There is a problem with a CA client not detecting a network
    connection going down. This only happens with some clients, though.
 
- o Statically built binaries don't work properly (yet).
-
- o GNU built binaries don't work properly (yet).
-
  o The 3.13 compatibility mode isn't thoroughly tested yet.