New README.hpux for 5.6.0

[p5pRT]

Migrated from rt.perl.org#2931 (status was 'resolved')

Searchable as RT2931$

[p5pRT]

From okamoto@xfiles.intercon.hp.com

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

README.hpux - 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 (this is very likely to be
out of date)​:

  D270, D280, D370, D380, K250, K260, K370, K380, K450, K460, K570, K580,
  T600, V2200, N-class

A complete list of models at the time the OS was built is in the file
/opt/langtools/lib/sched.models.
The first column corresponds to the output of the "uname -m" command
(without the leading "9000/").
The second column is the PA-RISC version
and the third column is the exact chip type used.

=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 flags +DAportable and +DS32
should be used.

It is no longer possible to compile PA-RISC 1.0 executables on either the
PA-RISC 1.1 or 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.20, files larger than 2GB (2^31) may be
created and manipulated.
Three separate methods of doing this are available.
Of these methods,
the best method for Perl is to compile using the -Duselargefiles
flag to Configure.
This will cause the -D_FILE_OFFSET_BITS=64 compiler flag to be used
when building Perl.
This causes Perl to be compiled using structures and functions in which
these are 64 bits wide, rather than 32 bits wide.
(Note that this will only work with HP's ANSI C compiler.
If you want to compile Perl using gcc, you will have to get a version
of the compiler that support 64-bit operations.)

The one drawback to this approach is that
any extension which calls any file-manipulating C function
will need to be recompiled
(just follow the usual "perl Makefile.PL; make; make test; make install"
procedure).
The list of functions that will need to recompiled is​:
creat, fgetpos, fopen,
freopen, fsetpos, fstat,
fstatvfs, fstatvfsdev, ftruncate,
ftw, lockf, lseek,
lstat, mmap, nftw,
open, prealloc, stat,
statvfs, statvfsdev, tmpfile,
truncate, getrlimit, setrlimit

=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,
use the -Duse64bitall flag to Configure.
This will force Perl to be compiled in a pure LP64 environment (via the
+DD64 flag).

You can also use the -Duse64bitint flag to Configure.
Although there are some minor differences between compiling Perl with
this flag versus the -Duse64bitall flag,
they should not be noticeable from a Perl user's perspective.

In both cases, it is strongly recommended that you use these flags
when you run Configure.
If you do not use them, but answer the questions about 64-bit numbers
when Configure asks you,
you may get a configuration that cannot be compiled, or that does
not function as expected.

(Note that these Configure flags will only work with HP's ANSI C compiler.
If you want to compile Perl using gcc, you will have to get a version
of the compiler that support 64-bit operations.)

=head2 GDBM and Threads

If you attempt to compile Perl with threads on an 11.X system and also link
in the GDBM library, then Perl will immediately core dump when it starts up.
The only workaround at this point is to relink the GDBM library under 11.X,
then relink it into Perl.

=head2 NFS filesystems and utime(2)

If you are compiling Perl on a remotely-mounted NFS filesystem, the test
io/fs.t may fail on test #18.
This appears to be a bug in HP-UX and no fix is currently available.

=head1 AUTHOR

Jeff Okamoto <okamoto@​corp.hp.com>

With much assistance regarding shared libraries from Marc Sabatella.

=head1 DATE

Version 0.3​: 2000/03/31

=cut

[p5pRT]

From [Unknown Contact. See original ticket]

At 16​:09 -0800 2000-03-31, Jeff Okamoto wrote​:

When compiling Perl, the use of an ANSI C compiler is highly recommended.
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  you must use an ANSI C compiler.

unless you're planning on putting the same README.hpux into the 5.004
maintenance track (which seems unlikely, given your later discussion
of large files and threading).

[p5pRT]

From [Unknown Contact. See original ticket]

When compiling Perl, the use of an ANSI C compiler is highly recommended.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
you must use an ANSI C compiler.

Good point.

unless you're planning on putting the same README.hpux into the 5.004
maintenance track (which seems unlikely, given your later discussion
of large files and threading).

Hmmm. Do you think it's worth making separate references to the main
track (5.6) versus the maintenance track (is it only 5.004, or is 5.005
also on the maintenance track)?

Jeff

[p5pRT]

From [Unknown Contact. See original ticket]

At 15​:20 -0700 2000-04-04, Jeff Okamoto wrote of README.hpux​:

Hmmm. Do you think it's worth making separate references to the main
track (5.6) versus the maintenance track

Well, I suppose it's up to you, according to how much effort you want
to put into helping people to continue using older variants of Perl.
Personally, all I do for maintenance track releases for such perls
is run make test against them on the then current release of
MachTen. As there's never been a problem, much less one that can be
documented around, I've never given the issue much thought.

(is it only 5.004, or is 5.005
also on the maintenance track)?

AFAIK, they're both on maintenance. My records, which are probably
out of date, show Chip Salzenberg as pumpking for both.

If you do want to cover all bases, and don't want to maintain
separate READMEs for each track (life being too short), you could
lard a single file with phrases like "for Perl versions greater than
5.004", although that would have a negative effect on readability.
Or you might, at the top of the file, say something like "The
information in this file applies to the latest version of Perl at the
time of writing, 5.6. If you are installing an earlier version of
Perl, see also L<Earlier versions of Perl>.".