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. | |
20 | There are many ways you can build Perl for z/OS. This document | |
21 | will describe how to build a 64-bit Dynamic EBCDIC Perl as well as a | |
22 | 64-bit Dynamic ASCII Perl. | |
8fde188e | 23 | |
9133bbab NIS |
24 | You may need to carry out some system configuration tasks before |
25 | running the Configure script for Perl. | |
8fde188e | 26 | |
37a78d01 JH |
27 | =head2 Tools |
28 | ||
adcefe44 MF |
29 | You will want to get GNU make 4.1 or later. GNU make can be downloaded from a port |
30 | that Rocket Software provides. | |
31 | You will need the z/OS c99 compiler from IBM. | |
32 | You can also obtain a z/OS native git client port that Rocket Software | |
33 | provides. This is optional - you can use git on another platform and | |
34 | transfer the code via ftp to z/OS | |
35 | For EBCDIC only, you will need gunzip client port that Rocket Software provides | |
36 | to unzip the zipped tarball you upload to z/OS | |
37a78d01 | 37 | |
adcefe44 | 38 | =head2 Building a 64-bit Dynamic ASCII Perl |
37a78d01 | 39 | |
adcefe44 | 40 | Using the native git on z/OS, clone Perl: |
9d116dd7 | 41 | |
adcefe44 | 42 | git clone https://github.com/Perl/perl5.git perl |
0e7519cd | 43 | |
adcefe44 | 44 | Change into the perl directory and tag all the code as ASCII: |
9d116dd7 | 45 | |
adcefe44 MF |
46 | cd perl |
47 | chtag -R -h -t -cISO8859-1 * | |
9d116dd7 | 48 | |
adcefe44 MF |
49 | Configure the build environment as 64-bit, Dynamic, ASCII, development, |
50 | deploying it to F</usr/local/perl/ascii>: | |
9d116dd7 | 51 | |
adcefe44 MF |
52 | export PATH=$PWD:$PATH |
53 | export LIBPATH=$PWD:$PATH | |
54 | ./Configure -Dprefix=/usr/local/perl/ascii -des -Dusedevel \ | |
55 | -Duse64bitall -Dusedl | |
9d116dd7 | 56 | |
adcefe44 | 57 | Run GNU make to build Perl |
bfd0ae40 | 58 | |
adcefe44 | 59 | make |
bfd0ae40 | 60 | |
adcefe44 | 61 | Run tests to ensure Perl is working correctly. Currently, there are 33 failing tests out of 2479 |
bbee22da | 62 | |
adcefe44 | 63 | make tests |
bbee22da | 64 | |
adcefe44 | 65 | Install Perl into F</usr/local/perl/ascii>: |
0e7519cd | 66 | |
adcefe44 | 67 | make install |
0e7519cd | 68 | |
adcefe44 | 69 | =head2 Building a 64-bit Dynamic EBCDIC Perl |
bbee22da | 70 | |
adcefe44 MF |
71 | Using the native git on a platform other than z/OS, (e.g. Mac, Windows, Linux) clone Perl: |
72 | ||
73 | git clone https://github.com/Perl/perl5.git perl | |
74 | ||
75 | Change into the perl directory and modify the source so it is suitable for building on z/OS | |
76 | ||
77 | cd perl | |
78 | Porting/makerel -e | |
79 | ||
80 | If the Porting/makerel step fails with an error that it can not issue the tar | |
81 | command, proceed to issue the command interactively, where V.R.M is the | |
82 | version/release/modification of Perl you are uploading: | |
83 | ||
84 | cd ../ | |
85 | tar cf - --format=ustar perl-V.R.M | gzip --best > perl-V.R.M.tar.gz | |
86 | ||
87 | Use sftp to upload the zipped tar file to z/OS: | |
88 | ||
89 | sftp <your system> | |
90 | cd /tmp | |
91 | put perl-V.R.M.tar.gz | |
8fde188e | 92 | |
adcefe44 | 93 | Unzip and untar the zipped tar file on z/OS: |
8fde188e | 94 | |
adcefe44 MF |
95 | cd /tmp |
96 | gunzip perl-V.R.M.tar.gz | |
97 | tar -xvf perl-V.R.M.tar | |
8fde188e | 98 | |
adcefe44 MF |
99 | You now have the source code for the EBCDIC Perl on z/OS and can proceed to build it. This is analagous to how you |
100 | would build the code for ASCII, but note: you B<should not> tag the code but instead leave it untagged. | |
8fde188e | 101 | |
adcefe44 MF |
102 | Configure the build environment as 64-bit, Dynamic, ASCII, development, |
103 | deploying it to F</usr/local/perl/ebcdic>: | |
9d116dd7 | 104 | |
adcefe44 MF |
105 | export PATH=$PWD:$PATH |
106 | export LIBPATH=$PWD:$PATH | |
107 | ./Configure -Dprefix=/usr/local/perl/ebcdic -des -Dusedevel \ | |
108 | -Duse64bitall -Dusedl | |
eae55d03 | 109 | |
adcefe44 | 110 | Run GNU make to build Perl |
8dd596cc | 111 | |
adcefe44 | 112 | make |
8dd596cc | 113 | |
adcefe44 | 114 | Run tests to ensure Perl is working correctly. Currently, there are 99 tests failing out of 1949 |
8dd596cc | 115 | |
adcefe44 | 116 | make tests |
f2766b05 | 117 | |
adcefe44 | 118 | Install Perl into F</usr/local/perl/ebcdic>: |
eae55d03 | 119 | |
adcefe44 | 120 | make install |
eae55d03 | 121 | |
adcefe44 MF |
122 | =head2 Setup and utilities for Perl on OS/390 |
123 | ||
124 | This may also be a good time to ensure that your F</etc/protocol> file | |
125 | and either your F</etc/resolv.conf> or F</etc/hosts> files are in place. | |
126 | The IBM document that describes such USS system setup issues is | |
127 | "z/OS UNIX System Services Planning" | |
eae55d03 | 128 | |
9133bbab | 129 | For successful testing you may need to turn on the sticky bit for your |
eae55d03 PK |
130 | world readable /tmp directory if you have not already done so (see man chmod). |
131 | ||
adcefe44 | 132 | =head2 Useful files for trouble-shooting |
8fde188e | 133 | |
adcefe44 MF |
134 | If your configuration is failing, read hints/os390.sh |
135 | This file provides z/OS specific options to direct the build process. | |
8fde188e | 136 | |
92ad49c1 | 137 | =head3 Shell |
8fde188e | 138 | |
eae55d03 PK |
139 | A message of the form: |
140 | ||
92ad49c1 | 141 | (I see you are using the Korn shell. Some ksh's blow up on Configure, |
adcefe44 MF |
142 | mainly on older exotic systems. If yours does, try the Bourne shell |
143 | instead.) | |
eae55d03 PK |
144 | |
145 | is nothing to worry about at all. | |
146 | ||
92ad49c1 MB |
147 | =head3 Dynamic loading |
148 | ||
149 | Dynamic loading is required if you want to use XS modules from CPAN (like | |
150 | DBI (and DBD's), JSON::XS, and Text::CSV_XS) or update CORE modules from | |
151 | CPAN with newer versions (like Encode) without rebuilding all of the perl | |
152 | binary. | |
8fde188e | 153 | |
adcefe44 MF |
154 | The instructions above will create a dynamic Perl. If you do not want to |
155 | use dynamic loading, remove the -Dusedl option. | |
f2766b05 | 156 | See the comments in hints/os390.sh for more information on dynamic loading. |
92ad49c1 MB |
157 | |
158 | =head3 Optimizing | |
9d116dd7 | 159 | |
adcefe44 MF |
160 | Optimization has not been turned on yet. There may be issues if Perl |
161 | is optimized. | |
8fde188e | 162 | |
a83b6f46 | 163 | =head2 Build Anomalies with Perl on OS/390 |
eae55d03 PK |
164 | |
165 | "Out of memory!" messages during the build of Perl are most often fixed | |
166 | by re building the GNU make utility for OS/390 from a source code kit. | |
167 | ||
adcefe44 | 168 | Within USS your F</etc/profile> or F<$HOME/.profile> may limit your ulimit |
eae55d03 PK |
169 | settings. Check that the following command returns reasonable values: |
170 | ||
171 | ulimit -a | |
172 | ||
a83b6f46 | 173 | =head2 Testing Anomalies with Perl on OS/390 |
eae55d03 | 174 | |
b432a672 | 175 | The "make test" step runs a Perl Verification Procedure, usually before |
eae55d03 | 176 | installation. You might encounter STDERR messages even during a successful |
b432a672 | 177 | run of "make test". Here is a guide to some of the more commonly seen |
eae55d03 PK |
178 | anomalies: |
179 | ||
adcefe44 | 180 | =head3 Out of Memory (31-bit only) |
eae55d03 | 181 | |
adcefe44 MF |
182 | Out of memory problems should not be an issue, unless you are attempting to build |
183 | a 31-bit Perl. | |
eae55d03 | 184 | |
adcefe44 MF |
185 | If you _are_ building a 31-bit Perl, the constrained environment may mean you |
186 | need to change memory options for Perl. | |
187 | In addition to the comments | |
9133bbab | 188 | above on memory limitations it is also worth checking for _CEE_RUNOPTS |
adcefe44 | 189 | in your environment. Perl now has (in miniperlmain.c) a C #pragma for 31-bit only |
210b36aa | 190 | to set CEE run options, but the environment variable wins. |
9133bbab | 191 | |
adcefe44 | 192 | The 31-bit C code asks for: |
9133bbab NIS |
193 | |
194 | #pragma runopts(HEAP(2M,500K,ANYWHERE,KEEP,8K,4K) STACK(,,ANY,) ALL31(ON)) | |
195 | ||
196 | The important parts of that are the second argument (the increment) to HEAP, | |
197 | and allowing the stack to be "Above the (16M) line". If the heap | |
210b36aa AMS |
198 | increment is too small then when perl (for example loading unicode/Name.pl) tries |
199 | to create a "big" (400K+) string it cannot fit in a single segment | |
9133bbab NIS |
200 | and you get "Out of Memory!" - even if there is still plenty of memory |
201 | available. | |
202 | ||
203 | A related issue is use with perl's malloc. Perl's malloc uses C<sbrk()> | |
204 | to get memory, and C<sbrk()> is limited to the first allocation so in this | |
205 | case something like: | |
206 | ||
207 | HEAP(8M,500K,ANYWHERE,KEEP,8K,4K) | |
208 | ||
209 | is needed to get through the test suite. | |
210 | ||
adcefe44 | 211 | =head2 Usage Hints for Perl on z/OS |
f2766b05 | 212 | |
adcefe44 | 213 | When using Perl on z/OS please keep in mind that the EBCDIC and ASCII |
9133bbab NIS |
214 | character sets are different. See perlebcdic.pod for more on such character |
215 | set issues. Perl builtin functions that may behave differently under | |
eae55d03 | 216 | EBCDIC are also mentioned in the perlport.pod document. |
9d116dd7 | 217 | |
59c9e5d6 | 218 | If you are having trouble with square brackets then consider switching your |
9133bbab | 219 | rlogin or telnet client. Try to avoid older 3270 emulators and ISHELL for |
59c9e5d6 PP |
220 | working with Perl on USS. |
221 | ||
adcefe44 | 222 | =head2 Modules and Extensions for Perl on z/OS (Static Only) |
eae55d03 | 223 | |
393dcb6c | 224 | Pure Perl (that is non XS) modules may be installed via the usual: |
eae55d03 PK |
225 | |
226 | perl Makefile.PL | |
227 | make | |
228 | make test | |
229 | make install | |
230 | ||
f2766b05 | 231 | If you built perl with dynamic loading capability then that would also |
92ad49c1 | 232 | be the way to build XS based extensions. However, if you built perl with |
adcefe44 | 233 | static linking you can still build XS based extensions for z/OS |
9133bbab NIS |
234 | but you will need to follow the instructions in ExtUtils::MakeMaker for |
235 | building statically linked perl binaries. In the simplest configurations | |
92ad49c1 | 236 | building a static perl + XS extension boils down to: |
9d116dd7 | 237 | |
eae55d03 PK |
238 | perl Makefile.PL |
239 | make | |
240 | make perl | |
241 | make test | |
242 | make install | |
243 | make -f Makefile.aperl inst_perl MAP_TARGET=perl | |
8fde188e | 244 | |
adcefe44 | 245 | =head2 Running Perl on z/OS |
8fde188e | 246 | |
adcefe44 MF |
247 | To run the 64-bit Dynamic Perl environment, update your PATH and LIBPATH |
248 | to include the location you installed Perl into, and then run the perl you | |
249 | installed as perlV.R.M where V/R/M is the Version/Release/Modification level | |
250 | of the current development level. | |
251 | If you are running the ASCII/EBCDIC Bi-Modal Perl environment, you also need to set up | |
252 | your ASCII/EBCDIC Bi-Modal environment variables, and ensure | |
253 | any Perl source code you run is tagged appropriately as ASCII or EBCDIC | |
254 | using chtag -t -c<CCSID>: | |
f2766b05 | 255 | |
adcefe44 | 256 | =head3 For ASCII Only: |
f2766b05 | 257 | |
adcefe44 MF |
258 | export _BPXK_AUTOCVT=ON |
259 | export _CEE_RUNOPTS="FILETAG(AUTOCVT,AUTOTAG),POSIX(ON)" | |
260 | export _TAG_REDIR_ERR="txt" | |
261 | export _TAG_REDIR_IN="txt" | |
262 | export _TAG_REDIR_OUT="txt" | |
263 | ||
264 | =head3 For ASCII or EBCDIC: | |
265 | ||
266 | export PATH=/usr/local/perl/ascii:$PATH | |
267 | export LIBPATH=/usr/local/perl/ascii/lib:$LIBPATH | |
268 | perlV.R.M args | |
f2766b05 | 269 | |
8fde188e GS |
270 | =head1 AUTHORS |
271 | ||
eae55d03 PK |
272 | David Fiander and Peter Prymmer with thanks to Dennis Longnecker |
273 | and William Raffloer for valuable reports, LPAR and PTF feedback. | |
274 | Thanks to Mike MacIsaac and Egon Terwedow for SG24-5944-00. | |
35a77668 | 275 | Thanks to Ignasi Roca for pointing out the floating point problems. |
f2766b05 | 276 | Thanks to John Goodyear for dynamic loading help. |
8fde188e | 277 | |
adcefe44 | 278 | Mike Fulton and Karl Williamson have provided updates for UTF8, DLL, 64-bit and ASCII/EBCDIC Bi-Modal support |
8fde188e | 279 | |
adcefe44 | 280 | =head2 Other sites |
9d116dd7 | 281 | |
adcefe44 MF |
282 | L<https://github.com/ZOSOpenTools/perlport/> provides documentation and tools |
283 | for building various z/OS Perl configurations and has some useful tools in the | |
284 | 'bin' directory you may want to use for building z/OS Perl yourself. | |
9d116dd7 | 285 | |
8fde188e GS |
286 | =head1 HISTORY |
287 | ||
adcefe44 | 288 | Updated 24 December 2021 to enable initial ASCII support |
8fde188e | 289 | |
adcefe44 | 290 | Updated 03 October 2019 for perl-5.33.3+ |
eae55d03 | 291 | |
adcefe44 | 292 | Updated 28 November 2001 for broken URLs. |
8fde188e | 293 | |
adcefe44 | 294 | Updated 12 March 2001 to mention //'SYS1.TCPPARMS(TCPDATA)'. |
92ad49c1 MB |
295 | |
296 | Updated 24 January 2001 to mention dynamic loading. | |
35a77668 | 297 | |
adcefe44 | 298 | Updated 15 January 2001 for the 5.7.1 release of Perl. |
92ad49c1 | 299 | |
adcefe44 | 300 | Updated 12 November 2000 for the 5.7.1 release of Perl. |
f2766b05 | 301 | |
adcefe44 | 302 | This document was podified for the 5.005_03 release of Perl 11 March 1999. |
59c9e5d6 | 303 | |
adcefe44 MF |
304 | This document was originally written by David Fiander for the 5.005 |
305 | release of Perl. | |
8fde188e | 306 | =cut |
eae55d03 | 307 |