# 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

Perl 5.44 on z/OS has been tested on z/OS 3.1 using "Unix System Services".
There have been extensive changes in the build process (such as using a
different compiler) from earlier releases, which were tested on earlier
versions of z/OS.  It could well be that this release of Perl will work on
different z/OS versions.

=head2 EBCDIC vs ASCII

The native character set for z/OS is EBCDIC (code page 1047 in North America),
but recent z/OS releases have added the ability for it to handle ASCII as well.
And an open source project now exists to port many open source tools, such as
C<git>, and yes C<Perl> to take advantage of these new capabilities.  (A blog
post about its early development is here
L<https://makingdeveloperslivesbetter.wordpress.com/2022/01/18/enabling-open-source-for-z-os-perl/>.)

Hiding a machine's character set without sacrificing too much performance
requires extensive wizardry, not all of which is transparent, and not all of
which yet works.  The project is being actively developed with significant
contributions by IBM of staff and machine time.  The project is called B<Open
Source for z/OS>.  L<https://zopen-community> brings you to its landing page.

Basically, files and streams need to have extra information about their
character set.  This can easily require manual intervention to get things to
work.  For background, including what steps you must do to get this to work
on your inputs, see
L<https://makingdeveloperslivesbetter.wordpress.com/2022/01/07/is-z-os-ascii-or-ebcdic-yes/>

You can obtain this Perl port at L<https://zopen-community/perlport>.  At the
moment this is written, one configuration of perl is available: dynamic
loading, unthreaded, non-debugging.  You can customize it to some extent by
modifying the file F<buildenv>.  Refer to L</Configuring perl> below for hints
on that.  Also, refer to L</Known Bugs> below.

=head2 EBCDIC perl

The rest of this document describes how to build a perl that runs native EBCDIC
on z/OS.

z/OS Unix System Services has a native shell much like C<ksh> or C<bash>, and
Unix commands that are similar to ones in Linux, such as C<sed>.  Available
options for these may differ from the Linux ones.

There aren't any known 32-bit z/OS systems in existence anymore, so this
document describes how to build a 64-bit EBCDIC Perl.

Most CPAN modules have been written assuming ASCII.  They may or may not work
on EBCDIC.  What we have found is that many do work, either mostly or
completely, but may not appear to pass all their tests.  Often the failures are
in edge cases that may not come up in mainstream uses.  Also any given failure
may not actually be a real failure, but a problem with the test.  This is
because the typical test compares results with expected values which the test's
author often hard-coded assuming ASCII, so the test is wrong, and the code is
correct.  Also, some failures may not be important for you.  For example, if you
do a plain C<sort>, ASCII will have the digits first, uppercase letters next,
and lowercase last.  EBCDIC sorts the opposite.  If your application really
needs ASCII ordering, the module won't give the proper results; but often you
just need a consistent sorting, and for that purpose the module could work
perfectly well.

Perl itself is shipped with some CPAN modules included.  Some of these do not
yet work fully on EBCDIC, and therefore testing of them is suppressed.  See
L</Bugs only in the EBCDIC mode>

=head2 Tools

The tools required for building perl are available as:

=over

=item * native commands on z/OS

z/OS has versions of many tools that come with the Linux OS.  Some of these
don't have as many options as replacements available in the next group:

=item * through the zopen community

C<gunzip> and C<clang> for example.  Also you can get C<bash> itself.

=item * at no cost from IBM

L<https://www.ibm.com/products/open-enterprise-foundation-zos>.  These
include GNU make, which you will need.

=back

=head2 Building EBCDIC Perl on z/OS

=head3 Getting perl source

You'll first need a tarball.  At the moment this is written, there are no
EBCDIC tarballs published, but it is easy to create one given that you have
access to a system with any relatively modern perl.

Get an ASCII tarball.  Choose one of the following:

=over 4

=item Official stable release

Go to L<https://www.perl.org/get.html> and choose any one of the "Download
latest Linuxy stable source" buttons.  The name of that tarball will be
something like I<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
  pax -r -f perl-V.R.M.tar

(or C<tar> instead of C<pax>)

This will create a directory named I<perl-V.R.M>, which you can rename to be
whatever you want.  The instructions below assume you choose F<perl>.

=item Development release

If instead you want the latest unstable development release, clone Perl:

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

=back

Either way, after getting the C<perl> directory populated, do

  cd perl
  perl Porting/makerel -e

This will use whatever perl already is on the system to create an EBCDIC
tarball named I<perl-V.R.M.tar.gz>.

Use C<scp> or C<sftp> to copy the tarball to the target z/OS system. Then, from
the directory where it is located, do

  gunzip perl-V.R.M.tar.gz
  pax -r -f perl-V.R.M.tar
  mv perl-V.R.M perl
  cd perl

(You likely can't use C<tar> instead of C<pax> here.)

=head3 Configuring perl

Now it is time to Configure it to your needs.  If you need a dynamically
loading perl (see below), first do:

  export PATH=$PWD:$PATH
  export LIBPATH=$PWD:$LIBPATH

Then run Configure

  ./Configure -Dprefix=/path-to/install/directory -des \
                                OTHER-OPTIONS-AS-BELOW

C<-d> means to use the default configuration values.  This is important, as we
have set those up specifically for z/OS.

C<-e> means to continue on to the bitter end, not stopping the process early.

C<-s> means to avoid unnecessary output verbiage.  This parameter is optional.

If the perl is an unstable development release, add C<-Dusedevel> as one of the
C<OTHER-OPTIONS-AS-BELOW>

If you think you may want to debug the perl, add C<-DDEBUGGING -Aoptimize=-g3
-Aoptimize=-ggdb3>.

To silence some unnecessary compilation warnings, you can add
C<-Accflags=-Wno-deprecated>.

To optimize the resultant perl binary, add C<-Aoptimize=-O2>, or C<-O3>, both
of which have been tested on z/OS 3.1.  

If you will want to use modules from CPAN (like C<DBI> (and C<DBD>s),
C<JSON::XS>, and C<Text::CSV_XS>), consider using dynamic loading.  This isn't
necessary if all such modules you might want are written only in Perl, but if
some of them are compiled (meaning they contain XS code), you'll either need to
recompile all of perl when you add one, or set it up initially to use dynamic
loading.  To do this, add C<-Dusedl> to the Configure options.

When Configure is run using the z/OS native shell, you'll see a message like

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

The native shell looks like C<ksh>, and it works fine, so just ignore the
message.

F<Configure> currently will output errors in finding the header dependencies
various object files have.  This just means that they may be recompiled
unnecessarily.

=head3 Building perl

Run GNU make to build Perl

  make

This will currently likely crash in making the Encode module.  To work around
that, execute the following command

 chtag -tc IBM-1047 cpan/Encode/Makefile

and rerun C<make>.  You may have to repeat this a second time.

=head3 Testing perl

  TEST_JOBS=n make test_harness

where I<n> is the number of tests to run in parallel.  On hardware that is
single core, 2 or 3 work well.  A common value (if you aren't crowding out
other users) is to set I<n> to twice the number of cores available, plus 1.

Some tests currently fail.

The failing tests in C<Test-Simple>, C<Pod-Html>, F<op/signatures>, and
F<io/nargv.t> are false alarms.

The failing tests in F<XS-APItest/t/utf8_warn00.t> show that the generated
warning for a particular very edge case is not exactly as expected and is
somewhat misleading.

=head3 Known Bugs

If zopen is installed on your machine, it is important to get the C<PATH>
variable correct.  When running the zopen port of Perl, its directories should
come first.  When running the EBCDIC perl, the zopen directories should either
not be in the PATH variable, or come last.  For example, F</bin/echo> needs to
have precedence over the zopen version in this case.

=head4 Bugs in both EBCDIC and ASCII versions

ExtUtils::MakeMaker does not work properly on perls built for dynamic loading.

=head4 Bugs only in the EBCDIC mode

Some cpan modules shipped with perl do not yet work fully on EBCDIC, and
therefore testing of them is suppressed.  You can see which by examining
F<t/TEST> and searching for EBCDIC.  Almost all of the problems with these are
in the cases where their input is from some other encoding.  These could be
because they communicate with a remote ASCII system, or read from a file
containing some other encoding.  So, for example, L<Pod::Simple> works fine on
files encoded in EBCDIC, but will fail miserably for files encoded in a
Cyrillic encoding.

Fixes for these are under active development.

=head4 Bugs only in the ASCII mode

Currently, in the zopen port of Perl, there are some issues when using UTF-8
locales; some of these lead to segfaults.

=head3 Installing perl

 make install

will install perl into the directory you gave in the command

  ./Configure -Dprefix=/path-to/install/directory ...

=head2 Optimization

Perl is now built using the C<clang> compiler.  Previous releases used
different compilers, and for them, optimization seemed iffy, so we recommended
against doing it.  (And we didn't revisit that advice with newer releases to
see if things had gotten fixed, so that recommendation may have been outdated.)
But with C<clang> it does seem to work, and L</Configuring perl> above gives
instructions for enabling it.

=head2 Installing other modules

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

=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 HISTORY

Updated 25 May 2026 to reflect Perl v5.44 and L<https://zopen-community>.

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
