Commit | Line | Data |
---|---|---|
9133bbab | 1 | This document is written in pod format hence there are punctuation |
adcefe44 | 2 | characters in odd places. You can read more |
a83b6f46 | 3 | about pod in pod/perlpod.pod or the short summary in the INSTALL file. |
9d116dd7 | 4 | |
8fde188e GS |
5 | =head1 NAME |
6 | ||
adcefe44 | 7 | perlos390 - building and installing Perl for z/OS (previously called OS/390) |
8fde188e GS |
8 | |
9 | =head1 SYNOPSIS | |
10 | ||
11 | This document will help you Configure, build, test and install Perl | |
adcefe44 | 12 | on z/OS Unix System Services. |
2b7f2baa | 13 | |
8fde188e GS |
14 | =head1 DESCRIPTION |
15 | ||
adcefe44 MF |
16 | This is a ported Perl for z/OS. It has been tested on z/OS 2.4 and |
17 | should work fine with z/OS 2.5. | |
18 | It may work on other versions or releases, but those are | |
19 | the ones it has been tested on. | |
8fde188e | 20 | |
821a824b KW |
21 | The native character set for z/OS is EBCDIC, but it can also run in ASCII mode. |
22 | Perl can support either, but you have to compile it explicitly for one or the | |
23 | other. You could have both an ASCII perl, and an EBCDIC perl on the same | |
24 | machine. If you use ASCII mode and an ASCII perl, the Encode module shipped | |
25 | with perl can be used to translate files from various EBCDIC code pages for | |
26 | handling by perl, and then back on output | |
27 | ||
28 | This document describes how to build a 64-bit Dynamic Perl, either ASCII or | |
29 | EBCDIC. You can interactively choose other configurations, as well as many | |
30 | other options in the Configure script that is run as part of the build | |
31 | process. You may need to carry out some system configuration tasks before | |
32 | running Configure, as detailed below. | |
8fde188e | 33 | |
37a78d01 JH |
34 | =head2 Tools |
35 | ||
821a824b KW |
36 | You will want to get GNU make 4.1 or later. GNU make can be downloaded from a |
37 | port that Rocket Software provides. You will need the z/OS c99 compiler from | |
38 | IBM (though xlc in c99 mode without optimization turned on works in EBCDIC). | |
39 | ||
40 | If you want the latest development version of Perl, you will need git. | |
41 | You can use git on another platform and transfer the result via sftp or ftp to | |
42 | z/OS. But there is a z/OS native git client port available through Rocket | |
43 | Software. | |
44 | ||
45 | You may also need the gunzip client port that Rocket Software provides to unzip | |
46 | any zipped tarball you upload to z/OS. | |
37a78d01 | 47 | |
adcefe44 | 48 | =head2 Building a 64-bit Dynamic ASCII Perl |
37a78d01 | 49 | |
821a824b KW |
50 | For building from an official stable release of Perl, go to |
51 | L<https://www.perl.org/get.html> and choose any one of the | |
52 | "Download latest stable source" buttons. This will get you a tarball. The | |
53 | name of that tarball will be something like 'perl-V.R.M,tar,gz', where V.R.M is | |
54 | the version/release/modification of the perl you are downloading. Do | |
55 | ||
56 | gunzip perl-V.R.M.tar.gz | |
57 | ||
58 | Then one of: | |
59 | ||
60 | tar -xvf perl-V.R.M.tar | |
61 | ||
62 | pax -r -f perl-V.R.M.tar | |
63 | ||
64 | Either of these will create the source directory. You can rename it to | |
65 | whatever you like; for these instructions, 'perl' is assumed to be the name. | |
66 | ||
67 | If instead you want the latest unstable development release, using the native | |
68 | git on z/OS, clone Perl: | |
9d116dd7 | 69 | |
adcefe44 | 70 | git clone https://github.com/Perl/perl5.git perl |
0e7519cd | 71 | |
821a824b KW |
72 | Either way, once you have a 'perl' directory containing the source, cd into it, |
73 | and tag all the code as ASCII: | |
9d116dd7 | 74 | |
adcefe44 MF |
75 | cd perl |
76 | chtag -R -h -t -cISO8859-1 * | |
9d116dd7 | 77 | |
adcefe44 MF |
78 | Configure the build environment as 64-bit, Dynamic, ASCII, development, |
79 | deploying it to F</usr/local/perl/ascii>: | |
9d116dd7 | 80 | |
adcefe44 MF |
81 | export PATH=$PWD:$PATH |
82 | export LIBPATH=$PWD:$PATH | |
83 | ./Configure -Dprefix=/usr/local/perl/ascii -des -Dusedevel \ | |
84 | -Duse64bitall -Dusedl | |
9d116dd7 | 85 | |
821a824b KW |
86 | If you are building from a stable source, you don't need "-Dusedevel". |
87 | (If you run Configure without options, it will interactively ask you about | |
88 | every possible option based on its probing of what's available on your | |
89 | particular machine, so you can choose as you go along.) | |
90 | ||
adcefe44 | 91 | Run GNU make to build Perl |
bfd0ae40 | 92 | |
adcefe44 | 93 | make |
bfd0ae40 | 94 | |
821a824b KW |
95 | Run tests to ensure Perl is working correctly. Currently, there are about a |
96 | dozen failing tests out of nearly 2500 | |
bbee22da | 97 | |
821a824b | 98 | make test_harness |
bbee22da | 99 | |
adcefe44 | 100 | Install Perl into F</usr/local/perl/ascii>: |
0e7519cd | 101 | |
adcefe44 | 102 | make install |
0e7519cd | 103 | |
adcefe44 | 104 | =head2 Building a 64-bit Dynamic EBCDIC Perl |
bbee22da | 105 | |
821a824b KW |
106 | You will need a working perl on some box with connectivity to the destination |
107 | machine. On z/OS, it could be an ASCII perl, or a previous EBCDIC one. | |
108 | Many machines will already have a pre-built perl already running, or one can | |
109 | easily be downloaded from L<https://www.perl.org/get.html>. | |
adcefe44 | 110 | |
821a824b KW |
111 | Follow the directions above in "Building a 64-bit Dynamic ASCII Perl" as far as |
112 | getting a populated 'perl' directory. Then come back here to proceed. | |
adcefe44 | 113 | |
821a824b | 114 | The downloaded perl will need to be converted to 1047 EBCDIC. To do this: |
adcefe44 MF |
115 | |
116 | cd perl | |
117 | Porting/makerel -e | |
118 | ||
119 | If the Porting/makerel step fails with an error that it can not issue the tar | |
120 | command, proceed to issue the command interactively, where V.R.M is the | |
121 | version/release/modification of Perl you are uploading: | |
122 | ||
123 | cd ../ | |
124 | tar cf - --format=ustar perl-V.R.M | gzip --best > perl-V.R.M.tar.gz | |
125 | ||
126 | Use sftp to upload the zipped tar file to z/OS: | |
127 | ||
128 | sftp <your system> | |
129 | cd /tmp | |
130 | put perl-V.R.M.tar.gz | |
8fde188e | 131 | |
adcefe44 | 132 | Unzip and untar the zipped tar file on z/OS: |
8fde188e | 133 | |
adcefe44 MF |
134 | cd /tmp |
135 | gunzip perl-V.R.M.tar.gz | |
821a824b KW |
136 | |
137 | Then one of: | |
138 | ||
adcefe44 | 139 | tar -xvf perl-V.R.M.tar |
8fde188e | 140 | |
821a824b | 141 | pax -r -f perl-V.R.M.tar |
8fde188e | 142 | |
821a824b KW |
143 | You now have the source code for the EBCDIC Perl on z/OS and can proceed to |
144 | build it. This is analagous to how you would build the code for ASCII, but | |
145 | note: you B<should not> tag the code but instead leave it untagged. | |
146 | ||
147 | Configure the build environment as 64-bit, Dynamic, native, development, | |
adcefe44 | 148 | deploying it to F</usr/local/perl/ebcdic>: |
9d116dd7 | 149 | |
adcefe44 MF |
150 | export PATH=$PWD:$PATH |
151 | export LIBPATH=$PWD:$PATH | |
152 | ./Configure -Dprefix=/usr/local/perl/ebcdic -des -Dusedevel \ | |
153 | -Duse64bitall -Dusedl | |
eae55d03 | 154 | |
821a824b KW |
155 | If you are building from a stable source, you don't need "-Dusedevel". |
156 | (If you run Configure without options, it will interactively ask you about | |
157 | every possible option based on its probing of what's available on your | |
158 | particular machine, so you can choose as you go along.) | |
159 | ||
adcefe44 | 160 | Run GNU make to build Perl |
8dd596cc | 161 | |
adcefe44 | 162 | make |
8dd596cc | 163 | |
821a824b KW |
164 | Run tests to ensure Perl is working correctly. |
165 | ||
166 | make test_harness | |
8dd596cc | 167 | |
821a824b KW |
168 | You might also want to have GNU groff for OS/390 installed before |
169 | running the "make install" step for Perl. | |
f2766b05 | 170 | |
adcefe44 | 171 | Install Perl into F</usr/local/perl/ebcdic>: |
eae55d03 | 172 | |
adcefe44 | 173 | make install |
eae55d03 | 174 | |
821a824b KW |
175 | EBCDIC Perl is still a work in progress. All the core code works as far as we |
176 | know, but various modules you might want to download from CPAN do not. The | |
177 | failures range from very minor to catastrophic. Many of them are simply bugs | |
178 | in the tests, with the module actually working properly. This happens because, | |
179 | for example, the test is coded to expect a certain character ASCII code point; | |
180 | when it gets the EBCDIC value back instead, it complains. But the code | |
181 | actually worked. Other potential failures that aren't really failures stem | |
182 | from checksums coming out differently, since C<A>, for example, has a different | |
183 | bit representation between the character sets. A test that is expecting the | |
184 | ASCII value will show failure, even if the module is working perfectly. Also | |
185 | in sorting, uppercase letters come before lowercase letters on ASCII systems; | |
186 | the reverse on EBCDIC. | |
187 | ||
188 | Some CPAN modules come bundled with the downloaded perl. And a few of those | |
189 | have yet to be fixed to pass on EBCDIC platforms. As a result they are skipped | |
190 | when you run 'make test'. The current list is: | |
191 | ||
192 | Archive::Tar | |
193 | Config::Perl::V | |
194 | CPAN::Meta | |
195 | CPAN::Meta::YAML | |
196 | Digest::MD5 | |
197 | Digest::SHA | |
198 | Encode | |
199 | ExtUtils::MakeMaker | |
200 | ExtUtils::Manifest | |
201 | HTTP::Tiny | |
202 | IO::Compress | |
203 | IPC::Cmd | |
204 | JSON::PP | |
205 | libnet | |
206 | MIME::Base64 | |
207 | Module::Metadata | |
208 | PerlIO::via-QuotedPrint | |
209 | Pod::Checker | |
210 | podlators | |
211 | Pod::Simple | |
212 | Socket | |
213 | Test::Harness | |
214 | ||
215 | See also F<hints/os390.sh> for other potential gotchas. | |
216 | ||
adcefe44 MF |
217 | =head2 Setup and utilities for Perl on OS/390 |
218 | ||
219 | This may also be a good time to ensure that your F</etc/protocol> file | |
220 | and either your F</etc/resolv.conf> or F</etc/hosts> files are in place. | |
221 | The IBM document that describes such USS system setup issues is | |
222 | "z/OS UNIX System Services Planning" | |
eae55d03 | 223 | |
9133bbab | 224 | For successful testing you may need to turn on the sticky bit for your |
eae55d03 PK |
225 | world readable /tmp directory if you have not already done so (see man chmod). |
226 | ||
adcefe44 | 227 | =head2 Useful files for trouble-shooting |
8fde188e | 228 | |
adcefe44 MF |
229 | If your configuration is failing, read hints/os390.sh |
230 | This file provides z/OS specific options to direct the build process. | |
8fde188e | 231 | |
92ad49c1 | 232 | =head3 Shell |
8fde188e | 233 | |
eae55d03 PK |
234 | A message of the form: |
235 | ||
92ad49c1 | 236 | (I see you are using the Korn shell. Some ksh's blow up on Configure, |
adcefe44 MF |
237 | mainly on older exotic systems. If yours does, try the Bourne shell |
238 | instead.) | |
eae55d03 PK |
239 | |
240 | is nothing to worry about at all. | |
241 | ||
92ad49c1 MB |
242 | =head3 Dynamic loading |
243 | ||
244 | Dynamic loading is required if you want to use XS modules from CPAN (like | |
245 | DBI (and DBD's), JSON::XS, and Text::CSV_XS) or update CORE modules from | |
246 | CPAN with newer versions (like Encode) without rebuilding all of the perl | |
247 | binary. | |
8fde188e | 248 | |
adcefe44 MF |
249 | The instructions above will create a dynamic Perl. If you do not want to |
250 | use dynamic loading, remove the -Dusedl option. | |
f2766b05 | 251 | See the comments in hints/os390.sh for more information on dynamic loading. |
92ad49c1 MB |
252 | |
253 | =head3 Optimizing | |
9d116dd7 | 254 | |
adcefe44 MF |
255 | Optimization has not been turned on yet. There may be issues if Perl |
256 | is optimized. | |
8fde188e | 257 | |
a83b6f46 | 258 | =head2 Build Anomalies with Perl on OS/390 |
eae55d03 PK |
259 | |
260 | "Out of memory!" messages during the build of Perl are most often fixed | |
261 | by re building the GNU make utility for OS/390 from a source code kit. | |
262 | ||
adcefe44 | 263 | Within USS your F</etc/profile> or F<$HOME/.profile> may limit your ulimit |
eae55d03 PK |
264 | settings. Check that the following command returns reasonable values: |
265 | ||
266 | ulimit -a | |
267 | ||
821a824b KW |
268 | To conserve memory you should have your compiler modules loaded into the |
269 | Link Pack Area (LPA/ELPA) rather than in a link list or step lib. | |
270 | ||
271 | If the compiler complains of syntax errors during the build of the | |
272 | Socket extension then be sure to fix the syntax error in the system | |
273 | header /usr/include/sys/socket.h. | |
274 | ||
a83b6f46 | 275 | =head2 Testing Anomalies with Perl on OS/390 |
eae55d03 | 276 | |
b432a672 | 277 | The "make test" step runs a Perl Verification Procedure, usually before |
eae55d03 | 278 | installation. You might encounter STDERR messages even during a successful |
b432a672 | 279 | run of "make test". Here is a guide to some of the more commonly seen |
eae55d03 PK |
280 | anomalies: |
281 | ||
adcefe44 | 282 | =head3 Out of Memory (31-bit only) |
eae55d03 | 283 | |
adcefe44 MF |
284 | Out of memory problems should not be an issue, unless you are attempting to build |
285 | a 31-bit Perl. | |
eae55d03 | 286 | |
adcefe44 MF |
287 | If you _are_ building a 31-bit Perl, the constrained environment may mean you |
288 | need to change memory options for Perl. | |
289 | In addition to the comments | |
9133bbab | 290 | above on memory limitations it is also worth checking for _CEE_RUNOPTS |
adcefe44 | 291 | in your environment. Perl now has (in miniperlmain.c) a C #pragma for 31-bit only |
210b36aa | 292 | to set CEE run options, but the environment variable wins. |
9133bbab | 293 | |
adcefe44 | 294 | The 31-bit C code asks for: |
9133bbab NIS |
295 | |
296 | #pragma runopts(HEAP(2M,500K,ANYWHERE,KEEP,8K,4K) STACK(,,ANY,) ALL31(ON)) | |
297 | ||
298 | The important parts of that are the second argument (the increment) to HEAP, | |
299 | and allowing the stack to be "Above the (16M) line". If the heap | |
210b36aa AMS |
300 | increment is too small then when perl (for example loading unicode/Name.pl) tries |
301 | to create a "big" (400K+) string it cannot fit in a single segment | |
9133bbab NIS |
302 | and you get "Out of Memory!" - even if there is still plenty of memory |
303 | available. | |
304 | ||
305 | A related issue is use with perl's malloc. Perl's malloc uses C<sbrk()> | |
306 | to get memory, and C<sbrk()> is limited to the first allocation so in this | |
307 | case something like: | |
308 | ||
309 | HEAP(8M,500K,ANYWHERE,KEEP,8K,4K) | |
310 | ||
311 | is needed to get through the test suite. | |
312 | ||
adcefe44 | 313 | =head2 Usage Hints for Perl on z/OS |
f2766b05 | 314 | |
adcefe44 | 315 | When using Perl on z/OS please keep in mind that the EBCDIC and ASCII |
c1f48c09 | 316 | character sets are different. See L<perlebcdic> for more on such character |
9133bbab | 317 | set issues. Perl builtin functions that may behave differently under |
eae55d03 | 318 | EBCDIC are also mentioned in the perlport.pod document. |
9d116dd7 | 319 | |
59c9e5d6 | 320 | If you are having trouble with square brackets then consider switching your |
9133bbab | 321 | rlogin or telnet client. Try to avoid older 3270 emulators and ISHELL for |
59c9e5d6 PP |
322 | working with Perl on USS. |
323 | ||
adcefe44 | 324 | =head2 Modules and Extensions for Perl on z/OS (Static Only) |
eae55d03 | 325 | |
393dcb6c | 326 | Pure Perl (that is non XS) modules may be installed via the usual: |
eae55d03 PK |
327 | |
328 | perl Makefile.PL | |
329 | make | |
330 | make test | |
331 | make install | |
332 | ||
f2766b05 | 333 | If you built perl with dynamic loading capability then that would also |
92ad49c1 | 334 | be the way to build XS based extensions. However, if you built perl with |
adcefe44 | 335 | static linking you can still build XS based extensions for z/OS |
9133bbab NIS |
336 | but you will need to follow the instructions in ExtUtils::MakeMaker for |
337 | building statically linked perl binaries. In the simplest configurations | |
92ad49c1 | 338 | building a static perl + XS extension boils down to: |
9d116dd7 | 339 | |
eae55d03 PK |
340 | perl Makefile.PL |
341 | make | |
342 | make perl | |
343 | make test | |
344 | make install | |
345 | make -f Makefile.aperl inst_perl MAP_TARGET=perl | |
8fde188e | 346 | |
adcefe44 | 347 | =head2 Running Perl on z/OS |
8fde188e | 348 | |
adcefe44 MF |
349 | To run the 64-bit Dynamic Perl environment, update your PATH and LIBPATH |
350 | to include the location you installed Perl into, and then run the perl you | |
351 | installed as perlV.R.M where V/R/M is the Version/Release/Modification level | |
352 | of the current development level. | |
821a824b KW |
353 | If you are running the ASCII/EBCDIC Bi-Modal Perl environment, you also need to |
354 | set up your ASCII/EBCDIC Bi-Modal environment variables, and ensure any Perl | |
355 | source code you run is tagged appropriately as ASCII or EBCDIC using | |
356 | "chtag -t -c<CCSID>": | |
357 | ||
358 | =over | |
f2766b05 | 359 | |
821a824b | 360 | =item For ASCII Only: |
f2766b05 | 361 | |
821a824b KW |
362 | export _BPXK_AUTOCVT=ON |
363 | export _CEE_RUNOPTS="FILETAG(AUTOCVT,AUTOTAG),POSIX(ON)" | |
364 | export _TAG_REDIR_ERR="txt" | |
365 | export _TAG_REDIR_IN="txt" | |
366 | export _TAG_REDIR_OUT="txt" | |
adcefe44 | 367 | |
821a824b | 368 | =item For ASCII or EBCDIC: |
adcefe44 | 369 | |
821a824b KW |
370 | export PATH=/usr/local/perl/ascii:$PATH |
371 | export LIBPATH=/usr/local/perl/ascii/lib:$LIBPATH | |
372 | perlV.R.M args | |
373 | ||
374 | =back | |
375 | ||
376 | If tcsh is your login shell then use the setenv command. | |
f2766b05 | 377 | |
8fde188e GS |
378 | =head1 AUTHORS |
379 | ||
eae55d03 PK |
380 | David Fiander and Peter Prymmer with thanks to Dennis Longnecker |
381 | and William Raffloer for valuable reports, LPAR and PTF feedback. | |
382 | Thanks to Mike MacIsaac and Egon Terwedow for SG24-5944-00. | |
35a77668 | 383 | Thanks to Ignasi Roca for pointing out the floating point problems. |
f2766b05 | 384 | Thanks to John Goodyear for dynamic loading help. |
8fde188e | 385 | |
821a824b KW |
386 | Mike Fulton and Karl Williamson have provided updates for UTF8, DLL, 64-bit and |
387 | ASCII/EBCDIC Bi-Modal support | |
8fde188e | 388 | |
821a824b | 389 | =head1 OTHER SITES |
9d116dd7 | 390 | |
adcefe44 MF |
391 | L<https://github.com/ZOSOpenTools/perlport/> provides documentation and tools |
392 | for building various z/OS Perl configurations and has some useful tools in the | |
393 | 'bin' directory you may want to use for building z/OS Perl yourself. | |
9d116dd7 | 394 | |
8fde188e GS |
395 | =head1 HISTORY |
396 | ||
adcefe44 | 397 | Updated 24 December 2021 to enable initial ASCII support |
8fde188e | 398 | |
adcefe44 | 399 | Updated 03 October 2019 for perl-5.33.3+ |
eae55d03 | 400 | |
adcefe44 | 401 | Updated 28 November 2001 for broken URLs. |
8fde188e | 402 | |
adcefe44 | 403 | Updated 12 March 2001 to mention //'SYS1.TCPPARMS(TCPDATA)'. |
92ad49c1 MB |
404 | |
405 | Updated 24 January 2001 to mention dynamic loading. | |
35a77668 | 406 | |
adcefe44 | 407 | Updated 15 January 2001 for the 5.7.1 release of Perl. |
92ad49c1 | 408 | |
adcefe44 | 409 | Updated 12 November 2000 for the 5.7.1 release of Perl. |
f2766b05 | 410 | |
adcefe44 | 411 | This document was podified for the 5.005_03 release of Perl 11 March 1999. |
59c9e5d6 | 412 | |
adcefe44 MF |
413 | This document was originally written by David Fiander for the 5.005 |
414 | release of Perl. | |
821a824b | 415 | |
8fde188e | 416 | =cut |
eae55d03 | 417 |