Set up Perl invocation method during configuration (Peter Prymmer)
[p5sagit/p5-mst-13.2.git] / README.hpux
1 If you read this file _as_is_, just ignore the funny characters you
2 see. It is written in the POD format (see pod/perlpod.pod) which is
3 specially designed to be readable as is.
4
5 =head1 NAME
6
7 README.hpux - Perl version 5 on Hewlett-Packard Unix (HP-UX) systems
8
9 =head1 DESCRIPTION
10
11 This document describes various features of HP's Unix operating system (HP-UX)
12 that will affect how Perl version 5 (hereafter just Perl) is compiled and/or
13 runs.
14
15 =head2 Compiling Perl 5 on HP-UX
16
17 When compiling Perl, the use of an ANSI C compiler is highly recommended.
18 The C compiler that ships with all HP-UX systems is a K&R compiler that
19 should only be used to build new kernels.
20
21 Perl can be compiled with either HP's ANSI C compiler or with gcc.  The
22 former is recommended, as not only can it compile Perl with no difficulty,
23 but also can take advantage of features listed later that require the use
24 of HP compiler-specific command-line flags.
25
26 If you decide to use gcc, make sure your installation is recent and complete,
27 and be sure to read the Perl README file for more gcc-specific details.
28
29 =head2 PA-RISC
30
31 HP's current Unix systems run on its own Precision Architecture (PA-RISC) chip.
32 HP-UX used to run on the Motorola MC68000 family of chips, but any machine with
33 this chip in it is quite obsolete and this document will not attempt to address
34 issues for compiling Perl on the Motorola chipset.
35
36 The most recent version of PA-RISC at the time of this document's last update
37 is 2.0.
38
39 =head2 PA-RISC 1.0
40
41 The original version of PA-RISC, HP no longer sells any system with this chip.
42
43 The 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
50 An upgrade to the PA-RISC design, it shipped for many years in many different
51 system.
52
53 The 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
65 The most recent upgrade to the PA-RISC design, it added support for 64-bit
66 integer data.
67
68 The following systems contain PA-RISC 2.0 chips (this is very likely to be
69 out of date):
70
71     D270, D280, D370, D380, K250, K260, K370, K380, K450, K460, K570, K580,
72     T600, V2200
73
74 A complete list of models at the time the OS was built is in the file
75 /opt/langtools/lib/sched.models.
76 The first column corresponds to the output of the "uname -m" command
77 (without the leading "9000/").
78 The second column is the PA-RISC version
79 and the third column is the exact chip type used.
80
81 =head2 Portability Between PA-RISC Versions
82
83 An executable compiled on a PA-RISC 2.0 platform will not execute on a
84 PA-RISC 1.1 platform, even if they are running the same version of HP-UX.
85 If you are building Perl on a PA-RISC 2.0 platform and want that Perl to
86 to also run on a PA-RISC 1.1, the compiler flags +DAportable and +DS32
87 should be used.
88
89 It is no longer possible to compile PA-RISC 1.0 executables on either the
90 PA-RISC 1.1 or 2.0 platforms.
91
92 =head2 Building Dynamic Extensions on HP-UX
93
94 HP-UX supports dynamically loadable libraries (shared libraries).
95 Shared libraries end with the suffix .sl.
96
97 Shared libraries created on a platform using a particular PA-RISC version
98 are not usable on platforms using an earlier PA-RISC version by default.
99 However, this backwards compatibility may be enabled using the same
100 +DAportable compiler flag (with the same PA-RISC 1.0 caveat mentioned above).
101
102 To 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
113 Makefile).
114
115 If these dependent libraries are not listed at shared library creation
116 time, you will get fatal "Unresolved symbol" errors at run time when the
117 library is loaded.
118
119 You may create a shared library that referers to another library, which
120 may be either an archive library or a shared library.  If it is a
121 shared library, this is called a "dependent library".
122 The dependent library's name is recorded in the main shared library,
123 but it is not linked into the shared library.
124 Instead, it is loaded when the main shared library is loaded.
125
126 If the referred library is an archive library, then it is treated as a
127 simple collection of .o modules (all of which must contain PIC).  These
128 modules are then linked into the shared library.
129
130 Note that it is okay to create a library which contains a dependent library
131 that is already linked into perl.
132
133 It is no longer possible to link PA-RISC 1.0 shared libraries.
134
135 =head2 The HP ANSI C Compiler
136
137 When using this compiler to build Perl, you should make sure that
138 the flag -Aa is added to the cpprun and cppstdin variables in the
139 config.sh file.
140
141 =head2 Using Large Files with Perl
142
143 Beginning with HP-UX version 10.20, files larger than 2GB (2^31) may be
144 created and manipulated.
145 Three separate methods of doing this are available.
146 Of these methods,
147 the best method for Perl is to compile using the -D_FILE_OFFSET_BITS=64
148 compiler flag.
149 This causes Perl to be compiled using structures and functions in which
150 these are 64 bits wide, rather than 32 bits wide.
151
152 There are only two drawbacks to this approach:
153 the first is that the seek and tell functions (both the builtin version
154 and the POSIX module's version) will not correctly
155 function for these large files
156 (the offset arguments in seek and tell are implemented as type long).
157 The second is that any extension which calls any file-manipulating C function
158 will need to be recompiled using the above-mentioned -D_FILE_OFFSET_BITS=64
159 flag.
160 The list of functions that will need to recompiled is:
161 creat,          fgetpos,        fopen,
162 freopen,        fsetpos,        fstat,
163 fstatvfs,       fstatvfsdev,    ftruncate,
164 ftw,            lockf,          lseek,
165 lstat,          mmap,           nftw,
166 open,           prealloc,       stat,
167 statvfs,        statvfsdev,     tmpfile,
168 truncate,       getrlimit,      setrlimit
169
170 =head2 Threaded Perl
171
172 It is impossible to compile a version of threaded Perl on any version of
173 HP-UX before 10.30, and it is strongly suggested that you be running on
174 HP-UX 11.00 at least.
175
176 To compile Perl with thread, add -Dusethreads to the arguments of Configure.
177 Ensure that the -D_POSIX_C_SOURCE=199506L compiler flag is automatically
178 added to the list of flags.  Also make sure that -lpthread is listed before
179 -lc in the list of libraries to link Perl with.
180
181 As of the date of this document, Perl threads are not fully supported on HP-UX.
182
183 =head2 64-bit Perl
184
185 Beginning with HP-UX 11.00, programs compiled under HP-UX can take advantage
186 of the LP64 programming environment (LP64 means Longs and Pointers are 64 bits
187 wide).
188
189 Work is being performed on Perl to make it 64-bit compliant on all versions
190 of Unix.  Once this is complete, scalar variables will be able to hold
191 numbers larger than 2^32 with complete precision.
192
193 As of the date of this document, Perl is not 64-bit compliant on HP-UX.
194
195 Should a user wish to experiment with compiling Perl in the LP64 environment,
196 the following steps must be taken: libraries must be searched only within
197 /lib/pa20_64, the compiler flag +DD64 must be used, and the C library is
198 now located at /lib/pa20_64/libc.sl.
199
200 On the brighter side, the large file problem goes away, as longs are now
201 64 bits wide.
202
203 =head2 GDBM and Threads
204
205 If you attempt to compile Perl with threads on an 11.X system and also link
206 in the GDBM library, then Perl will immediately core dump when it starts up.
207 The only workaround at this point is to relink the GDBM library under 11.X,
208 then relink it into Perl.
209
210 =head2 NFS filesystems and utime(2)
211
212 If you are compiling Perl on a remotely-mounted NFS filesystem, the test
213 io/fs.t may fail on test #18.
214 This appears to be a bug in HP-UX and no fix is currently available.
215
216 =head1 AUTHOR
217
218 Jeff Okamoto <okamoto@corp.hp.com>
219
220 With much assistance regarding shared libraries from Marc Sabatella.
221
222 =head1 DATE
223
224 Version 0.2: 1999/03/01
225
226 =cut