# 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 on z/OS has been tested on z/OS 3.1.
It may work on other versions or releases.

The native character set for z/OS is EBCDIC (code page 1047 in North America),
but recent OS releases have added the ability for individual processes to run
in ASCII mode.  This mode works reasonably well, but there can be glitches.  It
is under active development by IBM.

For background on the ASCII vs EBCDIC modes, see
L<https://makingdeveloperslivesbetter.wordpress.com/2022/01/07/is-z-os-ascii-or-ebcdic-yes/>

Perl can support either mode, 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 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.  The C<iconv> command in z/OS, may also be useful.

z/OS has a native shell much like C<ksh> or C<bash>, and many commands that are
similar to ones in Linux, such as C<sed>.  Available options for these may
differ from the Linux ones.  But not many Open Source tools that a Linux user
might be accustomed to using come with base z/OS.

However, there is now an B<Open Source for z/OS> initiative to bring many such
tools to z/OS users.  L<https://zopen-community> brings you to its landing
page.  If an ASCII perl is sufficient for your needs, you should obtain it
through them, at L<https://zopen-community/perlport>.

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, but may not appear to pass
all their tests.  They can be used in the areas that they do work in.  Also the
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.  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 does
need the ASCII ordering, the module won't give the proper results; but often
you just need a consistent sorting, and for that purpose the module works
perfectly well.

Perl itself is shipped with some CPAN modules included.  Some of these do not
work well on EBCDIC, and therefore testing of them is suppressed.  You can see
which by examining F<t/TEST> and searching for EBCDIC.  Fixing these is under
active development.

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

Then get an ASCII release 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

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 -c -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

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

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

=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 only ones that are real known errors are
in F<io/socket.t>.

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

=head3 Installing perl

 make install

will install perl into the directory you gave in the command

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

=head2 Optimization

Optimization has not been tested.

=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

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

(A blog
post about its early development is here
L<https://makingdeveloperslivesbetter.wordpress.com/2022/01/18/enabling-open-source-for-z-os-perl/>.)