.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.48) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Required to disable full justification in groff 1.23.0. .if n .ds AD l .\" ======================================================================== .\" .IX Title "PERLOS390 1" .TH PERLOS390 1 2026-10-26 "perl v5.44.0" "Perl Programmers Reference Guide" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME perlos390 \- building and installing Perl for z/OS (previously called OS/390) .SH SYNOPSIS .IX Header "SYNOPSIS" This document will help you Configure, build, test and install Perl on z/OS Unix System Services. .SH DESCRIPTION .IX Header "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. .SS "EBCDIC vs ASCII" .IX Subsection "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 \&\f(CW\*(C`git\*(C'\fR, and yes \f(CW\*(C`Perl\*(C'\fR to take advantage of these new capabilities. (A blog post about its early development is here .) .PP Hiding a machine\*(Aqs 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 \fBOpen Source for z/OS\fR. brings you to its landing page. .PP 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 .PP 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 \fIbuildenv\fR. Refer to "Configuring perl" below for hints on that. Also, refer to "Known Bugs" below. .SS "EBCDIC perl" .IX Subsection "EBCDIC perl" The rest of this document describes how to build a perl that runs native EBCDIC on z/OS. .PP z/OS Unix System Services has a native shell much like \f(CW\*(C`ksh\*(C'\fR or \f(CW\*(C`bash\*(C'\fR, and Unix commands that are similar to ones in Linux, such as \f(CW\*(C`sed\*(C'\fR. Available options for these may differ from the Linux ones. .PP There aren\*(Aqt any known 32\-bit z/OS systems in existence anymore, so this document describes how to build a 64\-bit EBCDIC Perl. .PP 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\*(Aqs 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 \f(CW\*(C`sort\*(C'\fR, 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\*(Aqt give the proper results; but often you just need a consistent sorting, and for that purpose the module could work perfectly well. .PP 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" .SS Tools .IX Subsection "Tools" The tools required for building perl are available as: .IP \(bu 4 native commands on z/OS .Sp z/OS has versions of many tools that come with the Linux OS. Some of these don\*(Aqt have as many options as replacements available in the next group: .IP \(bu 4 through the zopen community .Sp \&\f(CW\*(C`gunzip\*(C'\fR and \f(CW\*(C`clang\*(C'\fR for example. Also you can get \f(CW\*(C`bash\*(C'\fR itself. .IP \(bu 4 at no cost from IBM .Sp . These include GNU make, which you will need. .SS "Building EBCDIC Perl on z/OS" .IX Subsection "Building EBCDIC Perl on z/OS" \fIGetting perl source\fR .IX Subsection "Getting perl source" .PP You\*(Aqll 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. .PP Get an ASCII tarball. Choose one of the following: .IP "Official stable release" 4 .IX Item "Official stable release" Go to and choose any one of the "Download latest Linuxy stable source" buttons. The name of that tarball will be something like \fIperl\-V.R.M,tar,gz\fR, where V.R.M is the version/release/modification of the perl you are downloading. Do .Sp .Vb 2 \& gunzip perl\-V.R.M.tar.gz \& pax \-r \-f perl\-V.R.M.tar .Ve .Sp (or \f(CW\*(C`tar\*(C'\fR instead of \f(CW\*(C`pax\*(C'\fR) .Sp This will create a directory named \fIperl\-V.R.M\fR, which you can rename to be whatever you want. The instructions below assume you choose \fIperl\fR. .IP "Development release" 4 .IX Item "Development release" If instead you want the latest unstable development release, clone Perl: .Sp .Vb 1 \& git clone https://github.com/Perl/perl5.git perl .Ve .PP Either way, after getting the \f(CW\*(C`perl\*(C'\fR directory populated, do .PP .Vb 2 \& cd perl \& perl Porting/makerel \-e .Ve .PP This will use whatever perl already is on the system to create an EBCDIC tarball named \fIperl\-V.R.M.tar.gz\fR. .PP Use \f(CW\*(C`scp\*(C'\fR or \f(CW\*(C`sftp\*(C'\fR to copy the tarball to the target z/OS system. Then, from the directory where it is located, do .PP .Vb 4 \& gunzip perl\-V.R.M.tar.gz \& pax \-r \-f perl\-V.R.M.tar \& mv perl\-V.R.M perl \& cd perl .Ve .PP (You likely can\*(Aqt use \f(CW\*(C`tar\*(C'\fR instead of \f(CW\*(C`pax\*(C'\fR here.) .PP \fIConfiguring perl\fR .IX Subsection "Configuring perl" .PP Now it is time to Configure it to your needs. If you need a dynamically loading perl (see below), first do: .PP .Vb 2 \& export PATH=$PWD:$PATH \& export LIBPATH=$PWD:$LIBPATH .Ve .PP Then run Configure .PP .Vb 2 \& ./Configure \-Dprefix=/path\-to/install/directory \-des \e \& OTHER\-OPTIONS\-AS\-BELOW .Ve .PP \&\f(CW\*(C`\-d\*(C'\fR means to use the default configuration values. This is important, as we have set those up specifically for z/OS. .PP \&\f(CW\*(C`\-e\*(C'\fR means to continue on to the bitter end, not stopping the process early. .PP \&\f(CW\*(C`\-s\*(C'\fR means to avoid unnecessary output verbiage. This parameter is optional. .PP If the perl is an unstable development release, add \f(CW\*(C`\-Dusedevel\*(C'\fR as one of the \&\f(CW\*(C`OTHER\-OPTIONS\-AS\-BELOW\*(C'\fR .PP If you think you may want to debug the perl, add \f(CW\*(C`\-DDEBUGGING \-Aoptimize=\-g3 \&\-Aoptimize=\-ggdb3\*(C'\fR. .PP To silence some unnecessary compilation warnings, you can add \&\f(CW\*(C`\-Accflags=\-Wno\-deprecated\*(C'\fR. .PP To optimize the resultant perl binary, add \f(CW\*(C`\-Aoptimize=\-O2\*(C'\fR, or \f(CW\*(C`\-O3\*(C'\fR, both of which have been tested on z/OS 3.1. .PP If you will want to use modules from CPAN (like \f(CW\*(C`DBI\*(C'\fR (and \f(CW\*(C`DBD\*(C'\fRs), \&\f(CW\*(C`JSON::XS\*(C'\fR, and \f(CW\*(C`Text::CSV_XS\*(C'\fR), consider using dynamic loading. This isn\*(Aqt 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\*(Aqll either need to recompile all of perl when you add one, or set it up initially to use dynamic loading. To do this, add \f(CW\*(C`\-Dusedl\*(C'\fR to the Configure options. .PP When Configure is run using the z/OS native shell, you\*(Aqll see a message like .PP .Vb 3 \& (I see you are using the Korn shell. Some ksh\*(Aqs blow up on Configure, \& mainly on older exotic systems. If yours does, try the Bourne shell \& instead.) .Ve .PP The native shell looks like \f(CW\*(C`ksh\*(C'\fR, and it works fine, so just ignore the message. .PP \&\fIConfigure\fR currently will output errors in finding the header dependencies various object files have. This just means that they may be recompiled unnecessarily. .PP \fIBuilding perl\fR .IX Subsection "Building perl" .PP Run GNU make to build Perl .PP .Vb 1 \& make .Ve .PP This will currently likely crash in making the Encode module. To work around that, execute the following command .PP .Vb 1 \& chtag \-tc IBM\-1047 cpan/Encode/Makefile .Ve .PP and rerun \f(CW\*(C`make\*(C'\fR. You may have to repeat this a second time. .PP \fITesting perl\fR .IX Subsection "Testing perl" .PP .Vb 1 \& TEST_JOBS=n make test_harness .Ve .PP where \fIn\fR 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\*(Aqt crowding out other users) is to set \fIn\fR to twice the number of cores available, plus 1. .PP Some tests currently fail. .PP The failing tests in \f(CW\*(C`Test\-Simple\*(C'\fR, \f(CW\*(C`Pod\-Html\*(C'\fR, \fIop/signatures\fR, and \&\fIio/nargv.t\fR are false alarms. .PP The failing tests in \fIXS\-APItest/t/utf8_warn00.t\fR show that the generated warning for a particular very edge case is not exactly as expected and is somewhat misleading. .PP \fIKnown Bugs\fR .IX Subsection "Known Bugs" .PP If zopen is installed on your machine, it is important to get the \f(CW\*(C`PATH\*(C'\fR 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, \fI/bin/echo\fR needs to have precedence over the zopen version in this case. .PP Bugs in both EBCDIC and ASCII versions .IX Subsection "Bugs in both EBCDIC and ASCII versions" .PP ExtUtils::MakeMaker does not work properly on perls built for dynamic loading. .PP Bugs only in the EBCDIC mode .IX Subsection "Bugs only in the EBCDIC mode" .PP 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 \&\fIt/TEST\fR 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. .PP Fixes for these are under active development. .PP Bugs only in the ASCII mode .IX Subsection "Bugs only in the ASCII mode" .PP Currently, in the zopen port of Perl, there are some issues when using UTF\-8 locales; some of these lead to segfaults. .PP \fIInstalling perl\fR .IX Subsection "Installing perl" .PP .Vb 1 \& make install .Ve .PP will install perl into the directory you gave in the command .PP .Vb 1 \& ./Configure \-Dprefix=/path\-to/install/directory ... .Ve .SS Optimization .IX Subsection "Optimization" Perl is now built using the \f(CW\*(C`clang\*(C'\fR compiler. Previous releases used different compilers, and for them, optimization seemed iffy, so we recommended against doing it. (And we didn\*(Aqt revisit that advice with newer releases to see if things had gotten fixed, so that recommendation may have been outdated.) But with \f(CW\*(C`clang\*(C'\fR it does seem to work, and "Configuring perl" above gives instructions for enabling it. .SS "Installing other modules" .IX Subsection "Installing other modules" Pure Perl (that is non XS) modules may be installed via the usual: .PP .Vb 4 \& perl Makefile.PL \& make \& make test \& make install .Ve .PP 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: .PP .Vb 6 \& perl Makefile.PL \& make \& make perl \& make test \& make install \& make \-f Makefile.aperl inst_perl MAP_TARGET=perl .Ve .SS "Running EBCDIC Perl on z/OS" .IX Subsection "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. .SH AUTHORS .IX Header "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. .PP Mike Fulton and Karl Williamson have provided updates for UTF8, DLL, 64\-bit and ASCII/EBCDIC Bi\-Modal support .SH HISTORY .IX Header "HISTORY" Updated 25 May 2026 to reflect Perl v5.44 and . .PP Updated 24 December 2021 to enable initial ASCII support. .PP Updated 03 October 2019 for perl\-5.33.3+ .PP Updated 28 November 2001 for broken URLs. .PP Updated 12 March 2001 to mention //\*(AqSYS1.TCPPARMS(TCPDATA)\*(Aq. .PP Updated 24 January 2001 to mention dynamic loading. .PP Updated 15 January 2001 for the 5.7.1 release of Perl. .PP Updated 12 November 2000 for the 5.7.1 release of Perl. .PP This document was podified for the 5.005_03 release of Perl 11 March 1999. .PP This document was originally written by David Fiander for the 5.005 release of Perl.