add README.hpux

p4raw-id: //depot/perl@3032

1 files changed, 193 insertions, 0 deletions

diff --git a/README.hpux b/README.hpux
new file mode 100644
index 0000000000..1fda51a76d
--- /dev/null
+++ b/README.hpux
@@ -0,0 +1,193 @@
+If you read this file _as_is_, just ignore the funny characters you
+see. It is written in the POD format (see pod/perlpod.pod) which is
+specially designed to be readable as is.
+
+=head1 NAME
+
+perlhpux - Perl version 5 on Hewlett-Packard Unix (HP-UX) systems
+
+=head1 DESCRIPTION
+
+This document describes various features of HP's Unix operating system (HP-UX)
+that will affect how Perl version 5 (hereafter just Perl) is compiled and/or
+runs.
+
+=head2 Compiling Perl 5 on HP-UX
+
+When compiling Perl, the use of an ANSI C compiler is highly recommended.
+The C compiler that ships with all HP-UX systems is a K&R compiler that
+should only be used to build new kernels.
+
+Perl can be compiled with either HP's ANSI C compiler or with gcc.  The
+former is recommended, as not only can it compile Perl with no difficulty,
+but also can take advantage of features listed later that require the use
+of HP compiler-specific command-line flags.
+
+If you decide to use gcc, make sure your installation is recent and complete,
+and be sure to read the Perl README file for more gcc-specific details.
+
+=head2 PA-RISC
+
+HP's current Unix systems run on its own Precision Architecture (PA-RISC) chip.
+HP-UX used to run on the Motorola MC68000 family of chips, but any machine with
+this chip in it is quite obsolete and this document will not attempt to address
+issues for compiling Perl on the Motorola chipset.
+
+The most recent version of PA-RISC at the time of this document's last update
+is 2.0.
+
+=head2 PA-RISC 1.0
+
+The original version of PA-RISC, HP no longer sells any system with this chip.
+
+The following systems contain PA-RISC 1.0 chips:
+
+    600, 635, 645, 800, 808, 815, 822, 825, 832, 834, 835, 840,
+    842, 845, 850, 852, 855, 860, 865, 870, 890
+
+=head2 PA-RISC 1.1
+
+An upgrade to the PA-RISC design, it shipped for many years in many different
+system.
+
+The following systems contain with PA-RISC 1.1 chips:
+
+    705, 710, 712, 715, 720, 722, 725, 728, 730, 735, 743, 745, 747, 750,
+    755, 770, 807S, 817S, 827S, 837S, 847S, 857S, 867S, 877S, 887S, 897S,
+    D200, D210, D220, D230, D250, D260, D310, D320, D330, D350, D360, D400,
+    E25, E35, E45, E55, F10, F20, F30, G30, G40, G50, G60, G70, H30, H40,
+    H50, H60, H70, I30, I40, I50, I60, I70, K100, K200, K210, K220, K400,
+    K410, K420, T500, T520
+
+
+=head2 PA-RISC 2.0
+
+The most recent upgrade to the PA-RISC design, it added support for 64-bit
+integer data.
+
+The following systems contain PA-RISC 2.0 chips:
+
+    D270, D280, D370, D380, K250, K260, K370, K380, K450, K460, K570, K580,
+    T600, V2200
+
+=head2 Portability Between PA-RISC Versions
+
+An executable compiled on a PA-RISC 2.0 platform will not execute on a
+PA-RISC 1.1 platform, even if they are running the same version of HP-UX.
+If you are building Perl on a PA-RISC 2.0 platform and want that Perl to
+to also run on a PA-RISC 1.1, the compiler flag +DAportable should be used.
+
+It is no longer possible to compile PA-RISC 1.0 executables on either the
+PA-RISC 1.1 and 2.0 platforms.
+
+=head2 Building Dynamic Extensions on HP-UX
+
+HP-UX supports dynamically loadable libraries (shared libraries).
+Shared libraries end with the suffix .sl.
+
+Shared libraries created on a platform using a particular PA-RISC version
+are not usable on platforms using an earlier PA-RISC version by default.
+However, this backwards compatibility may be enabled using the same
++DAportable compiler flag (with the same PA-RISC 1.0 caveat mentioned above).
+
+To create a shared library, the following steps must be performed:
+
+    1. Compile source modules with +z or +Z flag to create a .o module
+       which contains Position-Independent Code (PIC).  The linker will
+       tell you in the next step if +Z was needed.
+
+    2. Link the shared library using the -b flag.  If the code calls
+       any functions in other system libraries (e.g., libm), it must
+       be included on this line.
+
+(Note that these steps are usually handled automatically by the extension's
+Makefile).
+
+If these dependent libraries are not listed at shared library creation
+time, you will get fatal "Unresolved symbol" errors at run time when the
+library is loaded.
+
+You may create a shared library that referers to another library, which
+may be either an archive library or a shared library.  If it is a
+shared library, this is called a "dependent library".
+The dependent library's name is recorded in the main shared library,
+but it is not linked into the shared library.
+Instead, it is loaded when the main shared library is loaded.
+
+If the referred library is an archive library, then it is treated as a
+simple collection of .o modules (all of which must contain PIC).  These
+modules are then linked into the shared library.
+
+Note that it is okay to create a library which contains a dependent library
+that is already linked into perl.
+
+It is no longer possible to link PA-RISC 1.0 shared libraries.
+
+=head2 The HP ANSI C Compiler
+
+When using this compiler to build Perl, you should make sure that
+the flag -Aa is added to the cpprun and cppstdin variables in the
+config.sh file.
+
+=head2 Using Large Files with Perl
+
+Beginning with HP-UX version 10.10, files larger than 2GB (2^31) may be
+created and manipulated.
+Three separate methods of doing this are available.
+The best method is to compile Perl using the -D_FILE_OFFSET_BITS=64
+compiler flag.
+This causes Perl to be compiled using structures and functions in which
+these are 64 bits wide, rather than 32 bits wide.
+
+There are only two drawbacks to this approach:
+the first is that the seek and tell functions (both the builtin version
+and the POSIX module's version) will not correctly
+function for these large files
+(POSIX declared the offset arguments in seek and tell as being of type long).
+The second is that any extension which calls any file-manipulating C function
+will need to be recompiled.
+
+=head2 Threaded Perl
+
+It is impossible to compile a version of threaded Perl on any version of
+HP-UX before 10.30, and it is strongly suggested that you be running on
+HP-UX 11.00 at least.
+
+To compile Perl with thread, add -Dusethreads to the arguments of Configure.
+Ensure that the -D_POSIX_C_SOURCE=199506L compiler flag is automatically
+added to the list of flags.  Also make sure that -lpthread is listed before
+-lc in the list of libraries to link Perl with.
+
+As of the date of this document, Perl threads are not fully supported on HP-UX.
+
+=head2 64-bit Perl
+
+Beginning with HP-UX 11.00, programs compiled under HP-UX can take advantage
+of the LP64 programming environment (LP64 means Longs and Pointers are 64 bits
+wide).
+
+Work is being performed on Perl to make it 64-bit compliant on all versions
+of Unix.  Once this is complete, scalar variables will be able to hold
+numbers larger than 2^32 with complete precision.
+
+As of the date of this document, Perl is not 64-bit compliant on HP-UX.
+
+Should a user wish to experiment with compiling Perl in the LP64 environment,
+the following steps must be taken: libraries must be searched only within
+/lib/pa20_64, the compiler flag +DD64 must be used, and the C library is
+now located at /lib/pa20_64/libc.sl.
+
+On the brighter side, the large file problem goes away, as longs are now
+64 bits wide.
+
+=head1 AUTHOR
+
+Jeff Okamoto <okamoto@corp.hp.com>
+
+With much assistance regarding shared libraries from Marc Sabatella.
+
+=head1 DATE
+
+Version 0.1: 1999/2/22
+
+=cut