This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
add README.hpux
[perl5.git] / README.hpux
CommitLineData
f2a260d6
GS
1If you read this file _as_is_, just ignore the funny characters you
2see. It is written in the POD format (see pod/perlpod.pod) which is
3specially designed to be readable as is.
4
5=head1 NAME
6
7perlhpux - Perl version 5 on Hewlett-Packard Unix (HP-UX) systems
8
9=head1 DESCRIPTION
10
11This document describes various features of HP's Unix operating system (HP-UX)
12that will affect how Perl version 5 (hereafter just Perl) is compiled and/or
13runs.
14
15=head2 Compiling Perl 5 on HP-UX
16
17When compiling Perl, the use of an ANSI C compiler is highly recommended.
18The C compiler that ships with all HP-UX systems is a K&R compiler that
19should only be used to build new kernels.
20
21Perl can be compiled with either HP's ANSI C compiler or with gcc. The
22former is recommended, as not only can it compile Perl with no difficulty,
23but also can take advantage of features listed later that require the use
24of HP compiler-specific command-line flags.
25
26If you decide to use gcc, make sure your installation is recent and complete,
27and be sure to read the Perl README file for more gcc-specific details.
28
29=head2 PA-RISC
30
31HP's current Unix systems run on its own Precision Architecture (PA-RISC) chip.
32HP-UX used to run on the Motorola MC68000 family of chips, but any machine with
33this chip in it is quite obsolete and this document will not attempt to address
34issues for compiling Perl on the Motorola chipset.
35
36The most recent version of PA-RISC at the time of this document's last update
37is 2.0.
38
39=head2 PA-RISC 1.0
40
41The original version of PA-RISC, HP no longer sells any system with this chip.
42
43The following systems contain PA-RISC 1.0 chips:
44
45 600, 635, 645, 800, 808, 815, 822, 825, 832, 834, 835, 840,
46 842, 845, 850, 852, 855, 860, 865, 870, 890
47
48=head2 PA-RISC 1.1
49
50An upgrade to the PA-RISC design, it shipped for many years in many different
51system.
52
53The following systems contain with PA-RISC 1.1 chips:
54
55 705, 710, 712, 715, 720, 722, 725, 728, 730, 735, 743, 745, 747, 750,
56 755, 770, 807S, 817S, 827S, 837S, 847S, 857S, 867S, 877S, 887S, 897S,
57 D200, D210, D220, D230, D250, D260, D310, D320, D330, D350, D360, D400,
58 E25, E35, E45, E55, F10, F20, F30, G30, G40, G50, G60, G70, H30, H40,
59 H50, H60, H70, I30, I40, I50, I60, I70, K100, K200, K210, K220, K400,
60 K410, K420, T500, T520
61
62
63=head2 PA-RISC 2.0
64
65The most recent upgrade to the PA-RISC design, it added support for 64-bit
66integer data.
67
68The following systems contain PA-RISC 2.0 chips:
69
70 D270, D280, D370, D380, K250, K260, K370, K380, K450, K460, K570, K580,
71 T600, V2200
72
73=head2 Portability Between PA-RISC Versions
74
75An executable compiled on a PA-RISC 2.0 platform will not execute on a
76PA-RISC 1.1 platform, even if they are running the same version of HP-UX.
77If you are building Perl on a PA-RISC 2.0 platform and want that Perl to
78to also run on a PA-RISC 1.1, the compiler flag +DAportable should be used.
79
80It is no longer possible to compile PA-RISC 1.0 executables on either the
81PA-RISC 1.1 and 2.0 platforms.
82
83=head2 Building Dynamic Extensions on HP-UX
84
85HP-UX supports dynamically loadable libraries (shared libraries).
86Shared libraries end with the suffix .sl.
87
88Shared libraries created on a platform using a particular PA-RISC version
89are not usable on platforms using an earlier PA-RISC version by default.
90However, this backwards compatibility may be enabled using the same
91+DAportable compiler flag (with the same PA-RISC 1.0 caveat mentioned above).
92
93To create a shared library, the following steps must be performed:
94
95 1. Compile source modules with +z or +Z flag to create a .o module
96 which contains Position-Independent Code (PIC). The linker will
97 tell you in the next step if +Z was needed.
98
99 2. Link the shared library using the -b flag. If the code calls
100 any functions in other system libraries (e.g., libm), it must
101 be included on this line.
102
103(Note that these steps are usually handled automatically by the extension's
104Makefile).
105
106If these dependent libraries are not listed at shared library creation
107time, you will get fatal "Unresolved symbol" errors at run time when the
108library is loaded.
109
110You may create a shared library that referers to another library, which
111may be either an archive library or a shared library. If it is a
112shared library, this is called a "dependent library".
113The dependent library's name is recorded in the main shared library,
114but it is not linked into the shared library.
115Instead, it is loaded when the main shared library is loaded.
116
117If the referred library is an archive library, then it is treated as a
118simple collection of .o modules (all of which must contain PIC). These
119modules are then linked into the shared library.
120
121Note that it is okay to create a library which contains a dependent library
122that is already linked into perl.
123
124It is no longer possible to link PA-RISC 1.0 shared libraries.
125
126=head2 The HP ANSI C Compiler
127
128When using this compiler to build Perl, you should make sure that
129the flag -Aa is added to the cpprun and cppstdin variables in the
130config.sh file.
131
132=head2 Using Large Files with Perl
133
134Beginning with HP-UX version 10.10, files larger than 2GB (2^31) may be
135created and manipulated.
136Three separate methods of doing this are available.
137The best method is to compile Perl using the -D_FILE_OFFSET_BITS=64
138compiler flag.
139This causes Perl to be compiled using structures and functions in which
140these are 64 bits wide, rather than 32 bits wide.
141
142There are only two drawbacks to this approach:
143the first is that the seek and tell functions (both the builtin version
144and the POSIX module's version) will not correctly
145function for these large files
146(POSIX declared the offset arguments in seek and tell as being of type long).
147The second is that any extension which calls any file-manipulating C function
148will need to be recompiled.
149
150=head2 Threaded Perl
151
152It is impossible to compile a version of threaded Perl on any version of
153HP-UX before 10.30, and it is strongly suggested that you be running on
154HP-UX 11.00 at least.
155
156To compile Perl with thread, add -Dusethreads to the arguments of Configure.
157Ensure that the -D_POSIX_C_SOURCE=199506L compiler flag is automatically
158added to the list of flags. Also make sure that -lpthread is listed before
159-lc in the list of libraries to link Perl with.
160
161As of the date of this document, Perl threads are not fully supported on HP-UX.
162
163=head2 64-bit Perl
164
165Beginning with HP-UX 11.00, programs compiled under HP-UX can take advantage
166of the LP64 programming environment (LP64 means Longs and Pointers are 64 bits
167wide).
168
169Work is being performed on Perl to make it 64-bit compliant on all versions
170of Unix. Once this is complete, scalar variables will be able to hold
171numbers larger than 2^32 with complete precision.
172
173As of the date of this document, Perl is not 64-bit compliant on HP-UX.
174
175Should a user wish to experiment with compiling Perl in the LP64 environment,
176the following steps must be taken: libraries must be searched only within
177/lib/pa20_64, the compiler flag +DD64 must be used, and the C library is
178now located at /lib/pa20_64/libc.sl.
179
180On the brighter side, the large file problem goes away, as longs are now
18164 bits wide.
182
183=head1 AUTHOR
184
185Jeff Okamoto <okamoto@corp.hp.com>
186
187With much assistance regarding shared libraries from Marc Sabatella.
188
189=head1 DATE
190
191Version 0.1: 1999/2/22
192
193=cut