This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
skip integrate of problematic change#6223 from cfgperl into mainline
[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
d66be8f9 7README.hpux - Perl version 5 on Hewlett-Packard Unix (HP-UX) systems
f2a260d6
GS
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
f74a9bd3
GS
17An ANSI C compiler is required to build Perl. The C compiler that ships
18with all HP-UX systems is a K&R compiler that can only be used to build
19new kernels.
f2a260d6
GS
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
d66be8f9
GS
68The following systems contain PA-RISC 2.0 chips (this is very likely to be
69out of date):
f2a260d6
GS
70
71 D270, D280, D370, D380, K250, K260, K370, K380, K450, K460, K570, K580,
f74a9bd3 72 T600, V2200, N-class
f2a260d6 73
d66be8f9
GS
74A complete list of models at the time the OS was built is in the file
75/opt/langtools/lib/sched.models.
76The first column corresponds to the output of the "uname -m" command
77(without the leading "9000/").
78The second column is the PA-RISC version
79and the third column is the exact chip type used.
80
f2a260d6
GS
81=head2 Portability Between PA-RISC Versions
82
83An executable compiled on a PA-RISC 2.0 platform will not execute on a
84PA-RISC 1.1 platform, even if they are running the same version of HP-UX.
85If you are building Perl on a PA-RISC 2.0 platform and want that Perl to
d66be8f9
GS
86to also run on a PA-RISC 1.1, the compiler flags +DAportable and +DS32
87should be used.
f2a260d6
GS
88
89It is no longer possible to compile PA-RISC 1.0 executables on either the
d66be8f9 90PA-RISC 1.1 or 2.0 platforms.
f2a260d6
GS
91
92=head2 Building Dynamic Extensions on HP-UX
93
94HP-UX supports dynamically loadable libraries (shared libraries).
95Shared libraries end with the suffix .sl.
96
97Shared libraries created on a platform using a particular PA-RISC version
98are not usable on platforms using an earlier PA-RISC version by default.
99However, this backwards compatibility may be enabled using the same
100+DAportable compiler flag (with the same PA-RISC 1.0 caveat mentioned above).
101
102To create a shared library, the following steps must be performed:
103
104 1. Compile source modules with +z or +Z flag to create a .o module
105 which contains Position-Independent Code (PIC). The linker will
106 tell you in the next step if +Z was needed.
107
108 2. Link the shared library using the -b flag. If the code calls
109 any functions in other system libraries (e.g., libm), it must
110 be included on this line.
111
112(Note that these steps are usually handled automatically by the extension's
113Makefile).
114
115If these dependent libraries are not listed at shared library creation
116time, you will get fatal "Unresolved symbol" errors at run time when the
117library is loaded.
118
4375e838 119You may create a shared library that refers to another library, which
f2a260d6
GS
120may be either an archive library or a shared library. If it is a
121shared library, this is called a "dependent library".
122The dependent library's name is recorded in the main shared library,
123but it is not linked into the shared library.
124Instead, it is loaded when the main shared library is loaded.
125
126If the referred library is an archive library, then it is treated as a
127simple collection of .o modules (all of which must contain PIC). These
128modules are then linked into the shared library.
129
130Note that it is okay to create a library which contains a dependent library
131that is already linked into perl.
132
133It is no longer possible to link PA-RISC 1.0 shared libraries.
134
135=head2 The HP ANSI C Compiler
136
137When using this compiler to build Perl, you should make sure that
138the flag -Aa is added to the cpprun and cppstdin variables in the
139config.sh file.
140
141=head2 Using Large Files with Perl
142
d66be8f9 143Beginning with HP-UX version 10.20, files larger than 2GB (2^31) may be
f2a260d6
GS
144created and manipulated.
145Three separate methods of doing this are available.
d66be8f9 146Of these methods,
f74a9bd3
GS
147the best method for Perl is to compile using the -Duselargefiles
148flag to Configure.
149This will cause the -D_FILE_OFFSET_BITS=64 compiler flag to be used
150when building Perl.
f2a260d6
GS
151This causes Perl to be compiled using structures and functions in which
152these are 64 bits wide, rather than 32 bits wide.
f74a9bd3
GS
153(Note that this will only work with HP's ANSI C compiler.
154If you want to compile Perl using gcc, you will have to get a version
155of the compiler that support 64-bit operations.)
156
157The one drawback to this approach is that
158any extension which calls any file-manipulating C function
159will need to be recompiled
160(just follow the usual "perl Makefile.PL; make; make test; make install"
161procedure).
d66be8f9
GS
162The list of functions that will need to recompiled is:
163creat, fgetpos, fopen,
164freopen, fsetpos, fstat,
165fstatvfs, fstatvfsdev, ftruncate,
166ftw, lockf, lseek,
167lstat, mmap, nftw,
168open, prealloc, stat,
169statvfs, statvfsdev, tmpfile,
170truncate, getrlimit, setrlimit
f2a260d6
GS
171
172=head2 Threaded Perl
173
174It is impossible to compile a version of threaded Perl on any version of
175HP-UX before 10.30, and it is strongly suggested that you be running on
176HP-UX 11.00 at least.
177
178To compile Perl with thread, add -Dusethreads to the arguments of Configure.
179Ensure that the -D_POSIX_C_SOURCE=199506L compiler flag is automatically
180added to the list of flags. Also make sure that -lpthread is listed before
181-lc in the list of libraries to link Perl with.
182
f74a9bd3
GS
183As of the date of this document,
184Perl threads are not fully supported on HP-UX.
f2a260d6
GS
185
186=head2 64-bit Perl
187
188Beginning with HP-UX 11.00, programs compiled under HP-UX can take advantage
189of the LP64 programming environment (LP64 means Longs and Pointers are 64 bits
190wide).
191
192Work is being performed on Perl to make it 64-bit compliant on all versions
193of Unix. Once this is complete, scalar variables will be able to hold
194numbers larger than 2^32 with complete precision.
195
196As of the date of this document, Perl is not 64-bit compliant on HP-UX.
197
198Should a user wish to experiment with compiling Perl in the LP64 environment,
f74a9bd3
GS
199use the -Duse64bitall flag to Configure.
200This will force Perl to be compiled in a pure LP64 environment (via the
201+DD64 flag).
202
203You can also use the -Duse64bitint flag to Configure.
204Although there are some minor differences between compiling Perl with
205this flag versus the -Duse64bitall flag,
206they should not be noticeable from a Perl user's perspective.
207
208In both cases, it is strongly recommended that you use these flags
209when you run Configure.
210If you do not use them, but answer the questions about 64-bit numbers
211when Configure asks you,
212you may get a configuration that cannot be compiled, or that does
213not function as expected.
214
215(Note that these Configure flags will only work with HP's ANSI C compiler.
216If you want to compile Perl using gcc, you will have to get a version
217of the compiler that support 64-bit operations.)
f2a260d6 218
d66be8f9
GS
219=head2 GDBM and Threads
220
221If you attempt to compile Perl with threads on an 11.X system and also link
222in the GDBM library, then Perl will immediately core dump when it starts up.
223The only workaround at this point is to relink the GDBM library under 11.X,
224then relink it into Perl.
225
226=head2 NFS filesystems and utime(2)
227
228If you are compiling Perl on a remotely-mounted NFS filesystem, the test
229io/fs.t may fail on test #18.
230This appears to be a bug in HP-UX and no fix is currently available.
231
f2a260d6
GS
232=head1 AUTHOR
233
234Jeff Okamoto <okamoto@corp.hp.com>
235
236With much assistance regarding shared libraries from Marc Sabatella.
237
238=head1 DATE
239
f74a9bd3 240Version 0.3: 2000/03/31
f2a260d6
GS
241
242=cut