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