This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
e6782e3dc127220ae031b4dfd98614d09fac5888
[perl5.git] / README.os2
1 If you read this file _as_is_, just ignore the funny characters you
2 see. It is written in the POD format (see perlpod manpage) which is
3 specially designed to be readable as is.
4
5 =head1 NAME
6
7 perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT.
8
9 =head1 SYNOPSIS
10
11 One can read this document in the following formats:
12
13         man perlos2
14         view perl perlos2
15         explorer perlos2.html
16         info perlos2
17
18 to list some (not all may be available simultaneously), or it may
19 be read I<as is>: either as F<README.os2>, or F<pod/perlos2.pod>.
20
21 To read the F<.INF> version of documentation (B<very> recommended)
22 outside of OS/2, one needs an IBM's reader (may be available on IBM
23 ftp sites (?)  (URL anyone?)) or shipped with PC DOS 7.0 and IBM's
24 Visual Age C++ 3.5.
25
26 A copy of a Win* viewer is contained in the "Just add OS/2 Warp" package
27
28   ftp://ftp.software.ibm.com/ps/products/os2/tools/jaow/jaow.zip
29
30 in F<?:\JUST_ADD\view.exe>. This gives one an access to B<EMX>'s 
31 F<.INF> docs as well (text form is available in F</emx/doc> in 
32 B<EMX>'s distribution).
33
34 =cut
35
36 Contents
37  
38  perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT. 
39
40       NAME 
41       SYNOPSIS 
42       DESCRIPTION 
43          -  Target 
44          -  Other OSes 
45          -  Prerequisites 
46          -  Starting Perl programs under OS/2 
47          -  Starting OS/2 programs under Perl 
48       Frequently asked questions 
49          -  I cannot run external programs 
50          -  I cannot embed perl into my program, or use perl.dll from my program. 
51          -  `` and pipe-open do not work under DOS. 
52       INSTALLATION 
53          -  Automatic binary installation 
54          -  Manual binary installation 
55          -  Warning 
56       Accessing documentation 
57          -  OS/2 .INF file 
58          -  Plain text 
59          -  Manpages 
60          -  HTML 
61          -  GNU info files 
62          -  .PDF files 
63          -  LaTeX docs 
64       BUILD 
65          -  Prerequisites 
66          -  Getting perl source 
67          -  Application of the patches 
68          -  Hand-editing 
69          -  Making 
70          -  Testing 
71          -  Installing the built perl 
72          -  a.out-style build 
73       Build FAQ 
74          -  Some / became \ in pdksh. 
75          -  'errno' - unresolved external 
76          -  Problems with tr 
77          -  Some problem (forget which ;-) 
78          -  Library ... not found 
79          -  Segfault in make 
80       Specific (mis)features of OS/2 port 
81          -  setpriority, getpriority 
82          -  system() 
83          -  Additional modules: 
84          -  Prebuilt methods: 
85          -  Misfeatures 
86          -  Modifications 
87       Perl flavors 
88          -  perl.exe 
89          -  perl_.exe 
90          -  perl__.exe 
91          -  perl___.exe 
92          -  Why strange names? 
93          -  Why dynamic linking? 
94          -  Why chimera build? 
95       ENVIRONMENT 
96          -  PERLLIB_PREFIX 
97          -  PERL_BADLANG 
98          -  PERL_BADFREE 
99          -  PERL_SH_DIR 
100          -  TMP or TEMP 
101       Evolution 
102          -  Priorities 
103          -  DLL name mangling 
104          -  Threading 
105          -  Calls to external programs 
106          -  Memory allocation 
107       AUTHOR 
108       SEE ALSO 
109   
110 =head1 DESCRIPTION
111
112 =head2 Target
113
114 The target is to make OS/2 the best supported platform for
115 using/building/developing Perl and I<Perl applications>, as well as
116 make Perl the best language to use under OS/2.
117
118 The current state is quite close to this target. Known limitations:
119
120 =over 5
121
122 =item *
123
124 Some *nix programs use fork() a lot, but currently fork() is not
125 supported after I<use>ing dynamically loaded extensions.
126
127 =item *
128
129 You need a separate perl executable F<perl__.exe> (see L<perl__.exe>)
130 to use PM code in your application (like the forthcoming Perl/Tk).
131
132 =item *
133
134 There is no simple way to access B<WPS> objects. The only way I know
135 is via C<OS2::REXX> extension (see L<OS2::REXX>), and we do not have access to
136 convenience methods of B<Object REXX>. (Is it possible at all? I know
137 of no B<Object-REXX> API.)
138
139 =back
140
141 Please keep this list up-to-date by informing me about other items.
142
143 =head2 Other OSes
144
145 Since OS/2 port of perl uses a remarkable B<EMX> environment, it can
146 run (and build extensions, and - possibly - be build itself) under any
147 environment which can run EMX. The current list is DOS,
148 DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT. Out of many perl flavors,
149 only one works, see L<"perl_.exe">.
150
151 Note that not all features of Perl are available under these
152 environments. This depends on the features the I<extender> - most
153 probably C<RSX> - decided to implement.
154
155 Cf. L<Prerequisites>.
156
157 =head2 Prerequisites
158
159 =over 6
160
161 =item B<EMX>
162
163 B<EMX> runtime is required (may be substituted by B<RSX>). Note that
164 it is possible to make F<perl_.exe> to run under DOS without any
165 external support by binding F<emx.exe>/F<rsx.exe> to it, see L<emxbind>. Note
166 that under DOS for best results one should use B<RSX> runtime, which
167 has much more functions working (like C<fork>, C<popen> and so on). In
168 fact B<RSX> is required if there is no C<VCPI> present. Note the
169 B<RSX> requires C<DPMI>.
170
171 Only the latest runtime is supported, currently C<0.9c>.
172
173 One can get different parts of B<EMX> from, say
174
175   ftp://ftp.cdrom.com/pub/os2/emx0.9c/
176   ftp://hobbes.nmsu.edu/os2/unix/gnu/
177
178 The runtime component should have the name F<emxrt.zip>.
179
180 B<NOTE>. It is enough to have F<emx.exe>/F<rsx.exe> on your path. One
181 does not need to specify them explicitly (though this
182
183   emx perl_.exe -de 0
184
185 will work as well.)
186
187 =item B<RSX>
188
189 To run Perl on C<DPMI> platforms one needs B<RSX> runtime. This is
190 needed under DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT (see 
191 L<"Other OSes">). B<RSX> would not work with C<VCPI>
192 only, as B<EMX> would, it requires C<DMPI>.
193
194 Having B<RSX> and the latest F<sh.exe> one gets a fully functional
195 B<*nix>-ish environment under DOS, say, C<fork>, C<``> and
196 pipe-C<open> work. In fact, MakeMaker works (for static build), so one
197 can have Perl development environment under DOS. 
198
199 One can get B<RSX> from, say
200
201   ftp://ftp.cdrom.com/pub/os2/emx0.9c/contrib
202   ftp://ftp.uni-bielefeld.de/pub/systems/msdos/misc
203
204 Contact the author on C<rainer@mathematik.uni-bielefeld.de>.
205
206 The latest F<sh.exe> with DOS hooks is available at
207
208   ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/sh_dos.exe
209
210 =item B<HPFS>
211
212 Perl does not care about file systems, but to install the whole perl
213 library intact one needs a file system which supports long file names.
214
215 Note that if you do not plan to build the perl itself, it may be
216 possible to fool B<EMX> to truncate file names. This is not supported,
217 read B<EMX> docs to see how to do it.
218
219 =back
220
221 =head2 Starting Perl programs under OS/2
222
223 Start your Perl program F<foo.pl> with arguments C<arg1 arg2 arg3> the
224 same way as on any other platform, by
225
226         perl foo.pl arg1 arg2 arg3
227
228 If you want to specify perl options C<-my_opts> to the perl itself (as
229 opposed to to your program), use
230
231         perl -my_opts foo.pl arg1 arg2 arg3
232
233 Alternately, if you use OS/2-ish shell, like C<CMD> or C<4os2>, put
234 the following at the start of your perl script:
235
236         extproc perl -x -S
237         #!/usr/bin/perl -my_opts 
238
239 rename your program to F<foo.cmd>, and start it by typing
240
241         foo arg1 arg2 arg3
242
243 (Note that having *nixish full path to perl F</usr/bin/perl> is not
244 necessary, F<perl> would be enough, but having full path would make it
245 easier to use your script under *nix.)
246
247 Note that because of stupid OS/2 limitations the full path of the perl
248 script is not available when you use C<extproc>, thus you are forced to
249 use C<-S> perl switch, and your script should be on path. As a plus
250 side, if you know a full path to your script, you may still start it
251 with 
252
253         perl -x ../../blah/foo.cmd arg1 arg2 arg3
254
255 (note that the argument C<-my_opts> is taken care of by the C<#!> line
256 in your script).
257
258 To understand what the above I<magic> does, read perl docs about C<-S>
259 and C<-x> switches - see L<perlrun>, and cmdref about C<extproc>:
260
261         view perl perlrun
262         man perlrun
263         view cmdref extproc
264         help extproc
265
266 or whatever method you prefer.
267
268 There are also endless possibilities to use I<executable extensions> of
269 B<4OS2>, I<associations> of B<WPS> and so on... However, if you use
270 *nixish shell (like F<sh.exe> supplied in the binary distribution),
271 you need to follow the syntax specified in L<perlrun/"Switches">.
272
273 =head2 Starting OS/2 programs under Perl
274
275 This is what system() (see L<perlfunc/system>), C<``> (see
276 L<perlop/"I/O Operators">), and I<open pipe> (see L<perlfunc/open>)
277 are for. (Avoid exec() (see L<perlfunc/exec>) unless you know what you
278 do).
279
280 Note however that to use some of these operators you need to have a
281 C<sh>-syntax shell installed (see L<"Pdksh">, 
282 L<"Frequently asked questions">), and perl should be able to find it
283 (see L<"PERL_SH_DIR">).
284
285 The only cases when the shell is not used is the multi-argument
286 system() (see L<perlfunc/system>)/exec() (see L<perlfunc/exec>), and
287 one-argument version thereof without redirection and shell
288 meta-characters.
289
290 =head1 Frequently asked questions
291
292 =head2 I cannot run external programs
293
294 =over 4
295
296 =item
297
298 Did you run your programs with C<-w> switch? See 
299 L<Starting OS/2 programs under Perl>.
300
301 =item
302
303 Do you try to run I<internal> shell commands, like C<`copy a b`>
304 (internal for F<cmd.exe>), or C<`glob a*b`> (internal for ksh)? You
305 need to specify your shell explicitly, like C<`cmd /c copy a b`>,
306 since Perl cannot deduce which commands are internal to your shell.
307
308 =back
309
310 =head2 I cannot embed perl into my program, or use F<perl.dll> from my
311 program. 
312
313 =over 4
314
315 =item Is your program B<EMX>-compiled with C<-Zmt -Zcrtdll>?
316
317 If not, you need to build a stand-alone DLL for perl. Contact me, I
318 did it once. Sockets would not work, as a lot of other stuff.
319
320 =item Did you use C<ExtUtils::Embed>?
321
322 I had reports it does not work. Somebody would need to fix it.
323
324 =back
325
326 =head2 C<``> and pipe-C<open> do not work under DOS.
327
328 This may a variant of just L<"I cannot run external programs">, or a
329 deeper problem. Basically: you I<need> B<RSX> (see L<"Prerequisites">)
330 for these commands to work, and you may need a port of F<sh.exe> which
331 understands command arguments. One of such ports is listed in
332 L<"Prerequisites"> under B<RSX>.
333
334 C<DPMI> is required for B<RSX>.
335
336 =head1 INSTALLATION
337
338 =head2 Automatic binary installation
339
340 The most convenient way of installing perl is via perl installer
341 F<install.exe>. Just follow the instructions, and 99% of the
342 installation blues would go away. 
343
344 Note however, that you need to have F<unzip.exe> on your path, and
345 B<EMX> environment I<running>. The latter means that if you just
346 installed B<EMX>, and made all the needed changes to F<Config.sys>,
347 you may need to reboot in between. Check B<EMX> runtime by running
348
349         emxrev
350
351 A folder is created on your desktop which contains some useful
352 objects.
353
354 B<Things not taken care of by automatic binary installation:>
355
356 =over 15
357
358 =item C<PERL_BADLANG>
359
360 may be needed if you change your codepage I<after> perl installation,
361 and the new value is not supported by B<EMX>. See L<"PERL_BADLANG">.
362
363 =item C<PERL_BADFREE>
364
365 see L<"PERL_BADFREE">.
366
367 =item F<Config.pm>
368
369 This file resides somewhere deep in the location you installed your
370 perl library, find it out by 
371
372   perl -MConfig -le "print $INC{'Config.pm'}"
373
374 While most important values in this file I<are> updated by the binary
375 installer, some of them may need to be hand-edited. I know no such
376 data, please keep me informed if you find one.
377
378 =back
379
380 =head2 Manual binary installation
381
382 As of version 5.00305, OS/2 perl binary distribution comes split
383 into 11 components. Unfortunately, to enable configurable binary
384 installation, the file paths in the C<zip> files are not absolute, but
385 relative to some directory.
386
387 Note that the extraction with the stored paths is still necessary
388 (default with C<unzip>, specify C<-d> to C<pkunzip>). However, you
389 need to know where to extract the files. You need also to manually
390 change entries in F<Config.sys> to reflect where did you put the
391 files. Note that if you have some primitive unzipper (like
392 C<pkunzip>), you may get a lot of warnings/errors during
393 unzipping. Upgrade to C<(w)unzip>.
394
395 Below is the sample of what to do to reproduce the configuration on my
396 machine:
397
398 =over 3
399
400 =item Perl VIO and PM executables (dynamically linked)
401
402   unzip perl_exc.zip *.exe *.ico -d f:/emx.add/bin
403   unzip perl_exc.zip *.dll -d f:/emx.add/dll
404
405 (have the directories with C<*.exe> on C<PATH>, and C<*.dll> on
406 C<LIBPATH>);
407
408 =item Perl_ VIO executable (statically linked)
409
410   unzip perl_aou.zip -d f:/emx.add/bin
411
412 (have the directory on C<PATH>);
413
414 =item Executables for Perl utilities
415
416   unzip perl_utl.zip -d f:/emx.add/bin
417
418 (have the directory on C<PATH>);
419
420 =item Main Perl library
421
422   unzip perl_mlb.zip -d f:/perllib/lib
423
424 If this directory is preserved, you do not need to change
425 anything. However, for perl to find it if it is changed, you need to
426 C<set PERLLIB_PREFIX> in F<Config.sys>, see L<"PERLLIB_PREFIX">.
427
428 =item Additional Perl modules
429
430   unzip perl_ste.zip -d f:/perllib/lib/site_perl
431
432 If you do not change this directory, do nothing. Otherwise put this
433 directory and subdirectory F<./os2> in C<PERLLIB> or C<PERL5LIB>
434 variable. Do not use C<PERL5LIB> unless you have it set already. See
435 L<perl/"ENVIRONMENT">. 
436
437 =item Tools to compile Perl modules
438
439   unzip perl_blb.zip -d f:/perllib/lib
440
441 If this directory is preserved, you do not need to change
442 anything. However, for perl to find it if it is changed, you need to
443 C<set PERLLIB_PREFIX> in F<Config.sys>, see L<"PERLLIB_PREFIX">.
444
445 =item Manpages for Perl and utilities
446
447   unzip perl_man.zip -d f:/perllib/man
448
449 This directory should better be on C<MANPATH>. You need to have a
450 working C<man> to access these files.
451
452 =item Manpages for Perl modules
453
454   unzip perl_mam.zip -d f:/perllib/man
455
456 This directory should better be on C<MANPATH>. You need to have a
457 working C<man> to access these files.
458
459 =item Source for Perl documentation
460
461   unzip perl_pod.zip -d f:/perllib/lib
462
463 This is used by by C<perldoc> program (see L<perldoc>), and may be used to
464 generate B<HTML> documentation usable by WWW browsers, and
465 documentation in zillions of other formats: C<info>, C<LaTeX>,
466 C<Acrobat>, C<FrameMaker> and so on.
467
468 =item Perl manual in .INF format
469
470   unzip perl_inf.zip -d d:/os2/book
471
472 This directory should better be on C<BOOKSHELF>.
473
474 =item Pdksh
475
476   unzip perl_sh.zip -d f:/bin
477
478 This is used by perl to run external commands which explicitly
479 require shell, like the commands using I<redirection> and I<shell
480 metacharacters>. It is also used instead of explicit F</bin/sh>.
481
482 Set C<PERL_SH_DIR> (see L<"PERL_SH_DIR">) if you move F<sh.exe> from
483 the above location.
484
485 B<Note.> It may be possible to use some other C<sh>-compatible shell
486 (I<not tested>).
487
488 =back
489
490 After you installed the components you needed and updated the
491 F<Config.sys> correspondingly, you need to hand-edit
492 F<Config.pm>. This file resides somewhere deep in the location you
493 installed your perl library, find it out by
494
495   perl -MConfig -le "print $INC{'Config.pm'}"
496
497 You need to correct all the entries which look like file paths (they
498 currently start with C<f:/>).
499
500 =head2 B<Warning>
501
502 The automatic and manual perl installation leave precompiled paths
503 inside perl executables. While these paths are overwriteable (see
504 L<"PERLLIB_PREFIX">, L<"PERL_SH_DIR">), one may get better results by
505 binary editing of paths inside the executables/DLLs.
506
507 =head1 Accessing documentation
508
509 Depending on how you built/installed perl you may have (otherwise
510 identical) Perl documentation in the following formats:
511
512 =head2 OS/2 F<.INF> file
513
514 Most probably the most convenient form. View it as
515
516   view perl
517   view perl perlfunc
518   view perl less
519   view perl ExtUtils::MakeMaker
520
521 (currently the last two may hit a wrong location, but this may improve
522 soon).
523
524 If you want to build the docs yourself, and have I<OS/2 toolkit>, run
525
526         pod2ipf > perl.ipf
527
528 in F</perllib/lib/pod> directory, then
529
530         ipfc /inf perl.ipf
531
532 (Expect a lot of errors during the both steps.) Now move it on your
533 BOOKSHELF path.
534
535 =head2 Plain text
536
537 If you have perl documentation in the source form, perl utilities
538 installed, and B<GNU> C<groff> installed, you may use 
539
540         perldoc perlfunc
541         perldoc less
542         perldoc ExtUtils::MakeMaker
543
544 to access the perl documentation in the text form (note that you may get
545 better results using perl manpages).
546
547 Alternately, try running pod2text on F<.pod> files.
548
549 =head2 Manpages
550
551 If you have C<man> installed on your system, and you installed perl
552 manpages, use something like this:
553
554         man perlfunc
555         man 3 less
556         man ExtUtils.MakeMaker
557
558 to access documentation for different components of Perl. Start with
559
560         man perl
561
562 Note that dot (F<.>) is used as a package separator for documentation
563 for packages, and as usual, sometimes you need to give the section - C<3>
564 above - to avoid shadowing by the I<less(1) manpage>.
565
566 Make sure that the directory B<above> the directory with manpages is
567 on our C<MANPATH>, like this
568
569   set MANPATH=c:/man;f:/perllib/man
570
571 =head2 B<HTML>
572
573 If you have some WWW browser available, installed the Perl
574 documentation in the source form, and Perl utilities, you can build
575 B<HTML> docs. Cd to directory with F<.pod> files, and do like this
576
577         cd f:/perllib/lib/pod
578         pod2html
579
580 After this you can direct your browser the file F<perl.html> in this
581 directory, and go ahead with reading docs, like this:
582
583         explore file:///f:/perllib/lib/pod/perl.html
584
585 Alternatively you may be able to get these docs prebuilt from C<CPAN>.
586
587 =head2 B<GNU> C<info> files
588
589 Users of C<Emacs> would appreciate it very much, especially with
590 C<CPerl> mode loaded. You need to get latest C<pod2info> from C<CPAN>,
591 or, alternately, prebuilt info pages.
592
593 =head2 F<.PDF> files
594
595 for C<Acrobat> are available on CPAN (for slightly old version of
596 perl).
597
598 =head2 C<LaTeX> docs
599
600 can be constructed using C<pod2latex>.
601
602 =head1 BUILD
603
604 Here we discuss how to build Perl under OS/2. There is an alternative
605 (but maybe older) view on L<http://www.shadow.net/~troc/os2perl.html>.
606
607 =head2 Prerequisites
608
609 You need to have the latest B<EMX> development environment, the full
610 B<GNU> tool suite (C<gawk> renamed to C<awk>, and B<GNU> F<find.exe>
611 earlier on path than the OS/2 F<find.exe>, same with F<sort.exe>, to
612 check use
613
614   find --version
615   sort --version
616
617 ). You need the latest version of F<pdksh> installed as F<sh.exe>.
618
619 Possible locations to get this from are
620
621   ftp://hobbes.nmsu.edu/os2/unix/gnu/
622   ftp://ftp.cdrom.com/pub/os2/unix/
623   ftp://ftp.cdrom.com/pub/os2/dev32/
624   ftp://ftp.cdrom.com/pub/os2/emx0.9c/
625
626
627 Make sure that no copies or perl are currently running.  Later steps
628 of the build may fail since an older version of perl.dll loaded into
629 memory may be found. 
630
631 Also make sure that you have F</tmp> directory on the current drive,
632 and F<.> directory in your C<LIBPATH>. One may try to correct the
633 latter condition by
634
635   set BEGINLIBPATH .
636
637 if you use something like F<CMD.EXE> or latest versions of F<4os2.exe>.
638
639 Make sure your C<gcc> is good for C<-Zomf> linking: run C<omflibs>
640 script in F</emx/lib> directory.
641
642 Check that you have C<link386> installed. It comes standard with OS/2,
643 but may be not installed due to customization. If typing
644
645   link386
646
647 shows you do not have it, do I<Selective install>, and choose C<Link
648 object modules> in I<Optional system utilities/More>. If you get into
649 C<link386>, press C<Ctrl-C>.
650
651 =head2 Getting perl source
652
653 You need to fetch the latest perl source (including developers
654 releases). With some probability it is located in 
655
656   http://www.perl.com/CPAN/src/5.0
657   http://www.perl.com/CPAN/src/5.0/unsupported
658
659 If not, you may need to dig in the indices to find it in the directory
660 of the current maintainer.
661
662 Quick cycle of developers release may break the OS/2 build time to
663 time, looking into 
664
665   http://www.perl.com/CPAN/ports/os2/ilyaz/
666
667 may indicate the latest release which was publicly released by the
668 maintainer. Note that the release may include some additional patches
669 to apply to the current source of perl.
670
671 Extract it like this
672
673   tar vzxf perl5.00409.tar.gz
674
675 You may see a message about errors while extracting F<Configure>. This is
676 because there is a conflict with a similarly-named file F<configure>.
677
678 Rename F<configure> to F<configure.gnu>. Extract F<Configure> like this
679
680   tar --case-sensitive -vzxf perl5.00409.tar.gz perl5.00409/Configure
681
682 Change to the directory of extraction.
683
684 =head2 Application of the patches
685
686 You need to apply the patches in F<./os2/diff.*> and
687 F<./os2/POSIX.mkfifo> like this:
688
689   gnupatch -p0 < os2\POSIX.mkfifo
690   gnupatch -p0 < os2\diff.configure
691
692 You may also need to apply the patches supplied with the binary
693 distribution of perl.
694
695 Note also that the F<db.lib> and F<db.a> from the B<EMX> distribution
696 are not suitable for multi-threaded compile (note that currently perl
697 is not multithreaded, but is compiled as multithreaded for
698 compatibility with B<XFree86>-OS/2). Get a corrected one from
699
700   ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/db_mt.zip
701
702 =head2 Hand-editing
703
704 You may look into the file F<./hints/os2.sh> and correct anything
705 wrong you find there. I do not expect it is needed anywhere.
706
707 =head2 Making
708
709   sh Configure -des -D prefix=f:/perllib
710
711 Prefix means where to install the resulting perl library. Giving
712 correct prefix you may avoid the need to specify C<PERLLIB_PREFIX>,
713 see L<"PERLLIB_PREFIX">.
714
715 I<Ignore the message about missing C<ln>, and about C<-c> option to
716 C<tr>>. In fact if you can trace where the latter spurious warning
717 comes from, please inform me.
718
719 Now
720
721   make
722
723 At some moment the built may die, reporting a I<version mismatch> or
724 I<unable to run F<perl>>. This means that most of the build has been
725 finished, and it is the time to move the constructed F<perl.dll> to
726 some I<absolute> location in C<LIBPATH>. After this done the build
727 should finish without a lot of fuss. I<One can avoid it if one has the
728 correct prebuilt version of F<perl.dll> on C<LIBPATH>.>
729
730 Warnings which are safe to ignore: I<mkfifo() redefined> inside
731 F<POSIX.c>.
732
733 =head2 Testing
734
735 Now run
736
737   make test
738
739 Some tests (4..6) should fail. Some perl invocations should end in a
740 segfault (system error C<SYS3175>). To get finer error reports, 
741
742   cd t
743   perl -I ../lib harness
744
745 The report you get may look like
746
747   Failed Test  Status Wstat Total Fail  Failed  List of failed
748   ---------------------------------------------------------------
749   io/fs.t                      26   11  42.31%  2-5, 7-11, 18, 25
750   lib/io_pipe.t     3   768     6   ??       %  ??
751   lib/io_sock.t     3   768     5   ??       %  ??
752   op/stat.t                    56    5   8.93%  3-4, 20, 35, 39
753   Failed 4/140 test scripts, 97.14% okay. 27/2937 subtests failed, 99.08% okay.
754
755 Note that using `make test' target two more tests may fail: C<op/exec:1>
756 because of (mis)feature of C<pdksh>, and C<lib/posix:15>, which checks
757 that the buffers are not flushed on C<_exit> (this is a bug in the test
758 which assumes that tty output is buffered).
759
760 I submitted a patch to B<EMX> which makes it possible to fork() with EMX 
761 dynamic libraries loaded, which makes F<lib/io*> tests pass. This means
762 that soon the number of failing tests may decrease yet more.
763
764 However, the test F<lib/io_udp.t> is disabled, since it never terminates, I
765 do not know why. Comments/fixes welcome.
766
767 The reasons for failed tests are:
768
769 =over 8
770
771 =item F<io/fs.t>
772
773 Checks I<file system> operations. Tests:
774
775 =over 10
776
777 =item 2-5, 7-11
778
779 Check C<link()> and C<inode count> - nonesuch under OS/2.
780
781 =item 18
782
783 Checks C<atime> and C<mtime> of C<stat()> - I could not understand this test.
784
785 =item 25
786
787 Checks C<truncate()> on a filehandle just opened for write - I do not
788 know why this should or should not work.
789
790 =back
791
792 =item F<lib/io_pipe.t>
793
794 Checks C<IO::Pipe> module. Some feature of B<EMX> - test fork()s with
795 dynamic extension loaded - unsupported now.
796
797 =item F<lib/io_sock.t>
798
799 Checks C<IO::Socket> module. Some feature of B<EMX> - test fork()s
800 with dynamic extension loaded - unsupported now.
801
802 =item F<op/stat.t>
803
804 Checks C<stat()>. Tests:
805
806 =over 4
807
808 =item 3
809
810 Checks C<inode count> - nonesuch under OS/2.
811
812 =item 4
813
814 Checks C<mtime> and C<ctime> of C<stat()> - I could not understand this test.
815
816 =item 20
817
818 Checks C<-x> - determined by the file extension only under OS/2.
819
820 =item 35
821
822 Needs F</usr/bin>.
823
824 =item 39
825
826 Checks C<-t> of F</dev/null>. Should not fail!
827
828 =back
829
830 =back
831
832 In addition to errors, you should get a lot of warnings. 
833
834 =over 4
835
836 =item A lot of `bad free'
837
838 in databases related to Berkeley DB. This is a confirmed bug of
839 DB. You may disable this warnings, see L<"PERL_BADFREE">.
840
841 =item Process terminated by SIGTERM/SIGINT
842
843 This is a standard message issued by OS/2 applications. *nix
844 applications die in silence. It is considered a feature. One can
845 easily disable this by appropriate sighandlers. 
846
847 However the test engine bleeds these message to screen in unexpected
848 moments. Two messages of this kind I<should> be present during
849 testing.
850
851 =item F<*/sh.exe>: ln: not found
852
853 =item C<ls>: /dev: No such file or directory
854
855 The last two should be self-explanatory. The test suite discovers that
856 the system it runs on is not I<that much> *nixish.
857
858 =back
859
860 A lot of `bad free'... in databases, bug in DB confirmed on other
861 platforms. You may disable it by setting PERL_BADFREE environment variable
862 to 1.
863
864 =head2 Installing the built perl
865
866 Run
867
868   make install
869
870 It would put the generated files into needed locations. Manually put
871 F<perl.exe>, F<perl__.exe> and F<perl___.exe> to a location on your
872 C<PATH>, F<perl.dll> to a location on your C<LIBPATH>.
873
874 Run
875
876   make cmdscripts INSTALLCMDDIR=d:/ir/on/path
877
878 to convert perl utilities to F<.cmd> files and put them on
879 C<PATH>. You need to put F<.EXE>-utilities on path manually. They are
880 installed in C<$prefix/bin>, here C<$prefix> is what you gave to
881 F<Configure>, see L<Making>.
882
883 =head2 C<a.out>-style build
884
885 Proceed as above, but make F<perl_.exe> (see L<"perl_.exe">) by
886
887   make perl_
888
889 test and install by
890
891   make aout_test
892   make aout_install
893
894 Manually put F<perl_.exe> to a location on your C<PATH>.
895
896 Since C<perl_> has the extensions prebuilt, it does not suffer from
897 the I<dynamic extensions + fork()> syndrome, thus the failing tests
898 look like
899
900   Failed Test  Status Wstat Total Fail  Failed  List of failed
901   ---------------------------------------------------------------
902   io/fs.t                      26   11  42.31%  2-5, 7-11, 18, 25
903   op/stat.t                    56    5   8.93%  3-4, 20, 35, 39
904   Failed 2/118 test scripts, 98.31% okay. 16/2445 subtests failed, 99.35% okay.
905
906 B<Note.> The build process for C<perl_> I<does not know> about all the
907 dependencies, so you should make sure that anything is up-to-date,
908 say, by doing
909
910   make perl.dll
911
912 first.
913
914 =head1 Build FAQ
915
916 =head2 Some C</> became C<\> in pdksh.
917
918 You have a very old pdksh. See L<Prerequisites>.
919
920 =head2 C<'errno'> - unresolved external
921
922 You do not have MT-safe F<db.lib>. See L<Prerequisites>.
923
924 =head2 Problems with C<tr>
925
926 reported with very old version of C<tr>.
927
928 =head2 Some problem (forget which ;-)
929
930 You have an older version of F<perl.dll> on your C<LIBPATH>, which
931 broke the build of extensions.
932
933 =head2 Library ... not found
934
935 You did not run C<omflibs>. See L<Prerequisites>.
936
937 =head2 Segfault in make
938
939 You use an old version of C<GNU> make. See L<Prerequisites>.
940
941 =head1 Specific (mis)features of OS/2 port
942
943 =head2 C<setpriority>, C<getpriority>
944
945 Note that these functions are compatible with *nix, not with the older
946 ports of '94 - 95. The priorities are absolute, go from 32 to -95,
947 lower is quicker. 0 is the default priority.
948
949 =head2 C<system()>
950
951 Multi-argument form of C<system()> allows an additional numeric
952 argument. The meaning of this argument is described in
953 L<OS2::Process>.
954
955 =head2 Additional modules:
956
957 L<OS2::Process>, L<OS2::REXX>, L<OS2::PrfDB>, L<OS2::ExtAttr>. This
958 modules provide access to additional numeric argument for C<system>,
959 to DLLs having functions with REXX signature and to REXX runtime, to
960 OS/2 databases in the F<.INI> format, and to Extended Attributes.
961
962 Two additional extensions by Andreas Kaiser, C<OS2::UPM>, and
963 C<OS2::FTP>, are included into my ftp directory, mirrored on CPAN.
964
965 =head2 Prebuilt methods:
966
967 =over 4
968
969 =item C<File::Copy::syscopy>
970
971 used by C<File::Copy::copy>, see L<File::Copy/copy>.
972
973 =item C<DynaLoader::mod2fname>
974
975 used by C<DynaLoader> for DLL name mangling.
976
977 =item  C<Cwd::current_drive()>
978
979 Self explanatory.
980
981 =item  C<Cwd::sys_chdir(name)>
982
983 leaves drive as it is.
984
985 =item  C<Cwd::change_drive(name)>
986
987
988 =item  C<Cwd::sys_is_absolute(name)>
989
990 means has drive letter and is_rooted.
991
992 =item  C<Cwd::sys_is_rooted(name)>
993
994 means has leading C<[/\\]> (maybe after a drive-letter:).
995
996 =item  C<Cwd::sys_is_relative(name)>
997
998 means changes with current dir.
999
1000 =item  C<Cwd::sys_cwd(name)>
1001
1002 Interface to cwd from B<EMX>. Used by C<Cwd::cwd>.
1003
1004 =item  C<Cwd::sys_abspath(name, dir)>
1005
1006 Really really odious function to implement. Returns absolute name of
1007 file which would have C<name> if CWD were C<dir>.  C<Dir> defaults to the
1008 current dir.
1009
1010 =item  C<Cwd::extLibpath([type])
1011
1012 Get current value of extended library search path. If C<type> is
1013 present and I<true>, works with END_LIBPATH, otherwise with
1014 C<BEGIN_LIBPATH>. 
1015
1016 =item  C<Cwd::extLibpath_set( path [, type ] )>
1017
1018 Set current value of extended library search path. If C<type> is
1019 present and I<true>, works with END_LIBPATH, otherwise with
1020 C<BEGIN_LIBPATH>. 
1021
1022 =back
1023
1024 (Note that some of these may be moved to different libraries -
1025 eventually).
1026
1027
1028 =head2 Misfeatures
1029
1030 =over 4
1031
1032 =item
1033
1034 Since <flock> is present in B<EMX>, but is not functional, the same is
1035 true for perl. Here is the list of things which may be "broken" on
1036 EMX (from EMX docs):
1037
1038   - The functions recvmsg(), sendmsg(), and socketpair() are not
1039     implemented.
1040   - sock_init() is not required and not implemented.
1041   - flock() is not yet implemented (dummy function).
1042   - kill:
1043       Special treatment of PID=0, PID=1 and PID=-1 is not implemented.
1044   - waitpid:
1045       WUNTRACED
1046               Not implemented.
1047       waitpid() is not implemented for negative values of PID.
1048
1049 Note that C<kill -9> does not work with the current version of EMX.
1050
1051 =item
1052
1053 Since F<sh.exe> is used for globing (see L<perlfunc/glob>), the bugs
1054 of F<sh.exe> plague perl as well. 
1055
1056 In particular, uppercase letters do not work in C<[...]>-patterns with
1057 the current C<pdksh>.
1058
1059 =back
1060
1061 =head2 Modifications
1062
1063 Perl modifies some standard C library calls in the following ways:
1064
1065 =over 9
1066
1067 =item C<popen>
1068
1069 C<my_popen> uses F<sh.exe> if shell is required, cf. L<"PERL_SH_DIR">.
1070
1071 =item C<tmpnam>
1072
1073 is created using C<TMP> or C<TEMP> environment variable, via
1074 C<tempnam>.
1075
1076 =item C<tmpfile>
1077
1078 If the current directory is not writable, file is created using modified
1079 C<tmpnam>, so there may be a race condition.
1080
1081 =item C<ctermid>
1082
1083 a dummy implementation.
1084
1085 =item C<stat>
1086
1087 C<os2_stat> special-cases F</dev/tty> and F</dev/con>.
1088
1089 =back
1090
1091 =head1 Perl flavors
1092
1093 Because of idiosyncrasies of OS/2 one cannot have all the eggs in the
1094 same basket (though C<EMX> environment tries hard to overcome this
1095 limitations, so the situation may somehow improve). There are 4
1096 executables for Perl provided by the distribution:
1097
1098 =head2 F<perl.exe>
1099
1100 The main workhorse. This is a chimera executable: it is compiled as an
1101 C<a.out>-style executable, but is linked with C<omf>-style dynamic
1102 library F<perl.dll>, and with dynamic B<CRT> DLL. This executable is a
1103 C<VIO> application.
1104
1105 It can load perl dynamic extensions, and it can fork(). Unfortunately,
1106 with the current version of B<EMX> it cannot fork() with dynamic
1107 extensions loaded (may be fixed by patches to B<EMX>).
1108
1109 B<Note.> Keep in mind that fork() is needed to open a pipe to yourself.
1110
1111 =head2 F<perl_.exe>
1112
1113 This is a statically linked C<a.out>-style executable. It can fork(),
1114 but cannot load dynamic Perl extensions. The supplied executable has a
1115 lot of extensions prebuilt, thus there are situations when it can
1116 perform tasks not possible using F<perl.exe>, like fork()ing when
1117 having some standard extension loaded. This executable is a C<VIO>
1118 application.
1119
1120 B<Note.> A better behaviour could be obtained from C<perl.exe> if it
1121 were statically linked with standard I<Perl extensions>, but
1122 dynamically linked with the I<Perl DLL> and C<CRT> DLL. Then it would
1123 be able to fork() with standard extensions, I<and> would be able to
1124 dynamically load arbitrary extensions. Some changes to Makefiles and
1125 hint files should be necessary to achieve this.
1126
1127 I<This is also the only executable with does not require OS/2.> The
1128 friends locked into C<M$> world would appreciate the fact that this
1129 executable runs under DOS, Win0.3*, Win0.95 and WinNT with an
1130 appropriate extender. See L<"Other OSes">.
1131
1132 =head2 F<perl__.exe>
1133
1134 This is the same executable as <perl___.exe>, but it is a C<PM>
1135 application. 
1136
1137 B<Note.> Usually C<STDIN>, C<STDERR>, and C<STDOUT> of a C<PM>
1138 application are redirected to C<nul>. However, it is possible to see
1139 them if you start C<perl__.exe> from a PM program which emulates a
1140 console window, like I<Shell mode> of C<Emacs> or C<EPM>. Thus it I<is
1141 possible> to use Perl debugger (see L<perldebug>) to debug your PM
1142 application.
1143
1144 This flavor is required if you load extensions which use C<PM>, like
1145 the forthcoming C<Perl/Tk>.
1146
1147 =head2 F<perl___.exe>
1148
1149 This is an C<omf>-style executable which is dynamically linked to
1150 F<perl.dll> and C<CRT> DLL. I know no advantages of this executable
1151 over C<perl.exe>, but it cannot fork() at all. Well, one advantage is
1152 that the build process is not so convoluted as with C<perl.exe>.
1153
1154 It is a C<VIO> application.
1155
1156 =head2 Why strange names?
1157
1158 Since Perl processes the C<#!>-line (cf. 
1159 L<perlrun/DESCRIPTION>, L<perlrun/Switches>,
1160 L<perldiag/"Not a perl script">, 
1161 L<perldiag/"No Perl script found in input">), it should know when a
1162 program I<is a Perl>. There is some naming convention which allows
1163 Perl to distinguish correct lines from wrong ones. The above names are
1164 almost the only names allowed by this convention which do not contain
1165 digits (which have absolutely different semantics).
1166
1167 =head2 Why dynamic linking?
1168
1169 Well, having several executables dynamically linked to the same huge
1170 library has its advantages, but this would not substantiate the
1171 additional work to make it compile. The reason is stupid-but-quick
1172 "hard" dynamic linking used by OS/2.
1173
1174 The address tables of DLLs are patched only once, when they are
1175 loaded. The addresses of entry points into DLLs are guaranteed to be
1176 the same for all programs which use the same DLL, which reduces the
1177 amount of runtime patching - once DLL is loaded, its code is
1178 read-only.
1179
1180 While this allows some performance advantages, this makes life
1181 terrible for developers, since the above scheme makes it impossible
1182 for a DLL to be resolved to a symbol in the .EXE file, since this
1183 would need a DLL to have different relocations tables for the
1184 executables which use it.
1185
1186 However, a Perl extension is forced to use some symbols from the perl
1187 executable, say to know how to find the arguments provided on the perl
1188 internal evaluation stack. The solution is that the main code of
1189 interpreter should be contained in a DLL, and the F<.EXE> file just loads
1190 this DLL into memory and supplies command-arguments.
1191
1192 This I<greatly> increases the load time for the application (as well as
1193 the number of problems during compilation). Since interpreter is in a DLL,
1194 the C<CRT> is basically forced to reside in a DLL as well (otherwise
1195 extensions would not be able to use C<CRT>).
1196
1197 =head2 Why chimera build?
1198
1199 Current C<EMX> environment does not allow DLLs compiled using Unixish
1200 C<a.out> format to export symbols for data. This forces C<omf>-style
1201 compile of F<perl.dll>.
1202
1203 Current C<EMX> environment does not allow F<.EXE> files compiled in
1204 C<omf> format to fork(). fork() is needed for exactly three Perl
1205 operations:
1206
1207 =over 4
1208
1209 =item explicit fork()
1210
1211 in the script, and
1212
1213 =item open FH, "|-"
1214
1215 =item open FH, "-|"
1216
1217 opening pipes to itself.
1218
1219 =back
1220
1221 While these operations are not questions of life and death, a lot of
1222 useful scripts use them. This forces C<a.out>-style compile of
1223 F<perl.exe>.
1224
1225
1226 =head1 ENVIRONMENT
1227
1228 Here we list environment variables with are either OS/2-specific, or
1229 are more important under OS/2 than under other OSes.
1230
1231 =head2 C<PERLLIB_PREFIX>
1232
1233 Specific for OS/2. Should have the form
1234
1235   path1;path2
1236
1237 or
1238
1239   path1 path2
1240
1241 If the beginning of some prebuilt path matches F<path1>, it is
1242 substituted with F<path2>.
1243
1244 Should be used if the perl library is moved from the default
1245 location in preference to C<PERL(5)LIB>, since this would not leave wrong
1246 entries in <@INC>. 
1247
1248 =head2 C<PERL_BADLANG>
1249
1250 If 1, perl ignores setlocale() failing. May be useful with some
1251 strange I<locale>s.
1252
1253 =head2 C<PERL_BADFREE>
1254
1255 If 1, perl would not warn of in case of unwarranted free(). May be
1256 useful in conjunction with the module DB_File, since Berkeley DB
1257 memory handling code is buggy.
1258
1259 =head2 C<PERL_SH_DIR>
1260
1261 Specific for OS/2. Gives the directory part of the location for
1262 F<sh.exe>.
1263
1264 =head2 C<TMP> or C<TEMP>
1265
1266 Specific for OS/2. Used as storage place for temporary files, most
1267 notably C<-e> scripts.
1268
1269 =head1 Evolution
1270
1271 Here we list major changes which could make you by surprise.
1272
1273 =head2 Priorities
1274
1275 C<setpriority> and C<getpriority> are not compatible with earlier
1276 ports by Andreas Kaiser. See C<"setpriority, getpriority">.
1277
1278 =head2 DLL name mangling
1279
1280 With the release 5.003_01 the dynamically loadable libraries
1281 should be rebuilt. In particular, DLLs are now created with the names
1282 which contain a checksum, thus allowing workaround for OS/2 scheme of
1283 caching DLLs.
1284
1285 =head2 Threading
1286
1287 As of release 5.003_01 perl is linked to multithreaded C<CRT>
1288 DLL. Perl itself is not multithread-safe, as is not perl
1289 malloc(). However, extensions may use multiple thread on their own
1290 risk. 
1291
1292 Needed to compile C<Perl/Tk> for C<XFreeOS/2> out-of-the-box.
1293
1294 =head2 Calls to external programs
1295
1296 Due to a popular demand the perl external program calling has been
1297 changed wrt Andreas Kaiser's port.  I<If> perl needs to call an
1298 external program I<via shell>, the F<f:/bin/sh.exe> will be called, or
1299 whatever is the override, see L<"PERL_SH_DIR">.
1300
1301 Thus means that you need to get some copy of a F<sh.exe> as well (I
1302 use one from pdksh). The drive F: above is set up automatically during
1303 the build to a correct value on the builder machine, but is
1304 overridable at runtime,
1305
1306 B<Reasons:> a consensus on C<perl5-porters> was that perl should use
1307 one non-overridable shell per platform. The obvious choices for OS/2
1308 are F<cmd.exe> and F<sh.exe>. Having perl build itself would be impossible
1309 with F<cmd.exe> as a shell, thus I picked up C<sh.exe>. Thus assures almost
1310 100% compatibility with the scripts coming from *nix.
1311
1312 B<Disadvantages:> currently F<sh.exe> of C<pdksh> calls external programs
1313 via fork()/exec(), and there is I<no> functioning exec() on
1314 OS/2. exec() is emulated by EMX by asyncroneous call while the caller
1315 waits for child completion (to pretend that the C<pid> did not change). This
1316 means that 1 I<extra> copy of F<sh.exe> is made active via fork()/exec(),
1317 which may lead to some resources taken from the system (even if we do
1318 not count extra work needed for fork()ing).
1319
1320 Note that this a lesser issue now when we do not spawn F<sh.exe>
1321 unless needed (metachars found).
1322
1323 One can always start F<cmd.exe> explicitly via
1324
1325   system 'cmd', '/c', 'mycmd', 'arg1', 'arg2', ...
1326
1327 If you need to use F<cmd.exe>, and do not want to hand-edit thousands of your
1328 scripts, the long-term solution proposed on p5-p is to have a directive
1329
1330   use OS2::Cmd;
1331
1332 which will override system(), exec(), C<``>, and
1333 C<open(,'...|')>. With current perl you may override only system(),
1334 readpipe() - the explicit version of C<``>, and maybe exec(). The code
1335 will substitute the one-argument call to system() by
1336 C<CORE::system('cmd.exe', '/c', shift)>.
1337
1338 If you have some working code for C<OS2::Cmd>, please send it to me,
1339 I will include it into distribution. I have no need for such a module, so
1340 cannot test it.
1341
1342 =head2 Memory allocation
1343
1344 Perl uses its own malloc() under OS/2 - interpreters are usually malloc-bound
1345 for speed, but perl is not, since its malloc is lightning-fast. 
1346 Unfortunately, it is also quite frivolous with memory usage as well.
1347
1348 Since kitchen-top machines are usually low on memory, perl is compiled with
1349 all the possible memory-saving options. This probably makes perl's 
1350 malloc() as greedy with memory as the neighbor's malloc(), but still
1351 much quickier. Note that this is true only for a "typical" usage,
1352 it is possible that the perl malloc will be worse for some very special usage.
1353
1354 Combination of perl's malloc() and rigid DLL name resolution creates
1355 a special problem with library functions which expect their return value to
1356 be free()d by system's free(). To facilitate extensions which need to call 
1357 such functions, system memory-allocation functions are still available with
1358 the prefix C<emx_> added. (Currently only DLL perl has this, it should 
1359 propagate to F<perl_.exe> shortly.)
1360
1361 =cut
1362
1363 OS/2 extensions
1364 ~~~~~~~~~~~~~~~
1365 I include 3 extensions by Andreas Kaiser, OS2::REXX, OS2::UPM, and OS2::FTP, 
1366 into my ftp directory, mirrored on CPAN. I made
1367 some minor changes needed to compile them by standard tools. I cannot 
1368 test UPM and FTP, so I will appreciate your feedback. Other extensions
1369 there are OS2::ExtAttr, OS2::PrfDB for tied access to EAs and .INI
1370 files - and maybe some other extensions at the time you read it.
1371
1372 Note that OS2 perl defines 2 pseudo-extension functions
1373 OS2::Copy::copy and DynaLoader::mod2fname.
1374
1375 The -R switch of older perl is deprecated. If you need to call a REXX code
1376 which needs access to variables, include the call into a REXX compartment
1377 created by 
1378         REXX_call {...block...};
1379
1380 Two new functions are supported by REXX code, 
1381         REXX_eval 'string';
1382         REXX_eval_with 'string', REXX_function_name => \&perl_sub_reference;
1383
1384 If you have some other extensions you want to share, send the code to
1385 me.  At least two are available: tied access to EA's, and tied access
1386 to system databases.
1387
1388 =head1 AUTHOR
1389
1390 Ilya Zakharevich, ilya@math.ohio-state.edu
1391
1392 =head1 SEE ALSO
1393
1394 perl(1).
1395
1396 =cut
1397