This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
minor update to README.os390
[perl5.git] / README.os390
CommitLineData
eae55d03 1
8fde188e 2This document is written in pod format hence there are punctuation
eae55d03 3characters in odd places. Do not worry, you've apparently got
8fde188e
GS
4the ASCII->EBCDIC translation worked out correctly. You can read
5more about pod in pod/perlpod.pod or the short summary in the
6INSTALL file.
9d116dd7 7
8fde188e
GS
8=head1 NAME
9
10README.os390 - building and installing Perl for OS/390.
11
12=head1 SYNOPSIS
13
14This document will help you Configure, build, test and install Perl
15on OS/390 Unix System Services.
16
17=head1 DESCRIPTION
18
eae55d03
PK
19This is a fully ported Perl for OS/390 Version 2 Release 3, 5, 6, 7,
208, and 9. It may work on other versions or releases, but those are
21the ones we've tested it on.
8fde188e
GS
22
23You may need to carry out some system configuration tasks before
eae55d03 24running the Configure script for Perl.
8fde188e
GS
25
26=head2 Unpacking
9d116dd7
JH
27
28Gunzip/gzip for OS/390 is discussed at:
29
30 http://www.s390.ibm.com/products/oe/bpxqp1.html
31
32to extract an ASCII tar archive on OS/390, try this:
33
34 pax -o to=IBM-1047,from=ISO8859-1 -r < latest.tar
35
8fde188e
GS
36=head2 Setup and utilities
37
38Be sure that your yacc installation is in place including any necessary
39parser template files. If you have not already done so then be sure to:
40
41 cp /samples/yyparse.c /etc
42
43This may also be a good time to ensure that your /etc/protocol file
44and either your /etc/resolv.conf or /etc/hosts files are in place.
eae55d03
PK
45The IBM document that described such USS system setup issues was
46SC28-1890-07 "OS/390 UNIX System Services Planning", in particular
47Chapter 6 on customizing the OE shell.
8fde188e 48
8dd596cc 49GNU make for OS/390, which is recommended for the build of perl (as well as
eae55d03 50building CPAN modules and extensions), is available from:
9d116dd7
JH
51
52 http://www.mks.com/s390/gnu/index.htm
53
eae55d03
PK
54Some people have reported encountering "Out of memory!" errors while
55trying to build Perl using GNU make binaries. If you encounter such
56trouble then try to download the source code kit and build GNU make
57from source to eliminate any such trouble. You might also find GNU make
58(as well as Perl and Apache) in the red-piece/book "Open Source Software
59for OS/390 UNIX", SG24-5944-00 from IBM.
60
8dd596cc
PP
61If instead of the recommended GNU make you would like to use the system
62supplied make program then be sure to install the default rules file
63properly via the shell command:
64
65 cp /samples/startup.mk /etc
66
67and be sure to also set the environment variable _C89_CCMODE=1 (exporting
68_C89_CCMODE=1 is also a good idea for users of GNU make).
69
f2766b05
PP
70You might also want to have GNU groff for OS/390 installed before
71running the `make install` step for Perl.
72
eae55d03
PK
73There is a syntax error in the /usr/include/sys/socket.h header file
74that IBM supplies with USS V2R7, V2R8, and possibly V2R9. The problem with
75the header file is that near the definition of the SO_REUSEPORT constant
76there is a spurious extra '/' character outside of a comment like so:
77
78 #define SO_REUSEPORT 0x0200 /* allow local address & port
79 reuse */ /
80
81You could edit that header yourself to remove that last '/', or you might
82note that Language Environment (LE) APAR PQ39997 describes the problem
83and PTF's UQ46272 and UQ46271 are the (R8 at least) fixes and apply them.
84If left unattended that syntax error will turn up as an inability for Perl
85to build its "Socket" extension.
86
87For successful testing you may need to turn on the sticky bit for your
88world readable /tmp directory if you have not already done so (see man chmod).
89
8fde188e
GS
90=head2 Configure
91
92Once you've unpacked the distribution, run "sh Configure" (see INSTALL
93for a full discussion of the Configure options). There is a "hints" file
94for os390 that specifies the correct values for most things. Some things
95to watch out for include:
96
97=over 4
98
99=item *
100
eae55d03
PK
101A message of the form:
102
103 (I see you are using the Korn shell. Some ksh's blow up on Configure,
104 mainly on older exotic systems. If yours does, try the Bourne shell instead.)
105
106is nothing to worry about at all.
107
108=item *
109
8fde188e
GS
110Some of the parser default template files in /samples are needed in /etc.
111In particular be sure that you at least copy /samples/yyparse.c to /etc
eae55d03
PK
112before running Perl's Configure. This step ensures successful extraction
113of EBCDIC versions of parser files such as perly.c. This has to be done
114before running Configure the first time. If you failed to do so then the
115easiest way to re-Configure Perl is to delete your misconfigured build root
116and re extract the source from the tar ball. If for some reason you do not
117want to do that then, after ensuring that /etc/yyparse.c is properly in place
118run the following commands from within the Perl build directory:
119
120 rm -f y.tab.c y.tab.h
121 yacc -d perly.y
122 mv -f y.tab.c perly.c
123 chmod u+w perly.c
124 sed -e '/^#include "perl\.h"/a\
125 \
126 #define yydebug PL_yydebug\
127 #define yynerrs PL_yynerrs\
128 #define yyerrflag PL_yyerrflag\
129 #define yychar PL_yychar\
130 #define yyval PL_yyval\
131 #define yylval PL_yylval' \
132 -e '/YYSTYPE *yyval;/D' \
133 -e '/YYSTYPE *yylval;/D' \
134 -e '/int yychar,/,/yynerrs;/D' \
135 -e 's/int yydebug = 0;/yydebug = 0;/' \
136 -e 's/[^_]realloc(/PerlMem_realloc(/g' \
137 -e 's/fprintf *( *stderr *,/PerlIO_printf(Perl_debug_log,/g' \
138 -e 's/y\.tab/perly/g' perly.c >perly.tmp
139 mv -f perly.tmp perly.c
140 mv -f y.tab.h perly.h
141 cd x2p
142 rm -f y.tab.c y.tab.h
143 yacc a2p.y
144 mv -f y.tab.c a2p.c
145 chmod u+w a2p.c
146 sed -e 's/fprintf *( *stderr *,/PerlIO_printf(Perl_debug_log,/g' \
147 -e 's/y\.tab/a2p/g' a2p.c >a2p.tmp
148 mv -f a2p.tmp a2p.c
149 mv -f y.tab.h a2p.h
150 cd ..
151
152There, easy huh? If you find typing all that in difficult then perhaps
153you should reconsider the rm -rf of the perl build directory and
154re extraction of the source tar ball.
8fde188e
GS
155
156=item *
157
f2766b05
PP
158This port will support dynamic loading, but it is not selected by
159default. If you would like to experiment with dynamic loading then
160be sure to specify -Dusedl in the arguments to the Configure script.
161See the comments in hints/os390.sh for more information on dynamic loading.
162If you build with dynamic loading then you will need to add the
163$archlibexp/CORE directory to your LIBPATH environment variable in order
164for perl to work. See the config.sh file for the value of $archlibexp.
8fde188e
GS
165
166=item *
9d116dd7 167
eae55d03 168Do not turn on the compiler optimization flag "-O". There is
8fde188e
GS
169a bug in either the optimizer or perl that causes perl to
170not work correctly when the optimizer is on.
9d116dd7 171
8fde188e 172=item *
9d116dd7 173
8fde188e
GS
174Some of the configuration files in /etc used by the
175networking APIs are either missing or have the wrong
176names. In particular, make sure that there's either
eae55d03 177an /etc/resolv.conf or an /etc/hosts, so that
8fde188e
GS
178gethostbyname() works, and make sure that the file
179/etc/proto has been renamed to /etc/protocol (NOT
180/etc/protocols, as used by other Unix systems).
9d116dd7 181
8fde188e
GS
182=back
183
184=head2 Build, test, install
185
186Simply put:
187
188 sh Configure
189 make
190 make test
191
eae55d03 192if everything looks ok (see the next section for test/IVP diagnosis) then:
8fde188e
GS
193
194 make install
195
196this last step may or may not require UID=0 privileges depending
197on how you answered the questions that Configure asked and whether
198or not you have write access to the directories you specified.
199
eae55d03
PK
200=head2 build anomalies
201
202"Out of memory!" messages during the build of Perl are most often fixed
203by re building the GNU make utility for OS/390 from a source code kit.
204
205Another memory limiting item to check is your MAXASSIZE parameter in your
206'SYS1.PARMLIB(BPXPRMxx)' data set (note too that as of V2R8 address space
207limits can be set on a per user ID basis in the USS segment of a RACF
208profile). People have reported successful builds of Perl with MAXASSIZE
209parameters as small as 503316480 (and it may be possible to build Perl
210with a MAXASSIZE smaller than that).
211
212Within USS your /etc/profile or $HOME/.profile may limit your ulimit
213settings. Check that the following command returns reasonable values:
214
215 ulimit -a
216
217To conserve memory you should have your compiler modules loaded into the
218Link Pack Area (LPA/ELPA) rather than in a link list or step lib.
219
220If the c89 compiler complains of syntax errors during the build of the
221Socket extension then be sure to fix the syntax error in the system
222header /usr/include/sys/socket.h.
223
224=head2 testing anomalies
225
226The `make test` step runs a Perl Verification Procedure, usually before
227installation. You might encounter STDERR messages even during a successful
228run of `make test`. Here is a guide to some of the more commonly seen
229anomalies:
230
231=over 4
232
233=item *
234
235A message of the form:
236
237 comp/cpp.............ERROR CBC3191 ./.301989890.c:1 The character $ is not a
238 valid C source character.
239 FSUM3065 The COMPILE step ended with return code 12.
240 FSUM3017 Could not compile .301989890.c. Correct the errors and try again.
241 ok
242
243indicates that the t/comp/cpp.t test of Perl's -P command line switch has
244passed but that the particular invocation of c89 -E in the cpp script does
245not suppress the C compiler check of source code validity.
246
247=item *
248
249A message of the form:
250
251 io/openpid...........CEE5210S The signal SIGHUP was received.
252 CEE5210S The signal SIGHUP was received.
253 CEE5210S The signal SIGHUP was received.
254 ok
255
256indicates that the t/io/openpid.t test of Perl has passed but done so
257with extraneous messages on stderr from CEE.
258
259=item *
260
261A message of the form:
262
263 lib/ftmp-security....File::Temp::_gettemp: Parent directory (/tmp/) is not safe
264 (sticky bit not set when world writable?) at lib/ftmp-security.t line 100
265 File::Temp::_gettemp: Parent directory (/tmp/) is not safe (sticky bit not
266 set when world writable?) at lib/ftmp-security.t line 100
267 ok
268
269indicates a problem with the permissions on your /tmp directory within the HFS.
270To correct that problem issue the command:
271
272 chmod a+t /tmp
273
274from an account with write access to the directory entry for /tmp.
275
276=back
277
f2766b05
PP
278=head2 installation anomalies
279
280The installman script will try to run on OS/390. There will be fewer errors
281if you have a roff utility installed. You can obtain GNU groff from the
282Redbook SG24-5944-00 ftp site.
283
8fde188e 284=head2 Usage Hints
64d55c8a 285
9d116dd7 286When using perl on OS/390 please keep in mind that the EBCDIC and ASCII
eae55d03
PK
287character sets are different. See perlebcdic.pod for more on such character
288set issues. Perl builtin functions that may behave differently under
289EBCDIC are also mentioned in the perlport.pod document.
9d116dd7 290
eae55d03
PK
291Open Edition (UNIX System Services) from V2R8 onward does support
292#!/path/to/perl script invocation. There is a PTF available from
293IBM for V2R7 that will allow shell/kernel support for #!. USS
294releases prior to V2R7 did not support the #! means of script invocation.
295If you are running V2R6 or earlier then see:
9d116dd7
JH
296
297 head `whence perldoc`
298
299for an example of how to use the "eval exec" trick to ask the shell to
eae55d03
PK
300have Perl run your scripts on those older releases of Unix System Services.
301
35a77668
PP
302=head2 Floating point anomalies
303
304There appears to be a bug in the floating point implementation on S/390
305systems such that calling int() on the product of a number and a small
306magnitude number is not the same as calling int() on the quotient of
307that number and a large magnitude number. For example, in the following
308Perl code:
309
310 my $x = 100000.0;
311 my $y = int($x * 1e-5) * 1e5; # '0'
312 my $z = int($x / 1e+5) * 1e5; # '100000'
313 print "\$y is $y and \$z is $z\n"; # $y is 0 and $z is 100000
314
315Although one would expect the quantities $y and $z to be the same and equal
316to 100000 they will differ and instead will be 0 and 100000 respectively.
317
318The problem can be further examined in a roughly equivalent C program:
319
320 #include <stdio.h>
321 #include <math.h>
322 main()
323 {
324 double r1,r2;
325 double x = 100000.0;
326 double y = 0.0;
327 double z = 0.0;
328 x = 100000.0 * 1e-5;
329 r1 = modf (x,&y);
330 x = 100000.0 / 1e+5;
331 r2 = modf (x,&z);
332 printf("y is %e and z is %e\n",y*1e5,z*1e5);
333 /* y is 0.000000e+00 and z is 1.000000e+05 (with c89) */
334 }
335
eae55d03
PK
336=head2 Modules and Extensions
337
338Pure pure (that is non xs) modules may be installed via the usual:
339
340 perl Makefile.PL
341 make
342 make test
343 make install
344
f2766b05
PP
345If you built perl with dynamic loading capability then that would also
346be the way to build xs based extensions. However, if you built perl with
347the default static linking you can still build xs based extensions for OS/390
348but you will need to follow the instructions in ExtUtils::MakeMaker for building
eae55d03
PK
349statically linked perl binaries. In the simplest configurations building
350a static perl + xs extension boils down to:
9d116dd7 351
eae55d03
PK
352 perl Makefile.PL
353 make
354 make perl
355 make test
356 make install
357 make -f Makefile.aperl inst_perl MAP_TARGET=perl
8fde188e 358
eae55d03
PK
359In most cases people have reported better results with GNU make rather
360than the system's /bin/make program, whether for plain modules or for
361xs based extensions.
8fde188e 362
f2766b05
PP
363If the make process encounters trouble with either compilation or
364linking then try setting the _C89_CCMODE to 1. Assuming sh is your
365login shell then run:
366
367 export _C89_CCMODE=1
368
369If tcsh is your login shell then use the setenv command.
370
8fde188e
GS
371=head1 AUTHORS
372
eae55d03
PK
373David Fiander and Peter Prymmer with thanks to Dennis Longnecker
374and William Raffloer for valuable reports, LPAR and PTF feedback.
375Thanks to Mike MacIsaac and Egon Terwedow for SG24-5944-00.
35a77668 376Thanks to Ignasi Roca for pointing out the floating point problems.
f2766b05 377Thanks to John Goodyear for dynamic loading help.
8fde188e
GS
378
379=head1 SEE ALSO
380
eae55d03
PK
381L<INSTALL>, L<perlport>, L<perlebcdic>, L<ExtUtils::MakeMaker>.
382
383 http://www.mks.com/s390/gnu/index.htm
384
385 http://www.redbooks.ibm.com/abstracts/sg245944.html
386
387 http://www.s390.ibm.com/products/oe/bpxa1ty1.html#opensrc
388
389 http://www.s390.ibm.com/products/oe/portbk/bpxacenv.html
390
391 http://www.xray.mpe.mpg.de/mailing-lists/perl-mvs/
8fde188e
GS
392
393=head2 Mailing list
394
395The Perl Institute (http://www.perl.org/) maintains a perl-mvs
396mailing list of interest to all folks building and/or
eae55d03
PK
397using perl on all EBCDIC platforms (not just OS/390).
398To subscribe, send a message of:
9d116dd7
JH
399
400 subscribe perl-mvs
401
35a77668
PP
402to majordomo@perl.org. See also:
403
404 http://lists.perl.org/showlist.cgi?name=perl-mvs
405
406There are web archives of the mailing list at:
eae55d03
PK
407
408 http://www.xray.mpe.mpg.de/mailing-lists/perl-mvs/
35a77668 409 http://archive.develooper.com/perl-mvs@perl.org/
9d116dd7 410
8fde188e
GS
411=head1 HISTORY
412
413This document was originally written by David Fiander for the 5.005
414release of Perl.
415
eae55d03
PK
416This document was podified for the 5.005_03 release of Perl 11 March 1999.
417
418Updated 12 November 2000 for the 5.7.1 release of Perl.
8fde188e 419
35a77668
PP
420Updated 15 January 2001 for the 5.7.1 release of Perl.
421
f2766b05
PP
422Updated 24 January 2001 to mention dynamic loading.
423
8fde188e 424=cut
eae55d03 425