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