# vim: syntax=pod

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

perlaix - Perl version 5 on IBM AIX (UNIX) systems

=head1 DESCRIPTION

This document describes various features of IBM's UNIX operating
system AIX that will affect how Perl version 5 (hereafter just Perl)
is compiled and/or runs.

=head2 Compiling Perl 5 on AIX

For information on compilers on older versions of AIX, see L</Compiling
Perl 5 on older AIX versions up to 4.3.3>.

When compiling Perl, you must use an ANSI C compiler. AIX does not ship
an ANSI compliant C compiler with AIX by default, but binary builds of
gcc for AIX are widely available. A version of gcc is also included in
the AIX Toolbox which is shipped with AIX.

=head2 Supported Compilers

Currently all versions of IBM's "xlc", "xlc_r", "cc", "cc_r" or
"vac" ANSI/C compiler will work for building Perl if that compiler
works on your system.

If you plan to link Perl to any module that requires thread-support,
like DBD::Oracle, it is better to use the _r version of the compiler.
This will not build a threaded Perl, but a thread-enabled Perl. See
also L</Threaded Perl> later on.

As of writing (2010-09) only the I<IBM XL C for AIX> or I<IBM XL C/C++
for AIX> compiler is supported by IBM on AIX 5L/6.1/7.1.

The following compiler versions are currently supported by IBM:

    IBM XL C and IBM XL C/C++ V8, V9, V10, V11

The XL C for AIX is integrated in the XL C/C++ for AIX compiler and
therefore also supported.

If you choose XL C/C++ V9 you need APAR IZ35785 installed
otherwise the integrated SDBM_File do not compile correctly due
to an optimization bug. You can circumvent this problem by
adding -qipa to the optimization flags (-Doptimize='-O -qipa').
The PTF for APAR IZ35785 which solves this problem is available
from IBM (April 2009 PTF for XL C/C++ Enterprise Edition for AIX, V9.0).

If you choose XL C/C++ V11 you need the April 2010 PTF (or newer)
installed otherwise you will not get a working Perl version.

Perl can be compiled with either IBM's ANSI C compiler or with gcc.
The former is recommended, as not only it can compile Perl with no
difficulty, but also can take advantage of features listed later
that require the use of IBM 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 INSTALL file for more gcc-specific
details. Please report any hoops you had to jump through to the
development team.

=head2 Incompatibility with AIX Toolbox lib gdbm

If the AIX Toolbox version of lib gdbm < 1.8.3-5 is installed on your
system then Perl will not work. This library contains the header files
/opt/freeware/include/gdbm/dbm.h|ndbm.h which conflict with the AIX
system versions. The lib gdbm will be automatically removed from the
wanted libraries if the presence of one of these two header files is
detected. If you want to build Perl with GDBM support then please install
at least gdbm-devel-1.8.3-5 (or higher).

=head2 Perl 5 was successfully compiled and tested on:

 Perl   | AIX Level           | Compiler Level          | w th | w/o th
 -------+---------------------+-------------------------+------+-------
 5.12.2 |5.1 TL9 32 bit       | XL C/C++ V7             | OK   | OK
 5.12.2 |5.1 TL9 64 bit       | XL C/C++ V7             | OK   | OK
 5.12.2 |5.2 TL10 SP8 32 bit  | XL C/C++ V8             | OK   | OK
 5.12.2 |5.2 TL10 SP8 32 bit  | gcc 3.2.2               | OK   | OK
 5.12.2 |5.2 TL10 SP8 64 bit  | XL C/C++ V8             | OK   | OK
 5.12.2 |5.3 TL8 SP8 32 bit   | XL C/C++ V9 + IZ35785   | OK   | OK
 5.12.2 |5.3 TL8 SP8 32 bit   | gcc 4.2.4               | OK   | OK
 5.12.2 |5.3 TL8 SP8 64 bit   | XL C/C++ V9 + IZ35785   | OK   | OK
 5.12.2 |5.3 TL10 SP3 32 bit  | XL C/C++ V11 + Apr 2010 | OK   | OK
 5.12.2 |5.3 TL10 SP3 64 bit  | XL C/C++ V11 + Apr 2010 | OK   | OK
 5.12.2 |6.1 TL1 SP7 32 bit   | XL C/C++ V10            | OK   | OK
 5.12.2 |6.1 TL1 SP7 64 bit   | XL C/C++ V10            | OK   | OK
 5.13   |7.1 TL0 SP1 32 bit   | XL C/C++ V11 + Jul 2010 | OK   | OK
 5.13   |7.1 TL0 SP1 64 bit   | XL C/C++ V11 + Jul 2010 | OK   | OK

 w th   = with thread support
 w/o th = without thread support
 OK     = tested

Successfully tested means that all "make test" runs finish with a
result of 100% OK. All tests were conducted with -Duseshrplib set.

All tests were conducted on the oldest supported AIX technology level
with the latest support package applied. If the tested AIX version is
out of support (AIX 4.3.3, 5.1, 5.2) then the last available support
level was used.

=head2 Building Dynamic Extensions on AIX

Starting from Perl 5.7.2 (and consequently 5.8.x / 5.10.x / 5.12.x)
and AIX 4.3 or newer Perl uses the AIX native dynamic loading interface
in the so called runtime linking mode instead of the emulated interface
that was used in Perl releases 5.6.1 and earlier or, for AIX releases
4.2 and earlier. This change does break backward compatibility with
compiled modules from earlier Perl releases. The change was made to make
Perl more compliant with other applications like Apache/mod_perl which are
using the AIX native interface. This change also enables the use of
C++ code with static constructors and destructors in Perl extensions,
which was not possible using the emulated interface.

It is highly recommended to use the new interface.

=head2 Using Large Files with Perl

Should yield no problems.

=head2 Threaded Perl

Should yield no problems with AIX 5.1 / 5.2 / 5.3 / 6.1 / 7.1.

IBM uses the AIX system Perl (V5.6.0 on AIX 5.1 and V5.8.2 on
AIX 5.2 / 5.3 and 6.1; V5.8.8 on AIX 5.3 TL11 and AIX 6.1 TL4; V5.10.1
on AIX 7.1) for some AIX system scripts. If you switch the links in
/usr/bin from the AIX system Perl (/usr/opt/perl5) to the newly build
Perl then you get the same features as with the IBM AIX system Perl if
the threaded options are used.

The threaded Perl build works also on AIX 5.1 but the IBM Perl
build (Perl v5.6.0) is not threaded on AIX 5.1.

Perl 5.12 an newer is not compatible with the IBM fileset perl.libext.

=head2 64-bit Perl

If your AIX system is installed with 64-bit support, you can expect 64-bit
configurations to work. If you want to use 64-bit Perl on AIX 6.1
you need an APAR for a libc.a bug which affects (n)dbm_XXX functions.
The APAR number for this problem is IZ39077.

If you need more memory (larger data segment) for your Perl programs you
can set:

    /etc/security/limits
    default:                    (or your user)
        data = -1               (default is 262144 * 512 byte)

With the default setting the size is limited to 128MB.
The -1 removes this limit. If the "make test" fails please change
your /etc/security/limits as stated above.

=head2 Long doubles

IBM calls its implementation of long doubles 128-bit, but it is not
the IEEE 128-bit ("quadruple precision") which would give 116 bit of
mantissa (nor it is implemented in hardware), instead it's a special
software implementation called "double-double", which gives 106 bits
of mantissa.

There seem to be various problems in this long double implementation.
If Configure detects this brokenness, it will disable the long double support.
This can be overridden with explicit C<-Duselongdouble> (or C<-Dusemorebits>,
which enables both long doubles and 64 bit integers).  If you decide to
enable long doubles, for most of the broken things Perl has implemented
workarounds, but the handling of the special values infinity and NaN
remains badly broken: for example infinity plus zero results in NaN.

=head2 Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (threaded/32-bit)

With the following options you get a threaded Perl version which
passes all make tests in threaded 32-bit mode, which is the default
configuration for the Perl builds that AIX ships with.

    rm config.sh
    ./Configure \
    -d \
    -Dcc=cc_r \
    -Duseshrplib \
    -Dusethreads \
    -Dprefix=/usr/opt/perl5_32

The -Dprefix option will install Perl in a directory parallel to the
IBM AIX system Perl installation.

=head2 Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (32-bit)

With the following options you get a Perl version which passes
all make tests in 32-bit mode.

    rm config.sh
    ./Configure \
    -d \
    -Dcc=cc_r \
    -Duseshrplib \
    -Dprefix=/usr/opt/perl5_32

The -Dprefix option will install Perl in a directory parallel to the
IBM AIX system Perl installation.

=head2 Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (threaded/64-bit)

With the following options you get a threaded Perl version which
passes all make tests in 64-bit mode.

 export OBJECT_MODE=64 / setenv OBJECT_MODE 64 (depending on your shell)

 rm config.sh
 ./Configure \
 -d \
 -Dcc=cc_r \
 -Duseshrplib \
 -Dusethreads \
 -Duse64bitall \
 -Dprefix=/usr/opt/perl5_64

=head2 Recommended Options AIX 5.1/5.2/5.3/6.1 and 7.1 (64-bit)

With the following options you get a Perl version which passes all
make tests in 64-bit mode.

 export OBJECT_MODE=64 / setenv OBJECT_MODE 64 (depending on your shell)

 rm config.sh
 ./Configure \
 -d \
 -Dcc=cc_r \
 -Duseshrplib \
 -Duse64bitall \
 -Dprefix=/usr/opt/perl5_64

The -Dprefix option will install Perl in a directory parallel to the
IBM AIX system Perl installation.

If you choose gcc to compile 64-bit Perl then you need to add the
following option:

    -Dcc='gcc -maix64'


=head2 Compiling Perl 5 on AIX 7.1.0

A regression in AIX 7 causes a failure in make test in Time::Piece during
daylight savings time.  APAR IV16514 provides the fix for this.  A quick
test to see if it's required, assuming it is currently daylight savings
in Eastern Time, would be to run C< TZ=EST5 date +%Z >.  This will come
back with C<EST> normally, but nothing if you have the problem.


=head2 Compiling Perl 5 on older AIX versions up to 4.3.3

Due to the fact that AIX 4.3.3 reached end-of-service in December 31,
2003 this information is provided as is. The Perl versions prior to
Perl 5.8.9 could be compiled on AIX up to 4.3.3 with the following
settings (your mileage may vary):

When compiling Perl, you must use an ANSI C compiler. AIX does not ship
an ANSI compliant C-compiler with AIX by default, but binary builds of
gcc for AIX are widely available.

At the moment of writing, AIX supports two different native C compilers,
for which you have to pay: B<xlC> and B<vac>. If you decide to use either
of these two (which is quite a lot easier than using gcc), be sure to
upgrade to the latest available patch level. Currently:

    xlC.C     3.1.4.10 or 3.6.6.0 or 4.0.2.2 or 5.0.2.9 or 6.0.0.3
    vac.C     4.4.0.3  or 5.0.2.6 or 6.0.0.1

note that xlC has the OS version in the name as of version 4.0.2.0, so
you will find xlC.C for AIX-5.0 as package

    xlC.aix50.rte   5.0.2.0 or 6.0.0.3

subversions are not the same "latest" on all OS versions. For example,
the latest xlC-5 on aix41 is 5.0.2.9, while on aix43, it is 5.0.2.7.

Perl can be compiled with either IBM'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 IBM compiler-specific command-line flags.

The IBM's compiler patch levels 5.0.0.0 and 5.0.1.0 have compiler
optimization bugs that affect compiling perl.c and regcomp.c,
respectively.  If Perl's configuration detects those compiler patch
levels, optimization is turned off for the said source code files.
Upgrading to at least 5.0.2.0 is recommended.

If you decide to use gcc, make sure your installation is recent and
complete, and be sure to read the Perl INSTALL file for more gcc-specific
details. Please report any hoops you had to jump through to the development
team.

=head2 OS level

Before installing the patches to the IBM C-compiler you need to know the
level of patching for the Operating System. IBM's command 'oslevel' will
show the base, but is not always complete (in this example oslevel shows
4.3.NULL, whereas the system might run most of 4.3.THREE):

    # oslevel
    4.3.0.0
    # lslpp -l | grep 'bos.rte '
    bos.rte           4.3.3.75  COMMITTED  Base Operating System Runtime
    bos.rte            4.3.2.0  COMMITTED  Base Operating System Runtime
    #

The same might happen to AIX 5.1 or other OS levels. As a side note, Perl
cannot be built without bos.adt.syscalls and bos.adt.libm installed

    # lslpp -l | egrep "syscalls|libm"
    bos.adt.libm      5.1.0.25  COMMITTED  Base Application Development
    bos.adt.syscalls  5.1.0.36  COMMITTED  System Calls Application
    #

=head2 Building Dynamic Extensions on AIX E<lt> 5L

AIX supports dynamically loadable objects as well as shared libraries.
Shared libraries by convention end with the suffix .a, which is a bit
misleading, as an archive can contain static as well as dynamic members.
For Perl dynamically loaded objects we use the .so suffix also used on
many other platforms.

Note that starting from Perl 5.7.2 (and consequently 5.8.0) and AIX 4.3
or newer Perl uses the AIX native dynamic loading interface in the so
called runtime linking mode instead of the emulated interface that was
used in Perl releases 5.6.1 and earlier or, for AIX releases 4.2 and
earlier.  This change does break backward compatibility with compiled
modules from earlier Perl releases.  The change was made to make Perl
more compliant with other applications like Apache/mod_perl which are
using the AIX native interface. This change also enables the use of C++
code with static constructors and destructors in Perl extensions, which
was not possible using the emulated interface.

=head2 The IBM ANSI C Compiler

All defaults for Configure can be used.

If you've chosen to use vac 4, be sure to run 4.4.0.3. Older versions
will turn up nasty later on. For vac 5 be sure to run at least 5.0.1.0,
but vac 5.0.2.6 or up is highly recommended. Note that since IBM has
removed vac 5.0.2.1 through 5.0.2.5 from the software depot, these
versions should be considered obsolete.

Here's a brief lead of how to upgrade the compiler to the latest
level.  Of course this is subject to changes.  You can only upgrade
versions from ftp-available updates if the first three digit groups
are the same (in where you can skip intermediate unlike the patches
in the developer snapshots of Perl), or to one version up where the
"base" is available.  In other words, the AIX compiler patches are
cumulative.

 vac.C.4.4.0.1 => vac.C.4.4.0.3  is OK     (vac.C.4.4.0.2 not needed)
 xlC.C.3.1.3.3 => xlC.C.3.1.4.10 is NOT OK (xlC.C.3.1.4.0 is not
                                                              available)

 # ftp ftp.software.ibm.com
 Connected to service.boulder.ibm.com.
 : welcome message ...
 Name (ftp.software.ibm.com:merijn): anonymous
 331 Guest login ok, send your complete e-mail address as password.
 Password:
 ... accepted login stuff
 ftp> cd /aix/fixes/v4/
 ftp> dir other other.ll
 output to local-file: other.ll? y
 200 PORT command successful.
 150 Opening ASCII mode data connection for /bin/ls.
 226 Transfer complete.
 ftp> dir xlc xlc.ll
 output to local-file: xlc.ll? y
 200 PORT command successful.
 150 Opening ASCII mode data connection for /bin/ls.
 226 Transfer complete.
 ftp> bye
 ... goodbye messages
 # ls -l *.ll
 -rw-rw-rw-   1 merijn   system    1169432 Nov  2 17:29 other.ll
 -rw-rw-rw-   1 merijn   system      29170 Nov  2 17:29 xlc.ll

On AIX 4.2 using xlC, we continue:

 # lslpp -l | fgrep 'xlC.C '
   xlC.C                     3.1.4.9  COMMITTED  C for AIX Compiler
   xlC.C                     3.1.4.0  COMMITTED  C for AIX Compiler
 # grep 'xlC.C.3.1.4.*.bff' xlc.ll
 -rw-r--r--   1 45776101 1       6286336 Jul 22 1996  xlC.C.3.1.4.1.bff
 -rw-rw-r--   1 45776101 1       6173696 Aug 24 1998  xlC.C.3.1.4.10.bff
 -rw-r--r--   1 45776101 1       6319104 Aug 14 1996  xlC.C.3.1.4.2.bff
 -rw-r--r--   1 45776101 1       6316032 Oct 21 1996  xlC.C.3.1.4.3.bff
 -rw-r--r--   1 45776101 1       6315008 Dec 20 1996  xlC.C.3.1.4.4.bff
 -rw-rw-r--   1 45776101 1       6178816 Mar 28 1997  xlC.C.3.1.4.5.bff
 -rw-rw-r--   1 45776101 1       6188032 May 22 1997  xlC.C.3.1.4.6.bff
 -rw-rw-r--   1 45776101 1       6191104 Sep  5 1997  xlC.C.3.1.4.7.bff
 -rw-rw-r--   1 45776101 1       6185984 Jan 13 1998  xlC.C.3.1.4.8.bff
 -rw-rw-r--   1 45776101 1       6169600 May 27 1998  xlC.C.3.1.4.9.bff
 # wget ftp://ftp.software.ibm.com/aix/fixes/v4/xlc/xlC.C.3.1.4.10.bff
 #

On AIX 4.3 using vac, we continue:

 # lslpp -l | grep 'vac.C '
  vac.C                      5.0.2.2  COMMITTED  C for AIX Compiler
  vac.C                      5.0.2.0  COMMITTED  C for AIX Compiler
 # grep 'vac.C.5.0.2.*.bff' other.ll
 -rw-rw-r--   1 45776101 1       13592576 Apr 16 2001  vac.C.5.0.2.0.bff
 -rw-rw-r--   1 45776101 1       14133248 Apr  9 2002  vac.C.5.0.2.3.bff
 -rw-rw-r--   1 45776101 1       14173184 May 20 2002  vac.C.5.0.2.4.bff
 -rw-rw-r--   1 45776101 1       14192640 Nov 22 2002  vac.C.5.0.2.6.bff
 # wget ftp://ftp.software.ibm.com/aix/fixes/v4/other/vac.C.5.0.2.6.bff
 #

Likewise on all other OS levels. Then execute the following command, and
fill in its choices

 # smit install_update
  -> Install and Update from LATEST Available Software
  * INPUT device / directory for software [ vac.C.5.0.2.6.bff    ]
  [ OK ]
  [ OK ]

Follow the messages ... and you're done.

If you like a more web-like approach, a good start point can be
L<http://www14.software.ibm.com/webapp/download/downloadaz.jsp> and click
"C for AIX", and follow the instructions.

=head2 The usenm option

If linking miniperl

 cc -o miniperl ... miniperlmain.o opmini.o perl.o ... -lm -lc ...

causes error like this

 ld: 0711-317 ERROR: Undefined symbol: .aintl
 ld: 0711-317 ERROR: Undefined symbol: .copysignl
 ld: 0711-317 ERROR: Undefined symbol: .syscall
 ld: 0711-317 ERROR: Undefined symbol: .eaccess
 ld: 0711-317 ERROR: Undefined symbol: .setresuid
 ld: 0711-317 ERROR: Undefined symbol: .setresgid
 ld: 0711-317 ERROR: Undefined symbol: .setproctitle
 ld: 0711-345 Use the -bloadmap or -bnoquiet option to obtain more
                                                            information.

you could retry with

 make realclean
 rm config.sh
 ./Configure -Dusenm ...

which makes Configure to use the C<nm> tool when scanning for library
symbols, which usually is not done in AIX.

Related to this, you probably should not use the C<-r> option of
Configure in AIX, because that affects of how the C<nm> tool is used.

=head2 Using GNU's gcc for building Perl

Using gcc-3.x (tested with 3.0.4, 3.1, and 3.2) now works out of the box,
as do recent gcc-2.9 builds available directly from IBM as part of their
Linux compatibility packages, available here:

  http://www.ibm.com/servers/aix/products/aixos/linux/

=head2 Using Large Files with Perl E<lt> 5L

Should yield no problems.

=head2 Threaded Perl E<lt> 5L

Threads seem to work OK, though at the moment not all tests pass when
threads are used in combination with 64-bit configurations.

You may get a warning when doing a threaded build:

  "pp_sys.c", line 4640.39: 1506-280 (W) Function argument assignment
  between types "unsigned char*" and "const void*" is not allowed.

The exact line number may vary, but if the warning (W) comes from a line
line this

  hent = PerlSock_gethostbyaddr(addr, (Netdb_hlen_t) addrlen, addrtype);

in the "pp_ghostent" function, you may ignore it safely.  The warning
is caused by the reentrant variant of gethostbyaddr() having a slightly
different prototype than its non-reentrant variant, but the difference
is not really significant here.

=head2 64-bit Perl E<lt> 5L

If your AIX is installed with 64-bit support, you can expect 64-bit
configurations to work. In combination with threads some tests might
still fail.

=head2 AIX 4.2 and extensions using C++ with statics

In AIX 4.2 Perl extensions that use C++ functions that use statics
may have problems in that the statics are not getting initialized.
In newer AIX releases this has been solved by linking Perl with
the libC_r library, but unfortunately in AIX 4.2 the said library
has an obscure bug where the various functions related to time
(such as time() and gettimeofday()) return broken values, and
therefore in AIX 4.2 Perl is not linked against the libC_r.

=head1 AUTHORS

Rainer Tammer <tammer@tammer.net>

=cut

# vim: syntax=pod

If you read this file _as_is_, just ignore the funny characters you
see. It is written in the POD format (see perlpod manpage) which is
specially designed to be readable as is.

=head1 NAME

perlamiga - Perl under AmigaOS 4.1

=head1 NOTE

This is a port of Perl 5.22.1, it is a fresh port and not in any way
compatible with my previous ports of Perl 5.8 and 5.16.3. This means
you will need to reinstall / rebuild any third party modules you have
installed.

newlib.library version 53.28 or greater is required.

=head1 SYNOPSIS

Once perl is installed you can read this document in the following way

	sh -c "perldoc perlamiga"

or you may read I<as is>: either as F<README.amiga>, or F<pod/perlamiga.pod>.

=cut

       NAME
       SYNOPSIS
       DESCRIPTION
         -  Prerequisites
         -  Starting Perl programs under AmigaOS
         -  Shortcomings of Perl under AmigaOS
       INSTALLATION
       CHANGES

=head1 DESCRIPTION

=head2 Prerequisites for running Perl 5.22.1 under AmigaOS 4.1

=over 6

=item B<AmigaOS 4.1 update 6 with all updates applied as of 9th October 2013>

The most important of which is:

=item B<newlib.library version 53.28 or greater>

=item B<AmigaOS SDK>

Perl installs into the SDK directory structure and expects many of the
build tools present in the SDK to be available. So for the best results
install the SDK first.

=item B<abc-shell>

If you do not have the SDK installed you must at least have abc-shell
installed or some other suitable sh port. This is required to run
external commands and should be available as 'sh' in your path.

=back

=head2 Starting Perl programs under AmigaOS 4.1

Perl may be run from the AmigaOS shell but for best results should be
run under abc-shell.  (abc-shell handles file globbing, pattern
expansion, and sets up environment variables in the UN*Xy way that
Perl expects.)

For example:

	New Shell process 10
	10.AmigaOS4:> sh
	/AmigaOS4>perl path:to/myprog arg1 arrg2 arg3

Abc-shell can also launch programs via the #! syntax at the start of
the program file, it's best use the form #!SDK:Local/C/perl so that
the AmigaOS shell may also find perl in the same way. AmigaOS requires
the script bit to be set for this to work

	10.AmigaOS4:> sh
	/AmigaOS4>myprog arg1 arrg2 arg3

=head2 Limitations of Perl under AmigaOS 4.1

=over 6

=item B<Nested Piped programs can crash when run from older abc-shells>

abc-shell version 53.2 has a bug that can cause crashes in the
subprocesses used to run piped programs, if a later version is
available you should install it instead.

=item B<Incorrect or unexpected command line unescaping>

newlib.library 53.30 and earlier incorrectly unescape slashed escape
sequences e.g. \" \n \t etc requiring unusual extra escaping.

=item B<Starting subprocesses via open has limitations>

	open FH, "command |"

Subprocesses started with open use a minimal popen() routine and
therefore they do not return pids usable with waitpid etc.

=item If you find any other limitations or bugs then let me know.

Please report bugs in this version of perl to andy@broad.ology.org.uk
in the first instance.

=back

=head1 INSTALLATION

This guide assumes you have obtained a prebuilt archive from os4depot.net.

Unpack the main archive to a temporary location (RAM: is fine).

Execute the provided install script from shell or via its icon.

You B<must not> attempt to install by hand.

Once installed you may delete the temporary archive.

This approach will preserve links in the installation without creating
duplicate binaries.

If you have the earlier ports perl 5.16 or 5.8 installed you may like
to rename your perl executable to perl516 or perl58 or something
similar before the installation of 5.22.1, this will allow you to use
both versions at the same time.

=head1 Amiga Specific Modules

=head2 Amiga::ARexx

The Amiga::ARexx module allows you to easily create a perl based ARexx
host or to send ARexx commands to other programs.

Try C<perldoc Amiga::ARexx> for more info.

=head2 Amiga::Exec

The Amiga::Exec module introduces support for Wait().

Try C<perldoc Amiga::Exec> for more info.

=head1 BUILDING

To build perl under AmigaOS from the patched sources you will need to
have a recent version of the SDK. Version 53.29 is recommended,
earlier versions will probably work too.

With the help of Jarkko Hietaniemi the Configure system has been tweaked to
run under abc-shell so the recommend build process is as follows.

	stack 2000000
	sh Configure -de
	gmake

This will build the default setup that installs under SDK:local/newlib/lib/

=head1 CHANGES

=over 6

=item B<August 2015>

=over 2

=item Port to Perl 5.22

=item Add handling of NIL: to afstat()

=item Fix inheritance of environment variables by subprocesses.

=item Fix exec, and exit in "forked" subprocesses.

=item Fix issue with newlib's unlink, which could cause infinite loops.

=item Add flock() emulation using IDOS->LockRecord thanks to Tony Cook
for the suggestion.

=item Fix issue where kill was using the wrong kind of process ID

=back

=item B<27th November 2013>

=over 2

=item Create new installation system based on installperl links
and Amiga protection bits now set correctly.

=item Pod now defaults to text.

=item File::Spec should now recognise an Amiga style absolute path as well
as an Unix style one. Relative paths must always be Unix style.

=back

=item B<20th November 2013>

=over 2

=item Configured to use SDK:Local/C/perl to start standard scripts

=item Added Amiga::Exec module with support for Wait() and AmigaOS signal numbers.

=back

=item B<10th October 13>

First release of port to 5.16.3.

=back

=head1 SEE ALSO

You like this port?  See L<http://www.broad.ology.org.uk/amiga/>
for how you can help.

=cut

# vim: syntax=pod

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

perlandroid - Perl under Android

=head1 SYNOPSIS

The first portions of this document contains instructions
to cross-compile Perl for Android 2.0 and later, using the
binaries provided by Google.  The latter portions describe how to build
perl native using one of the toolchains available on the Play Store.

=head1 DESCRIPTION

This document describes how to set up your host environment when
attempting to build Perl for Android.

=head1 Cross-compilation

These instructions assume an Unixish build environment on your host system;
they've been tested on Linux and OS X, and may work on Cygwin and MSYS.
While Google also provides an NDK for Windows, these steps won't work
native there, although it may be possible to cross-compile through different
means.

If your host system's architecture is 32 bits, remember to change the
C<x86_64>'s below to C<x86>'s.  On a similar vein, the examples below
use the 4.8 toolchain; if you want to use something older or newer (for
example, the 4.4.3 toolchain included in the 8th revision of the NDK), just
change those to the relevant version.

=head2 Get the Android Native Development Kit (NDK)

You can download the NDK from L<https://developer.android.com/tools/sdk/ndk/index.html>.
You'll want the normal, non-legacy version.

=head2 Determine the architecture you'll be cross-compiling for

There's three possible options: arm-linux-androideabi for ARM,
mipsel-linux-android for MIPS, and simply x86 for x86.
As of 2014, most Android devices run on ARM, so that is generally a safe bet.

With those two in hand, you should add

  $ANDROID_NDK/toolchains/$TARGETARCH-4.8/prebuilt/`uname | tr '[A-Z]' '[a-z]'`-x86_64/bin

to your C<PATH>, where C<$ANDROID_NDK> is the location where you unpacked the
NDK, and C<$TARGETARCH> is your target's architecture.

=head2 Set up a standalone toolchain

This creates a working sysroot that we can feed to Configure later.

    $ export ANDROID_TOOLCHAIN=/tmp/my-toolchain-$TARGETARCH
    $ export SYSROOT=$ANDROID_TOOLCHAIN/sysroot
    $ $ANDROID_NDK/build/tools/make-standalone-toolchain.sh \
            --platform=android-9 \
            --install-dir=$ANDROID_TOOLCHAIN \
            --system=`uname | tr '[A-Z]' '[a-z]'`-x86_64 \
            --toolchain=$TARGETARCH-4.8

=head2 adb or ssh?

adb is the Android Debug Bridge.  For our purposes, it's basically a way
of establishing an ssh connection to an Android device without having to
install anything on the device itself, as long as the device is either on
the same local network as the host, or it is connected to the host through
USB.

Perl can be cross-compiled using either adb or a normal ssh connection;
in general, if you can connect your device to the host using a USB port,
or if you don't feel like installing an sshd app on your device,
you may want to use adb, although you may be forced to switch to ssh if
your device is not rooted and you're unlucky -- more on that later.
Alternatively, if you're cross-compiling to an emulator, you'll have to
use adb.

=head3 adb

To use adb, download the Android SDK from L<https://developer.android.com/sdk/index.html>.
The "SDK Tools Only" version should suffice -- if you downloaded the ADT
Bundle, you can find the sdk under F<$ADT_BUNDLE/sdk/>.

Add F<$ANDROID_SDK/platform-tools> to your C<PATH>, which should give you access
to adb.  You'll now have to find your device's name using C<adb devices>,
and later pass that to Configure through C<-Dtargethost=$DEVICE>.

However, before calling Configure, you need to check if using adb is a
viable choice in the first place.  Because Android doesn't have a F</tmp>,
nor does it allow executables in the sdcard, we need to find somewhere in
the device for Configure to put some files in, as well as for the tests
to run in. If your device is rooted, then you're good.  Try running these:

    $ export TARGETDIR=/mnt/asec/perl
    $ adb -s $DEVICE shell "echo sh -c '\"mkdir $TARGETDIR\"' | su --"

Which will create the directory we need, and you can move on to the next
step.  F</mnt/asec> is mounted as a tmpfs in Android, but it's only
accessible to root.

If your device is not rooted, you may still be in luck. Try running this:

    $ export TARGETDIR=/data/local/tmp/perl
    $ adb -s $DEVICE shell "mkdir $TARGETDIR"

If the command works, you can move to the next step, but beware:
B<You'll have to remove the directory from the device once you are done!
Unlike F</mnt/asec>, F</data/local/tmp> may not get automatically garbage
collected once you shut off the phone>.

If neither of those work, then you can't use adb to cross-compile to your
device.  Either try rooting it, or go for the ssh route.

=head3 ssh

To use ssh, you'll need to install and run a sshd app and set it up
properly.  There are several paid and free apps that do this rather
easily, so you should be able to spot one on the store.
Remember that Perl requires a passwordless connection, so set up a
public key.

Note that several apps spew crap to stderr every time you
connect, which can throw off Configure.  You may need to monkeypatch
the part of Configure that creates C<run-ssh> to have it discard stderr.

Since you're using ssh, you'll have to pass some extra arguments to
Configure:

  -Dtargetrun=ssh -Dtargethost=$TARGETHOST -Dtargetuser=$TARGETUSER -Dtargetport=$TARGETPORT

=head2 Configure and beyond

With all of the previous done, you're now ready to call Configure.

If using adb, a "basic" Configure line will look like this:

  $ ./Configure -des -Dusedevel -Dusecrosscompile -Dtargetrun=adb \
      -Dcc=$TARGETARCH-gcc   \
      -Dsysroot=$SYSROOT     \
      -Dtargetdir=$TARGETDIR \
      -Dtargethost=$DEVICE

If using ssh, it's not too different -- we just change targetrun to ssh,
and pass in targetuser and targetport.  It ends up looking like this:

  $ ./Configure -des -Dusedevel -Dusecrosscompile -Dtargetrun=ssh \
      -Dcc=$TARGETARCH-gcc        \
      -Dsysroot=$SYSROOT          \
      -Dtargetdir=$TARGETDIR      \
      -Dtargethost="$TARGETHOST"  \
      -Dtargetuser=$TARGETUSER    \
      -Dtargetport=$TARGETPORT

Now you're ready to run C<make> and C<make test>!

As a final word of warning, if you're using adb, C<make test> may appear to
hang; this is because it doesn't output anything until it finishes
running all tests.  You can check its progress by logging into the
device, moving to F<$TARGETDIR>, and looking at the file F<output.stdout>.

=head3 Notes

=over

=item *

If you are targetting x86 Android, you will have to change C<$TARGETARCH-gcc>
to C<i686-linux-android-gcc>.

=item *

On some older low-end devices -- think early 2.2 era -- some tests,
particularly F<t/re/uniprops.t>, may crash the phone, causing it to turn
itself off once, and then back on again.

=back

=head1 Native Builds

While Google doesn't provide a native toolchain for Android,
you can still get one from the Play Store.

=head2 CCTools

You may be able to get the CCTools app, which is free.
Keep in mind that you want a full toolchain;
some apps tend to default to installing only a barebones
version without some important utilities, like ar or nm.

Once you have the toolchain set up properly, the only
remaining hurdle is actually locating where in the device it was installed
in.  For example, CCTools installs its toolchain in
F</data/data/com.pdaxrom.cctools/root/cctools>.  With the path in hand,
compiling perl is little more than:

 export SYSROOT=<location of the native toolchain>
 export LD_LIBRARY_PATH="$SYSROOT/lib:`pwd`:`pwd`/lib:`pwd`/lib/auto:$LD_LIBRARY_PATH"
 sh Configure -des -Dsysroot=$SYSROOT -Alibpth="/system/lib /vendor/lib"

=head2 Termux

L<Termux|https://termux.com/> provides an Android terminal emulator and Linux environment.
It comes with a cross-compiled perl already installed.

Natively compiling perl 5.30 or later should be as straightforward as:

 sh Configure -des -Alibpth="/system/lib /vendor/lib"

This certainly works on Android 8.1 (Oreo) at least...

=head1 AUTHOR

Brian Fraser <fraserbn@gmail.com>

=cut

# vim: syntax=pod

This document is written in pod format hence there are punctuation
characters in odd places.  Do not worry, you've apparently got the
ASCII->EBCDIC translation worked out correctly.  You can read more
about pod in pod/perlpod.pod or the short summary in the INSTALL file.

=head1 NAME

perlbs2000 - building and installing Perl for BS2000.

B<This document needs to be updated, but we don't know what it should say.
Please submit comments to L<https://github.com/Perl/perl5/issues>.>

=head1 SYNOPSIS

This document will help you Configure, build, test and install Perl
on BS2000 in the POSIX subsystem.

=head1 DESCRIPTION

This is a ported perl for the POSIX subsystem in BS2000 VERSION OSD
V3.1A or later.  It may work on other versions, but we started porting
and testing it with 3.1A and are currently using Version V4.0A.

You may need the following GNU programs in order to install perl:

=head2 gzip on BS2000

We used version 1.2.4, which could be installed out of the box with
one failure during 'make check'.

=head2 bison on BS2000

The yacc coming with BS2000 POSIX didn't work for us.  So we had to
use bison.  We had to make a few changes to perl in order to use the
pure (reentrant) parser of bison.  We used version 1.25, but we had to
add a few changes due to EBCDIC.  See below for more details
concerning yacc.

=head2 Unpacking Perl Distribution on BS2000

To extract an ASCII tar archive on BS2000 POSIX you need an ASCII
filesystem (we used the mountpoint /usr/local/ascii for this).  Now
you extract the archive in the ASCII filesystem without
I/O-conversion:

cd /usr/local/ascii
export IO_CONVERSION=NO
gunzip < /usr/local/src/perl.tar.gz | pax -r

You may ignore the error message for the first element of the archive
(this doesn't look like a tar archive / skipping to next file...),
it's only the directory which will be created automatically anyway.

After extracting the archive you copy the whole directory tree to your
EBCDIC filesystem.  B<This time you use I/O-conversion>:

cd /usr/local/src
IO_CONVERSION=YES
cp -r /usr/local/ascii/perl5.005_02 ./

=head2 Compiling Perl on BS2000

There is a "hints" file for BS2000 called hints.posix-bc (because
posix-bc is the OS name given by `uname`) that specifies the correct
values for most things.  The major problem is (of course) the EBCDIC
character set.  We have german EBCDIC version.

Because of our problems with the native yacc we used GNU bison to
generate a pure (=reentrant) parser for perly.y.  So our yacc is
really the following script:

-----8<-----/usr/local/bin/yacc-----8<-----
#! /usr/bin/sh

# Bison as a reentrant yacc:

# save parameters:
params=""
while [[ $# -gt 1 ]]; do
    params="$params $1"
    shift
done

# add flag %pure_parser:

tmpfile=/tmp/bison.$$.y
echo %pure_parser > $tmpfile
cat $1 >> $tmpfile

# call bison:

echo "/usr/local/bin/bison --yacc $params $1\t\t\t(Pure Parser)"
/usr/local/bin/bison --yacc $params $tmpfile

# cleanup:

rm -f $tmpfile
-----8<----------8<-----

We still use the normal yacc for a2p.y though!!!  We made a softlink
called byacc to distinguish between the two versions:

ln -s /usr/bin/yacc /usr/local/bin/byacc

We build perl using GNU make.  We tried the native make once and it
worked too.

=head2 Testing Perl on BS2000

We still got a few errors during C<make test>.  Some of them are the
result of using bison.  Bison prints I<parser error> instead of I<syntax
error>, so we may ignore them.  The following list shows
our errors, your results may differ:

op/numconvert.......FAILED tests 1409-1440
op/regexp...........FAILED tests 483, 496
op/regexp_noamp.....FAILED tests 483, 496
pragma/overload.....FAILED tests 152-153, 170-171
pragma/warnings.....FAILED tests 14, 82, 129, 155, 192, 205, 207
lib/bigfloat........FAILED tests 351-352, 355
lib/bigfltpm........FAILED tests 354-355, 358
lib/complex.........FAILED tests 267, 487
lib/dumper..........FAILED tests 43, 45
Failed 11/231 test scripts, 95.24% okay. 57/10595 subtests failed, 99.46% okay.

=head2 Installing Perl on BS2000

We have no nroff on BS2000 POSIX (yet), so we ignored any errors while
installing the documentation.


=head2 Using Perl in the Posix-Shell of BS2000

BS2000 POSIX doesn't support the shebang notation
(C<#!/usr/local/bin/perl>), so you have to use the following lines
instead:

: # use perl
    eval 'exec /usr/local/bin/perl -S $0 ${1+"$@"}'
        if 0; # ^ Run only under a shell

=head2 Using Perl in "native" BS2000

We don't have much experience with this yet, but try the following:

Copy your Perl executable to a BS2000 LLM using bs2cp:

C<bs2cp /usr/local/bin/perl 'bs2:perl(perl,l)'>

Now you can start it with the following (SDF) command:

C</START-PROG FROM-FILE=*MODULE(PERL,PERL),PROG-MODE=*ANY,RUN-MODE=*ADV>

First you get the BS2000 commandline prompt ('*').  Here you may enter
your parameters, e.g. C<-e 'print "Hello World!\\n";'> (note the
double backslash!) or C<-w> and the name of your Perl script.
Filenames starting with C</> are searched in the Posix filesystem,
others are searched in the BS2000 filesystem.  You may even use
wildcards if you put a C<%> in front of your filename (e.g. C<-w
checkfiles.pl %*.c>).  Read your C/C++ manual for additional
possibilities of the commandline prompt (look for
PARAMETER-PROMPTING).

=head2 Floating point anomalies on BS2000

There appears to be a bug in the floating point implementation on BS2000 POSIX
systems such that calling int() on the product of a number and a small
magnitude number is not the same as calling int() on the quotient of
that number and a large magnitude number.  For example, in the following
Perl code:

    my $x = 100000.0;
    my $y = int($x * 1e-5) * 1e5; # '0'
    my $z = int($x / 1e+5) * 1e5;  # '100000'
    print "\$y is $y and \$z is $z\n"; # $y is 0 and $z is 100000

Although one would expect the quantities $y and $z to be the same and equal
to 100000 they will differ and instead will be 0 and 100000 respectively.

=head2 Using PerlIO and different encodings on ASCII and EBCDIC partitions

Since version 5.8 Perl uses the new PerlIO on BS2000.  This enables
you using different encodings per IO channel.  For example you may use

    use Encode;
    open($f, ">:encoding(ascii)", "test.ascii");
    print $f "Hello World!\n";
    open($f, ">:encoding(posix-bc)", "test.ebcdic");
    print $f "Hello World!\n";
    open($f, ">:encoding(latin1)", "test.latin1");
    print $f "Hello World!\n";
    open($f, ">:encoding(utf8)", "test.utf8");
    print $f "Hello World!\n";

to get two files containing "Hello World!\n" in ASCII, EBCDIC, ISO
Latin-1 (in this example identical to ASCII) respective UTF-EBCDIC (in
this example identical to normal EBCDIC).  See the documentation of
Encode::PerlIO for details.

As the PerlIO layer uses raw IO internally, all this totally ignores
the type of your filesystem (ASCII or EBCDIC) and the IO_CONVERSION
environment variable.  If you want to get the old behavior, that the
BS2000 IO functions determine conversion depending on the filesystem
PerlIO still is your friend.  You use IO_CONVERSION as usual and tell
Perl, that it should use the native IO layer:

    export IO_CONVERSION=YES
    export PERLIO=stdio

Now your IO would be ASCII on ASCII partitions and EBCDIC on EBCDIC
partitions.  See the documentation of PerlIO (without C<Encode::>!)
for further possibilities.

=head1 AUTHORS

Thomas Dorner

=head1 SEE ALSO

L<INSTALL>, L<perlport>.

=head2 Mailing list

If you are interested in the z/OS (formerly known as OS/390)
and POSIX-BC (BS2000) ports of Perl then see the perl-mvs mailing list.
To subscribe, send an empty message to perl-mvs-subscribe@perl.org.

See also:

    https://lists.perl.org/list/perl-mvs.html

There are web archives of the mailing list at:

    https://www.nntp.perl.org/group/perl.mvs/

=head1 HISTORY

This document was originally written by Thomas Dorner for the 5.005
release of Perl.

This document was podified for the 5.6 release of perl 11 July 2000.

=cut

# vim: syntax=pod

如果你用一般的文字编辑器阅览这份文件, 请忽略文中奇特的注记字符.
这份文件是以 POD (简明文件格式) 写成; 这种格式是为了能让人直接阅读,
而特别设计的. 关于此格式的进一步信息, 请参考 perlpod 在线文档.

=encoding utf8

=head1 NAME

perlcn - 简体中文 Perl 指南

=head1 DESCRIPTION

欢迎来到 Perl 的天地!

从 5.8.0 版开始, Perl 具备了完善的 Unicode (统一码) 支持,
也连带支持了许多拉丁语系以外的编码方式; CJK (中日韩) 便是其中的一部分.
Unicode 是国际性的标准, 试图涵盖世界上所有的字符: 西方世界, 东方世界,
以及两者间的一切 (希腊文, 叙利亚文, 阿拉伯文, 希伯来文, 印度文,
印地安文, 等等). 它也容纳了多种操作系统与平台 (如 PC 及麦金塔).

Perl 本身以 Unicode 进行操作. 这表示 Perl 内部的字符串数据可用 Unicode
表示; Perl 的函数与运算符 (例如正则表达式匹配) 也能对 Unicode 进行操作.
在输入及输出时, 为了处理以 Unicode 之前的编码方式储存的数据, Perl
提供了 Encode 这个模块, 可以让你轻易地读写使用旧有的编码格式的数据.

Encode 扩展模块支持下列简体中文的编码方式 ('gb2312' 表示 'euc-cn'):

    euc-cn	Unix 扩展字符集, 也就是俗称的国标码
    gb2312-raw	未经处理的 (低比特) GB2312 字符表
    gb12345	未经处理的中国用繁体中文编码
    iso-ir-165	GB2312 + GB6345 + GB8565 + 新增字符
    cp936	字码页 936, 也可以用 'GBK' (扩充国标码) 指明
    hz		7 比特逸出式 GB2312 编码

举例来说, 将 EUC-CN 编码的文件转成 Unicode, 只需输入以下命令:

    perl -Mencoding=euc-cn,STDOUT,utf8 -pe1 < file.euc-cn > file.utf8

Perl 也内附了 "piconv", 一个完全以 Perl 写成的字符转换工具程序, 用法如下:

    piconv -f euc-cn -t utf8 < file.euc-cn > file.utf8
    piconv -f utf8 -t euc-cn < file.utf8 > file.euc-cn

另外, 利用 encoding 模块, 你可以轻易写出以字符为单位的代码, 如下所示:

    #!/usr/bin/env perl
    # 启动 euc-cn 字串解析; 标准输出入及标准错误都设为 euc-cn 编码
    use encoding 'euc-cn', STDIN => 'euc-cn', STDOUT => 'euc-cn';
    print length("骆驼");	     #  2 (双引号表示字符)
    print length('骆驼');	     #  4 (单引号表示字节)
    print index("谆谆教诲", "蛔唤"); # -1 (不包含此子字符串)
    print index('谆谆教诲', '蛔唤'); #  1 (从第二个字节开始)

在最后一列例子里, "谆" 的第二个字节与 "谆" 的第一个字节结合成 EUC-CN
码的 "蛔"; "谆" 的第二个字节则与 "教" 的第一个字节结合成 "唤".
这解决了以前 EUC-CN 码匹配处理上常见的问题.

=head2 额外的中文编码

如果需要更多的中文编码, 可以从 CPAN (L<https://www.cpan.org/>) 下载
Encode::HanExtra 模块. 它目前提供下列编码方式:

    gb18030	扩充过的国标码, 包含繁体中文

另外, Encode::HanConvert 模块则提供了简繁转换用的两种编码:

    big5-simp	Big5 繁体中文与 Unicode 简体中文互转
    gbk-trad	GBK 简体中文与 Unicode 繁体中文互转

若想在 GBK 与 Big5 之间互转, 请参考该模块内附的 b2g.pl 与 g2b.pl 两个程序,
或在程序内使用下列写法:

    use Encode::HanConvert;
    $euc_cn = big5_to_gb($big5); # 从 Big5 转为 GBK
    $big5 = gb_to_big5($euc_cn); # 从 GBK 转为 Big5

=head2 进一步的信息

请参考 Perl 内附的大量说明文件 (不幸全是用英文写的), 来学习更多关于
Perl 的知识, 以及 Unicode 的使用方式. 不过, 外部的资源相当丰富:

=head2 提供 Perl 资源的网址

=over 4

=item L<https://www.perl.org/>

=back

Perl 的首页

=over 4

=item L<https://www.perl.com/>

由 Perl 基金会运营的文章辑录

=item L<https://www.cpan.org/>

Perl 综合典藏网 (Comprehensive Perl Archive Network)

=item L<https://lists.perl.org/>

Perl 邮递论坛一览

=back

=head2 学习 Perl 的网址

=over 4

=item L<http://www.oreilly.com.cn/index.php?func=booklist&cat=68>

简体中文版的欧莱礼 Perl 书藉

=back

=head2 Perl 使用者集会

=over 4

=item L<https://www.pm.org/groups/asia.html>

中国 Perl 推广组一览

=back

=head2 Unicode 相关网址

=over 4

=item L<https://www.unicode.org/>

Unicode 学术学会 (Unicode 标准的制定者)

=item L<https://www.cl.cam.ac.uk/%7Emgk25/unicode.html>

Unix/Linux 上的 UTF-8 及 Unicode 常见问题解答

=back

=head1 SEE ALSO

L<Encode>, L<Encode::CN>, L<encoding>, L<perluniintro>, L<perlunicode>

=head1 AUTHORS

Jarkko Hietaniemi E<lt>jhi@iki.fiE<gt>

Audrey Tang (唐凤) E<lt>audreyt@audreyt.orgE<gt>

Sizhe Zhao E<lt>prc.zhao@outlook.comE<gt>

=cut

# vim: syntax=pod

If you read this file _as_is_, just ignore the funny characters you
see. It is written in the POD format (see F<pod/perlpod.pod>) which is
specially designed to be readable as is.

=head1 NAME

perlcygwin - Perl for Cygwin

=head1 SYNOPSIS

This document will help you configure, make, test and install Perl
on Cygwin.  This document also describes features of Cygwin that will
affect how Perl behaves at runtime.

B<NOTE:> There are pre-built Perl packages available for Cygwin and a
version of Perl is provided in the normal Cygwin install.  If you do
not need to customize the configuration, consider using one of those
packages.


=head1 PREREQUISITES FOR COMPILING PERL ON CYGWIN

=head2 Cygwin = GNU+Cygnus+Windows (Don't leave UNIX without it)

The Cygwin tools are ports of the popular GNU development tools for Win32
platforms.  They run thanks to the Cygwin library which provides the UNIX
system calls and environment these programs expect.  More information
about this project can be found at:

L<https://www.cygwin.com/>

A recent net or commercial release of Cygwin is required.

At the time this document was last updated, Cygwin 3.0.7 was current.


=head2 Cygwin Configuration

While building Perl some changes may be necessary to your Cygwin setup so
that Perl builds cleanly.  These changes are B<not> required for normal
Perl usage.

B<NOTE:> The binaries that are built will run on all Win32 versions.
They do not depend on your host system or your
Cygwin configuration (binary/text mounts, cygserver).
The only dependencies come from hard-coded pathnames like F</usr/local>.
However, your host system and Cygwin configuration will affect Perl's
runtime behavior (see L</"TEST">).

=over 4

=item * C<PATH>

Set the C<PATH> environment variable so that Configure finds the Cygwin
versions of programs. Any not-needed Windows directories should be removed or
moved to the end of your C<PATH>.

=item * I<nroff>

If you do not have I<nroff> (which is part of the I<groff> package),
Configure will B<not> prompt you to install I<man> pages.

=back

=head1 CONFIGURE PERL ON CYGWIN

The default options gathered by Configure with the assistance of
F<hints/cygwin.sh> will build a Perl that supports dynamic loading
(which requires a shared F<cygperl5_16.dll>).

This will run Configure and keep a record:

  ./Configure 2>&1 | tee log.configure

If you are willing to accept all the defaults run Configure with B<-de>.
However, several useful customizations are available.

=head2 Stripping Perl Binaries on Cygwin

It is possible to strip the EXEs and DLLs created by the build process.
The resulting binaries will be significantly smaller.  If you want the
binaries to be stripped, you can either add a B<-s> option when Configure
prompts you,

  Any additional ld flags (NOT including libraries)? [none] -s
  Any special flags to pass to g++ to create a dynamically loaded
  library?
  [none] -s
  Any special flags to pass to gcc to use dynamic linking? [none] -s

or you can edit F<hints/cygwin.sh> and uncomment the relevant variables
near the end of the file.

=head2 Optional Libraries for Perl on Cygwin

Several Perl functions and modules depend on the existence of
some optional libraries.  Configure will find them if they are
installed in one of the directories listed as being used for library
searches.  Pre-built packages for most of these are available from
the Cygwin installer.

=over 4

=item * C<-lcrypt>

The crypt package distributed with Cygwin is a Linux compatible 56-bit
DES crypt port by Corinna Vinschen.

Alternatively, the crypt libraries in GNU libc have been ported to Cygwin.

As of libcrypt 1.3 (March 2016), you will need to install the
libcrypt-devel package for Configure to detect crypt().

=item * C<-lgdbm_compat> (C<use GDBM_File>)

GDBM is available for Cygwin.

NOTE: The GDBM library only works on NTFS partitions.

=item * C<-ldb> (C<use DB_File>)

BerkeleyDB is available for Cygwin.

NOTE: The BerkeleyDB library only completely works on NTFS partitions.

=item * C<cygserver> (C<use IPC::SysV>)

A port of SysV IPC is available for Cygwin.

NOTE: This has B<not> been extensively tested.  In particular,
C<d_semctl_semun> is undefined because it fails a Configure test.  It
also creates a compile time dependency because F<perl.h> includes
F<<sys/ipc.h>> and F<<sys/sem.h>> (which will be required in the
future when compiling CPAN modules). CURRENTLY NOT SUPPORTED!

=item * C<-lutil>

Included with the standard Cygwin netrelease is the inetutils package
which includes libutil.a.

=back

=head2 Configure-time Options for Perl on Cygwin

The F<INSTALL> document describes several Configure-time options.  Some of
these will work with Cygwin, others are not yet possible.  Also, some of
these are experimental.  You can either select an option when Configure
prompts you or you can define (undefine) symbols on the command line.

=over 4

=item * C<-Uusedl>

Undefining this symbol forces Perl to be compiled statically.

=item * C<-Dusemymalloc>

By default Perl does not use the C<malloc()> included with the Perl source,
because it was slower and not entirely thread-safe.  If you want to force
Perl to build with the old -Dusemymalloc define this.

=item * C<-Uuseperlio>

Undefining this symbol disables the PerlIO abstraction.  PerlIO is now the
default; it is not recommended to disable PerlIO.

=item * C<-Dusemultiplicity>

Multiplicity is required when embedding Perl in a C program and using
more than one interpreter instance.  This is only required when you build
a not-threaded perl with C<-Uuseithreads>.

=item * C<-Uuse64bitint>

By default Perl uses 64 bit integers.  If you want to use smaller 32 bit
integers, define this symbol.

=item * C<-Duselongdouble>

I<gcc> supports long doubles (12 bytes).  However, several additional
long double math functions are necessary to use them within Perl
(I<{atan2, cos, exp, floor, fmod, frexp, isnan, log, modf, pow, sin, sqrt}l,
strtold>).
These are B<not> yet available with newlib, the Cygwin libc.

=item * C<-Uuseithreads>

Define this symbol if you want not-threaded faster perl.

=item * C<-Duselargefiles>

Cygwin uses 64-bit integers for internal size and position calculations,
this will be correctly detected and defined by Configure.

=item * C<-Dmksymlinks>

Use this to build perl outside of the source tree.  Details can be
found in the F<INSTALL> document.  This is the recommended way to
build perl from sources.

=back

=head1 MAKE ON CYGWIN

Simply run I<make> and wait:

  make -jn 2>&1 | tee log.make

where I<n> is the maximum number of simultaneous compilations you want;
omitting this parameter is the same as specifying C<-j1>.

=head1 TEST ON CYGWIN

There are two steps to running the test suite:

  make test 2>&1 | tee log.make-test

  cd t; ./perl harness 2>&1 | tee ../log.harness

The same tests are run both times, but more information is provided when
running as C<./perl harness>, and you can run the tests in parallel by
instead specifying

  cd t; TEST_JOBS=n ./perl harness 2>&1 | tee ../log.harness

where I<n> is the maximum number of tests to run simulataneously.

Test results vary depending on your host system and your Cygwin
configuration.  If a test can pass in some Cygwin setup, it is always
attempted and explainable test failures are documented.  It is possible
for Perl to pass all the tests, but it is more likely that some tests
will fail for one of the reasons listed below.

=head2 File Permissions on Cygwin

UNIX file permissions are based on sets of mode bits for
{read,write,execute} for each {user,group,other}.  By default Cygwin
only tracks the Win32 read-only attribute represented as the UNIX file
user write bit (files are always readable, files are executable if they
have a F<.{com,bat,exe}> extension or begin with C<#!>, directories are
always readable and executable).  On WinNT with the I<ntea> C<CYGWIN>
setting, the additional mode bits are stored as extended file attributes.
On WinNT with the default I<ntsec> C<CYGWIN> setting, permissions use the
standard WinNT security descriptors and access control lists. Without one of
these options, these tests will fail (listing not updated yet):

  Failed Test           List of failed
  ------------------------------------
  io/fs.t               5, 7, 9-10
  lib/anydbm.t          2
  lib/db-btree.t        20
  lib/db-hash.t         16
  lib/db-recno.t        18
  lib/gdbm.t            2
  lib/ndbm.t            2
  lib/odbm.t            2
  lib/sdbm.t            2
  op/stat.t             9, 20 (.tmp not an executable extension)

=head2 NDBM_File and ODBM_File do not work on FAT filesystems

Do not use NDBM_File or ODBM_File on FAT filesystem.  They can be
built on a FAT filesystem, but many tests will fail:

 ../ext/NDBM_File/ndbm.t       13  3328    71   59  83.10%  1-2 4 16-71
 ../ext/ODBM_File/odbm.t      255 65280    ??   ??       %  ??
 ../lib/AnyDBM_File.t           2   512    12    2  16.67%  1 4
 ../lib/Memoize/t/errors.t      0   139    11    5  45.45%  7-11
 ../lib/Memoize/t/tie_ndbm.t   13  3328     4    4 100.00%  1-4
 run/fresh_perl.t                          97    1   1.03%  91

If you intend to run only on FAT (or if using AnyDBM_File on FAT),
run Configure with the -Ui_ndbm and -Ui_dbm options to prevent
NDBM_File and ODBM_File being built.

With NTFS (and no CYGWIN=nontsec), there should be no problems even if
perl was built on FAT.

=head2 C<fork()> failures in io_* tests

A C<fork()> failure may result in the following tests failing:

  ext/IO/lib/IO/t/io_multihomed.t
  ext/IO/lib/IO/t/io_sock.t
  ext/IO/lib/IO/t/io_unix.t

See comment on fork in L</Miscellaneous> below.

=head1 Specific features of the Cygwin port

=head2 Script Portability on Cygwin

Cygwin does an outstanding job of providing UNIX-like semantics on top of
Win32 systems.  However, in addition to the items noted above, there are
some differences that you should know about.  This is a very brief guide
to portability, more information can be found in the Cygwin documentation.

=over 4

=item * Pathnames

Cygwin pathnames are separated by forward (F</>) slashes, Universal
Naming Codes (F<//UNC>) are also supported.  Since cygwin-1.7 non-POSIX
pathnames should not be used.  Names may contain all printable
characters.

File names are case insensitive, but case preserving.  A pathname that
contains a backslash or drive letter is a Win32 pathname, and not
subject to the translations applied to POSIX style pathnames, but
cygwin will warn you, so better convert them to POSIX.

For conversion we have C<Cygwin::win_to_posix_path()> and
C<Cygwin::posix_to_win_path()>.

Since cygwin-1.7 pathnames are UTF-8 encoded.

=item * Text/Binary

Since cygwin-1.7 textmounts are deprecated and strongly discouraged.

When a file is opened it is in either text or binary mode.  In text mode
a file is subject to CR/LF/Ctrl-Z translations.  With Cygwin, the default
mode for an C<open()> is determined by the mode of the mount that underlies
the file. See L</Cygwin::is_binmount>(). Perl provides a C<binmode()> function
to set binary mode on files that otherwise would be treated as text.
C<sysopen()> with the C<O_TEXT> flag sets text mode on files that otherwise
would be treated as binary:

    sysopen(FOO, "bar", O_WRONLY|O_CREAT|O_TEXT)

C<lseek()>, C<tell()> and C<sysseek()> only work with files opened in binary
mode.

The text/binary issue is covered at length in the Cygwin documentation.

=item * PerlIO

PerlIO overrides the default Cygwin Text/Binary behaviour.  A file will
always be treated as binary, regardless of the mode of the mount it lives
on, just like it is in UNIX.  So CR/LF translation needs to be requested in
either the C<open()> call like this:

  open(FH, ">:crlf", "out.txt");

which will do conversion from LF to CR/LF on the output, or in the
environment settings (add this to your .bashrc):

  export PERLIO=crlf

which will pull in the crlf PerlIO layer which does LF -> CRLF conversion
on every output generated by perl.

=item * F<.exe>

The Cygwin C<stat()>, C<lstat()> and C<readlink()> functions make the F<.exe>
extension transparent by looking for F<foo.exe> when you ask for F<foo>
(unless a F<foo> also exists).  Cygwin does not require a F<.exe>
extension, but I<gcc> adds it automatically when building a program.
However, when accessing an executable as a normal file (e.g., I<cp>
in a makefile) the F<.exe> is not transparent.  The I<install> program
included with Cygwin automatically appends a F<.exe> when necessary.

=item * Cygwin vs. Windows process ids

Cygwin processes have their own pid, which is different from the
underlying windows pid.  Most posix compliant Proc functions expect
the cygwin pid, but several Win32::Process functions expect the
winpid. E.g. C<$$> is the cygwin pid of F</usr/bin/perl>, which is not
the winpid.  Use C<Cygwin::pid_to_winpid()> and C<Cygwin::winpid_to_pid()>
to translate between them.

=item * Cygwin vs. Windows errors

Under Cygwin, $^E is the same as $!.  When using L<Win32 API Functions|Win32>,
use C<Win32::GetLastError()> to get the last Windows error.

=item * rebase errors on fork or system

Using C<fork()> or C<system()> out to another perl after loading multiple dlls
may result on a DLL baseaddress conflict. The internal cygwin error
looks like like the following:

 0 [main] perl 8916 child_info_fork::abort: data segment start:
 parent (0xC1A000) != child(0xA6A000)

or:

 183 [main] perl 3588 C:\cygwin\bin\perl.exe: *** fatal error -
 unable to remap C:\cygwin\bin\cygsvn_subr-1-0.dll to same address
 as parent(0x6FB30000) != 0x6FE60000 46 [main] perl 3488 fork: child
 3588 - died waiting for dll loading, errno11

See L<https://cygwin.com/faq/faq.html#faq.using.fixing-fork-failures>
It helps if not too many DLLs are loaded in memory so the available address space is larger,
e.g. stopping the MS Internet Explorer might help.

+Use the rebase utilities to resolve the conflicting dll addresses.
The rebase package is included in the Cygwin setup. Use F<setup.exe>
from L<https://cygwin.com/install.html> to install it.

1. kill all perl processes and run
   C<</bin/find <dir> -xdev -name \*.dll | /bin/rebase -OT ->> or

2. kill all cygwin processes and services, and run setup.exe.

=item * Miscellaneous

File locking using the C<F_GETLK> command to C<fcntl()> is a stub that
returns C<ENOSYS>.

The Cygwin C<chroot()> implementation has holes (it can not restrict file
access by native Win32 programs).

Inplace editing C<perl -i> of files doesn't work without doing a backup
of the file being edited C<perl -i.bak> because of windowish restrictions,
therefore Perl adds the suffix C<.bak> automatically if you use C<perl -i>
without specifying a backup extension.

=back

=head2 Prebuilt methods:

=over 4

=item C<Cwd::cwd>

Returns the current working directory.

=item C<Cygwin::pid_to_winpid>

Translates a cygwin pid to the corresponding Windows pid (which may or
may not be the same).

=item C<Cygwin::winpid_to_pid>

Translates a Windows pid to the corresponding cygwin pid (if any).

=item C<Cygwin::win_to_posix_path>

Translates a Windows path to the corresponding cygwin path respecting
the current mount points. With a second non-null argument returns an
absolute path. Double-byte characters will not be translated.

=item C<Cygwin::posix_to_win_path>

Translates a cygwin path to the corresponding cygwin path respecting
the current mount points. With a second non-null argument returns an
absolute path. Double-byte characters will not be translated.

=item C<Cygwin::mount_table()>

Returns an array of [mnt_dir, mnt_fsname, mnt_type, mnt_opts].

  perl -e 'for $i (Cygwin::mount_table) {print join(" ",@$i),"\n";}'
  /bin c:\cygwin\bin system binmode,cygexec
  /usr/bin c:\cygwin\bin system binmode
  /usr/lib c:\cygwin\lib system binmode
  / c:\cygwin system binmode
  /cygdrive/c c: system binmode,noumount
  /cygdrive/d d: system binmode,noumount
  /cygdrive/e e: system binmode,noumount

=item C<Cygwin::mount_flags>

Returns the mount type and flags for a specified mount point.
A comma-separated string of mntent->mnt_type (always
"system" or "user"), then the mntent->mnt_opts, where
the first is always "binmode" or "textmode".

  system|user,binmode|textmode,exec,cygexec,cygdrive,mixed,
  notexec,managed,nosuid,devfs,proc,noumount

If the argument is "/cygdrive", then just the volume mount settings,
and the cygdrive mount prefix are returned.

User mounts override system mounts.

  $ perl -e 'print Cygwin::mount_flags "/usr/bin"'
  system,binmode,cygexec
  $ perl -e 'print Cygwin::mount_flags "/cygdrive"'
  binmode,cygdrive,/cygdrive

=item C<Cygwin::is_binmount>

Returns true if the given cygwin path is binary mounted, false if the
path is mounted in textmode.

=item C<Cygwin::sync_winenv>

Cygwin does not initialize all original Win32 environment variables.
See the bottom of this page L<https://cygwin.com/cygwin-ug-net/setup-env.html>
for "Restricted Win32 environment".

Certain Win32 programs called from cygwin programs might need some environment
variable, such as e.g. ADODB needs %COMMONPROGRAMFILES%.
Call Cygwin::sync_winenv() to copy all Win32 environment variables to your
process and note that cygwin will warn on every encounter of non-POSIX paths.

=back

=head1 INSTALL PERL ON CYGWIN

This will install Perl, including I<man> pages.

  make install 2>&1 | tee log.make-install

NOTE: If C<STDERR> is redirected C<make install> will B<not> prompt
you to install I<perl> into F</usr/bin>.

You may need to be I<Administrator> to run C<make install>.  If you
are not, you must have write access to the directories in question.

Information on installing the Perl documentation in HTML format can be
found in the F<INSTALL> document.

=head1 MANIFEST ON CYGWIN

These are the files in the Perl release that contain references to Cygwin.
These very brief notes attempt to explain the reason for all conditional
code.  Hopefully, keeping this up to date will allow the Cygwin port to
be kept as clean as possible.

=over 4

=item Documentation

 INSTALL README.cygwin README.win32 MANIFEST
 pod/perl.pod pod/perlport.pod pod/perlfaq3.pod
 pod/perldelta.pod pod/perl5004delta.pod pod/perl56delta.pod
 pod/perl561delta.pod pod/perl570delta.pod pod/perl572delta.pod
 pod/perl573delta.pod pod/perl58delta.pod pod/perl581delta.pod
 pod/perl590delta.pod pod/perlhist.pod pod/perlmodlib.pod
 pod/perltoc.pod Porting/Glossary pod/perlgit.pod
 Porting/updateAUTHORS.pl
 dist/Cwd/Changes ext/Compress-Raw-Zlib/Changes
 dist/Time-HiRes/Changes
 ext/Compress-Raw-Zlib/README ext/Compress-Zlib/Changes
 ext/DB_File/Changes ext/Encode/Changes ext/Sys-Syslog/Changes
 ext/Win32API-File/Changes
 lib/ExtUtils/CBuilder/Changes lib/ExtUtils/Changes
 lib/ExtUtils/NOTES lib/ExtUtils/PATCHING lib/ExtUtils/README
 lib/Net/Ping/Changes lib/Test/Harness/Changes
 lib/Term/ANSIColor/ChangeLog lib/Term/ANSIColor/README

=item Build, Configure, Make, Install

 cygwin/Makefile.SHs
 ext/IPC/SysV/hints/cygwin.pl
 ext/NDBM_File/hints/cygwin.pl
 ext/ODBM_File/hints/cygwin.pl
 hints/cygwin.sh
 Configure             - help finding hints from uname,
                         shared libperl required for dynamic loading
 Makefile.SH Cross/Makefile-cross-SH
                       - linklibperl
 Porting/patchls       - cygwin in port list
 installman            - man pages with :: translated to .
 installperl           - install dll, install to 'pods'
 makedepend.SH         - uwinfix
 regen_lib.pl          - file permissions

 plan9/mkfile
 vms/descrip_mms.template
 win32/Makefile

=item Tests

 t/io/fs.t             - no file mode checks if not ntsec
                         skip rename() check when not
                         check_case:relaxed
 t/io/tell.t           - binmode
 t/lib/cygwin.t        - builtin cygwin function tests
 t/op/groups.t         - basegroup has ID = 0
 t/op/magic.t          - $^X/symlink WORKAROUND, s/.exe//
 t/op/stat.t           - no /dev, skip Win32 ftCreationTime quirk
                         (cache manager sometimes preserves ctime of
                         file previously created and deleted), no -u
                         (setuid)
 t/op/taint.t          - can't use empty path under Cygwin Perl
 t/op/time.t           - no tzset()

=item Compiled Perl Source

 EXTERN.h              - __declspec(dllimport)
 XSUB.h                - __declspec(dllexport)
 cygwin/cygwin.c       - os_extras (getcwd, spawn, and several
                         Cygwin:: functions)
 perl.c                - os_extras, -i.bak
 perl.h                - binmode
 doio.c                - win9x can not rename a file when it is open
 pp_sys.c              - do not define h_errno, init
                         _pwent_struct.pw_comment
 util.c                - use setenv
 util.h                - PERL_FILE_IS_ABSOLUTE macro
 pp.c                  - Comment about Posix vs IEEE math under
                         Cygwin
 perlio.c              - CR/LF mode
 perliol.c             - Comment about EXTCONST under Cygwin

=item Compiled Module Source

 ext/Compress-Raw-Zlib/Makefile.PL
                       - Can't install via CPAN shell under Cygwin
 ext/Compress-Raw-Zlib/zlib-src/zutil.h
                       - Cygwin is Unix-like and has vsnprintf
 ext/Errno/Errno_pm.PL - Special handling for Win32 Perl under
                         Cygwin
 ext/POSIX/POSIX.xs    - tzname defined externally
 ext/SDBM_File/sdbm/pair.c
                       - EXTCONST needs to be redefined from
                         EXTERN.h
 ext/SDBM_File/sdbm/sdbm.c
                       - binary open
 ext/Sys/Syslog/Syslog.xs
                       - Cygwin has syslog.h
 ext/Sys/Syslog/win32/compile.pl
                       - Convert paths to Windows paths
 ext/Time-HiRes/HiRes.xs
                       - Various timers not available
 ext/Time-HiRes/Makefile.PL
                       - Find w32api/windows.h
 ext/Win32/Makefile.PL - Use various libraries under Cygwin
 ext/Win32/Win32.xs    - Child dir and child env under Cygwin
 ext/Win32API-File/File.xs
                       - _open_osfhandle not implemented under
                         Cygwin
 ext/Win32CORE/Win32CORE.c
                       - __declspec(dllexport)

=item Perl Modules/Scripts

 ext/B/t/OptreeCheck.pm - Comment about stderr/stdout order under
                          Cygwin
 ext/Digest-SHA/bin/shasum
                       - Use binary mode under Cygwin
 ext/Sys/Syslog/win32/Win32.pm
                       - Convert paths to Windows paths
 ext/Time-HiRes/HiRes.pm
                       - Comment about various timers not available
 ext/Win32API-File/File.pm
                       - _open_osfhandle not implemented under
                         Cygwin
 ext/Win32CORE/Win32CORE.pm
                       - History of Win32CORE under Cygwin
 lib/Cwd.pm            - hook to internal Cwd::cwd
 lib/ExtUtils/CBuilder/Platform/cygwin.pm
                       - use gcc for ld, and link to libperl.dll.a
 lib/ExtUtils/CBuilder.pm
                       - Cygwin is Unix-like
 lib/ExtUtils/Install.pm - Install and rename issues under Cygwin
 lib/ExtUtils/MM.pm    - OS classifications
 lib/ExtUtils/MM_Any.pm - Example for Cygwin
 lib/ExtUtils/MakeMaker.pm
                       - require MM_Cygwin.pm
 lib/ExtUtils/MM_Cygwin.pm
                       - canonpath, cflags, manifypods, perl_archive
 lib/File/Fetch.pm     - Comment about quotes using a Cygwin example
 lib/File/Find.pm      - on remote drives stat() always sets
                         st_nlink to 1
 lib/File/Spec/Cygwin.pm - case_tolerant
 lib/File/Spec/Unix.pm - preserve //unc
 lib/File/Spec/Win32.pm - References a message on cygwin.com
 lib/File/Spec.pm      - Pulls in lib/File/Spec/Cygwin.pm
 lib/File/Temp.pm      - no directory sticky bit
 lib/Module/CoreList.pm - List of all module files and versions
 lib/Net/Domain.pm     - No domainname command under Cygwin
 lib/Net/Netrc.pm      - Bypass using stat() under Cygwin
 lib/Net/Ping.pm       - ECONREFUSED is EAGAIN under Cygwin
 lib/Pod/Find.pm       - Set 'pods' dir
 lib/Pod/Perldoc/ToMan.pm - '-c' switch for pod2man
 lib/Pod/Perldoc.pm    - Use 'less' pager, and use .exe extension
 lib/Term/ANSIColor.pm - Cygwin terminal info
 lib/perl5db.pl        - use stdin not /dev/tty
 utils/perlbug.PL      - Add CYGWIN environment variable to report

=item Perl Module Tests

 dist/Cwd/t/cwd.t
 ext/Compress-Zlib/t/14gzopen.t
 ext/DB_File/t/db-btree.t
 ext/DB_File/t/db-hash.t
 ext/DB_File/t/db-recno.t
 ext/DynaLoader/t/DynaLoader.t
 ext/File-Glob/t/basic.t
 ext/GDBM_File/t/gdbm.t
 ext/POSIX/t/sysconf.t
 ext/POSIX/t/time.t
 ext/SDBM_File/t/sdbm.t
 ext/Sys/Syslog/t/syslog.t
 ext/Time-HiRes/t/HiRes.t
 ext/Win32/t/Unicode.t
 ext/Win32API-File/t/file.t
 ext/Win32CORE/t/win32core.t
 lib/AnyDBM_File.t
 lib/Archive/Extract/t/01_Archive-Extract.t
 lib/Archive/Tar/t/02_methods.t
 lib/ExtUtils/t/Embed.t
 lib/ExtUtils/t/eu_command.t
 lib/ExtUtils/t/MM_Cygwin.t
 lib/ExtUtils/t/MM_Unix.t
 lib/File/Compare.t
 lib/File/Copy.t
 lib/File/Find/t/find.t
 lib/File/Path.t
 lib/File/Spec/t/crossplatform.t
 lib/File/Spec/t/Spec.t
 lib/Net/hostent.t
 lib/Net/Ping/t/110_icmp_inst.t
 lib/Net/Ping/t/500_ping_icmp.t
 lib/Net/t/netrc.t
 lib/Pod/Simple/t/perlcyg.pod
 lib/Pod/Simple/t/perlcygo.txt
 lib/Pod/Simple/t/perlfaq.pod
 lib/Pod/Simple/t/perlfaqo.txt
 lib/User/grent.t
 lib/User/pwent.t

=back

=head1 BUGS ON CYGWIN

Support for swapping real and effective user and group IDs is incomplete.
On WinNT Cygwin provides C<setuid()>, C<seteuid()>, C<setgid()> and C<setegid()>.
However, additional Cygwin calls for manipulating WinNT access tokens
and security contexts are required.

=head1 AUTHORS

Charles Wilson <cwilson@ece.gatech.edu>,
Eric Fifer <egf7@columbia.edu>,
alexander smishlajev <als@turnhere.com>,
Steven Morlock <newspost@morlock.net>,
Sebastien Barre <Sebastien.Barre@utc.fr>,
Teun Burgers <burgers@ecn.nl>,
Gerrit P. Haase <gp@familiehaase.de>,
Reini Urban <rurban@cpan.org>,
Jan Dubois <jand@activestate.com>,
Jerry D. Hedden <jdhedden@cpan.org>.

=head1 HISTORY

Last updated: 2019-11-14

# vim: syntax=pod

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
specifically designed to be readable as is.

=head1 NAME

perlfreebsd - Perl version 5 on FreeBSD systems

=head1 DESCRIPTION

This document describes various features of FreeBSD that will affect how Perl
version 5 (hereafter just Perl) is compiled and/or runs.

=head2 FreeBSD core dumps from readdir_r with ithreads

When perl is configured to use ithreads, it will use re-entrant library calls
in preference to non-re-entrant versions.  There is a bug in FreeBSD's
C<readdir_r> function in versions 4.5 and earlier that can cause a SEGV when
reading large directories. A patch for FreeBSD libc is available
(see L<https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=30631>)
which has been integrated into FreeBSD 4.6.

=head2 C<$^X> doesn't always contain a full path in FreeBSD

perl sets C<$^X> where possible to a full path by asking the operating
system. On FreeBSD the full path of the perl interpreter is found by using
C<sysctl> with C<KERN_PROC_PATHNAME> if that is supported, else by reading
the symlink F</proc/curproc/file>. FreeBSD 7 and earlier has a bug where
either approach sometimes returns an incorrect value
(see L<https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=35703>).
In these cases perl will fall back to the old behaviour of using C's
C<argv[0]> value for C<$^X>.

=head1 AUTHOR

Nicholas Clark <nick@ccl4.org>, collating wisdom supplied by Slaven Rezic
and Tim Bunce.

Please report any errors, updates, or suggestions to
L<https://github.com/Perl/perl5/issues>.

# vim: syntax=pod

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

perlhpux - 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 Using perl as shipped with HP-UX

Application release September 2001, HP-UX 11.00 is the first to ship
with Perl. By the time it was perl-5.6.1 in /opt/perl. The first
occurrence is on CD 5012-7954 and can be installed using

  swinstall -s /cdrom perl

assuming you have mounted that CD on /cdrom.

That build was a portable hppa-1.1 multithread build that supports large
files compiled with gcc-2.9-hppa-991112.

If you perform a new installation, then (a newer) Perl will be installed
automatically.  Pre-installed HP-UX systems now have more recent versions
of Perl and the updated modules.

The official (threaded) builds from HP, as they are shipped on the
Application DVD/CD's are available on
L<http://www.software.hp.com/portal/swdepot/displayProductInfo.do?productNumber=PERL>
for both PA-RISC and IPF (Itanium Processor Family). They are built
with the HP ANSI-C compiler. Up till 5.8.8 that was done by ActiveState.

To see what version is included on the DVD (assumed here to be mounted
on /cdrom), issue this command:

  # swlist -s /cdrom perl
  # perl           D.5.8.8.B  5.8.8 Perl Programming Language
    perl.Perl5-32  D.5.8.8.B  32-bit 5.8.8 Perl Programming Language
                                           with Extensions
    perl.Perl5-64  D.5.8.8.B  64-bit 5.8.8 Perl Programming Language
                                           with Extensions

To see what is installed on your system:

  # swlist -R perl
  # perl                    E.5.8.8.J  Perl Programming Language
  # perl.Perl5-32           E.5.8.8.J  32-bit Perl Programming Language
                                       with Extensions
    perl.Perl5-32.PERL-MAN  E.5.8.8.J  32-bit Perl Man Pages for IA
    perl.Perl5-32.PERL-RUN  E.5.8.8.J  32-bit Perl Binaries for IA
  # perl.Perl5-64           E.5.8.8.J  64-bit Perl Programming Language
                                       with Extensions
    perl.Perl5-64.PERL-MAN  E.5.8.8.J  64-bit Perl Man Pages for IA
    perl.Perl5-64.PERL-RUN  E.5.8.8.J  64-bit Perl Binaries for IA

=head2 Using perl from HP's porting centre

HP porting centre tries to keep up with customer demand and release
updates from the Open Source community. Having precompiled Perl binaries
available is obvious, though "up-to-date" is something relative. At the
moment of writing perl-5.10.1 and 5.28.0 were available.

The HP porting centres are limited in what systems they are allowed
to port to and they usually choose the two most recent OS versions
available.

HP has asked the porting centre to move Open Source binaries
from /opt to /usr/local, so binaries produced since the start
of July 2002 are located in /usr/local.

One of HP porting centres URL's is L<http://hpux.connect.org.uk/>
The port currently available is built with GNU gcc. As porting modern
GNU gcc is extremely hard on HP-UX, they are stuck at version gcc-4.2.3.

=head2 Other prebuilt perl binaries

To get more perl depots for the whole range of HP-UX, visit
H.Merijn Brand's site at L<http://mirrors.develooper.com/hpux/#Perl>.
Carefully read the notes to see if the available versions suit your needs.

=head2 Compiling Perl 5 on HP-UX

When compiling Perl, you must use an ANSI C compiler.  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 INSTALL file for more gcc-specific
details.

=head2 PA-RISC

The last and final version of PA-RISC is 2.0, HP no longer sells any
system with these CPU's.

HP's HP9000 Unix systems run on HP's 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. Even though PA-RISC hardware is not sold anymore, a
lot of machines still running on these CPU's can be found in the wild.

The last order date for HP 9000 systems was December 31, 2008.

HP PA-RISC systems are usually referred to with model description "HP 9000".
The last CPU in this series is the PA-8900.  Support for PA-RISC
architectured machines officially ended as shown in the following table:

   PA-RISC End-of-Life Roadmap
 +--------+----------------+----------------+-----------------+
 | HP9000 | Superdome      | PA-8700        | Spring 2011     |
 | 4-128  |                | PA-8800/sx1000 | Summer 2012     |
 | cores  |                | PA-8900/sx1000 | 2014            |
 |        |                | PA-8900/sx2000 | 2015            |
 +--------+----------------+----------------+-----------------+
 | HP9000 | rp7410, rp8400 | PA-8700        | Spring 2011     |
 | 2-32   | rp7420, rp8420 | PA-8800/sx1000 | 2012            |
 | cores  | rp7440, rp8440 | PA-8900/sx1000 | Autumn 2013     |
 |        |                | PA-8900/sx2000 | 2015            |
 +--------+----------------+----------------+-----------------+
 | HP9000 | rp44x0         | PA-8700        | Spring 2011     |
 | 1-8    |                | PA-8800/rp44x0 | 2012            |
 | cores  |                | PA-8900/rp44x0 | 2014            |
 +--------+----------------+----------------+-----------------+
 | HP9000 | rp34x0         | PA-8700        | Spring 2011     |
 | 1-4    |                | PA-8800/rp34x0 | 2012            |
 | cores  |                | PA-8900/rp34x0 | 2014            |
 +--------+----------------+----------------+-----------------+

A complete list of models at the time the OS was built is in the file
/usr/sam/lib/mo/sched.models. The first column corresponds to the last
part of the output of the "model" command.  The second column is the
PA-RISC version and the third column is the exact chip type used.
(Start browsing at the bottom to prevent confusion ;-)

  # model
  9000/800/L1000-44
  # grep L1000-44 /usr/sam/lib/mo/sched.models
  L1000-44        2.0     PA8500

=head2 PA-RISC 1.0

The original version of PA-RISC, HP no longer sells any system with this chip.

The following systems contained PA-RISC 1.0 chips:

  600, 635, 645, 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, 742, 743, 744, 745,
  747, 750, 755, 770, 777, 778, 779, 800, 801, 803, 806, 807, 809, 811,
  813, 816, 817, 819, 821, 826, 827, 829, 831, 837, 839, 841, 847, 849,
  851, 856, 857, 859, 867, 869, 877, 887, 891, 892, 897, A180, A180C,
  B115, B120, B132L, B132L+, B160L, B180L, C100, C110, C115, C120,
  C160L, D200, D210, D220, D230, D250, D260, D310, D320, D330, D350,
  D360, D410, DX0, DX5, DXO, E25, E35, E45, E55, F10, F20, F30, G30,
  G40, G50, G60, G70, H20, H30, H40, H50, H60, H70, I30, I40, I50, I60,
  I70, J200, J210, J210XC, K100, K200, K210, K220, K230, K400, K410,
  K420, S700i, S715, S744, S760, T500, T520

=head2 PA-RISC 2.0

The most recent upgrade to the PA-RISC design, it added support for
64-bit integer data.

As of the date of this document's last update, the following systems
contain PA-RISC 2.0 chips:

  700, 780, 781, 782, 783, 785, 802, 804, 810, 820, 861, 871, 879, 889,
  893, 895, 896, 898, 899, A400, A500, B1000, B2000, C130, C140, C160,
  C180, C180+, C180-XP, C200+, C400+, C3000, C360, C3600, CB260, D270,
  D280, D370, D380, D390, D650, J220, J2240, J280, J282, J400, J410,
  J5000, J5500XM, J5600, J7000, J7600, K250, K260, K260-EG, K270, K360,
  K370, K380, K450, K460, K460-EG, K460-XP, K470, K570, K580, L1000,
  L2000, L3000, N4000, R380, R390, SD16000, SD32000, SD64000, T540,
  T600, V2000, V2200, V2250, V2500, V2600

Just before HP took over Compaq, some systems were renamed. the link
that contained the explanation is dead, so here's a short summary:

  HP 9000 A-Class servers, now renamed HP Server rp2400 series.
  HP 9000 L-Class servers, now renamed HP Server rp5400 series.
  HP 9000 N-Class servers, now renamed HP Server rp7400.

  rp2400, rp2405, rp2430, rp2450, rp2470, rp3410, rp3440, rp4410,
  rp4440, rp5400, rp5405, rp5430, rp5450, rp5470, rp7400, rp7405,
  rp7410, rp7420, rp7440, rp8400, rp8420, rp8440, Superdome

The current naming convention is:

  aadddd
  ||||`+- 00 - 99 relative capacity & newness (upgrades, etc.)
  |||`--- unique number for each architecture to ensure different
  |||     systems do not have the same numbering across
  |||     architectures
  ||`---- 1 - 9 identifies family and/or relative positioning
  ||
  |`----- c = ia32 (cisc)
  |       p = pa-risc
  |       x = ia-64 (Itanium & Itanium 2)
  |       h = housing
  `------ t = tower
          r = rack optimized
          s = super scalable
          b = blade
          sa = appliance

=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 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.  The command-line flags are accepted,
but the resulting executable will not run when transferred to a PA-RISC
1.0 system.

=head2 Itanium Processor Family (IPF) and HP-UX

HP-UX also runs on the newer Itanium processor.  This requires the use
of HP-UX version 11.23 (11i v2) or 11.31 (11i v3), and with the exception
of a few differences detailed below and in later sections, Perl should
compile with no problems.

Although PA-RISC binaries can run on Itanium systems, you should not
attempt to use a PA-RISC version of Perl on an Itanium system.  This is
because shared libraries created on an Itanium system cannot be loaded
while running a PA-RISC executable.

HP Itanium 2 systems are usually referred to with model description
"HP Integrity".

=head2 Itanium, Itanium 2 & Madison 6

HP also ships servers with the 128-bit Itanium processor(s). The cx26x0
is told to have Madison 6. As of the date of this document's last update,
the following systems contain Itanium or Itanium 2 chips (this is likely
to be out of date):

  BL60p, BL860c, BL870c, BL890c, cx2600, cx2620, rx1600, rx1620, rx2600,
  rx2600hptc, rx2620, rx2660, rx2800, rx3600, rx4610, rx4640, rx5670,
  rx6600, rx7420, rx7620, rx7640, rx8420, rx8620, rx8640, rx9610,
  sx1000, sx2000

To see all about your machine, type

  # model
  ia64 hp server rx2600
  # /usr/contrib/bin/machinfo

=head2 HP-UX versions

Not all architectures (PA = PA-RISC, IPF = Itanium Processor Family)
support all versions of HP-UX, here is a short list

  HP-UX version  Kernel  Architecture End-of-factory support
  -------------  ------  ------------ ----------------------------------
  10.20          32 bit  PA           30-Jun-2003
  11.00          32/64   PA           31-Dec-2006
  11.11  11i v1  32/64   PA           31-Dec-2015
  11.22  11i v2     64        IPF     30-Apr-2004
  11.23  11i v2     64   PA & IPF     31-Dec-2015
  11.31  11i v3     64   PA & IPF     31-Dec-2020 (PA) 31-Dec-2025 (IPF)

See for the full list of hardware/OS support and expected end-of-life
L<https://h20195.www2.hpe.com/V2/getpdf.aspx/4AA4-7673ENW.pdf>

=head2 Building Dynamic Extensions on HP-UX

HP-UX supports dynamically loadable libraries (shared libraries).
Shared libraries end with the suffix .sl.  On Itanium systems,
they end with the suffix .so.

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).

Shared libraries created on an Itanium platform cannot be loaded on
a PA-RISC platform.  Shared libraries created on a PA-RISC platform
can only be loaded on an Itanium platform if it is a PA-RISC executable
that is attempting to load the PA-RISC library.  A PA-RISC shared
library cannot be loaded into an Itanium executable nor vice-versa.

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.
     (For gcc, the appropriate flag is -fpic or -fPIC.)

  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 refers to another library, which
may be either an archive library or a shared library.  If this second
library 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.  This can cause problems if you build an
extension on one system and move it to another system where the
libraries may not be located in the same place as on the first system.

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.

Some extensions, like DB_File and Compress::Zlib use/require prebuilt
libraries for the perl extensions/modules to work. If these libraries
are built using the default configuration, it might happen that you
run into an error like "invalid loader fixup" during load phase.
HP is aware of this problem.  Search the HP-UX cxx-dev forums for
discussions about the subject.  The short answer is that B<everything>
(all libraries, everything) must be compiled with C<+z> or C<+Z> to be
PIC (position independent code).  (For gcc, that would be
C<-fpic> or C<-fPIC>).  In HP-UX 11.00 or newer the linker
error message should tell the name of the offending object file.

A more general approach is to intervene manually, as with an example for
the DB_File module, which requires SleepyCat's libdb.sl:

  # cd .../db-3.2.9/build_unix
  # vi Makefile
  ... add +Z to all cflags to create shared objects
  CFLAGS=         -c $(CPPFLAGS) +Z -Ae +O2 +Onolimit \
                  -I/usr/local/include -I/usr/include/X11R6
  CXXFLAGS=       -c $(CPPFLAGS) +Z -Ae +O2 +Onolimit \
                  -I/usr/local/include -I/usr/include/X11R6

  # make clean
  # make
  # mkdir tmp
  # cd tmp
  # ar x ../libdb.a
  # ld -b -o libdb-3.2.sl *.o
  # mv libdb-3.2.sl /usr/local/lib
  # rm *.o
  # cd /usr/local/lib
  # rm -f libdb.sl
  # ln -s libdb-3.2.sl libdb.sl

  # cd .../DB_File-1.76
  # make distclean
  # perl Makefile.PL
  # make
  # make test
  # make install

As of db-4.2.x it is no longer needed to do this by hand. Sleepycat
has changed the configuration process to add +z on HP-UX automatically.

  # cd .../db-4.2.25/build_unix
  # env CFLAGS=+DD64 LDFLAGS=+DD64 ../dist/configure

should work to generate 64bit shared libraries for HP-UX 11.00 and 11i.

It is no longer possible to link PA-RISC 1.0 shared libraries (even
though the command-line flags are still present).

PA-RISC and Itanium object files are not interchangeable.  Although
you may be able to use ar to create an archive library of PA-RISC
object files on an Itanium system, you cannot link against it using
an Itanium link editor.

=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 (though see the section on 64-bit perl below). If you are using a
recent version of the Perl distribution, these flags are set automatically.

Even though HP-UX 10.20 and 11.00 are not actively maintained by HP
anymore, updates for the HP ANSI C compiler are still available from
time to time, and it might be advisable to see if updates are applicable.
At the moment of writing, the latests available patches for 11.00 that
should be applied are PHSS_35098, PHSS_35175, PHSS_35100, PHSS_33036,
and PHSS_33902). If you have a SUM account, you can use it to search
for updates/patches. Enter "ANSI" as keyword.

=head2 The GNU C Compiler

When you are going to use the GNU C compiler (gcc), and you don't have
gcc yet, you can either build it yourself (if you feel masochistic enough)
from the sources (available from e.g. L<http://gcc.gnu.org/mirrors.html>)
or fetch a prebuilt binary from the HP porting center at
L<http://hpux.connect.org.uk/hppd/cgi-bin/search?term=gcc&Search=Search>
or from the DSPP (you need to be a member) at
L<http://h21007.www2.hp.com/portal/site/dspp/menuitem.863c3e4cbcdc3f3515b49c108973a801?ciid=2a08725cc2f02110725cc2f02110275d6e10RCRD&jumpid=reg_r1002_usen_c-001_title_r0001>
(Browse through the list, because there are often multiple versions of
the same package available).

Most mentioned distributions are depots. H.Merijn Brand has made prebuilt
gcc binaries available on L<http://mirrors.develooper.com/hpux/> and/or
L<http://www.cmve.net/~merijn/> for HP-UX 10.20 (only 32bit), HP-UX 11.00,
HP-UX 11.11 (HP-UX 11i v1), and HP-UX 11.23 (HP-UX 11i v2 PA-RISC) in both
32- and 64-bit versions. For HP-UX 11.23 IPF and HP-UX 11.31 IPF depots are
available too. The IPF versions do not need two versions of GNU gcc.

On PA-RISC you need a different compiler for 32-bit applications and for
64-bit applications. On PA-RISC, 32-bit objects and 64-bit objects do
not mix. Period. There is no different behaviour for HP C-ANSI-C or GNU
gcc. So if you require your perl binary to use 64-bit libraries, like
Oracle-64bit, you MUST build a 64-bit perl.

Building a 64-bit capable gcc on PA-RISC from source is possible only when
you have the HP C-ANSI C compiler or an already working 64-bit binary of
gcc available. Best performance for perl is achieved with HP's native
compiler.

=head2 Using Large Files with Perl on HP-UX

Beginning with HP-UX version 10.20, files larger than 2GB (2^31 bytes)
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 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 supports 64-bit operations. See above for
where to find it.)

There are some drawbacks to this approach.  One 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

Another drawback is only valid for Perl versions before 5.6.0.  This
drawback is that the seek and tell functions (both the builtin version
and POSIX module version) will not perform correctly.

It is strongly recommended that you use this flag when you run
Configure.  If you do not do this, but later answer the question about
large files when Configure asks you, you may get a configuration that
cannot be compiled, or that does not function as expected.

=head2 Threaded Perl on HP-UX

It is possible to compile a version of threaded Perl on any version of
HP-UX before 10.30, but it is strongly suggested that you be running on
HP-UX 11.00 at least.

To compile Perl with threads, add -Dusethreads to the arguments of
Configure.  Verify 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. The
hints provided for HP-UX during Configure will try very hard to get
this right for you.

HP-UX versions before 10.30 require a separate installation of a POSIX
threads library package. Two examples are the HP DCE package, available
on "HP-UX Hardware Extensions 3.0, Install and Core OS, Release 10.20,
April 1999 (B3920-13941)" or the Freely available PTH package, available
on H.Merijn's site (L<http://mirrors.develooper.com/hpux/>). The use of PTH
will be unsupported in perl-5.12 and up and is rather buggy in 5.11.x.

If you are going to use the HP DCE package, the library used for threading
is /usr/lib/libcma.sl, but there have been multiple updates of that
library over time. Perl will build with the first version, but it
will not pass the test suite. Older Oracle versions might be a compelling
reason not to update that library, otherwise please find a newer version
in one of the following patches: PHSS_19739, PHSS_20608, or PHSS_23672

reformatted output:

  d3:/usr/lib 106 > what libcma-*.1
  libcma-00000.1:
     HP DCE/9000 1.5               Module: libcma.sl (Export)
                                   Date: Apr 29 1996 22:11:24
  libcma-19739.1:
     HP DCE/9000 1.5 PHSS_19739-40 Module: libcma.sl (Export)
                                   Date: Sep  4 1999 01:59:07
  libcma-20608.1:
     HP DCE/9000 1.5 PHSS_20608    Module: libcma.1 (Export)
                                   Date: Dec  8 1999 18:41:23
  libcma-23672.1:
     HP DCE/9000 1.5 PHSS_23672    Module: libcma.1 (Export)
                                   Date: Apr  9 2001 10:01:06
  d3:/usr/lib 107 >

If you choose for the PTH package, use swinstall to install pth in
the default location (/opt/pth), and then make symbolic links to the
libraries from /usr/lib

  # cd /usr/lib
  # ln -s /opt/pth/lib/libpth* .

For building perl to support Oracle, it needs to be linked with libcl
and libpthread. So even if your perl is an unthreaded build, these
libraries might be required. See "Oracle on HP-UX" below.

=head2 64-bit Perl on HP-UX

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), in which scalar variables will be able
to hold numbers larger than 2^32 with complete precision.  Perl has
proven to be consistent and reliable in 64bit mode since 5.8.1 on
all HP-UX 11.xx.

As of the date of this document, Perl is fully 64-bit compliant on
HP-UX 11.00 and up for both cc- and gcc builds. If you are about to
build a 64-bit perl with GNU gcc, please read the gcc section carefully.

Should a user have the need for compiling Perl in the LP64 environment,
use the -Duse64bitall flag to Configure.  This will force Perl to be
compiled in a pure LP64 environment (with the +DD64 flag for HP C-ANSI-C,
with no additional options for GNU gcc 64-bit on PA-RISC, and with
-mlp64 for GNU gcc on Itanium).
If you want to compile Perl using gcc, you will have to get a version of
the compiler that supports 64-bit operations.)

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. When configuring -Duse64bitint using a 64bit gcc on a
pa-risc architecture, -Duse64bitint is silently promoted to -Duse64bitall.

In both cases, it is strongly recommended that you use these flags when
you run Configure.  If you do not use do this, but later 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.

=head2 Oracle on HP-UX

Using perl to connect to Oracle databases through DBI and DBD::Oracle
has caused a lot of people many headaches. Read README.hpux in the
DBD::Oracle for much more information. The reason to mention it here
is that Oracle requires a perl built with libcl and libpthread, the
latter even when perl is build without threads. Building perl using
all defaults, but still enabling to build DBD::Oracle later on can be
achieved using

  Configure -A prepend:libswanted='cl pthread ' ...

Do not forget the space before the trailing quote.

Also note that this does not (yet) work with all configurations,
it is known to fail with 64-bit versions of GCC.

=head2 GDBM and Threads on HP-UX

If you attempt to compile Perl with (POSIX) 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.

the error might show something like:

Pthread internal error: message: __libc_reinit() failed, file: ../pthreads/pthread.c, line: 1096
Return Pointer is 0xc082bf33
sh: 5345 Quit(coredump)

and Configure will give up.

=head2 NFS filesystems and utime(2) on HP-UX

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.

=head2 HP-UX Kernel Parameters (maxdsiz) for Compiling Perl

By default, HP-UX comes configured with a maximum data segment size of
64MB.  This is too small to correctly compile Perl with the maximum
optimization levels.  You can increase the size of the maxdsiz kernel
parameter through the use of SAM.

When using the GUI version of SAM, click on the Kernel Configuration
icon, then the Configurable Parameters icon.  Scroll down and select
the maxdsiz line.  From the Actions menu, select the Modify Configurable
Parameter item.  Insert the new formula into the Formula/Value box.
Then follow the instructions to rebuild your kernel and reboot your
system.

In general, a value of 256MB (or "256*1024*1024") is sufficient for
Perl to compile at maximum optimization.

=head1 nss_delete core dump from op/pwent or op/grent

You may get a bus error core dump from the op/pwent or op/grent
tests. If compiled with -g you will see a stack trace much like
the following:

  #0  0xc004216c in  () from /usr/lib/libc.2
  #1  0xc00d7550 in __nss_src_state_destr () from /usr/lib/libc.2
  #2  0xc00d7768 in __nss_src_state_destr () from /usr/lib/libc.2
  #3  0xc00d78a8 in nss_delete () from /usr/lib/libc.2
  #4  0xc01126d8 in endpwent () from /usr/lib/libc.2
  #5  0xd1950 in Perl_pp_epwent () from ./perl
  #6  0x94d3c in Perl_runops_standard () from ./perl
  #7  0x23728 in S_run_body () from ./perl
  #8  0x23428 in perl_run () from ./perl
  #9  0x2005c in main () from ./perl

The key here is the C<nss_delete> call.  One workaround for this
bug seems to be to create add to the file F</etc/nsswitch.conf>
(at least) the following lines

  group: files
  passwd: files

Whether you are using NIS does not matter.  Amazingly enough,
the same bug also affects Solaris.

=head1 error: pasting ")" and "l" does not give a valid preprocessing token

There seems to be a broken system header file in HP-UX 11.00 that
breaks perl building in 32bit mode with GNU gcc-4.x causing this
error. The same file for HP-UX 11.11 (even though the file is older)
does not show this failure, and has the correct definition, so the
best fix is to patch the header to match:

 --- /usr/include/inttypes.h  2001-04-20 18:42:14 +0200
 +++ /usr/include/inttypes.h  2000-11-14 09:00:00 +0200
 @@ -72,7 +72,7 @@
  #define UINT32_C(__c)                   __CONCAT_U__(__c)
  #else /* __LP64 */
  #define INT32_C(__c)                    __CONCAT__(__c,l)
 -#define UINT32_C(__c)                   __CONCAT__(__CONCAT_U__(__c),l)
 +#define UINT32_C(__c)                   __CONCAT__(__c,ul)
  #endif /* __LP64 */

  #define INT64_C(__c)                    __CONCAT_L__(__c,l)

=head1 Redeclaration of "sendpath" with a different storage class specifier

The following compilation warnings may happen in HP-UX releases
earlier than 11.31 but are harmless:

 cc: "/usr/include/sys/socket.h", line 535: warning 562:
    Redeclaration of "sendfile" with a different storage class
    specifier: "sendfile" will have internal linkage.
 cc: "/usr/include/sys/socket.h", line 536: warning 562:
    Redeclaration of "sendpath" with a different storage class
    specifier: "sendpath" will have internal linkage.

They seem to be caused by broken system header files, and also other
open source projects are seeing them.  The following HP-UX patches
should make the warnings go away:

  CR JAGae12001: PHNE_27063
  Warning 562 on sys/socket.h due to redeclaration of prototypes

  CR JAGae16787:
  Warning 562 from socket.h sendpath/sendfile -D_FILEFFSET_BITS=64

  CR JAGae73470 (11.23)
  ER: Compiling socket.h with cc -D_FILEFFSET_BITS=64 warning 267/562

=head1 Miscellaneous

HP-UX 11 Y2K patch "Y2K-1100 B.11.00.B0125 HP-UX Core OS Year 2000
Patch Bundle" has been reported to break the io/fs test #18 which
tests whether utime() can change timestamps.  The Y2K patch seems to
break utime() so that over NFS the timestamps do not get changed
(on local filesystems utime() still works). This has probably been
fixed on your system by now.

=head1 AUTHOR

H.Merijn Brand <h.m.brand@xs4all.nl>
Jeff Okamoto <okamoto@corp.hp.com>

With much assistance regarding shared libraries from Marc Sabatella.

=cut

# vim: syntax=pod

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

perlhurd - Perl version 5 on Hurd

=head1 DESCRIPTION

If you want to use Perl on the Hurd, I recommend using the Debian
GNU/Hurd distribution ( see L<https://www.debian.org/> ), even if an
official, stable release has not yet been made.  The old "gnu-0.2"
binary distribution will most certainly have additional problems.

=head2 Known Problems with Perl on Hurd

The Perl test suite may still report some errors on the Hurd.  The
"lib/anydbm" and "pragma/warnings" tests will almost certainly fail.
Both failures are not really specific to the Hurd, as indicated by the
test suite output.

The socket tests may fail if the network is not configured.  You have
to make "/hurd/pfinet" the translator for "/servers/socket/2", giving
it the right arguments.  Try "/hurd/pfinet --help" for more
information.

Here are the statistics for Perl 5.005_62 on my system:

 Failed Test  Status Wstat Total Fail  Failed  List of failed
 -----------------------------------------------------------------------
 lib/anydbm.t                 12    1   8.33%  12
 pragma/warnings             333    1   0.30%  215

 8 tests and 24 subtests skipped.
 Failed 2/229 test scripts, 99.13% okay. 2/10850 subtests failed,
     99.98% okay.

There are quite a few systems out there that do worse!

However, since I am running a very recent Hurd snapshot, in which a lot of
bugs that were exposed by the Perl test suite have been fixed, you may
encounter more failures.  Likely candidates are: "op/stat", "lib/io_pipe",
"lib/io_sock", "lib/io_udp" and "lib/time".

In any way, if you're seeing failures beyond those mentioned in this
document, please consider upgrading to the latest Hurd before reporting
the failure as a bug.

=head1 AUTHOR

Mark Kettenis <kettenis@gnu.org>

Last Updated: Fri, 29 Oct 1999 22:50:30 +0200

# vim: syntax=pod

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
specifically designed to be readable as is.

=head1 NAME

perlirix - Perl version 5 on Irix systems

=head1 DESCRIPTION

This document describes various features of Irix that will affect how Perl
version 5 (hereafter just Perl) is compiled and/or runs.

=head2 Building 32-bit Perl in Irix

Use

	sh Configure -Dcc='cc -n32'

to compile Perl 32-bit.  Don't bother with -n32 unless you have 7.1
or later compilers (use cc -version to check).

(Building 'cc -n32' is the default.)

=head2 Building 64-bit Perl in Irix

Use

	sh Configure -Dcc='cc -64' -Duse64bitint

This requires require a 64-bit MIPS CPU (R8000, R10000, ...)

You can also use

	sh Configure -Dcc='cc -64' -Duse64bitall

but that makes no difference compared with the -Duse64bitint because
of the C<cc -64>.

You can also do

	sh Configure -Dcc='cc -n32' -Duse64bitint

to use long longs for the 64-bit integer type, in case you don't
have a 64-bit CPU.

If you are using gcc, just

	sh Configure -Dcc=gcc -Duse64bitint

should be enough, the Configure should automatically probe for the
correct 64-bit settings.

=head2 About Compiler Versions of Irix

Some Irix cc versions, e.g. 7.3.1.1m (try cc -version) have been known
to have issues (coredumps) when compiling perl.c.  If you've used
-OPT:fast_io=ON and this happens, try removing it.  If that fails, or
you didn't use that, then try adjusting other optimization options
(-LNO, -INLINE, -O3 to -O2, et cetera).  The compiler bug has been
reported to SGI.  (Allen Smith <easmith@beatrice.rutgers.edu>)

=head2 Linker Problems in Irix

If you get complaints about so_locations then search in the file
hints/irix_6.sh for "lddflags" and do the suggested adjustments.
(David Billinghurst <David.Billinghurst@riotinto.com.au>)

=head2 Malloc in Irix

Do not try to use Perl's malloc, this will lead into very mysterious
errors (especially with -Duse64bitall).

=head2 Building with threads in Irix

Run Configure with -Duseithreads which will configure Perl with
the Perl 5.8.0 "interpreter threads", see L<threads>.

For Irix 6.2 with perl threads, you have to have the following
patches installed:

        1404 Irix 6.2 Posix 1003.1b man pages
        1645 Irix 6.2 & 6.3 POSIX header file updates
        2000 Irix 6.2 Posix 1003.1b support modules
        2254 Pthread library fixes
        2401 6.2 all platform kernel rollup

B<IMPORTANT>: Without patch 2401, a kernel bug in Irix 6.2 will cause
your machine to panic and crash when running threaded perl.  Irix 6.3
and later are okay.

    Thanks to Hannu Napari <Hannu.Napari@hut.fi> for the IRIX
    pthreads patches information.

=head2 Irix 5.3

While running Configure and when building, you are likely to get
quite a few of these warnings:

  ld:
  The shared object /usr/lib/libm.so did not resolve any symbols.
        You may want to remove it from your link line.

Ignore them: in IRIX 5.3 there is no way to quieten ld about this.

During compilation you will see this warning from toke.c:

  uopt: Warning: Perl_yylex: this procedure not optimized because it
        exceeds size threshold; to optimize this procedure, use -Olimit
        option with value >= 4252.

Ignore the warning.

In IRIX 5.3 and with Perl 5.8.1 (Perl 5.8.0 didn't compile in IRIX 5.3)
the following failures are known.

 Failed Test                  Stat Wstat Total Fail  Failed|Failing List
 -----------------------------------------------------------------------
 ../ext/List/Util/t/shuffle.t    0   139    ??   ??       %  ??
 ../lib/Math/Trig.t            255 65280    29   12  41.38%  24-29
 ../lib/sort.t                   0   138   119   72  60.50%  48-119
 56 tests and 474 subtests skipped.
 Failed 3/811 test scripts, 99.63% okay. 78/75813 subtests failed,
    99.90% okay.

They are suspected to be compiler errors (at least the shuffle.t
failure is known from some IRIX 6 setups) and math library errors
(the Trig.t failure), but since IRIX 5 is long since end-of-lifed,
further fixes for the IRIX are unlikely.  If you can get gcc for 5.3,
you could try that, too, since gcc in IRIX 6 is a known workaround for
at least the shuffle.t and sort.t failures.

=head1 AUTHOR

Jarkko Hietaniemi <jhi@iki.fi>

Please report any errors, updates, or suggestions to
L<https://github.com/Perl/perl5/issues>.

# vim: syntax=pod

=encoding utf8

=head1 NAME

perljp - 日本語 Perl ガイド

=head1 説明

Perl の世界へようこそ!

Perl 5.8.0 より、Unicodeサポートが大幅に強化され、その結果ラテン文字以外の文字コードのサポートが CJK (中国語、日本語、ハングル)を含めて加わりました。Unicodeは世界中の文字を一つの文字コードで扱うことを目指した標準規格であり、東から西、はたまたその間の文字（ギリシャ文字、キリール文字、アラビア文字、ヘブライ文字、ディーヴァナガーリ文字、などなど）や、これまではOSベンダーが独自に定めていた文字(PCおよびMacintosh)がすでに含まれています。

Perl 自身は Unicode で動作します。Perl スクリプト内の文字列リテラルや正規表現は Unicode を前提としています。そして入出力のためには、これまで使われてきたさまざまな文字コードに対応するモジュール、「 Encode 」が標準装備されており、Unicode とこれらの文字コードの相互変換も簡単に行えるようになっています。

現時点で Encode がサポートする文字コードは以下のとおりです。

  7bit-jis      AdobeStandardEncoding AdobeSymbol       AdobeZdingbat
  ascii             big5              big5-hkscs        cp1006
  cp1026            cp1047            cp1250            cp1251
  cp1252            cp1253            cp1254            cp1255
  cp1256            cp1257            cp1258            cp37
  cp424             cp437             cp500             cp737
  cp775             cp850             cp852             cp855
  cp856             cp857             cp860             cp861
  cp862             cp863             cp864             cp865
  cp866             cp869             cp874             cp875
  cp932             cp936             cp949             cp950
  dingbats          euc-cn            euc-jp            euc-kr
  gb12345-raw       gb2312-raw        gsm0338           hp-roman8
  hz                iso-2022-jp       iso-2022-jp-1     iso-8859-1
  iso-8859-10       iso-8859-11       iso-8859-13       iso-8859-14
  iso-8859-15       iso-8859-16       iso-8859-2        iso-8859-3
  iso-8859-4        iso-8859-5        iso-8859-6        iso-8859-7
  iso-8859-8        iso-8859-9        iso-ir-165        jis0201-raw
  jis0208-raw       jis0212-raw       johab             koi8-f
  koi8-r            koi8-u            ksc5601-raw       MacArabic
  MacCentralEurRoman  MacChineseSimp    MacChineseTrad    MacCroatian
  MacCyrillic       MacDingbats       MacFarsi          MacGreek
  MacHebrew         MacIcelandic      MacJapanese       MacKorean
  MacRoman          MacRomanian       MacRumanian       MacSami
  MacSymbol         MacThai           MacTurkish        MacUkrainian
  nextstep          posix-bc          shiftjis          symbol
  UCS-2BE           UCS-2LE           UTF-16            UTF-16BE
  UTF-16LE          UTF-32            UTF-32BE          UTF-32LE
  utf8              viscii

(全114種類)

例えば、文字コードFOOのファイルをUTF-8に変換するには、以下のようにします。

    perl -Mencoding=FOO,STDOUT,utf8 -pe1 < file.FOO > file.utf8

また、Perlには、全部がPerlで書かれた文字コード変換ユーティリティ、piconvも付属しているので、以下のようにすることもできます。

   piconv -f FOO -t utf8 < file.FOO > file.utf8
   piconv -f utf8 -t FOO < file.utf8 > file.FOO

=head2 (jcode.pl|Jcode.pm|JPerl) からの移行

5.8以前の、スクリプトがEUC-JPであればリテラルだけは扱うことができました。また、入出力を扱うモジュールとしてはJcode.pmが( L<http://openlab.ring.gr.jp/Jcode/> )、perl4用のユーティリティとしてはjcode.plがそれぞれ存在し、日本語の扱えるCGIでよく利用されていることを御存じの方も少なくないかと思われます。ただし、日本語による正規表現をうまく扱うことは不可能でした。

5.005以前のPerlには、日本語に特化したローカライズ版、Jperlが存在しました( L<http://homepage2.nifty.com/kipp/perl/jperl/index.html> ※1)。また、Mac OS 9.x/Classic用のPerl、MacPerlの日本語版もMacJPerlとして存在してました。( L<https://habilis.net/macjperl/> ).これらでは文字コードとしてEUC-JPに加えShift_JISもそのまま扱うことができ、また日本語による正規表現を扱うことも可能でした。

Perl5.8では、これらの機能がすべてPerl本体だけで実現できる上に、日本語のみならず上記114の文字コードをすべて、しかも同時に扱うことができます。さらに、CPANなどから新しい文字コード用のモジュールを入手することも簡単にできるようになっています。

※1: ホスティングサービスの終了により現在は閲覧できません。 Vector( L<https://www.vector.co.jp/soft/win95/util/se098198.html> )からWindow用のバイナリを、CPAN( L<https://www.cpan.org/src/unsupported/4.036/jperl/> )からperl4用のパッチを入手することができます。

=over 4

=item *

入出力

以下の例はいずれもShift_JISの入力をEUC-JPに変換して出力します。

  # jcode.pl
  require "jcode.pl";
  while(<>){
    jcode::convert(*_, 'euc', 'sjis');
    print;
  }
  # Jcode.pm
  use Jcode;
  while(<>){
  	print Jcode->new($_, 'sjis')->euc;
  }
  # Perl 5.8
  use Encode;
  while(<>){
    from_to($_, 'shiftjis', 'euc-jp');
    print;
  }
  # Perl 5.8 - encoding を利用して
  use encoding 'euc-jp', STDIN => 'shiftjis';
  while(<>){
  	print;
  }

=item *

Jperl 互換スクリプト

いわゆる"shebang"を変更するだけで、Jperl用のscriptのほとんどは変更なしに利用可能だと思われます。

   #!/path/to/jperl
   ↓
   #!/path/to/perl -Mencoding=euc-jp

詳しくは perldoc encoding を参照してください。

=back

=head2 さらに詳しく

Perlには膨大な資料が付属しており、Perlの新機能やUnicodeサポート、そしてEncodeモジュールの使用法などが細かく網羅されています（残念ながら、ほとんど英語ではありますが）。以下のコマンドでそれらの一部を閲覧することが可能です。

  perldoc perlunicode # PerlのUnicodeサポート全般
  perldoc Encode      # Encodeモジュールに関して
  perldoc Encode::JP  # うち日本語文字コードに関して

=head2 Perl全般に関する URL

=over 4

=item L<https://www.perl.org/>

Perl ホームページ

=item L<https://www.perl.com/>

Perl 財団が営業する文章作品集

=item L<https://www.cpan.org/>

CPAN (Comprehensive Perl Archive Network)

=item L<https://metacpan.org/>

MetaCPAN CPANの検索エンジン

=item L<https://lists.perl.org/>

Perl メーリングリスト集

=item L<https://perldoc.jp/>

perldoc.jp Perl の公式ドキュメント、モジュールドキュメントの日本語訳

=back

=head2 Perlの修得に役立つ URL

=over 4

=item L<http://www.oreilly.com.cn/>

O'Reilly 社のPerl関連書籍(簡体字中国語)

=item L<https://www.oreilly.co.jp/catalog/>

オライリー社のPerl関連書籍(日本語)

=back

=head2 Perl に関する団体

=over 4

=item L<https://www.pm.org/groups/asia.html>

アジア地域の Perl Mongers (Perlのユーザーグループ) 一覧

=item L<https://japan.perlassociation.org>

一般社団法人Japan Perl Association (JPA) Perl技術及び文化の啓蒙・促進のための組織

=back

=head2 Unicode関連のURL

=over 4

=item L<https://www.unicode.org/>

Unicode コンソーシアム (Unicode規格の選定団体)

=item L<https://www.cl.cam.ac.uk/%7Emgk25/unicode.html>

UTF-8 and Unicode FAQ for Unix/Linux

=item L<https://wiki.kldp.org/Translations/html/UTF8-Unicode-KLDP/UTF8-Unicode-KLDP.html>

UTF-8 and Unicode FAQ for Unix/Linux (ハングル訳)

=back

=head1 AUTHORS

=over

=item * Jarkko Hietaniemi E<lt>jhi@iki.fiE<gt>

=item * Dan Kogai (小飼　弾) E<lt>dankogai@dan.co.jpE<gt>

=item * Shogo Ichinose (一野瀬　翔吾) E<lt>shogo82148@gmail.comE<gt>

=back

=cut

# vim: syntax=pod

이 파일을 내용 그대로 읽고 있다면 우스꽝스러운 문자는 무시해주세요.
이 문서는 POD로 읽을 수 있도록 POD 형식(F<pod/perlpod.pod> 문서를
확인하세요)으로 작성되어 있습니다.

=encoding utf8

=head1 NAME

perlko - 한국어 Perl 안내서

=head1 DESCRIPTION

Perl의 세계에 오신 것을 환영합니다!

Perl은 가끔 B<'Practical Extraction and Report Language'>라고 하기도 합니다만
다른 널리 알려진 것들 중에서 B<'Pathologically Eclectic Rubbish Lister'>라고
하기도 합니다. 사실 이것은 끼워 맞춘 것이며 Perl이 이것들의 첫 글자를
가져와서 이름을 붙인 것은 아닙니다. Perl의 창시자 Larry가 첫 번째 이름을
먼저 생각했고 널리 알려진 것을 나중에 지었기 때문입니다. 그렇기 때문에
B<'Perl'>은 모두 대문자가 아닙니다. 널리 알려진 어떤 것을 가지고 논쟁하는
것은 의미가 없습니다. Larry는 두 개 다 지지합니다.

가끔 p가 소문자로 작성된 B<'perl'>을 볼 것입니다. P가 대문자로 되어 있는
B<'Perl'>은 언어를 참조할 때 쓰이며 B<'perl'>처럼 p가 소문자인 경우는 여러분의
프로그램을 컴파일하고 돌릴 때 사용되는 해석기를 지칭할 때 사용됩니다.


=head1 Perl에 관하여

Perl은 본래 문자열 생성을 위해 만들졌지만 지금은 시스템 관리와 웹 개발,
네트워크 프로그래밍, GUI 개발 등을 포함한 여러 분야에서 널리 사용되는
범용 프로그래밍 언어입니다.

이 언어는 아름다움(아주 작고, 우아하고, 아주 적고)보다
실용적(사용하기 쉽고, 효율적이며, 가능한 최대한)인 것을 지향하고 있습니다.
사용하기 쉽고, 절차적 프로그래밍과 객체 지향 프로그래밍을 모두 지원하고,
강력한 문자열 처리 기능을 내장하고, 세상에서 가장 인상적인 제 3자의 모듈
모음처를 가지고 있다는 것은 Perl의 가장 중요한 특징입니다.

Perl의 언어적 특징은 F<pod/perlintro.pod> 문서에서 소개합니다.

이번 릴리스에서 가장 중요한 변화는 F<pod/perldelta.pod>에서 논의합니다.

또한 다양한 출판사가 출판한 많은 Perl 책은 다양한 주제를 다루고 있습니다.
자세한 정보는 F<pod/perlbook.pod> 문서를 확인하세요.


=head1 설치

여러분이 비교적 현대의 운영체제를 사용하고 있고 현재 버전의 Perl을
지역적으로 설치하고 싶다면 다음 명령을 실행하세요.

    ./Configure -des -Dprefix=$HOME/localperl
    make test
    make install

앞의 명령은 여러분의 플랫폼에 맞게 환경을 설정하고 컴파일을 수행한 후,
회기 테스트를 수행한뒤, 홈 디렉터리 하부의 F<localperl> 디렉터리에 perl을
설치합니다.

여러분이 어떠한 문제든 겪게 되거나 사용자 정의 버전 Perl을 설치할 필요가 있다면
현재 배포판에 들어있는 F<INSTALL> 파일 안의 자세한 설명을 읽어야 합니다.
추가적으로 일반적이지 않은 다양한 플랫폼에서 Perl을 빌드하고 사용하는
방법에 대한 도움말과 귀띔이 적혀있는 많은 수의 F<README> 파일이 있습니다.

일단 Perl을 설치하고 나면 C<perldoc> 도구를 이용해 풍부한 문서를 사용할
수 있습니다. 시작하기 위해서 다음 명령을 실행하세요.

    perldoc perl


=head1 실행에 어려움을 겪는다면

Perl은 뜨개질에서 부터 로켓 과학까지 모든 분야에서 사용할 수 있는 크고
복잡한 시스템입니다. 여러분이 어려움에 부딪혔을때 그 문제는 이미 다른
사람이 해결했을 가능성이 높습니다. 문서를 모두 확인했는데도 버그가
확실하다면 C<perlbug> 도구를 이용해서 저희에게 버그를 보고해주세요.
C<perlbug>에 대한 더 자세한 정보는 C<perldoc perlbug> 또는 C<perlbug>를
명령줄에서 실행해서 확인할 수 있습니다.

Perl을 사용 가능하게 만들었다 하더라도 Perl은 계속해서 진화하기 때문에
여러분이 맞닥뜨린 버그를 수정했거나 여러분이 유용하다고 생각할법한
새로운 기능이 추가된 좀 더 최신 버전이 있을 수 있습니다.

여러분은 항상 최신 버전의 perl을 CPAN (Comprehensive Perl Archive Network)
사이트 L<http://www.cpan.org/src/> 에서 찾을 수 있습니다.

perl 소스에 간단한 패치를 등록하고 싶다면 F<pod/perlhack.pod> 문서의
B<"SUPER QUICK PATCH GUIDE">를 살펴보세요.

그냥 개인적으로 참고하세요.
제가 이것처럼 멋진 물건을 만든다는 것을 여러분이 알기를 바랍니다.
그것은 제 이야기의 B<"저자(Author)">를 기쁘게하기 때문입니다.
이것이 여러분을 귀찮게 한다면 여러분의 B<"저작(Authorship)">에
대한 생각을 정정해야 할 수도 있습니다. 하지만 어쨌거나 여러분은
Perl을 사용하는데는 문제가 없답니다. :-)

- B<"저자">로부터.


=head1 인코딩

Perl은 5.8.0판부터 유니코드/ISO 10646에 대해 광범위하게 지원합니다.
유니코드 지원의 일환으로 한중일을 비롯한 세계 각국에서
유니코드 이전에 쓰고 있었고 지금도 널리 쓰이고 있는 수많은 인코딩을
지원합니다. 유니코드는 전 세계에서 쓰이는 모든 언어를 위한
표기 체계(유럽의 라틴 알파벳, 키릴 알파벳, 그리스 알파벳, 인도와 동남 아시아의
브라미 계열 스크립트, 아랍 문자, 히브리 문자, 한중일의 한자, 한국어의 한글,
일본어의 가나, 북미 인디안의 표기 체계 등)를 수용하는 것을 목표로 하고
있기 때문에 기존에 쓰이던  각 언어 및 국가 그리고 운영 체계에 고유한
문자 집합과 인코딩에 쓸 수 있는 모든 글자는 물론이고  기존 문자 집합에서
지원하고 있지 않던 아주 많은 글자를  포함하고 있습니다.

Perl은 내부적으로 유니코드를 문자 표현을 위해 사용합니다.
보다 구체적으로 말하면 Perl 스크립트 안에서  UTF-8 문자열을 쓸 수 있고,
각종 함수와 연산자(예를 들어, 정규식, index, substr)가 바이트 단위
대신 유니코드 글자 단위로 동작합니다.
더 자세한 것은 F<pod/perlunicode.pod> 문서를 참고하세요.
유니코드가 널리 보급되기 전에 널리 쓰이고 있었고, 여전히 널리 쓰이고 있는
각국/각 언어별 인코딩으로 입출력을 하고 이들 인코딩으로 된 데이터와 문서를
다루는 것을 돕기 위해 L<Encode> 모듈이 쓰이고 있습니다.
무엇보다 L<Encode> 모듈을 사용하면 수많은 인코딩 사이의 변환을 쉽게 할 수 있습니다.


=head2 Encode 모듈

=head3 지원 인코딩

L<Encode> 모듈은 다음과 같은 한국어 인코딩을 지원합니다.

=over 4

=item * C<euc-kr>

US-ASCII와 KS X 1001을 같이 쓰는 멀티바이트 인코딩으로 흔히
완성형이라고 불림. KS X 2901과 RFC 1557 참고.

=item * C<cp949>

MS-Windows 9x/ME에서 쓰이는 확장 완성형. euc-kr에 8,822자의
한글 음절을 더한 것임. alias는 uhc, windows-949, x-windows-949,
ks_c_5601-1987. 맨 마지막 이름은 적절하지 않은 이름이지만, Microsoft
제품에서 CP949의 의미로 쓰이고 있음.

=item * C<johab>

KS X 1001:1998 부록 3에서 규정한 조합형. 문자 레퍼토리는 cp949와 마찬가지로
US-ASCII와  KS X 1001에 8,822자의 한글 음절을 더한 것으로 인코딩 방식은 전혀 다름.

=item * C<iso-2022-kr>

RFC 1557에서 규정한 한국어 인터넷 메일 교환용 인코딩으로 US-ASCII와
KS X 1001을 레퍼토리로 하는 점에서 euc-kr과 같지만 인코딩 방식이 다름.
1997-8년 경까지 쓰였으나 더 이상 메일 교환에 쓰이지 않음.

=item * C<ksc5601-raw>

KS X 1001(KS C 5601)을 GL(즉, MSB를 0으로 한 경우)에 놓았을 때의 인코딩.
US-ASCII와 결합하지 않고 단독으로 쓰이는 일은 X11 등에서 글꼴
인코딩(ksc5601.1987-0. '0'은 GL을 의미함)으로 쓰이는 것을 제외하고는
거의 없음. KS C 5601은 1997년 KS X 1001로 이름을 바꾸었음. 1998년에는 두
글자(유로화 부호와 등록 상표 부호)가 더해졌음.

=back

=head3 변환 예제

예를 들어, euc-kr 인코딩으로 된 파일을 UTF-8로 변환하려면
명령줄에서 다음처럼 실행합니다.

    perl -Mencoding=euc-kr,STDOUT,utf8 -pe1 < file.euc-kr > file.utf8

반대로 변환할 경우 다음처럼 실행합니다.

    perl -Mencoding=utf8,STDOUT,euc-kr -pe1 < file.utf8 > file.euc-kr

이런 변환을 좀더 편리하게 할 수 있도록 도와주는 F<piconv>가 Perl에
기본으로 들어있습니다. 이 유틸리티는 L<Encode> 모듈을 이용한 순수 Perl
유틸리티로 이름에서 알 수 있듯이 Unix의 C<iconv>를 모델로 한 것입니다.
사용법은 다음과 같습니다.

   piconv -f euc-kr -t utf8 < file.euc-kr > file.utf8
   piconv -f utf8 -t euc-kr < file.utf8 > file.euc-kr

=head3 모범 사례

Perl은 기본적으로 내부에서 UTF-8을 사용하며 Encode 모듈을 통해
다양한 인코딩을 지원하지만 항상 다음 규칙을 지킴으로써 인코딩과
관련한 다양하게 발생할 수 있는 문제의 가능성을 줄이는 것을 추천합니다.

=over 4

=item * 소스 코드는 항상 UTF-8 인코딩으로 저장

=item * 소스 코드 상단에 C<use utf8;> 프라그마 사용

=item * 소스 코드, 터미널, 운영체제, 데이터 인코딩을 분리해서 이해

=item * 입출력 파일 핸들에 명시적인 인코딩을 사용

=item * 중복(double) 인코딩을 주의

=back


=head3 유니코드 및 한국어 인코딩 관련 자료

=over 4

=item * L<perluniintro>

=item * L<perlunicode>

=item * L<Encode>

=item * L<Encode::KR>

=item * L<encoding>

=item * L<https://www.unicode.org/>

유니코드 컨소시엄

=item * L<http://std.dkuug.dk/JTC1/SC2/WG2>

기본적으로 Unicode와 같은 ISO 표준인  ISO/IEC 10646 UCS(Universal
Character Set)을 만드는 ISO/IEC JTC1/SC2/WG2의 웹 페이지

=item * L<https://www.cl.cam.ac.uk/~mgk25/unicode.html>

유닉스/리눅스 사용자를 위한 UTF-8 및 유니코드 관련 FAQ

=item * L<http://wiki.kldp.org/Translations/html/UTF8-Unicode-KLDP/UTF8-Unicode-KLDP.html>

유닉스/리눅스 사용자를 위한 UTF-8 및 유니코드 관련 FAQ의 한국어 번역

=back


=head1 Perl 관련 자료

다음은 공식적인 Perl 관련 자료중 일부입니다.

=over 4

=item * L<https://www.perl.org/>

Perl 공식 홈페이지

=item * L<https://www.perl.com/>

O'Reilly의 Perl 웹 페이지

=item * L<https://www.cpan.org/>

CPAN - Comprehensive Perl Archive Network, 통합적 Perl 파일 보관 네트워크

=item * L<https://metacpan.org>

메타 CPAN

=item * L<https://lists.perl.org/>

Perl 메일링 리스트

=item * L<http://blogs.perl.org/>

Perl 메타 블로그

=item * L<https://www.perlmonks.org/>

Perl 수도승들을 위한 수도원

=item * L<https://www.pm.org/groups/asia.html>

아시아 지역 Perl 몽거스 모임

=item * L<http://www.perladvent.org/>

Perl 크리스마스 달력

=back


다음은 Perl을 더 깊게 공부하는데 도움을 줄 수 있는 한국어 관련 사이트입니다.

=over 4

=item * L<https://perl.kr/>

한국 Perl 커뮤니티 공식 포털

=item * L<https://doc.perl.kr/>

Perl 문서 한글화 프로젝트

=item * L<https://cafe.naver.com/perlstudy.cafe>

네이버 Perl 카페

=item * L<http://www.perl.or.kr/>

한국 Perl 사용자 모임

=item * L<https://advent.perl.kr>

Seoul.pm Perl 크리스마스 달력 (2010 ~ 2012)

=item * L<http://gypark.pe.kr/wiki/Perl>

GYPARK(Geunyoung Park)의 Perl 관련 한글 문서 저장소

=back


=head1 라이센스

F<README> 파일의 B<'LICENSING'> 항목을 참고하세요.


=head1 AUTHORS

=over

=item * Jarkko Hietaniemi E<lt>jhi@iki.fiE<gt>

=item * 신정식 E<lt>jshin@mailaps.orgE<gt>

=item * 김도형 E<lt>keedi@cpan.orgE<gt>

=back


=cut

# vim: syntax=pod

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
specifically designed to be readable as is.

=head1 NAME

perllinux - Perl version 5 on Linux systems

=head1 DESCRIPTION

This document describes various features of Linux that will affect how Perl
version 5 (hereafter just Perl) is compiled and/or runs.

=head2 Deploying Perl on Linux

Normally one can install F</usr/bin/perl> on Linux using your distribution's
package manager (e.g: C<sudo apt-get install perl>, or
C<sudo dnf install perl>). Note that sometimes one needs to install some
extra system packages in order to be able to use CPAN frontends, and that
messing with the system's perl is not always recommended. One can use
L<perlbrew|https://perlbrew.pl/> to avoid such issues.

Otherwise, perl should build fine on Linux using the mainstream compilers
GCC and clang, while following the usual instructions.

=head2 Experimental Support for Sun Studio Compilers for Linux OS

Sun Microsystems has released a port of their Sun Studio compilers for
Linux.  As of May 2019, the last stable release took place on 2017, and one can
buy support contracts for them.

There are some special instructions for building Perl with Sun Studio on
Linux.  Following the normal C<Configure>, you have to run make as follows:

    LDLOADLIBS=-lc make

C<LDLOADLIBS> is an environment variable used by the linker to link
C</ext> modules to glibc.  Currently, that environment variable is not getting
populated by a combination of C<Config> entries and C<ExtUtil::MakeMaker>.
While there may be a bug somewhere in Perl's configuration or
C<ExtUtil::MakeMaker> causing the problem, the most likely cause is an
incomplete understanding of Sun Studio by this author.  Further investigation
is needed to get this working better.

=head1 AUTHOR

Steve Peters <steve@fisharerojo.org>

Please report any errors, updates, or suggestions to
L<https://github.com/Perl/perl5/issues>.

# vim: syntax=pod

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
specifically designed to be readable as is.

=head1 NAME

perlopenbsd - Perl version 5 on OpenBSD systems

=head1 DESCRIPTION

This document describes various features of OpenBSD that will affect how Perl
version 5 (hereafter just Perl) is compiled and/or runs.

=head2 OpenBSD core dumps from getprotobyname_r and getservbyname_r with ithreads

When Perl is configured to use ithreads, it will use re-entrant library calls
in preference to non-re-entrant versions.  There is an incompatibility in
OpenBSD's C<getprotobyname_r> and C<getservbyname_r> function in versions 3.7
and later that will cause a SEGV when called without doing a C<bzero> on
their return structs prior to calling these functions.  Current Perl's
should handle this problem correctly.  Older threaded Perls (5.8.6 or earlier)
will run into this problem.  If you want to run a threaded Perl on OpenBSD
3.7 or higher, you will need to upgrade to at least Perl 5.8.7.

=head1 AUTHOR

Steve Peters <steve@fisharerojo.org>

Please report any errors, updates, or suggestions to
L<https://github.com/Perl/perl5/issues>.

# vim: syntax=pod

This document is written in pod format hence there are punctuation
characters in odd places. You can read more
about pod in pod/perlpod.pod or the short summary in the INSTALL file.

=head1 NAME

perlos390 - building and installing Perl for z/OS (previously called OS/390)

=head1 SYNOPSIS

This document will help you Configure, build, test and install Perl
on z/OS Unix System Services.

=head1 DESCRIPTION

This is a ported Perl for z/OS. It has been tested on z/OS 2.4 and
should work fine with z/OS 2.5.
It may work on other versions or releases, but those are
the ones it has been tested on.

The native character set for z/OS is EBCDIC, but it can also run in ASCII mode.
Perl can support either, but you have to compile it explicitly for one or the
other.  You could have both an ASCII perl, and an EBCDIC perl on the same
machine.  If you use ASCII mode and an ASCII perl, the Encode module shipped
with perl can be used to translate files from various EBCDIC code pages for
handling by perl, and then back on output

This document describes how to build a 64-bit Dynamic Perl, either ASCII or
EBCDIC.  You can interactively choose other configurations, as well as many
other options in the Configure script that is run as part of the build
process.  You may need to carry out some system configuration tasks before
running Configure, as detailed below.

=head2 Tools

You will want to get GNU make 4.1 or later. GNU make can be downloaded from a
port that Rocket Software provides.  You will need the z/OS c99 compiler from
IBM (though xlc in c99 mode without optimization turned on works in EBCDIC).

If you want the latest development version of Perl, you will need git.
You can use git on another platform and transfer the result via sftp or ftp to
z/OS.  But there is a z/OS native git client port available through Rocket
Software.

You may also need the gunzip client port that Rocket Software provides to unzip
any zipped tarball you upload to z/OS.

=head2 Building a 64-bit Dynamic ASCII Perl

For building from an official stable release of Perl, go to
L<https://www.perl.org/get.html> and choose any one of the
"Download latest stable source" buttons.  This will get you a tarball.  The
name of that tarball will be something like 'perl-V.R.M,tar,gz', where V.R.M is
the version/release/modification of the perl you are downloading. Do

  gunzip perl-V.R.M.tar.gz

Then one of:

  tar -xvf perl-V.R.M.tar

  pax -r -f perl-V.R.M.tar

Either of these will create the source directory.  You can rename it to
whatever you like; for these instructions, 'perl' is assumed to be the name.

If instead you want the latest unstable development release, using the native
git on z/OS, clone Perl:

  git clone https://github.com/Perl/perl5.git perl

Either way, once you have a 'perl' directory containing the source, cd into it,
and tag all the code as ASCII:

  cd perl
  chtag -R -h -t -cISO8859-1 *

Configure the build environment as 64-bit, Dynamic, ASCII, development,
deploying it to F</usr/local/perl/ascii>:

  export PATH=$PWD:$PATH
  export LIBPATH=$PWD:$PATH
  ./Configure -Dprefix=/usr/local/perl/ascii -des -Dusedevel \
        -Duse64bitall -Dusedl

If you are building from a stable source, you don't need "-Dusedevel".
(If you run Configure without options, it will interactively ask you about
every possible option based on its probing of what's available on your
particular machine, so you can choose as you go along.)

Run GNU make to build Perl

  make

Run tests to ensure Perl is working correctly. Currently, there are about a
dozen failing tests out of nearly 2500

  make test_harness

Install Perl into F</usr/local/perl/ascii>:

  make install

=head2 Building a 64-bit Dynamic EBCDIC Perl

You will need a working perl on some box with connectivity to the destination
machine.  On z/OS, it could be an ASCII perl, or a previous EBCDIC one.
Many machines will already have a pre-built perl already running, or one can
easily be downloaded from L<https://www.perl.org/get.html>.

Follow the directions above in "Building a 64-bit Dynamic ASCII Perl" as far as
getting a populated 'perl' directory.  Then come back here to proceed.

The downloaded perl will need to be converted to 1047 EBCDIC.  To do this:

  cd perl
  Porting/makerel -e

If the Porting/makerel step fails with an error that it can not issue the tar
command, proceed to issue the command interactively, where V.R.M is the
version/release/modification of Perl you are uploading:

  cd ../
  tar cf -  --format=ustar perl-V.R.M | gzip --best > perl-V.R.M.tar.gz

Use sftp to upload the zipped tar file to z/OS:

  sftp <your system>
  cd /tmp
  put perl-V.R.M.tar.gz

Unzip and untar the zipped tar file on z/OS:

  cd /tmp
  gunzip perl-V.R.M.tar.gz

Then one of:

  tar -xvf perl-V.R.M.tar

  pax -r -f perl-V.R.M.tar

You now have the source code for the EBCDIC Perl on z/OS and can proceed to
build it. This is analagous to how you would build the code for ASCII, but
note: you B<should not> tag the code but instead leave it untagged.

Configure the build environment as 64-bit, Dynamic, native, development,
deploying it to F</usr/local/perl/ebcdic>:

  export PATH=$PWD:$PATH
  export LIBPATH=$PWD:$PATH
  ./Configure -Dprefix=/usr/local/perl/ebcdic -des -Dusedevel \
        -Duse64bitall -Dusedl

If you are building from a stable source, you don't need "-Dusedevel".
(If you run Configure without options, it will interactively ask you about
every possible option based on its probing of what's available on your
particular machine, so you can choose as you go along.)

Run GNU make to build Perl

  make

Run tests to ensure Perl is working correctly.

  make test_harness

You might also want to have GNU groff for OS/390 installed before
running the "make install" step for Perl.

Install Perl into F</usr/local/perl/ebcdic>:

  make install

EBCDIC Perl is still a work in progress.  All the core code works as far as we
know, but various modules you might want to download from CPAN do not.  The
failures range from very minor to catastrophic.  Many of them are simply bugs
in the tests, with the module actually working properly.  This happens because,
for example, the test is coded to expect a certain character ASCII code point;
when it gets the EBCDIC value back instead, it complains.  But the code
actually worked.  Other potential failures that aren't really failures stem
from checksums coming out differently, since C<A>, for example, has a different
bit representation between the character sets.  A test that is expecting the
ASCII value will show failure, even if the module is working perfectly.  Also
in sorting, uppercase letters come before lowercase letters on ASCII systems;
the reverse on EBCDIC.

Some CPAN modules come bundled with the downloaded perl.  And a few of those
have yet to be fixed to pass on EBCDIC platforms.  As a result they are skipped
when you run 'make test'.  The current list is:

 Archive::Tar
 Config::Perl::V
 CPAN::Meta
 CPAN::Meta::YAML
 Digest::MD5
 Digest::SHA
 Encode
 ExtUtils::MakeMaker
 ExtUtils::Manifest
 HTTP::Tiny
 IO::Compress
 IPC::Cmd
 JSON::PP
 libnet
 MIME::Base64
 Module::Metadata
 PerlIO::via-QuotedPrint
 Pod::Checker
 podlators
 Pod::Simple
 Socket
 Test::Harness

See also F<hints/os390.sh> for other potential gotchas.

=head2 Setup and utilities for Perl on OS/390

This may also be a good time to ensure that your F</etc/protocol> file
and either your F</etc/resolv.conf> or F</etc/hosts> files are in place.
The IBM document that describes such USS system setup issues is
"z/OS UNIX System Services Planning"

For successful testing you may need to turn on the sticky bit for your
world readable /tmp directory if you have not already done so (see man chmod).

=head2 Useful files for trouble-shooting

If your configuration is failing, read hints/os390.sh
This file provides z/OS specific options to direct the build process.

=head3 Shell

A message of the form:

 (I see you are using the Korn shell.  Some ksh's blow up on Configure,
 mainly on older exotic systems.  If yours does, try the Bourne shell
 instead.)

is nothing to worry about at all.

=head3 Dynamic loading

Dynamic loading is required if you want to use XS modules from CPAN (like
DBI (and DBD's), JSON::XS, and Text::CSV_XS) or update CORE modules from
CPAN with newer versions (like Encode) without rebuilding all of the perl
binary.

The instructions above will create a dynamic Perl. If you do not want to
use dynamic loading, remove the -Dusedl option.
See the comments in hints/os390.sh for more information on dynamic loading.

=head3 Optimizing

Optimization has not been turned on yet. There may be issues if Perl
is optimized.

=head2 Build Anomalies with Perl on OS/390

"Out of memory!" messages during the build of Perl are most often fixed
by re building the GNU make utility for OS/390 from a source code kit.

Within USS your F</etc/profile> or F<$HOME/.profile> may limit your ulimit
settings.  Check that the following command returns reasonable values:

    ulimit -a

To conserve memory you should have your compiler modules loaded into the
Link Pack Area (LPA/ELPA) rather than in a link list or step lib.

If the compiler complains of syntax errors during the build of the
Socket extension then be sure to fix the syntax error in the system
header /usr/include/sys/socket.h.

=head2 Testing Anomalies with Perl on OS/390

The "make test" step runs a Perl Verification Procedure, usually before
installation.  You might encounter STDERR messages even during a successful
run of "make test".  Here is a guide to some of the more commonly seen
anomalies:

=head3 Out of Memory (31-bit only)

Out of memory problems should not be an issue, unless you are attempting to build
a 31-bit Perl.

If you _are_ building a 31-bit Perl, the constrained environment may mean you
need to change memory options for Perl.
In addition to the comments
above on memory limitations it is also worth checking for _CEE_RUNOPTS
in your environment. Perl now has (in miniperlmain.c) a C #pragma for 31-bit only
to set CEE run options, but the environment variable wins.

The 31-bit C code asks for:

 #pragma runopts(HEAP(2M,500K,ANYWHERE,KEEP,8K,4K) STACK(,,ANY,) ALL31(ON))

The important parts of that are the second argument (the increment) to HEAP,
and allowing the stack to be "Above the (16M) line". If the heap
increment is too small then when perl (for example loading unicode/Name.pl) tries
to create a "big" (400K+) string it cannot fit in a single segment
and you get "Out of Memory!" - even if there is still plenty of memory
available.

A related issue is use with perl's malloc. Perl's malloc uses C<sbrk()>
to get memory, and C<sbrk()> is limited to the first allocation so in this
case something like:

  HEAP(8M,500K,ANYWHERE,KEEP,8K,4K)

is needed to get through the test suite.

=head2 Usage Hints for Perl on z/OS

When using Perl on z/OS please keep in mind that the EBCDIC and ASCII
character sets are different.  See L<perlebcdic> for more on such character
set issues.  Perl builtin functions that may behave differently under
EBCDIC are also mentioned in the perlport.pod document.

If you are having trouble with square brackets then consider switching your
rlogin or telnet client.  Try to avoid older 3270 emulators and ISHELL for
working with Perl on USS.

=head2 Modules and Extensions for Perl on z/OS (Static Only)

Pure Perl (that is non XS) modules may be installed via the usual:

    perl Makefile.PL
    make
    make test
    make install

If you built perl with dynamic loading capability then that would also
be the way to build XS based extensions.  However, if you built perl with
static linking you can still build XS based extensions for z/OS
but you will need to follow the instructions in ExtUtils::MakeMaker for
building statically linked perl binaries.  In the simplest configurations
building a static perl + XS extension boils down to:

    perl Makefile.PL
    make
    make perl
    make test
    make install
    make -f Makefile.aperl inst_perl MAP_TARGET=perl

=head2 Running Perl on z/OS

To run the 64-bit Dynamic Perl environment, update your PATH and LIBPATH
to include the location you installed Perl into, and then run the perl you
installed as perlV.R.M where V/R/M is the Version/Release/Modification level
of the current development level.
If you are running the ASCII/EBCDIC Bi-Modal Perl environment, you also need to
set up your ASCII/EBCDIC Bi-Modal environment variables, and ensure any Perl
source code you run is tagged appropriately as ASCII or EBCDIC using
"chtag -t -c<CCSID>":

=over

=item For ASCII Only:

 export _BPXK_AUTOCVT=ON
 export _CEE_RUNOPTS="FILETAG(AUTOCVT,AUTOTAG),POSIX(ON)"
 export _TAG_REDIR_ERR="txt"
 export _TAG_REDIR_IN="txt"
 export _TAG_REDIR_OUT="txt"

=item For ASCII or EBCDIC:

 export PATH=/usr/local/perl/ascii:$PATH
 export LIBPATH=/usr/local/perl/ascii/lib:$LIBPATH
 perlV.R.M args

=back

If tcsh is your login shell then use the setenv command.

=head1 AUTHORS

David Fiander and Peter Prymmer with thanks to Dennis Longnecker
and William Raffloer for valuable reports, LPAR and PTF feedback.
Thanks to Mike MacIsaac and Egon Terwedow for SG24-5944-00.
Thanks to Ignasi Roca for pointing out the floating point problems.
Thanks to John Goodyear for dynamic loading help.

Mike Fulton and Karl Williamson have provided updates for UTF8, DLL, 64-bit and
ASCII/EBCDIC Bi-Modal support

=head1 OTHER SITES

L<https://github.com/ZOSOpenTools/perlport/> provides documentation and tools
for building various z/OS Perl configurations and has some useful tools in the
'bin' directory you may want to use for building z/OS Perl yourself.

=head1 HISTORY

Updated 24 December 2021 to enable initial ASCII support

Updated 03 October  2019 for perl-5.33.3+

Updated 28 November 2001 for broken URLs.

Updated 12 March    2001 to mention //'SYS1.TCPPARMS(TCPDATA)'.

Updated 24 January  2001 to mention dynamic loading.

Updated 15 January  2001 for the 5.7.1 release of Perl.

Updated 12 November 2000 for the 5.7.1 release of Perl.

This document was podified for the 5.005_03 release of Perl 11 March 1999.

This document was originally written by David Fiander for the 5.005
release of Perl.

=cut