Test case for #10433/#10424.
[p5sagit/p5-mst-13.2.git] / README.hpux
CommitLineData
60ed1d8c 1If you read this file _as_is_, just ignore the funny characters you see.
2It is written in the POD format (see pod/perlpod.pod) which is specially
3designed to be readable as is.
f2a260d6 4
5=head1 NAME
6
d66be8f9 7README.hpux - Perl version 5 on Hewlett-Packard Unix (HP-UX) systems
f2a260d6 8
9=head1 DESCRIPTION
10
60ed1d8c 11This document describes various features of HP's Unix operating system
12(HP-UX) that will affect how Perl version 5 (hereafter just Perl) is
13compiled and/or runs.
f2a260d6 14
15=head2 Compiling Perl 5 on HP-UX
16
60ed1d8c 17When compiling Perl, you must use an ANSI C compiler. The C compiler
18that ships with all HP-UX systems is a K&R compiler that should only be
19used to build new kernels.
f2a260d6 20
21Perl can be compiled with either HP's ANSI C compiler or with gcc. The
60ed1d8c 22former is recommended, as not only can it compile Perl with no
23difficulty, but also can take advantage of features listed later that
24require the use of HP compiler-specific command-line flags.
f2a260d6 25
60ed1d8c 26If you decide to use gcc, make sure your installation is recent and
27complete, and be sure to read the Perl README file for more gcc-specific
28details.
f2a260d6 29
30=head2 PA-RISC
31
60ed1d8c 32HP's current Unix systems run on its own Precision Architecture
33(PA-RISC) chip. HP-UX used to run on the Motorola MC68000 family of
34chips, but any machine with this chip in it is quite obsolete and this
35document will not attempt to address issues for compiling Perl on the
36Motorola chipset.
f2a260d6 37
60ed1d8c 38The most recent version of PA-RISC at the time of this document's last
39update is 2.0.
f2a260d6 40
41=head2 PA-RISC 1.0
42
43The original version of PA-RISC, HP no longer sells any system with this chip.
44
13e84f2c 45The following systems contained PA-RISC 1.0 chips:
f2a260d6 46
60ed1d8c 47 600, 635, 645, 808, 815, 822, 825, 832, 834, 835, 840, 842, 845, 850, 852,
48 855, 860, 865, 870, 890
f2a260d6 49
50=head2 PA-RISC 1.1
51
52An upgrade to the PA-RISC design, it shipped for many years in many different
53system.
54
55The following systems contain with PA-RISC 1.1 chips:
56
60ed1d8c 57 705, 710, 712, 715, 720, 722, 725, 728, 730, 735, 742, 743, 745, 747, 750,
58 755, 770, 777, 778, 779, 800, 801, 803, 806, 807, 809, 811, 813, 816, 817,
59 819, 821, 826, 827, 829, 831, 837, 839, 841, 847, 849, 851, 856, 857, 859,
60 867, 869, 877, 887, 891, 892, 897, A180, A180C, B115, B120, B132L, B132L+,
61 B160L, B180L, C100, C110, C115, C120, C160L, D200, D210, D220, D230, D250,
62 D260, D310, D320, D330, D350, D360, D410, DX0, DX5, DZO, E25, E35, E45,
63 E55, F10, F20, F30, G30, G40, G50, G60, G70, H20, H30, H40, H50, H60, H70,
64 I30, I40, I50, I60, I70, J200, J210, J210XC, K100, K200, K210, K220, K230,
65 K400, K410, K420, S700i, S715, S724, S760, T500, T520
f2a260d6 66
67=head2 PA-RISC 2.0
68
60ed1d8c 69The most recent upgrade to the PA-RISC design, it added support for
7064-bit integer data.
f2a260d6 71
60ed1d8c 72As of the date of this document's last update, the following systems
73contain PA-RISC 2.0 chips (this is very likely to be out of date):
f2a260d6 74
60ed1d8c 75 700, 780, 781, 782, 783, 785, 802, 804, 810, 820, 861, 871, 879, 889, 893,
76 895, 896, 898, 899, B1000, C130, C140, C160, C180, C180+, C180-XP, C200+,
77 C400+, C3000, C360, CB260, D270, D280, D370, D380, D390, D650, J220, J2240,
78 J280, J282, J400, J410, J5000, J7000, K250, K260, K260-EG, K270, K360,
79 K370, K380, K450, K460, K460-EG, K460-XP, K470, K570, K580, L1000, L2000,
80 N4000, R380, R390, T540, T600, V2000, V2200, V2250, V2500
f2a260d6 81
d66be8f9 82A complete list of models at the time the OS was built is in the file
60ed1d8c 83/opt/langtools/lib/sched.models. The first column corresponds to the
84output of the "uname -m" command (without the leading "9000/"). The
85second column is the PA-RISC version and the third column is the exact
42be3f00 86chip type used. (Start browsing at the bottom to prevent confusion ;-)
d66be8f9 87
f2a260d6 88=head2 Portability Between PA-RISC Versions
89
90An executable compiled on a PA-RISC 2.0 platform will not execute on a
60ed1d8c 91PA-RISC 1.1 platform, even if they are running the same version of
92HP-UX. If you are building Perl on a PA-RISC 2.0 platform and want that
93Perl to to also run on a PA-RISC 1.1, the compiler flags +DAportable and
94+DS32 should be used.
f2a260d6 95
60ed1d8c 96It is no longer possible to compile PA-RISC 1.0 executables on either
13e84f2c 97the PA-RISC 1.1 or 2.0 platforms. The command-line flags are accepted,
98but the resulting executable will not run when transferred to a PA-RISC
991.0 system.
100
101=head2 Itanium Processor Family
102
103HP-UX also runs on the new Itanium processor. This requires the use
104of a different version of HP-UX (currently 11.20), and with the exception
105of a few differences detailed below and in later sections, Perl should
106compile with no problems.
107
108Although PA-RISC binaries can run on Itanium systems, you should not
109attempt to use a PA-RISC version of Perl on an Itanium system. This is
110because shared libraries created on an Itanium system cannot be loaded
111while running a PA-RISC executable.
f2a260d6 112
113=head2 Building Dynamic Extensions on HP-UX
114
115HP-UX supports dynamically loadable libraries (shared libraries).
13e84f2c 116Shared libraries end with the suffix .sl. On Itanium systems,
117they end with the suffix .so.
f2a260d6 118
60ed1d8c 119Shared libraries created on a platform using a particular PA-RISC
120version are not usable on platforms using an earlier PA-RISC version by
121default. However, this backwards compatibility may be enabled using the
122same +DAportable compiler flag (with the same PA-RISC 1.0 caveat
123mentioned above).
f2a260d6 124
13e84f2c 125Shared libraries created on an Itanium platform cannot be loaded on
126a PA-RISC platform. Shared libraries created on a PA-RISC platform
127can only be loaded on an Itanium platform if it is a PA-RISC executable
128that is attempting to load the PA-RISC library. A PA-RISC shared
129library cannot be loaded into an Itanium executable nor vice-versa.
130
f2a260d6 131To create a shared library, the following steps must be performed:
132
133 1. Compile source modules with +z or +Z flag to create a .o module
134 which contains Position-Independent Code (PIC). The linker will
135 tell you in the next step if +Z was needed.
136
137 2. Link the shared library using the -b flag. If the code calls
138 any functions in other system libraries (e.g., libm), it must
139 be included on this line.
140
141(Note that these steps are usually handled automatically by the extension's
142Makefile).
143
144If these dependent libraries are not listed at shared library creation
145time, you will get fatal "Unresolved symbol" errors at run time when the
146library is loaded.
147
a75f7dba 148You may create a shared library that refers to another library, which
60ed1d8c 149may be either an archive library or a shared library. If this second
150library is a shared library, this is called a "dependent library". The
151dependent library's name is recorded in the main shared library, but it
152is not linked into the shared library. Instead, it is loaded when the
153main shared library is loaded. This can cause problems if you build an
154extension on one system and move it to another system where the
155libraries may not be located in the same place as on the first system.
f2a260d6 156
157If the referred library is an archive library, then it is treated as a
158simple collection of .o modules (all of which must contain PIC). These
159modules are then linked into the shared library.
160
60ed1d8c 161Note that it is okay to create a library which contains a dependent
162library that is already linked into perl.
f2a260d6 163
42be3f00 164Some extensions, like DB_File and Compress::Zlib use/require prebuilt
165libraries for the perl extensions/modules to work. If these libraries
166are built using the default configuration, it might happen that you run
167into an error like "invalid loader fixup" during load phase. HP is aware
168of this problem and address it at
169 http://devresource.hp.com/devresource/Docs/TechTips/cxxTips.html#tip13
170
171A more general approach is to intervene manually, as with an example for
172the DB_File module, which requires SleepyCat's libdb.sl:
173
174 # cd .../db-3.2.9/build_unix
175 # vi Makefile
176 ... add +Z to all cflags to create shared objects
177 CFLAGS= -c $(CPPFLAGS) +Z -Ae +O2 +Onolimit \
178 -I/usr/local/include -I/usr/include/X11R6
179 CXXFLAGS= -c $(CPPFLAGS) +Z -Ae +O2 +Onolimit \
180 -I/usr/local/include -I/usr/include/X11R6
181
182 # make clean
183 # make
184 # mkdir tmp
185 # cd tmp
186 # ar x ../libdb.a
187 # ld -b -o libdb-3.2.sl *.o
188 # mv libdb-3.2.sl /usr/local/lib
189 # rm *.o
190 # cd /usr/local/lib
191 # rm -f libdb.sl
192 # ln -s libdb-3.2.sl libdb.sl
193
194 # cd .../DB_File-1.76
195 # make distclean
196 # perl Makefile.PL
197 # make
198 # make test
199 # make install
200
13e84f2c 201It is no longer possible to link PA-RISC 1.0 shared libraries (even
202though the command-line flags are still present).
203
204PA-RISC and Itanium object files are not interchangeable. Although
205you may be able to use ar to create an archive library of PA-RISC
206object files on an Itanium system, you cannot link against it using
207an Itanium link editor.
f2a260d6 208
209=head2 The HP ANSI C Compiler
210
60ed1d8c 211When using this compiler to build Perl, you should make sure that the
212flag -Aa is added to the cpprun and cppstdin variables in the config.sh
42be3f00 213file (though see the section on 64-bit perl below). If you are using a
214recent version of the Perl distribution, these flags are set automatically.
f2a260d6 215
216=head2 Using Large Files with Perl
217
60ed1d8c 218Beginning with HP-UX version 10.20, files larger than 2GB (2^31 bytes)
219may be created and manipulated. Three separate methods of doing this
220are available. Of these methods, the best method for Perl is to compile
221using the -Duselargefiles flag to Configure. This causes Perl to be
222compiled using structures and functions in which these are 64 bits wide,
223rather than 32 bits wide. (Note that this will only work with HP's ANSI
224C compiler. If you want to compile Perl using gcc, you will have to get
225a version of the compiler that support 64-bit operations.)
226
227There are some drawbacks to this approach. One is that any extension
228which calls any file-manipulating C function will need to be recompiled
f74a9bd3 229(just follow the usual "perl Makefile.PL; make; make test; make install"
230procedure).
60ed1d8c 231
d66be8f9 232The list of functions that will need to recompiled is:
233creat, fgetpos, fopen,
234freopen, fsetpos, fstat,
235fstatvfs, fstatvfsdev, ftruncate,
236ftw, lockf, lseek,
237lstat, mmap, nftw,
238open, prealloc, stat,
239statvfs, statvfsdev, tmpfile,
240truncate, getrlimit, setrlimit
f2a260d6 241
60ed1d8c 242Another drawback is only valid for Perl versions before 5.6.0. This
243drawback is that the seek and tell functions (both the builtin version
244and POSIX module version) will not perform correctly.
245
246It is strongly recommended that you use this flag when you run
247Configure. If you do not do this, but later answer the question about
248large files when Configure asks you, you may get a configuration that
249cannot be compiled, or that does not function as expected.
250
f2a260d6 251=head2 Threaded Perl
252
c7d9b096 253It is possible to compile a version of threaded Perl on any version of
254HP-UX before 10.30, but it is strongly suggested that you be running on
f2a260d6 255HP-UX 11.00 at least.
256
60ed1d8c 257To compile Perl with threads, add -Dusethreads to the arguments of
258Configure. Verify that the -D_POSIX_C_SOURCE=199506L compiler flag is
259automatically added to the list of flags. Also make sure that -lpthread
42be3f00 260is listed before -lc in the list of libraries to link Perl with. The
261hints provided for HP-UX during Configure will try very hard to get
262this right for you.
f2a260d6 263
c7d9b096 264HP-UX versions before 10.30 require a seperate installation of a POSIX
265threads library package. Two examples are the HP DCE package, available
266on "HP-UX Hardware Extensions 3.0, Install and Core OS, Release 10.20,
267April 1999 (B3920-13941)" or the Freely available PTH package, available
268though worldwide HP-UX mirrors of precompiled packages
269(e.g. http://hpux.tn.tudelft.nl/hppd/hpux/alpha.html)
270
f2a260d6 271=head2 64-bit Perl
272
60ed1d8c 273Beginning with HP-UX 11.00, programs compiled under HP-UX can take
274advantage of the LP64 programming environment (LP64 means Longs and
275Pointers are 64 bits wide).
f2a260d6 276
60ed1d8c 277Work is being performed on Perl to make it 64-bit compliant on all
278versions of Unix. Once this is complete, scalar variables will be able
279to hold numbers larger than 2^32 with complete precision.
f2a260d6 280
281As of the date of this document, Perl is not 64-bit compliant on HP-UX.
282
60ed1d8c 283Should a user wish to experiment with compiling Perl in the LP64
284environment, use the -Duse64bitall flag to Configure. This will force
285Perl to be compiled in a pure LP64 environment (via the +DD64 flag).
f74a9bd3 286
60ed1d8c 287You can also use the -Duse64bitint flag to Configure. Although there
288are some minor differences between compiling Perl with this flag versus
289the -Duse64bitall flag, they should not be noticeable from a Perl user's
290perspective.
f74a9bd3 291
60ed1d8c 292In both cases, it is strongly recommended that you use these flags when
293you run Configure. If you do not use do this, but later answer the
294questions about 64-bit numbers when Configure asks you, you may get a
295configuration that cannot be compiled, or that does not function as
296expected.
f74a9bd3 297
60ed1d8c 298(Note that these Configure flags will only work with HP's ANSI C
299compiler. If you want to compile Perl using gcc, you will have to get a
300version of the compiler that support 64-bit operations.)
f2a260d6 301
d66be8f9 302=head2 GDBM and Threads
303
60ed1d8c 304If you attempt to compile Perl with threads on an 11.X system and also
305link in the GDBM library, then Perl will immediately core dump when it
306starts up. The only workaround at this point is to relink the GDBM
307library under 11.X, then relink it into Perl.
d66be8f9 308
309=head2 NFS filesystems and utime(2)
310
311If you are compiling Perl on a remotely-mounted NFS filesystem, the test
60ed1d8c 312io/fs.t may fail on test #18. This appears to be a bug in HP-UX and no
313fix is currently available.
d66be8f9 314
183968aa 315=head2 perl -P and //
316
efdf3af0 317In HP-UX Perl is compiled with flags that will cause problems if the
183968aa 318-P flag of Perl (preprocess Perl code with the C preprocessor before
319perl sees it) is used. The problem is that C<//>, being a C++-style
320until-end-of-line comment, will disappear along with the remainder
321of the line. This means that common Perl constructs like
322
efdf3af0 323 s/foo//;
183968aa 324
325will turn into illegal code
326
efdf3af0 327 s/foo
183968aa 328
efdf3af0 329The workaround is to use some other quoting separator than C<"/">,
330like for example C<"!">:
183968aa 331
efdf3af0 332 s!foo!!;
183968aa 333
13e84f2c 334=head2 Kernel parameters (maxdsiz)
335
336By default, HP-UX comes configured with a maximum data segment size of
33764MB. This is too small to correctly compile Perl with the maximum
338optimization levels. You can increase the size of the maxdsiz kernel
339parameter through the use of SAM.
340
341When using the GUI version of SAM, click on the Kernel Configuration
342icon, then the Configurable Parameters icon. Scroll down and select
343the maxdsiz line. From the Actions menu, select the Modify Configurable
344Parameter item. Insert the new formula into the Formula/Value box.
345Then follow the instructions to rebuild your kernel and reboot your
346system.
347
348In general, a value of 256MB (or "256*1024*1024") is sufficient for
349Perl to compile at maximum optimization.
350
f2a260d6 351=head1 AUTHOR
352
353Jeff Okamoto <okamoto@corp.hp.com>
354
355With much assistance regarding shared libraries from Marc Sabatella.
356
357=head1 DATE
358
13e84f2c 359Version 0.6.3: 2001-05-16
f2a260d6 360
361=cut