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