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