PERLOS390(1) Perl Programmers Reference Guide PERLOS390(1) NAME perlos390 - building and installing Perl for z/OS (previously called OS/390) SYNOPSIS This document will help you Configure, build, test and install Perl on z/OS Unix System Services. 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. EBCDIC vs ASCII The native character set for z/OS is EBCDIC (code page 1047 in North Amer- ica), 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 "git", and yes "Perl" to take advantage of these new capabilities. (A blog post about its early development is here .) 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 signifi- cant contributions by IBM of staff and machine time. The project is called Open Source for z/OS. 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 You can obtain this Perl port at . 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 buildenv. Refer to "Configuring perl" below for hints on that. Also, refer to "Known Bugs" below. 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 "ksh" or "bash", and Unix commands that are similar to ones in Linux, such as "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 "sort", ASCII will have the digits first, uppercase letters next, and lowercase last. EBCDIC sorts the oppo- site. 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 "Bugs only in the EBCDIC mode" Tools The tools required for building perl are available as: * 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: * through the zopen community "gunzip" and "clang" for example. Also you can get "bash" itself. * at no cost from IBM . These include GNU make, which you will need. Building EBCDIC Perl on z/OS 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: Official stable release Go to and choose any one of the "Down- load latest Linuxy stable source" buttons. The name of that tarball will be something like perl-V.R.M,tar,gz, where V.R.M is the ver- sion/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 "tar" instead of "pax") This will create a directory named perl-V.R.M, which you can rename to be whatever you want. The instructions below assume you choose perl. Development release If instead you want the latest unstable development release, clone Perl: git clone https://github.com/Perl/perl5.git perl Either way, after getting the "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 perl-V.R.M.tar.gz. Use "scp" or "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 "tar" instead of "pax" here.) 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 "-d" means to use the default configuration values. This is important, as we have set those up specifically for z/OS. "-e" means to continue on to the bitter end, not stopping the process early. "-s" means to avoid unnecessary output verbiage. This parameter is op- tional. If the perl is an unstable development release, add "-Dusedevel" as one of the "OTHER-OPTIONS-AS-BELOW" If you think you may want to debug the perl, add "-DDEBUGGING -Aopti- mize=-g3 -Aoptimize=-ggdb3". To silence some unnecessary compilation warnings, you can add "-Ac- cflags=-Wno-deprecated". To optimize the resultant perl binary, add "-Aoptimize=-O2", or "-O3", both of which have been tested on z/OS 3.1. If you will want to use modules from CPAN (like "DBI" (and "DBD"s), "JSON::XS", and "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 "-Dusedl" to the Config- ure 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 "ksh", and it works fine, so just ignore the message. Configure currently will output errors in finding the header dependencies various object files have. This just means that they may be recompiled un- necessarily. 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 "make". You may have to repeat this a second time. Testing perl TEST_JOBS=n make test_harness where 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 n to twice the number of cores available, plus 1. Some tests currently fail. The failing tests in "Test-Simple", "Pod-Html", op/signatures, and io/nargv.t are false alarms. The failing tests in 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. Known Bugs If zopen is installed on your machine, it is important to get the "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, /bin/echo needs to have precedence over the zopen version in this case. Bugs in both EBCDIC and ASCII versions ExtUtils::MakeMaker does not work properly on perls built for dynamic load- ing. 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 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, 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. 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. Installing perl make install will install perl into the directory you gave in the command ./Configure -Dprefix=/path-to/install/directory ... Optimization Perl is now built using the "clang" compiler. Previous releases used dif- ferent 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 "clang" it does seem to work, and "Configuring perl" above gives instructions for enabling it. 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 sta- tic linking you can still build XS based extensions for z/OS but you will need to follow the instructions in ExtUtils::MakeMaker for building stati- cally linked perl binaries. In the simplest configurations building a sta- tic 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 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 in- stalled as perlV.R.M where V/R/M is the Version/Release/Modification level of the current development level. 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 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. perl v5.44.0 2026-06-29 PERLOS390(1)