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