This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Cwd.pm needs to be installed in lib before Encode recurses. Mark the dependency
[perl5.git] / README.os2
CommitLineData
a56dbb1c
PP
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
PP
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
IZ
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
IZ
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
25417810 32EMX's distribution). There is also a different viewer named xview.
72ea3524 33
25417810 34Note that if you have F<lynx.exe> or F<netscape.exe> installed, you can follow WWW links
d7678ab8
CS
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
PP
40=cut
41
25417810 42Contents (This may be a little bit obsolete)
a56dbb1c 43
df3ef7a9 44 perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT.
a56dbb1c 45
25417810
IZ
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 - "It does not work"
56 - I cannot run external programs
57 - I cannot embed perl into my program, or use perl.dll from my
58 - `` and pipe-open do not work under DOS.
59 - Cannot start find.exe "pattern" file
60 INSTALLATION
61 - Automatic binary installation
62 - Manual binary installation
63 - Warning
64 Accessing documentation
65 - OS/2 .INF file
66 - Plain text
67 - Manpages
68 - HTML
69 - GNU info files
70 - PDF files
71 - LaTeX docs
72 BUILD
73 - The short story
74 - Prerequisites
75 - Getting perl source
76 - Application of the patches
77 - Hand-editing
78 - Making
79 - Testing
80 - Installing the built perl
81 - a.out-style build
82 Build FAQ
83 - Some / became \ in pdksh.
84 - 'errno' - unresolved external
85 - Problems with tr or sed
86 - Some problem (forget which ;-)
87 - Library ... not found
88 - Segfault in make
89 - op/sprintf test failure
90 Specific (mis)features of OS/2 port
91 - setpriority, getpriority
92 - system()
93 - extproc on the first line
94 - Additional modules:
95 - Prebuilt methods:
96 - Prebuilt variables:
97 - Misfeatures
98 - Modifications
99 - Identifying DLLs
100 - Centralized management of resources
101 Perl flavors
102 - perl.exe
103 - perl_.exe
104 - perl__.exe
105 - perl___.exe
106 - Why strange names?
107 - Why dynamic linking?
108 - Why chimera build?
109 ENVIRONMENT
110 - PERLLIB_PREFIX
111 - PERL_BADLANG
112 - PERL_BADFREE
113 - PERL_SH_DIR
114 - USE_PERL_FLOCK
115 - TMP or TEMP
116 Evolution
117 - Text-mode filehandles
118 - Priorities
119 - DLL name mangling: pre 5.6.2
120 - DLL name mangling: 5.6.2 and beyond
121 - DLL forwarder generation
122 - Threading
123 - Calls to external programs
124 - Memory allocation
125 - Threads
126 BUGS
127 AUTHOR
128 SEE ALSO
abe67105 129
a56dbb1c
PP
130=head1 DESCRIPTION
131
132=head2 Target
133
25417810 134The target is to make OS/2 one of the best supported platform for
72ea3524 135using/building/developing Perl and I<Perl applications>, as well as
aa689395
PP
136make Perl the best language to use under OS/2. The secondary target is
137to try to make this work under DOS and Win* as well (but not B<too> hard).
a56dbb1c
PP
138
139The current state is quite close to this target. Known limitations:
140
141=over 5
142
143=item *
144
25417810
IZ
145Some *nix programs use fork() a lot; with the mostly useful flavors of
146perl for OS/2 (there are several built simultaneously) this is
147supported; but some flavors do not support this (e.g., when Perl is
148called from inside REXX). Using fork() after
149I<use>ing dynamically loading extensions would not work with I<very> old
150versions of EMX.
a56dbb1c
PP
151
152=item *
153
154You need a separate perl executable F<perl__.exe> (see L<perl__.exe>)
3998488b
JH
155if you want to use PM code in your application (as Perl/Tk or OpenGL
156Perl modules do) without having a text-mode window present.
157
158While using the standard F<perl.exe> from a text-mode window is possible
159too, I have seen cases when this causes degradation of the system stability.
160Using F<perl__.exe> avoids such a degradation.
a56dbb1c
PP
161
162=item *
163
aa689395 164There is no simple way to access WPS objects. The only way I know
25417810
IZ
165is via C<OS2::REXX> and C<SOM> extensions (see L<OS2::REXX>, L<Som>).
166However, we do not have access to
aa689395 167convenience methods of Object-REXX. (Is it possible at all? I know
3998488b 168of no Object-REXX API.) The C<SOM> extension (currently in alpha-text)
25417810
IZ
169may eventually remove this shortcoming; however, due to the fact that
170DII is not supported by the C<SOM> module, using C<SOM> is not as
171convenient as one would like it.
a56dbb1c
PP
172
173=back
174
175Please keep this list up-to-date by informing me about other items.
176
177=head2 Other OSes
178
aa689395 179Since OS/2 port of perl uses a remarkable EMX environment, it can
3998488b 180run (and build extensions, and - possibly - be built itself) under any
a56dbb1c 181environment which can run EMX. The current list is DOS,
72ea3524 182DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT. Out of many perl flavors,
a56dbb1c
PP
183only one works, see L<"perl_.exe">.
184
185Note that not all features of Perl are available under these
186environments. This depends on the features the I<extender> - most
aa689395 187probably RSX - decided to implement.
a56dbb1c
PP
188
189Cf. L<Prerequisites>.
190
191=head2 Prerequisites
192
193=over 6
194
aa689395 195=item EMX
a56dbb1c 196
aa689395 197EMX runtime is required (may be substituted by RSX). Note that
55497cff 198it is possible to make F<perl_.exe> to run under DOS without any
72ea3524 199external support by binding F<emx.exe>/F<rsx.exe> to it, see L<emxbind>. Note
aa689395 200that under DOS for best results one should use RSX runtime, which
55497cff 201has much more functions working (like C<fork>, C<popen> and so on). In
aa689395 202fact RSX is required if there is no VCPI present. Note the
25417810
IZ
203RSX requires DPMI. Many implementations of DPMI are known to be very
204buggy, beware!
a56dbb1c 205
884335e8 206Only the latest runtime is supported, currently C<0.9d fix 03>. Perl may run
aa689395 207under earlier versions of EMX, but this is not tested.
a56dbb1c 208
aa689395 209One can get different parts of EMX from, say
a56dbb1c 210
884335e8
YST
211 http://www.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/
212 http://powerusersbbs.com/pub/os2/dev/ [EMX+GCC Development]
213 http://hobbes.nmsu.edu/pub/os2/dev/emx/v0.9d/
a56dbb1c
PP
214
215The runtime component should have the name F<emxrt.zip>.
216
25417810 217B<NOTE>. When using F<emx.exe>/F<rsx.exe>, it is enough to have them on your path. One
72ea3524
IZ
218does not need to specify them explicitly (though this
219
220 emx perl_.exe -de 0
221
222will work as well.)
223
aa689395 224=item RSX
a56dbb1c 225
aa689395 226To run Perl on DPMI platforms one needs RSX runtime. This is
72ea3524 227needed under DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT (see
aa689395
PP
228L<"Other OSes">). RSX would not work with VCPI
229only, as EMX would, it requires DMPI.
55497cff 230
aa689395 231Having RSX and the latest F<sh.exe> one gets a fully functional
55497cff
PP
232B<*nix>-ish environment under DOS, say, C<fork>, C<``> and
233pipe-C<open> work. In fact, MakeMaker works (for static build), so one
234can have Perl development environment under DOS.
a56dbb1c 235
aa689395 236One can get RSX from, say
a56dbb1c 237
d7678ab8 238 ftp://ftp.cdrom.com/pub/os2/emx09c/contrib
a56dbb1c 239 ftp://ftp.uni-bielefeld.de/pub/systems/msdos/misc
d7678ab8 240 ftp://ftp.leo.org/pub/comp/os/os2/leo/devtools/emx+gcc/contrib
a56dbb1c
PP
241
242Contact the author on C<rainer@mathematik.uni-bielefeld.de>.
243
3998488b
JH
244The latest F<sh.exe> with DOS hooks is available in
245
25417810 246 http://www.ilyaz.org/software/os2/
55497cff 247
3998488b 248as F<sh_dos.zip> or under similar names starting with C<sh>, C<pdksh> etc.
55497cff 249
aa689395 250=item HPFS
a56dbb1c 251
25417810
IZ
252Perl does not care about file systems, but the perl library contains
253many files with long names, so to install it intact one needs a file
254system which supports long file names.
a56dbb1c
PP
255
256Note that if you do not plan to build the perl itself, it may be
aa689395
PP
257possible to fool EMX to truncate file names. This is not supported,
258read EMX docs to see how to do it.
259
260=item pdksh
261
262To start external programs with complicated command lines (like with
263pipes in between, and/or quoting of arguments), Perl uses an external
3998488b 264shell. With EMX port such shell should be named F<sh.exe>, and located
aa689395
PP
265either in the wired-in-during-compile locations (usually F<F:/bin>),
266or in configurable location (see L<"PERL_SH_DIR">).
267
3998488b
JH
268For best results use EMX pdksh. The standard binary (5.2.14 or later) runs
269under DOS (with L<RSX>) as well, see
aa689395 270
25417810 271 http://www.ilyaz.org/software/os2/
a56dbb1c
PP
272
273=back
274
aa689395 275=head2 Starting Perl programs under OS/2 (and DOS and...)
a56dbb1c
PP
276
277Start your Perl program F<foo.pl> with arguments C<arg1 arg2 arg3> the
278same way as on any other platform, by
279
280 perl foo.pl arg1 arg2 arg3
281
282If you want to specify perl options C<-my_opts> to the perl itself (as
d1be9408 283opposed to your program), use
a56dbb1c
PP
284
285 perl -my_opts foo.pl arg1 arg2 arg3
286
aa689395 287Alternately, if you use OS/2-ish shell, like CMD or 4os2, put
a56dbb1c
PP
288the following at the start of your perl script:
289
aa689395 290 extproc perl -S -my_opts
a56dbb1c
PP
291
292rename your program to F<foo.cmd>, and start it by typing
293
294 foo arg1 arg2 arg3
295
a56dbb1c
PP
296Note that because of stupid OS/2 limitations the full path of the perl
297script is not available when you use C<extproc>, thus you are forced to
3998488b 298use C<-S> perl switch, and your script should be on the C<PATH>. As a plus
a56dbb1c
PP
299side, if you know a full path to your script, you may still start it
300with
301
aa689395 302 perl ../../blah/foo.cmd arg1 arg2 arg3
a56dbb1c 303
aa689395
PP
304(note that the argument C<-my_opts> is taken care of by the C<extproc> line
305in your script, see L<C<extproc> on the first line>).
a56dbb1c
PP
306
307To understand what the above I<magic> does, read perl docs about C<-S>
aa689395 308switch - see L<perlrun>, and cmdref about C<extproc>:
a56dbb1c
PP
309
310 view perl perlrun
311 man perlrun
312 view cmdref extproc
313 help extproc
314
315or whatever method you prefer.
316
72ea3524 317There are also endless possibilities to use I<executable extensions> of
aa689395 3184os2, I<associations> of WPS and so on... However, if you use
a56dbb1c 319*nixish shell (like F<sh.exe> supplied in the binary distribution),
72ea3524 320you need to follow the syntax specified in L<perlrun/"Switches">.
a56dbb1c 321
25417810 322Note that B<-S> switch supports scripts with additional extensions
d8c2d278
IZ
323F<.cmd>, F<.btm>, F<.bat>, F<.pl> as well.
324
aa689395 325=head2 Starting OS/2 (and DOS) programs under Perl
a56dbb1c
PP
326
327This is what system() (see L<perlfunc/system>), C<``> (see
328L<perlop/"I/O Operators">), and I<open pipe> (see L<perlfunc/open>)
329are for. (Avoid exec() (see L<perlfunc/exec>) unless you know what you
330do).
331
332Note however that to use some of these operators you need to have a
aa689395 333sh-syntax shell installed (see L<"Pdksh">,
a56dbb1c
PP
334L<"Frequently asked questions">), and perl should be able to find it
335(see L<"PERL_SH_DIR">).
336
2c2e0e8c
IZ
337The cases when the shell is used are:
338
339=over
340
341=item 1
342
343One-argument system() (see L<perlfunc/system>), exec() (see L<perlfunc/exec>)
344with redirection or shell meta-characters;
345
346=item 2
347
348Pipe-open (see L<perlfunc/open>) with the command which contains redirection
349or shell meta-characters;
350
351=item 3
352
353Backticks C<``> (see L<perlop/"I/O Operators">) with the command which contains
354redirection or shell meta-characters;
355
356=item 4
357
358If the executable called by system()/exec()/pipe-open()/C<``> is a script
359with the "magic" C<#!> line or C<extproc> line which specifies shell;
360
361=item 5
362
363If the executable called by system()/exec()/pipe-open()/C<``> is a script
364without "magic" line, and C<$ENV{EXECSHELL}> is set to shell;
365
366=item 6
367
368If the executable called by system()/exec()/pipe-open()/C<``> is not
25417810 369found (is not this remark obsolete?);
2c2e0e8c
IZ
370
371=item 7
372
25417810
IZ
373For globbing (see L<perlfunc/glob>, L<perlop/"I/O Operators">)
374(obsolete? Perl uses builtin globbing nowadays...).
2c2e0e8c
IZ
375
376=back
377
378For the sake of speed for a common case, in the above algorithms
379backslashes in the command name are not considered as shell metacharacters.
380
381Perl starts scripts which begin with cookies
382C<extproc> or C<#!> directly, without an intervention of shell. Perl uses the
383same algorithm to find the executable as F<pdksh>: if the path
25417810
IZ
384on C<#!> line does not work, and contains C</>, then the directory
385part of the executable is ignored, and the executable
2c2e0e8c
IZ
386is searched in F<.> and on C<PATH>. To find arguments for these scripts
387Perl uses a different algorithm than F<pdksh>: up to 3 arguments are
388recognized, and trailing whitespace is stripped.
389
390If a script
391does not contain such a cooky, then to avoid calling F<sh.exe>, Perl uses
392the same algorithm as F<pdksh>: if C<$ENV{EXECSHELL}> is set, the
393script is given as the first argument to this command, if not set, then
394C<$ENV{COMSPEC} /c> is used (or a hardwired guess if C<$ENV{COMSPEC}> is
395not set).
491527d0 396
25417810 397When starting scripts directly, Perl uses exactly the same algorithm as for
491527d0
GS
398the search of script given by B<-S> command-line option: it will look in
399the current directory, then on components of C<$ENV{PATH}> using the
400following order of appended extensions: no extension, F<.cmd>, F<.btm>,
401F<.bat>, F<.pl>.
402
403Note that Perl will start to look for scripts only if OS/2 cannot start the
404specified application, thus C<system 'blah'> will not look for a script if
25417810
IZ
405there is an executable file F<blah.exe> I<anywhere> on C<PATH>. In
406other words, C<PATH> is essentially searched twice: once by the OS for
407an executable, then by Perl for scripts.
491527d0
GS
408
409Note also that executable files on OS/2 can have an arbitrary extension,
410but F<.exe> will be automatically appended if no dot is present in the name.
d1be9408 411The workaround is as simple as that: since F<blah.> and F<blah> denote the
25417810 412same file (at list on FAT and HPFS file systems), to start an executable residing in file F<n:/bin/blah> (no
3998488b 413extension) give an argument C<n:/bin/blah.> (dot appended) to system().
491527d0 414
25417810
IZ
415Perl will start PM programs from VIO (=text-mode) Perl process in a
416separate PM session;
3998488b 417the opposite is not true: when you start a non-PM program from a PM
25417810 418Perl process, Perl would not run it in a separate session. If a separate
3998488b
JH
419session is desired, either ensure
420that shell will be used, as in C<system 'cmd /c myprog'>, or start it using
491527d0 421optional arguments to system() documented in C<OS2::Process> module. This
3998488b 422is considered to be a feature.
a56dbb1c
PP
423
424=head1 Frequently asked questions
425
3998488b
JH
426=head2 "It does not work"
427
428Perl binary distributions come with a F<testperl.cmd> script which tries
429to detect common problems with misconfigured installations. There is a
430pretty large chance it will discover which step of the installation you
431managed to goof. C<;-)>
432
72ea3524 433=head2 I cannot run external programs
a56dbb1c 434
55497cff
PP
435=over 4
436
13a2d996 437=item *
55497cff 438
a56dbb1c 439Did you run your programs with C<-w> switch? See
aa689395 440L<Starting OS/2 (and DOS) programs under Perl>.
a56dbb1c 441
13a2d996 442=item *
55497cff
PP
443
444Do you try to run I<internal> shell commands, like C<`copy a b`>
445(internal for F<cmd.exe>), or C<`glob a*b`> (internal for ksh)? You
72ea3524 446need to specify your shell explicitly, like C<`cmd /c copy a b`>,
55497cff
PP
447since Perl cannot deduce which commands are internal to your shell.
448
449=back
450
a56dbb1c
PP
451=head2 I cannot embed perl into my program, or use F<perl.dll> from my
452program.
453
454=over 4
455
aa689395 456=item Is your program EMX-compiled with C<-Zmt -Zcrtdll>?
a56dbb1c 457
25417810
IZ
458Well, nowadays Perl DLL should be usable from a differently compiled
459program too... If you can run Perl code from REXX scripts (see
460L<OS2::REXX>), then there are some other aspect of interaction which
461are overlooked by the current hackish code to support
462differently-compiled principal programs.
463
464If everything else fails, you need to build a stand-alone DLL for
465perl. Contact me, I did it once. Sockets would not work, as a lot of
466other stuff.
a56dbb1c 467
aa689395 468=item Did you use L<ExtUtils::Embed>?
a56dbb1c 469
25417810
IZ
470Some time ago I had reports it does not work. Nowadays it is checked
471in the Perl test suite, so grep F<./t> subdirectory of the build tree
472(as well as F<*.t> files in the F<./lib> subdirectory) to find how it
473should be done "correctly".
a56dbb1c
PP
474
475=back
476
55497cff
PP
477=head2 C<``> and pipe-C<open> do not work under DOS.
478
72ea3524 479This may a variant of just L<"I cannot run external programs">, or a
aa689395 480deeper problem. Basically: you I<need> RSX (see L<"Prerequisites">)
72ea3524 481for these commands to work, and you may need a port of F<sh.exe> which
55497cff 482understands command arguments. One of such ports is listed in
aa689395
PP
483L<"Prerequisites"> under RSX. Do not forget to set variable
484C<L<"PERL_SH_DIR">> as well.
485
486DPMI is required for RSX.
487
488=head2 Cannot start C<find.exe "pattern" file>
55497cff 489
25417810
IZ
490The whole idea of the "standard C API to start applications" is that
491the forms C<foo> and C<"foo"> of program arguments are completely
492interchangable. F<find> breaks this paradigm;
493
494 find "pattern" file
495 find pattern file
496
497are not equivalent; F<find> cannot be started directly using the above
498API. One needs a way to surround the doublequotes in some other
499quoting construction, necessarily having an extra non-Unixish shell in
500between.
501
aa689395
PP
502Use one of
503
504 system 'cmd', '/c', 'find "pattern" file';
505 `cmd /c 'find "pattern" file'`
506
507This would start F<find.exe> via F<cmd.exe> via C<sh.exe> via
508C<perl.exe>, but this is a price to pay if you want to use
25417810 509non-conforming program.
55497cff 510
a56dbb1c
PP
511=head1 INSTALLATION
512
513=head2 Automatic binary installation
514
3998488b 515The most convenient way of installing a binary distribution of perl is via perl installer
a56dbb1c
PP
516F<install.exe>. Just follow the instructions, and 99% of the
517installation blues would go away.
518
519Note however, that you need to have F<unzip.exe> on your path, and
aa689395
PP
520EMX environment I<running>. The latter means that if you just
521installed EMX, and made all the needed changes to F<Config.sys>,
522you may need to reboot in between. Check EMX runtime by running
a56dbb1c
PP
523
524 emxrev
525
25417810
IZ
526Binary installer also creates a folder on your desktop with some useful
527objects. If you need to change some aspects of the work of the binary
528installer, feel free to edit the file F<Perl.pkg>. This may be useful
529e.g., if you need to run the installer many times and do not want to
530make many interactive changes in the GUI.
a56dbb1c
PP
531
532B<Things not taken care of by automatic binary installation:>
533
534=over 15
535
536=item C<PERL_BADLANG>
537
538may be needed if you change your codepage I<after> perl installation,
aa689395 539and the new value is not supported by EMX. See L<"PERL_BADLANG">.
a56dbb1c
PP
540
541=item C<PERL_BADFREE>
542
543see L<"PERL_BADFREE">.
544
545=item F<Config.pm>
546
547This file resides somewhere deep in the location you installed your
548perl library, find it out by
549
550 perl -MConfig -le "print $INC{'Config.pm'}"
551
552While most important values in this file I<are> updated by the binary
553installer, some of them may need to be hand-edited. I know no such
25417810
IZ
554data, please keep me informed if you find one. Moreover, manual
555changes to the installed version may need to be accompanied by an edit
556of this file.
a56dbb1c
PP
557
558=back
559
aa689395
PP
560B<NOTE>. Because of a typo the binary installer of 5.00305
561would install a variable C<PERL_SHPATH> into F<Config.sys>. Please
562remove this variable and put C<L<PERL_SH_DIR>> instead.
563
a56dbb1c
PP
564=head2 Manual binary installation
565
72ea3524 566As of version 5.00305, OS/2 perl binary distribution comes split
a56dbb1c 567into 11 components. Unfortunately, to enable configurable binary
aa689395 568installation, the file paths in the zip files are not absolute, but
a56dbb1c
PP
569relative to some directory.
570
571Note that the extraction with the stored paths is still necessary
aa689395 572(default with unzip, specify C<-d> to pkunzip). However, you
a56dbb1c
PP
573need to know where to extract the files. You need also to manually
574change entries in F<Config.sys> to reflect where did you put the
72ea3524 575files. Note that if you have some primitive unzipper (like
25417810 576C<pkunzip>), you may get a lot of warnings/errors during
72ea3524 577unzipping. Upgrade to C<(w)unzip>.
a56dbb1c
PP
578
579Below is the sample of what to do to reproduce the configuration on my
25417810
IZ
580machine. In F<VIEW.EXE> you can press C<Ctrl-Insert> now, and
581cut-and-paste from the resulting file - created in the directory you
582started F<VIEW.EXE> from.
583
584For each component, we mention environment variables related to each
585installation directory. Either choose directories to match your
586values of the variables, or create/append-to variables to take into
587account the directories.
a56dbb1c
PP
588
589=over 3
590
591=item Perl VIO and PM executables (dynamically linked)
592
593 unzip perl_exc.zip *.exe *.ico -d f:/emx.add/bin
594 unzip perl_exc.zip *.dll -d f:/emx.add/dll
595
aa689395
PP
596(have the directories with C<*.exe> on PATH, and C<*.dll> on
597LIBPATH);
a56dbb1c
PP
598
599=item Perl_ VIO executable (statically linked)
600
601 unzip perl_aou.zip -d f:/emx.add/bin
602
aa689395 603(have the directory on PATH);
a56dbb1c
PP
604
605=item Executables for Perl utilities
606
607 unzip perl_utl.zip -d f:/emx.add/bin
608
aa689395 609(have the directory on PATH);
a56dbb1c
PP
610
611=item Main Perl library
612
613 unzip perl_mlb.zip -d f:/perllib/lib
614
3998488b
JH
615If this directory is exactly the same as the prefix which was compiled
616into F<perl.exe>, you do not need to change
617anything. However, for perl to find the library if you use a different
618path, you need to
a56dbb1c
PP
619C<set PERLLIB_PREFIX> in F<Config.sys>, see L<"PERLLIB_PREFIX">.
620
621=item Additional Perl modules
622
fa7a1c65 623 unzip perl_ste.zip -d f:/perllib/lib/site_perl/5.11.0/
a56dbb1c 624
3998488b
JH
625Same remark as above applies. Additionally, if this directory is not
626one of directories on @INC (and @INC is influenced by C<PERLLIB_PREFIX>), you
627need to put this
a56dbb1c
PP
628directory and subdirectory F<./os2> in C<PERLLIB> or C<PERL5LIB>
629variable. Do not use C<PERL5LIB> unless you have it set already. See
3998488b 630L<perl/"ENVIRONMENT">.
a56dbb1c 631
25417810
IZ
632B<[Check whether this extraction directory is still applicable with
633the new directory structure layout!]>
634
a56dbb1c
PP
635=item Tools to compile Perl modules
636
637 unzip perl_blb.zip -d f:/perllib/lib
638
3998488b 639Same remark as for F<perl_ste.zip>.
a56dbb1c
PP
640
641=item Manpages for Perl and utilities
642
643 unzip perl_man.zip -d f:/perllib/man
644
645This directory should better be on C<MANPATH>. You need to have a
25417810 646working F<man> to access these files.
a56dbb1c
PP
647
648=item Manpages for Perl modules
649
650 unzip perl_mam.zip -d f:/perllib/man
651
652This directory should better be on C<MANPATH>. You need to have a
aa689395 653working man to access these files.
a56dbb1c
PP
654
655=item Source for Perl documentation
656
657 unzip perl_pod.zip -d f:/perllib/lib
658
3998488b 659This is used by the C<perldoc> program (see L<perldoc>), and may be used to
aa689395 660generate HTML documentation usable by WWW browsers, and
a56dbb1c 661documentation in zillions of other formats: C<info>, C<LaTeX>,
25417810
IZ
662C<Acrobat>, C<FrameMaker> and so on. [Use programs such as
663F<pod2latex> etc.]
a56dbb1c 664
aa689395 665=item Perl manual in F<.INF> format
a56dbb1c
PP
666
667 unzip perl_inf.zip -d d:/os2/book
668
669This directory should better be on C<BOOKSHELF>.
670
671=item Pdksh
672
673 unzip perl_sh.zip -d f:/bin
674
72ea3524 675This is used by perl to run external commands which explicitly
a56dbb1c
PP
676require shell, like the commands using I<redirection> and I<shell
677metacharacters>. It is also used instead of explicit F</bin/sh>.
678
679Set C<PERL_SH_DIR> (see L<"PERL_SH_DIR">) if you move F<sh.exe> from
680the above location.
681
25417810 682B<Note.> It may be possible to use some other sh-compatible shell (untested).
a56dbb1c
PP
683
684=back
685
686After you installed the components you needed and updated the
687F<Config.sys> correspondingly, you need to hand-edit
688F<Config.pm>. This file resides somewhere deep in the location you
689installed your perl library, find it out by
690
691 perl -MConfig -le "print $INC{'Config.pm'}"
692
693You need to correct all the entries which look like file paths (they
694currently start with C<f:/>).
695
696=head2 B<Warning>
697
698The automatic and manual perl installation leave precompiled paths
699inside perl executables. While these paths are overwriteable (see
25417810 700L<"PERLLIB_PREFIX">, L<"PERL_SH_DIR">), some people may prefer
a56dbb1c
PP
701binary editing of paths inside the executables/DLLs.
702
703=head1 Accessing documentation
704
705Depending on how you built/installed perl you may have (otherwise
706identical) Perl documentation in the following formats:
707
708=head2 OS/2 F<.INF> file
709
aa689395 710Most probably the most convenient form. Under OS/2 view it as
a56dbb1c
PP
711
712 view perl
713 view perl perlfunc
714 view perl less
715 view perl ExtUtils::MakeMaker
716
717(currently the last two may hit a wrong location, but this may improve
aa689395 718soon). Under Win* see L<"SYNOPSIS">.
a56dbb1c
PP
719
720If you want to build the docs yourself, and have I<OS/2 toolkit>, run
721
722 pod2ipf > perl.ipf
723
724in F</perllib/lib/pod> directory, then
725
726 ipfc /inf perl.ipf
727
728(Expect a lot of errors during the both steps.) Now move it on your
729BOOKSHELF path.
730
731=head2 Plain text
732
733If you have perl documentation in the source form, perl utilities
aa689395 734installed, and GNU groff installed, you may use
a56dbb1c
PP
735
736 perldoc perlfunc
737 perldoc less
738 perldoc ExtUtils::MakeMaker
739
72ea3524 740to access the perl documentation in the text form (note that you may get
a56dbb1c
PP
741better results using perl manpages).
742
743Alternately, try running pod2text on F<.pod> files.
744
745=head2 Manpages
746
25417810 747If you have F<man> installed on your system, and you installed perl
a56dbb1c 748manpages, use something like this:
5243f9ae 749
5243f9ae
PP
750 man perlfunc
751 man 3 less
752 man ExtUtils.MakeMaker
5243f9ae 753
a56dbb1c
PP
754to access documentation for different components of Perl. Start with
755
756 man perl
757
758Note that dot (F<.>) is used as a package separator for documentation
759for packages, and as usual, sometimes you need to give the section - C<3>
760above - to avoid shadowing by the I<less(1) manpage>.
761
762Make sure that the directory B<above> the directory with manpages is
763on our C<MANPATH>, like this
764
765 set MANPATH=c:/man;f:/perllib/man
766
3998488b
JH
767for Perl manpages in C<f:/perllib/man/man1/> etc.
768
aa689395 769=head2 HTML
a56dbb1c
PP
770
771If you have some WWW browser available, installed the Perl
772documentation in the source form, and Perl utilities, you can build
aa689395 773HTML docs. Cd to directory with F<.pod> files, and do like this
a56dbb1c
PP
774
775 cd f:/perllib/lib/pod
5243f9ae 776 pod2html
5243f9ae 777
a56dbb1c
PP
778After this you can direct your browser the file F<perl.html> in this
779directory, and go ahead with reading docs, like this:
5243f9ae 780
a56dbb1c 781 explore file:///f:/perllib/lib/pod/perl.html
5243f9ae 782
aa689395 783Alternatively you may be able to get these docs prebuilt from CPAN.
5243f9ae 784
aa689395 785=head2 GNU C<info> files
bb14ff96 786
aa689395 787Users of Emacs would appreciate it very much, especially with
25417810
IZ
788C<CPerl> mode loaded. You need to get latest C<pod2texi> from C<CPAN>,
789or, alternately, the prebuilt info pages.
615d1a09 790
5cb3728c 791=head2 F<PDF> files
a56dbb1c 792
25417810 793for C<Acrobat> are available on CPAN (may be for slightly older version of
a56dbb1c
PP
794perl).
795
796=head2 C<LaTeX> docs
797
798can be constructed using C<pod2latex>.
799
800=head1 BUILD
801
802Here we discuss how to build Perl under OS/2. There is an alternative
25417810 803(but maybe older) view on L<http://www.shadow.net/~troc/os2perl.html>.
a56dbb1c 804
3998488b
JH
805=head2 The short story
806
807Assume that you are a seasoned porter, so are sure that all the necessary
808tools are already present on your system, and you know how to get the Perl
809source distribution. Untar it, change to the extract directory, and
810
811 gnupatch -p0 < os2\diff.configure
812 sh Configure -des -D prefix=f:/perllib
813 make
814 make test
815 make install
816 make aout_test
817 make aout_install
818
819This puts the executables in f:/perllib/bin. Manually move them to the
25417810
IZ
820C<PATH>, manually move the built F<perl*.dll> to C<LIBPATH> (here for
821Perl DLL F<*> is a not-very-meaningful hex checksum), and run
3998488b
JH
822
823 make installcmd INSTALLCMDDIR=d:/ir/on/path
824
25417810
IZ
825Assuming that the C<man>-files were put on an appropriate location,
826this completes the installation of minimal Perl system. (The binary
827distribution contains also a lot of additional modules, and the
828documentation in INF format.)
829
3998488b
JH
830What follows is a detailed guide through these steps.
831
a56dbb1c
PP
832=head2 Prerequisites
833
aa689395
PP
834You need to have the latest EMX development environment, the full
835GNU tool suite (gawk renamed to awk, and GNU F<find.exe>
a56dbb1c
PP
836earlier on path than the OS/2 F<find.exe>, same with F<sort.exe>, to
837check use
838
839 find --version
840 sort --version
841
842). You need the latest version of F<pdksh> installed as F<sh.exe>.
843
2c2e0e8c
IZ
844Check that you have B<BSD> libraries and headers installed, and -
845optionally - Berkeley DB headers and libraries, and crypt.
846
25417810 847Possible locations to get the files:
a56dbb1c 848
d7678ab8 849 ftp://hobbes.nmsu.edu/os2/unix/
a56dbb1c
PP
850 ftp://ftp.cdrom.com/pub/os2/unix/
851 ftp://ftp.cdrom.com/pub/os2/dev32/
d7678ab8 852 ftp://ftp.cdrom.com/pub/os2/emx09c/
a56dbb1c 853
eb447b86 854It is reported that the following archives contain enough utils to
3998488b 855build perl: F<gnufutil.zip>, F<gnusutil.zip>, F<gnututil.zip>, F<gnused.zip>,
25417810 856F<gnupatch.zip>, F<gnuawk.zip>, F<gnumake.zip>, F<gnugrep.zip>, F<bsddev.zip> and
3998488b
JH
857F<ksh527rt.zip> (or a later version). Note that all these utilities are
858known to be available from LEO:
eb447b86
IZ
859
860 ftp://ftp.leo.org/pub/comp/os/os2/leo/gnu
a56dbb1c 861
25417810
IZ
862Note also that the F<db.lib> and F<db.a> from the EMX distribution
863are not suitable for multi-threaded compile (even single-threaded
864flavor of Perl uses multi-threaded C RTL, for
865compatibility with XFree86-OS/2). Get a corrected one from
866
867 http://www.ilyaz.org/software/os2/db_mt.zip
868
3998488b
JH
869If you have I<exactly the same version of Perl> installed already,
870make sure that no copies or perl are currently running. Later steps
871of the build may fail since an older version of F<perl.dll> loaded into
1933e12c
IZ
872memory may be found. Running C<make test> becomes meaningless, since
873the test are checking a previous build of perl (this situation is detected
874and reported by F<lib/os2_base.t> test). Do not forget to unset
875C<PERL_EMXLOAD_SEC> in environment.
a56dbb1c
PP
876
877Also make sure that you have F</tmp> directory on the current drive,
878and F<.> directory in your C<LIBPATH>. One may try to correct the
879latter condition by
880
25417810 881 set BEGINLIBPATH .\.
a56dbb1c 882
25417810
IZ
883if you use something like F<CMD.EXE> or latest versions of
884F<4os2.exe>. (Setting BEGINLIBPATH to just C<.> is ignored by the
885OS/2 kernel.)
a56dbb1c 886
aa689395 887Make sure your gcc is good for C<-Zomf> linking: run C<omflibs>
a56dbb1c
PP
888script in F</emx/lib> directory.
889
aa689395 890Check that you have link386 installed. It comes standard with OS/2,
a56dbb1c
PP
891but may be not installed due to customization. If typing
892
893 link386
894
895shows you do not have it, do I<Selective install>, and choose C<Link
72ea3524 896object modules> in I<Optional system utilities/More>. If you get into
3998488b 897link386 prompts, press C<Ctrl-C> to exit.
a56dbb1c
PP
898
899=head2 Getting perl source
900
72ea3524 901You need to fetch the latest perl source (including developers
a56dbb1c
PP
902releases). With some probability it is located in
903
e59066d8
LB
904 http://www.cpan.org/src/
905 http://www.cpan.org/src/unsupported
a56dbb1c
PP
906
907If not, you may need to dig in the indices to find it in the directory
908of the current maintainer.
909
72ea3524 910Quick cycle of developers release may break the OS/2 build time to
a56dbb1c
PP
911time, looking into
912
6c8d78fb 913 http://www.cpan.org/ports/os2/
a56dbb1c
PP
914
915may indicate the latest release which was publicly released by the
916maintainer. Note that the release may include some additional patches
917to apply to the current source of perl.
918
919Extract it like this
920
921 tar vzxf perl5.00409.tar.gz
922
923You may see a message about errors while extracting F<Configure>. This is
924because there is a conflict with a similarly-named file F<configure>.
925
a56dbb1c
PP
926Change to the directory of extraction.
927
928=head2 Application of the patches
929
10fb174d 930You need to apply the patches in F<./os2/diff.*> like this:
a56dbb1c 931
df3ef7a9 932 gnupatch -p0 < os2\diff.configure
a56dbb1c
PP
933
934You may also need to apply the patches supplied with the binary
25417810
IZ
935distribution of perl. It also makes sense to look on the
936perl5-porters mailing list for the latest OS/2-related patches (see
937L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/>). Such
938patches usually contain strings C</os2/> and C<patch>, so it makes
939sense looking for these strings.
a56dbb1c
PP
940
941=head2 Hand-editing
942
943You may look into the file F<./hints/os2.sh> and correct anything
944wrong you find there. I do not expect it is needed anywhere.
615d1a09 945
a56dbb1c 946=head2 Making
615d1a09 947
a56dbb1c 948 sh Configure -des -D prefix=f:/perllib
615d1a09 949
aa689395 950C<prefix> means: where to install the resulting perl library. Giving
a56dbb1c
PP
951correct prefix you may avoid the need to specify C<PERLLIB_PREFIX>,
952see L<"PERLLIB_PREFIX">.
5243f9ae 953
a56dbb1c 954I<Ignore the message about missing C<ln>, and about C<-c> option to
3998488b
JH
955tr>. The latter is most probably already fixed, if you see it and can trace
956where the latter spurious warning comes from, please inform me.
615d1a09 957
a56dbb1c 958Now
5243f9ae 959
a56dbb1c 960 make
5243f9ae 961
a56dbb1c 962At some moment the built may die, reporting a I<version mismatch> or
3998488b
JH
963I<unable to run F<perl>>. This means that you do not have F<.> in
964your LIBPATH, so F<perl.exe> cannot find the needed F<perl67B2.dll> (treat
965these hex digits as line noise). After this is fixed the build
966should finish without a lot of fuss.
615d1a09 967
a56dbb1c
PP
968=head2 Testing
969
970Now run
971
972 make test
973
25417810
IZ
974All tests should succeed (with some of them skipped). If you have the
975same version of Perl installed, it is crucial that you have C<.> early
976in your LIBPATH (or in BEGINLIBPATH), otherwise your tests will most
977probably test the wrong version of Perl.
a56dbb1c 978
ec40c0cd 979Some tests may generate extra messages similar to
a56dbb1c 980
ec40c0cd 981=over 4
a56dbb1c 982
ec40c0cd 983=item A lot of C<bad free>
a56dbb1c 984
3998488b
JH
985in database tests related to Berkeley DB. I<This should be fixed already.>
986If it persists, you may disable this warnings, see L<"PERL_BADFREE">.
72ea3524 987
ec40c0cd 988=item Process terminated by SIGTERM/SIGINT
72ea3524 989
ec40c0cd 990This is a standard message issued by OS/2 applications. *nix
3998488b 991applications die in silence. It is considered to be a feature. One can
ec40c0cd 992easily disable this by appropriate sighandlers.
a56dbb1c 993
ec40c0cd
IZ
994However the test engine bleeds these message to screen in unexpected
995moments. Two messages of this kind I<should> be present during
996testing.
a56dbb1c 997
ec40c0cd 998=back
a56dbb1c 999
ec40c0cd
IZ
1000To get finer test reports, call
1001
1002 perl t/harness
1003
1004The report with F<io/pipe.t> failing may look like this:
a56dbb1c 1005
ec40c0cd
IZ
1006 Failed Test Status Wstat Total Fail Failed List of failed
1007 ------------------------------------------------------------
1008 io/pipe.t 12 1 8.33% 9
1009 7 tests skipped, plus 56 subtests skipped.
1010 Failed 1/195 test scripts, 99.49% okay. 1/6542 subtests failed, 99.98% okay.
1011
1012The reasons for most important skipped tests are:
1013
1014=over 8
a56dbb1c 1015
ec40c0cd 1016=item F<op/fs.t>
a56dbb1c 1017
a7665c5e
GS
1018=over 4
1019
a56dbb1c
PP
1020=item 18
1021
ec40c0cd
IZ
1022Checks C<atime> and C<mtime> of C<stat()> - unfortunately, HPFS
1023provides only 2sec time granularity (for compatibility with FAT?).
a56dbb1c
PP
1024
1025=item 25
1026
1027Checks C<truncate()> on a filehandle just opened for write - I do not
1028know why this should or should not work.
1029
1030=back
1031
a56dbb1c
PP
1032=item F<op/stat.t>
1033
1034Checks C<stat()>. Tests:
1035
1036=over 4
1037
a56dbb1c
PP
1038=item 4
1039
ec40c0cd
IZ
1040Checks C<atime> and C<mtime> of C<stat()> - unfortunately, HPFS
1041provides only 2sec time granularity (for compatibility with FAT?).
a56dbb1c
PP
1042
1043=back
1044
a56dbb1c 1045=back
615d1a09 1046
a56dbb1c 1047=head2 Installing the built perl
615d1a09 1048
25417810 1049If you haven't yet moved C<perl*.dll> onto LIBPATH, do it now.
491527d0 1050
a56dbb1c 1051Run
615d1a09 1052
a56dbb1c 1053 make install
615d1a09 1054
a56dbb1c
PP
1055It would put the generated files into needed locations. Manually put
1056F<perl.exe>, F<perl__.exe> and F<perl___.exe> to a location on your
aa689395 1057PATH, F<perl.dll> to a location on your LIBPATH.
615d1a09 1058
a56dbb1c 1059Run
615d1a09 1060
3998488b 1061 make installcmd INSTALLCMDDIR=d:/ir/on/path
615d1a09 1062
a56dbb1c 1063to convert perl utilities to F<.cmd> files and put them on
aa689395 1064PATH. You need to put F<.EXE>-utilities on path manually. They are
a56dbb1c
PP
1065installed in C<$prefix/bin>, here C<$prefix> is what you gave to
1066F<Configure>, see L<Making>.
1067
25417810
IZ
1068If you use C<man>, either move the installed F<*/man/> directories to
1069your C<MANPATH>, or modify C<MANPATH> to match the location. (One
1070could have avoided this by providing a correct C<manpath> option to
1071F<./Configure>, or editing F<./config.sh> between configuring and
1072making steps.)
1073
a56dbb1c
PP
1074=head2 C<a.out>-style build
1075
1076Proceed as above, but make F<perl_.exe> (see L<"perl_.exe">) by
1077
1078 make perl_
1079
1080test and install by
1081
1082 make aout_test
1083 make aout_install
1084
aa689395 1085Manually put F<perl_.exe> to a location on your PATH.
a56dbb1c 1086
a56dbb1c
PP
1087B<Note.> The build process for C<perl_> I<does not know> about all the
1088dependencies, so you should make sure that anything is up-to-date,
1089say, by doing
1090
3998488b 1091 make perl_dll
a56dbb1c
PP
1092
1093first.
1094
1933e12c
IZ
1095=head1 Building a binary distribution
1096
1097[This section provides a short overview only...]
1098
1099Building should proceed differently depending on whether the version of perl
1100you install is already present and used on your system, or is a new version
1101not yet used. The description below assumes that the version is new, so
1102installing its DLLs and F<.pm> files will not disrupt the operation of your
1103system even if some intermediate steps are not yet fully working.
1104
1105The other cases require a little bit more convoluted procedures. Below I
1106suppose that the current version of Perl is C<5.8.2>, so the executables are
1107named accordingly.
1108
1109=over
1110
1111=item 1.
1112
1113Fully build and test the Perl distribution. Make sure that no tests are
1114failing with C<test> and C<aout_test> targets; fix the bugs in Perl and
1115the Perl test suite detected by these tests. Make sure that C<all_test>
1116make target runs as clean as possible. Check that C<os2/perlrexx.cmd>
1117runs fine.
1118
1119=item 2.
1120
1121Fully install Perl, including C<installcmd> target. Copy the generated DLLs
1122to C<LIBPATH>; copy the numbered Perl executables (as in F<perl5.8.2.exe>)
1123to C<PATH>; copy C<perl_.exe> to C<PATH> as C<perl_5.8.2.exe>. Think whether
1124you need backward-compatibility DLLs. In most cases you do not need to install
1125them yet; but sometime this may simplify the following steps.
1126
1127=item 3.
1128
1129Make sure that C<CPAN.pm> can download files from CPAN. If not, you may need
1130to manually install C<Net::FTP>.
1131
1132=item 4.
1133
1134Install the bundle C<Bundle::OS2_default>
1135
1136 perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_1
1137
1138This may take a couple of hours on 1GHz processor (when run the first time).
1139And this should not be necessarily a smooth procedure. Some modules may not
1140specify required dependencies, so one may need to repeat this procedure several
1141times until the results stabilize.
1142
1143 perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_2
1144 perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_3
1145
1146Even after they stabilize, some tests may fail.
1147
1148Fix as many discovered bugs as possible. Document all the bugs which are not
1149fixed, and all the failures with unknown reasons. Inspect the produced logs
1150F<00cpan_i_1> to find suspiciously skipped tests, and other fishy events.
1151
1152Keep in mind that I<installation> of some modules may fail too: for example,
1153the DLLs to update may be already loaded by F<CPAN.pm>. Inspect the C<install>
1154logs (in the example above F<00cpan_i_1> etc) for errors, and install things
1155manually, as in
1156
1157 cd $CPANHOME/.cpan/build/Digest-MD5-2.31
1158 make install
1159
1160Some distributions may fail some tests, but you may want to install them
1161anyway (as above, or via C<force install> command of C<CPAN.pm> shell-mode).
1162
1163Since this procedure may take quite a long time to complete, it makes sense
1164to "freeze" your CPAN configuration by disabling periodic updates of the
1165local copy of CPAN index: set C<index_expire> to some big value (I use 365),
1166then save the settings
1167
1168 CPAN> o conf index_expire 365
1169 CPAN> o conf commit
1170
1171Reset back to the default value C<1> when you are finished.
1172
1173=item 5.
1174
1175When satisfied with the results, rerun the C<installcmd> target. Now you
1176can copy C<perl5.8.2.exe> to C<perl.exe>, and install the other OMF-build
1177executables: C<perl__.exe> etc. They are ready to be used.
1178
1179=item 6.
1180
1181Change to the C<./pod> directory of the build tree, download the Perl logo
1182F<CamelGrayBig.BMP>, and run
1183
1184 ( perl2ipf > perl.ipf ) |& tee 00ipf
1185 ipfc /INF perl.ipf |& tee 00inf
1186
1187This produces the Perl docs online book C<perl.INF>. Install in on
1188C<BOOKSHELF> path.
1189
1190=item 7.
1191
1192Now is the time to build statically linked executable F<perl_.exe> which
1193includes newly-installed via C<Bundle::OS2_default> modules. Doing testing
1194via C<CPAN.pm> is going to be painfully slow, since it statically links
1195a new executable per XS extension.
1196
1197Here is a possible workaround: create a toplevel F<Makefile.PL> in
1198F<$CPANHOME/.cpan/build/> with contents being (compare with L<Making
1199executables with a custom collection of statically loaded extensions>)
1200
1201 use ExtUtils::MakeMaker;
1202 WriteMakefile NAME => 'dummy';
1203
1204execute this as
1205
1206 perl_5.8.2.exe Makefile.PL <nul |& tee 00aout_c1
1207 make -k all test <nul |& 00aout_t1
1208
1209Again, this procedure should not be absolutely smooth. Some C<Makefile.PL>'s
1210in subdirectories may be buggy, and would not run as "child" scripts. The
1211interdependency of modules can strike you; however, since non-XS modules
1212are already installed, the prerequisites of most modules have a very good
1213chance to be present.
1214
1215If you discover some glitches, move directories of problematic modules to a
1216different location; if these modules are non-XS modules, you may just ignore
1217them - they are already installed; the remaining, XS, modules you need to
1218install manually one by one.
1219
1220After each such removal you need to rerun the C<Makefile.PL>/C<make> process;
1221usually this procedure converges soon. (But be sure to convert all the
1222necessary external C libraries from F<.lib> format to F<.a> format: run one of
1223
1224 emxaout foo.lib
1225 emximp -o foo.a foo.lib
1226
1227whichever is appropriate.) Also, make sure that the DLLs for external
1228libraries are usable with with executables compiled without C<-Zmtd> options.
1229
1230When you are sure that only a few subdirectories
1231lead to failures, you may want to add C<-j4> option to C<make> to speed up
1232skipping subdirectories with already finished build.
1233
1234When you are satisfied with the results of tests, install the build C libraries
1235for extensions:
1236
1237 make install |& tee 00aout_i
1238
1239Now you can rename the file F<./perl.exe> generated during the last phase
1240to F<perl_5.8.2.exe>; place it on C<PATH>; if there is an inter-dependency
1241between some XS modules, you may need to repeat the C<test>/C<install> loop
1242with this new executable and some excluded modules - until the procedure
1243converges.
1244
1245Now you have all the necessary F<.a> libraries for these Perl modules in the
1246places where Perl builder can find it. Use the perl builder: change to an
1247empty directory, create a "dummy" F<Makefile.PL> again, and run
1248
1249 perl_5.8.2.exe Makefile.PL |& tee 00c
1250 make perl |& tee 00p
1251
1252This should create an executable F<./perl.exe> with all the statically loaded
1253extensions built in. Compare the generated F<perlmain.c> files to make sure
1254that during the iterations the number of loaded extensions only increases.
1255Rename F<./perl.exe> to F<perl_5.8.2.exe> on C<PATH>.
1256
1257When it converges, you got a functional variant of F<perl_5.8.2.exe>; copy it
1258to C<perl_.exe>. You are done with generation of the local Perl installation.
1259
1260=item 8.
1261
1262Make sure that the installed modules are actually installed in the location
1263of the new Perl, and are not inherited from entries of @INC given for
1264inheritance from the older versions of Perl: set C<PERLLIB_582_PREFIX> to
1265redirect the new version of Perl to a new location, and copy the installed
1266files to this new location. Redo the tests to make sure that the versions of
1267modules inherited from older versions of Perl are not needed.
1268
1269Actually, the log output of L<pod2ipf> during the step 6 gives a very detailed
1270info about which modules are loaded from which place; so you may use it as
1271an additional verification tool.
1272
1273Check that some temporary files did not make into the perl install tree.
1274Run something like this
1275
1276 pfind . -f "!(/\.(pm|pl|ix|al|h|a|lib|txt|pod|imp|bs|dll|ld|bs|inc|xbm|yml|cgi|uu|e2x|skip|packlist|eg|cfg|html|pub|enc|all|ini|po|pot)$/i or /^\w+$/") | less
1277
1278in the install tree (both top one and F<sitelib> one).
1279
1280Compress all the DLLs with F<lxlite>. The tiny F<.exe> can be compressed with
1281C</c:max> (the bug only appears when there is a fixup in the last 6 bytes of a
1282page (?); since the tiny executables are much smaller than a page, the bug
1283will not hit). Do not compress C<perl_.exe> - it would not work under DOS.
1284
1285=item 9.
1286
1287Now you can generate the binary distribution. This is done by running the
1288test of the CPAN distribution C<OS2::SoftInstaller>. Tune up the file
1289F<test.pl> to suit the layout of current version of Perl first. Do not
1290forget to pack the necessary external DLLs accordingly. Include the
1291description of the bugs and test suite failures you could not fix. Include
1292the small-stack versions of Perl executables from Perl build directory.
1293
1294Include F<perl5.def> so that people can relink the perl DLL preserving
1295the binary compatibility, or can create compatibility DLLs. Include the diff
1296files (C<diff -pu old new>) of fixes you did so that people can rebuild your
1297version. Include F<perl5.map> so that one can use remote debugging.
1298
1299=item 10.
1300
1301Share what you did with the other people. Relax. Enjoy fruits of your work.
1302
1303=item 11.
1304
1305Brace yourself for thanks, bug reports, hate mail and spam coming as result
1306of the previous step. No good deed should remain unpunished!
1307
1308=back
1309
1310=head1 Building custom F<.EXE> files
1311
1312The Perl executables can be easily rebuilt at any moment. Moreover, one can
1313use the I<embedding> interface (see L<perlembed>) to make very customized
1314executables.
1315
1316=head2 Making executables with a custom collection of statically loaded extensions
1317
1318It is a little bit easier to do so while I<decreasing> the list of statically
1319loaded extensions. We discuss this case only here.
1320
1321=over
1322
1323=item 1.
1324
1325Change to an empty directory, and create a placeholder <Makefile.PL>:
1326
1327 use ExtUtils::MakeMaker;
1328 WriteMakefile NAME => 'dummy';
1329
1330=item 2.
1331
1332Run it with the flavor of Perl (F<perl.exe> or F<perl_.exe>) you want to
1333rebuild.
1334
1335 perl_ Makefile.PL
1336
1337=item 3.
1338
1339Ask it to create new Perl executable:
1340
1341 make perl
1342
1343(you may need to manually add C<PERLTYPE=-DPERL_CORE> to this commandline on
1344some versions of Perl; the symptom is that the command-line globbing does not
1345work from OS/2 shells with the newly-compiled executable; check with
1346
1347 .\perl.exe -wle "print for @ARGV" *
1348
1349).
1350
1351=item 4.
1352
1353The previous step created F<perlmain.c> which contains a list of newXS() calls
1354near the end. Removing unnecessary calls, and rerunning
1355
1356 make perl
1357
1358will produce a customized executable.
1359
1360=back
1361
1362=head2 Making executables with a custom search-paths
1363
1364The default perl executable is flexible enough to support most usages.
1365However, one may want something yet more flexible; for example, one may want
1366to find Perl DLL relatively to the location of the EXE file; or one may want
1367to ignore the environment when setting the Perl-library search patch, etc.
1368
1369If you fill comfortable with I<embedding> interface (see L<perlembed>), such
1370things are easy to do repeating the steps outlined in L<Making
1371executables with a custom collection of statically loaded extensions>, and
1372doing more comprehensive edits to main() of F<perlmain.c>. The people with
1373little desire to understand Perl can just rename main(), and do necessary
1374modification in a custom main() which calls the renamed function in appropriate
1375time.
1376
1377However, there is a third way: perl DLL exports the main() function and several
1378callbacks to customize the search path. Below is a complete example of a
1379"Perl loader" which
1380
1381=over
1382
1383=item 1.
1384
1385Looks for Perl DLL in the directory C<$exedir/../dll>;
1386
1387=item 2.
1388
1389Prepends the above directory to C<BEGINLIBPATH>;
1390
1391=item 3.
1392
1393Fails if the Perl DLL found via C<BEGINLIBPATH> is different from what was
1394loaded on step 1; e.g., another process could have loaded it from C<LIBPATH>
1395or from a different value of C<BEGINLIBPATH>. In these cases one needs to
1396modify the setting of the system so that this other process either does not
1397run, or loads the DLL from C<BEGINLIBPATH> with C<LIBPATHSTRICT=T> (available
1398with kernels after September 2000).
1399
1400=item 4.
1401
1402Loads Perl library from C<$exedir/../dll/lib/>.
1403
1404=item 5.
1405
1406Uses Bourne shell from C<$exedir/../dll/sh/ksh.exe>.
1407
1408=back
1409
1410For best results compile the C file below with the same options as the Perl
1411DLL. However, a lot of functionality will work even if the executable is not
1412an EMX applications, e.g., if compiled with
1413
1414 gcc -Wall -DDOSISH -DOS2=1 -O2 -s -Zomf -Zsys perl-starter.c -DPERL_DLL_BASENAME=\"perl312F\" -Zstack 8192 -Zlinker /PM:VIO
1415
1416Here is the sample C file:
1417
1418 #define INCL_DOS
1419 #define INCL_NOPM
1420 /* These are needed for compile if os2.h includes os2tk.h, not os2emx.h */
1421 #define INCL_DOSPROCESS
1422 #include <os2.h>
1423
1424 #include "EXTERN.h"
1425 #define PERL_IN_MINIPERLMAIN_C
1426 #include "perl.h"
1427
1428 static char *me;
1429 HMODULE handle;
1430
1431 static void
1432 die_with(char *msg1, char *msg2, char *msg3, char *msg4)
1433 {
1434 ULONG c;
1435 char *s = " error: ";
1436
1437 DosWrite(2, me, strlen(me), &c);
1438 DosWrite(2, s, strlen(s), &c);
1439 DosWrite(2, msg1, strlen(msg1), &c);
1440 DosWrite(2, msg2, strlen(msg2), &c);
1441 DosWrite(2, msg3, strlen(msg3), &c);
1442 DosWrite(2, msg4, strlen(msg4), &c);
1443 DosWrite(2, "\r\n", 2, &c);
1444 exit(255);
1445 }
1446
1447 typedef ULONG (*fill_extLibpath_t)(int type, char *pre, char *post, int replace, char *msg);
1448 typedef int (*main_t)(int type, char *argv[], char *env[]);
1449 typedef int (*handler_t)(void* data, int which);
1450
1451 #ifndef PERL_DLL_BASENAME
1452 # define PERL_DLL_BASENAME "perl"
1453 #endif
1454
1455 static HMODULE
1456 load_perl_dll(char *basename)
1457 {
1458 char buf[300], fail[260];
1459 STRLEN l, dirl;
1460 fill_extLibpath_t f;
1461 ULONG rc_fullname;
1462 HMODULE handle, handle1;
1463
1464 if (_execname(buf, sizeof(buf) - 13) != 0)
1465 die_with("Can't find full path: ", strerror(errno), "", "");
1466 /* XXXX Fill `me' with new value */
1467 l = strlen(buf);
1468 while (l && buf[l-1] != '/' && buf[l-1] != '\\')
1469 l--;
1470 dirl = l - 1;
1471 strcpy(buf + l, basename);
1472 l += strlen(basename);
1473 strcpy(buf + l, ".dll");
1474 if ( (rc_fullname = DosLoadModule(fail, sizeof fail, buf, &handle)) != 0
1475 && DosLoadModule(fail, sizeof fail, basename, &handle) != 0 )
1476 die_with("Can't load DLL ", buf, "", "");
1477 if (rc_fullname)
1478 return handle; /* was loaded with short name; all is fine */
1479 if (DosQueryProcAddr(handle, 0, "fill_extLibpath", (PFN*)&f))
1480 die_with(buf, ": DLL exports no symbol ", "fill_extLibpath", "");
1481 buf[dirl] = 0;
1482 if (f(0 /*BEGINLIBPATH*/, buf /* prepend */, NULL /* append */,
1483 0 /* keep old value */, me))
1484 die_with(me, ": prepending BEGINLIBPATH", "", "");
1485 if (DosLoadModule(fail, sizeof fail, basename, &handle1) != 0)
1486 die_with(me, ": finding perl DLL again via BEGINLIBPATH", "", "");
1487 buf[dirl] = '\\';
1488 if (handle1 != handle) {
1489 if (DosQueryModuleName(handle1, sizeof(fail), fail))
1490 strcpy(fail, "???");
1491 die_with(buf, ":\n\tperl DLL via BEGINLIBPATH is different: \n\t",
1492 fail,
1493 "\n\tYou may need to manipulate global BEGINLIBPATH and LIBPATHSTRICT"
1494 "\n\tso that the other copy is loaded via BEGINLIBPATH.");
1495 }
1496 return handle;
1497 }
1498
1499 int
1500 main(int argc, char **argv, char **env)
1501 {
1502 main_t f;
1503 handler_t h;
1504
1505 me = argv[0];
1506 /**/
1507 handle = load_perl_dll(PERL_DLL_BASENAME);
1508
1509 if (DosQueryProcAddr(handle, 0, "Perl_OS2_handler_install", (PFN*)&h))
1510 die_with(PERL_DLL_BASENAME, ": DLL exports no symbol ", "Perl_OS2_handler_install", "");
1511 if ( !h((void *)"~installprefix", Perlos2_handler_perllib_from)
1512 || !h((void *)"~dll", Perlos2_handler_perllib_to)
1513 || !h((void *)"~dll/sh/ksh.exe", Perlos2_handler_perl_sh) )
1514 die_with(PERL_DLL_BASENAME, ": Can't install @INC manglers", "", "");
1515
1516 if (DosQueryProcAddr(handle, 0, "dll_perlmain", (PFN*)&f))
1517 die_with(PERL_DLL_BASENAME, ": DLL exports no symbol ", "dll_perlmain", "");
1518 return f(argc, argv, env);
1519 }
1520
1521
a56dbb1c
PP
1522=head1 Build FAQ
1523
1524=head2 Some C</> became C<\> in pdksh.
1525
1526You have a very old pdksh. See L<Prerequisites>.
1527
1528=head2 C<'errno'> - unresolved external
1529
1530You do not have MT-safe F<db.lib>. See L<Prerequisites>.
1531
2c2e0e8c 1532=head2 Problems with tr or sed
a56dbb1c 1533
2c2e0e8c 1534reported with very old version of tr and sed.
a56dbb1c
PP
1535
1536=head2 Some problem (forget which ;-)
1537
aa689395 1538You have an older version of F<perl.dll> on your LIBPATH, which
a56dbb1c
PP
1539broke the build of extensions.
1540
1541=head2 Library ... not found
1542
1543You did not run C<omflibs>. See L<Prerequisites>.
1544
1545=head2 Segfault in make
1546
aa689395 1547You use an old version of GNU make. See L<Prerequisites>.
a56dbb1c 1548
884335e8
YST
1549=head2 op/sprintf test failure
1550
1551This can result from a bug in emx sprintf which was fixed in 0.9d fix 03.
1552
a56dbb1c
PP
1553=head1 Specific (mis)features of OS/2 port
1554
1555=head2 C<setpriority>, C<getpriority>
1556
1557Note that these functions are compatible with *nix, not with the older
1558ports of '94 - 95. The priorities are absolute, go from 32 to -95,
72ea3524 1559lower is quicker. 0 is the default priority.
a56dbb1c 1560
d88df687
IZ
1561B<WARNING>. Calling C<getpriority> on a non-existing process could lock
1562the system before Warp3 fixpak22. Starting with Warp3, Perl will use
1563a workaround: it aborts getpriority() if the process is not present.
1564This is not possible on older versions C<2.*>, and has a race
1565condition anyway.
3998488b 1566
a56dbb1c
PP
1567=head2 C<system()>
1568
1569Multi-argument form of C<system()> allows an additional numeric
1570argument. The meaning of this argument is described in
1571L<OS2::Process>.
1572
3998488b 1573When finding a program to run, Perl first asks the OS to look for executables
d88df687
IZ
1574on C<PATH> (OS/2 adds extension F<.exe> if no extension is present).
1575If not found, it looks for a script with possible extensions
3998488b
JH
1576added in this order: no extension, F<.cmd>, F<.btm>,
1577F<.bat>, F<.pl>. If found, Perl checks the start of the file for magic
1578strings C<"#!"> and C<"extproc ">. If found, Perl uses the rest of the
1579first line as the beginning of the command line to run this script. The
1580only mangling done to the first line is extraction of arguments (currently
1581up to 3), and ignoring of the path-part of the "interpreter" name if it can't
1582be found using the full path.
1583
1584E.g., C<system 'foo', 'bar', 'baz'> may lead Perl to finding
1585F<C:/emx/bin/foo.cmd> with the first line being
1586
1587 extproc /bin/bash -x -c
1588
d88df687 1589If F</bin/bash.exe> is not found, then Perl looks for an executable F<bash.exe> on
3998488b
JH
1590C<PATH>. If found in F<C:/emx.add/bin/bash.exe>, then the above system() is
1591translated to
1592
1593 system qw(C:/emx.add/bin/bash.exe -x -c C:/emx/bin/foo.cmd bar baz)
1594
1595One additional translation is performed: instead of F</bin/sh> Perl uses
1596the hardwired-or-customized shell (see C<L<"PERL_SH_DIR">>).
1597
1598The above search for "interpreter" is recursive: if F<bash> executable is not
1599found, but F<bash.btm> is found, Perl will investigate its first line etc.
1600The only hardwired limit on the recursion depth is implicit: there is a limit
16014 on the number of additional arguments inserted before the actual arguments
1602given to system(). In particular, if no additional arguments are specified
1603on the "magic" first lines, then the limit on the depth is 4.
1604
25417810
IZ
1605If Perl finds that the found executable is of PM type when the
1606current session is not, it will start the new process in a separate session of
3998488b
JH
1607necessary type. Call via C<OS2::Process> to disable this magic.
1608
d88df687
IZ
1609B<WARNING>. Due to the described logic, you need to explicitly
1610specify F<.com> extension if needed. Moreover, if the executable
1611F<perl5.6.1> is requested, Perl will not look for F<perl5.6.1.exe>.
1612[This may change in the future.]
1613
aa689395
PP
1614=head2 C<extproc> on the first line
1615
3998488b 1616If the first chars of a Perl script are C<"extproc ">, this line is treated
aa689395 1617as C<#!>-line, thus all the switches on this line are processed (twice
3998488b 1618if script was started via cmd.exe). See L<perlrun/DESCRIPTION>.
aa689395 1619
a56dbb1c 1620=head2 Additional modules:
615d1a09 1621
3998488b 1622L<OS2::Process>, L<OS2::DLL>, L<OS2::REXX>, L<OS2::PrfDB>, L<OS2::ExtAttr>. These
2c2e0e8c 1623modules provide access to additional numeric argument for C<system>
3998488b
JH
1624and to the information about the running process,
1625to DLLs having functions with REXX signature and to the REXX runtime, to
a56dbb1c 1626OS/2 databases in the F<.INI> format, and to Extended Attributes.
615d1a09 1627
72ea3524 1628Two additional extensions by Andreas Kaiser, C<OS2::UPM>, and
3998488b 1629C<OS2::FTP>, are included into C<ILYAZ> directory, mirrored on CPAN.
25417810 1630Other OS/2-related extensions are available too.
615d1a09 1631
a56dbb1c 1632=head2 Prebuilt methods:
615d1a09 1633
a56dbb1c 1634=over 4
615d1a09 1635
a56dbb1c 1636=item C<File::Copy::syscopy>
615d1a09 1637
d7678ab8 1638used by C<File::Copy::copy>, see L<File::Copy>.
615d1a09 1639
a56dbb1c 1640=item C<DynaLoader::mod2fname>
615d1a09 1641
72ea3524 1642used by C<DynaLoader> for DLL name mangling.
615d1a09 1643
a56dbb1c 1644=item C<Cwd::current_drive()>
615d1a09 1645
a56dbb1c 1646Self explanatory.
615d1a09 1647
a56dbb1c 1648=item C<Cwd::sys_chdir(name)>
615d1a09 1649
a56dbb1c 1650leaves drive as it is.
615d1a09 1651
a56dbb1c 1652=item C<Cwd::change_drive(name)>
615d1a09 1653
3998488b 1654chanes the "current" drive.
615d1a09 1655
a56dbb1c 1656=item C<Cwd::sys_is_absolute(name)>
615d1a09 1657
a56dbb1c 1658means has drive letter and is_rooted.
615d1a09 1659
a56dbb1c 1660=item C<Cwd::sys_is_rooted(name)>
615d1a09 1661
a56dbb1c 1662means has leading C<[/\\]> (maybe after a drive-letter:).
615d1a09 1663
a56dbb1c 1664=item C<Cwd::sys_is_relative(name)>
615d1a09 1665
a56dbb1c 1666means changes with current dir.
615d1a09 1667
a56dbb1c 1668=item C<Cwd::sys_cwd(name)>
615d1a09 1669
aa689395 1670Interface to cwd from EMX. Used by C<Cwd::cwd>.
615d1a09 1671
a56dbb1c 1672=item C<Cwd::sys_abspath(name, dir)>
615d1a09 1673
a56dbb1c
PP
1674Really really odious function to implement. Returns absolute name of
1675file which would have C<name> if CWD were C<dir>. C<Dir> defaults to the
1676current dir.
615d1a09 1677
6d0f518e 1678=item C<Cwd::extLibpath([type])>
615d1a09 1679
a56dbb1c 1680Get current value of extended library search path. If C<type> is
25417810
IZ
1681present and positive, works with C<END_LIBPATH>, if negative, works
1682with C<LIBPATHSTRICT>, otherwise with C<BEGIN_LIBPATH>.
615d1a09 1683
a56dbb1c 1684=item C<Cwd::extLibpath_set( path [, type ] )>
615d1a09 1685
a56dbb1c 1686Set current value of extended library search path. If C<type> is
25417810
IZ
1687present and positive, works with <END_LIBPATH>, if negative, works
1688with C<LIBPATHSTRICT>, otherwise with C<BEGIN_LIBPATH>.
615d1a09 1689
3998488b
JH
1690=item C<OS2::Error(do_harderror,do_exception)>
1691
1692Returns C<undef> if it was not called yet, otherwise bit 1 is
1693set if on the previous call do_harderror was enabled, bit
d1be9408 16942 is set if on previous call do_exception was enabled.
3998488b
JH
1695
1696This function enables/disables error popups associated with
1697hardware errors (Disk not ready etc.) and software exceptions.
1698
1699I know of no way to find out the state of popups I<before> the first call
1700to this function.
1701
1702=item C<OS2::Errors2Drive(drive)>
1703
1704Returns C<undef> if it was not called yet, otherwise return false if errors
1705were not requested to be written to a hard drive, or the drive letter if
1706this was requested.
1707
1708This function may redirect error popups associated with hardware errors
1709(Disk not ready etc.) and software exceptions to the file POPUPLOG.OS2 at
1710the root directory of the specified drive. Overrides OS2::Error() specified
1711by individual programs. Given argument undef will disable redirection.
1712
1713Has global effect, persists after the application exits.
1714
1715I know of no way to find out the state of redirection of popups to the disk
1716I<before> the first call to this function.
1717
1718=item OS2::SysInfo()
1719
1720Returns a hash with system information. The keys of the hash are
1721
1722 MAX_PATH_LENGTH, MAX_TEXT_SESSIONS, MAX_PM_SESSIONS,
1723 MAX_VDM_SESSIONS, BOOT_DRIVE, DYN_PRI_VARIATION,
1724 MAX_WAIT, MIN_SLICE, MAX_SLICE, PAGE_SIZE,
1725 VERSION_MAJOR, VERSION_MINOR, VERSION_REVISION,
1726 MS_COUNT, TIME_LOW, TIME_HIGH, TOTPHYSMEM, TOTRESMEM,
1727 TOTAVAILMEM, MAXPRMEM, MAXSHMEM, TIMER_INTERVAL,
1728 MAX_COMP_LENGTH, FOREGROUND_FS_SESSION,
1729 FOREGROUND_PROCESS
1730
1731=item OS2::BootDrive()
1732
1733Returns a letter without colon.
1734
1735=item C<OS2::MorphPM(serve)>, C<OS2::UnMorphPM(serve)>
1736
1737Transforms the current application into a PM application and back.
1738The argument true means that a real message loop is going to be served.
1739OS2::MorphPM() returns the PM message queue handle as an integer.
1740
1741See L<"Centralized management of resources"> for additional details.
1742
1743=item C<OS2::Serve_Messages(force)>
1744
1745Fake on-demand retrieval of outstanding PM messages. If C<force> is false,
1746will not dispatch messages if a real message loop is known to
1747be present. Returns number of messages retrieved.
1748
1749Dies with "QUITing..." if WM_QUIT message is obtained.
1750
1751=item C<OS2::Process_Messages(force [, cnt])>
1752
1753Retrieval of PM messages until window creation/destruction.
1754If C<force> is false, will not dispatch messages if a real message loop
1755is known to be present.
1756
1757Returns change in number of windows. If C<cnt> is given,
1758it is incremented by the number of messages retrieved.
1759
1760Dies with "QUITing..." if WM_QUIT message is obtained.
1761
1762=item C<OS2::_control87(new,mask)>
1763
1764the same as L<_control87(3)> of EMX. Takes integers as arguments, returns
1765the previous coprocessor control word as an integer. Only bits in C<new> which
1766are present in C<mask> are changed in the control word.
1767
1768=item OS2::get_control87()
1769
1770gets the coprocessor control word as an integer.
1771
1772=item C<OS2::set_control87_em(new=MCW_EM,mask=MCW_EM)>
1773
1774The variant of OS2::_control87() with default values good for
1775handling exception mask: if no C<mask>, uses exception mask part of C<new>
1776only. If no C<new>, disables all the floating point exceptions.
1777
1778See L<"Misfeatures"> for details.
1779
25417810
IZ
1780=item C<OS2::DLLname([how [, \&xsub]])>
1781
1782Gives the information about the Perl DLL or the DLL containing the C
1783function bound to by C<&xsub>. The meaning of C<how> is: default (2):
1784full name; 0: handle; 1: module name.
1785
a56dbb1c 1786=back
615d1a09 1787
a56dbb1c
PP
1788(Note that some of these may be moved to different libraries -
1789eventually).
615d1a09 1790
615d1a09 1791
3998488b
JH
1792=head2 Prebuilt variables:
1793
1794=over 4
1795
1796=item $OS2::emx_rev
1797
25417810
IZ
1798numeric value is the same as _emx_rev of EMX, a string value the same
1799as _emx_vprt (similar to C<0.9c>).
3998488b
JH
1800
1801=item $OS2::emx_env
1802
1803same as _emx_env of EMX, a number similar to 0x8001.
1804
1805=item $OS2::os_ver
1806
1807a number C<OS_MAJOR + 0.001 * OS_MINOR>.
1808
25417810
IZ
1809=item $OS2::is_aout
1810
1811true if the Perl library was compiled in AOUT format.
1812
1813=item $OS2::can_fork
1814
1815true if the current executable is an AOUT EMX executable, so Perl can
1816fork. Do not use this, use the portable check for
1817$Config::Config{dfork}.
1818
1819=item $OS2::nsyserror
1820
1821This variable (default is 1) controls whether to enforce the contents
1822of $^E to start with C<SYS0003>-like id. If set to 0, then the string
1823value of $^E is what is available from the OS/2 message file. (Some
1824messages in this file have an C<SYS0003>-like id prepended, some not.)
1825
3998488b
JH
1826=back
1827
a56dbb1c 1828=head2 Misfeatures
615d1a09 1829
a56dbb1c 1830=over 4
615d1a09 1831
13a2d996 1832=item *
615d1a09 1833
367f3c24
IZ
1834Since L<flock(3)> is present in EMX, but is not functional, it is
1835emulated by perl. To disable the emulations, set environment variable
1836C<USE_PERL_FLOCK=0>.
1837
13a2d996 1838=item *
367f3c24
IZ
1839
1840Here is the list of things which may be "broken" on
55497cff
PP
1841EMX (from EMX docs):
1842
13a2d996 1843=over 4
d7678ab8
CS
1844
1845=item *
1846
1847The functions L<recvmsg(3)>, L<sendmsg(3)>, and L<socketpair(3)> are not
1848implemented.
1849
1850=item *
1851
1852L<sock_init(3)> is not required and not implemented.
1853
1854=item *
1855
367f3c24 1856L<flock(3)> is not yet implemented (dummy function). (Perl has a workaround.)
d7678ab8
CS
1857
1858=item *
1859
1860L<kill(3)>: Special treatment of PID=0, PID=1 and PID=-1 is not implemented.
1861
1862=item *
1863
1864L<waitpid(3)>:
1865
55497cff
PP
1866 WUNTRACED
1867 Not implemented.
1868 waitpid() is not implemented for negative values of PID.
1869
d7678ab8
CS
1870=back
1871
55497cff 1872Note that C<kill -9> does not work with the current version of EMX.
615d1a09 1873
13a2d996 1874=item *
615d1a09 1875
25417810 1876See L<"Text-mode filehandles">.
615d1a09 1877
3998488b
JH
1878=item *
1879
1880Unix-domain sockets on OS/2 live in a pseudo-file-system C</sockets/...>.
1881To avoid a failure to create a socket with a name of a different form,
1882C<"/socket/"> is prepended to the socket name (unless it starts with this
1883already).
1884
1885This may lead to problems later in case the socket is accessed via the
1886"usual" file-system calls using the "initial" name.
1887
1888=item *
1889
1890Apparently, IBM used a compiler (for some period of time around '95?) which
1891changes FP mask right and left. This is not I<that> bad for IBM's
1892programs, but the same compiler was used for DLLs which are used with
1893general-purpose applications. When these DLLs are used, the state of
1894floating-point flags in the application is not predictable.
1895
1896What is much worse, some DLLs change the floating point flags when in
1897_DLLInitTerm() (e.g., F<TCP32IP>). This means that even if you do not I<call>
1898any function in the DLL, just the act of loading this DLL will reset your
1899flags. What is worse, the same compiler was used to compile some HOOK DLLs.
1900Given that HOOK dlls are executed in the context of I<all> the applications
1901in the system, this means a complete unpredictablity of floating point
1902flags on systems using such HOOK DLLs. E.g., F<GAMESRVR.DLL> of B<DIVE>
1903origin changes the floating point flags on each write to the TTY of a VIO
1904(windowed text-mode) applications.
1905
1906Some other (not completely debugged) situations when FP flags change include
1907some video drivers (?), and some operations related to creation of the windows.
1908People who code B<OpenGL> may have more experience on this.
1909
1910Perl is generally used in the situation when all the floating-point
1911exceptions are ignored, as is the default under EMX. If they are not ignored,
1912some benign Perl programs would get a C<SIGFPE> and would die a horrible death.
1913
1914To circumvent this, Perl uses two hacks. They help against I<one> type of
1915damage only: FP flags changed when loading a DLL.
1916
25417810 1917One of the hacks is to disable floating point exceptions on Perl startup (as
3998488b
JH
1918is the default with EMX). This helps only with compile-time-linked DLLs
1919changing the flags before main() had a chance to be called.
1920
1921The other hack is to restore FP flags after a call to dlopen(). This helps
1922against similar damage done by DLLs _DLLInitTerm() at runtime. Currently
1923no way to switch these hacks off is provided.
1924
a56dbb1c 1925=back
615d1a09 1926
55497cff
PP
1927=head2 Modifications
1928
1929Perl modifies some standard C library calls in the following ways:
1930
1931=over 9
1932
1933=item C<popen>
1934
72ea3524 1935C<my_popen> uses F<sh.exe> if shell is required, cf. L<"PERL_SH_DIR">.
55497cff
PP
1936
1937=item C<tmpnam>
1938
1939is created using C<TMP> or C<TEMP> environment variable, via
1940C<tempnam>.
1941
1942=item C<tmpfile>
1943
72ea3524 1944If the current directory is not writable, file is created using modified
55497cff
PP
1945C<tmpnam>, so there may be a race condition.
1946
1947=item C<ctermid>
1948
1949a dummy implementation.
1950
1951=item C<stat>
1952
1953C<os2_stat> special-cases F</dev/tty> and F</dev/con>.
1954
3998488b
JH
1955=item C<mkdir>, C<rmdir>
1956
1957these EMX functions do not work if the path contains a trailing C</>.
1958Perl contains a workaround for this.
1959
367f3c24
IZ
1960=item C<flock>
1961
1962Since L<flock(3)> is present in EMX, but is not functional, it is
1963emulated by perl. To disable the emulations, set environment variable
1964C<USE_PERL_FLOCK=0>.
1965
55497cff
PP
1966=back
1967
3998488b
JH
1968=head2 Identifying DLLs
1969
1970All the DLLs built with the current versions of Perl have ID strings
1971identifying the name of the extension, its version, and the version
1972of Perl required for this DLL. Run C<bldlevel DLL-name> to find this
1973info.
1974
1975=head2 Centralized management of resources
1976
1977Since to call certain OS/2 API one needs to have a correctly initialized
1978C<Win> subsystem, OS/2-specific extensions may require getting C<HAB>s and
1979C<HMQ>s. If an extension would do it on its own, another extension could
1980fail to initialize.
1981
1982Perl provides a centralized management of these resources:
1983
1984=over
1985
1986=item C<HAB>
1987
1988To get the HAB, the extension should call C<hab = perl_hab_GET()> in C. After
1989this call is performed, C<hab> may be accessed as C<Perl_hab>. There is
1990no need to release the HAB after it is used.
1991
1992If by some reasons F<perl.h> cannot be included, use
1993
1994 extern int Perl_hab_GET(void);
1995
1996instead.
1997
1998=item C<HMQ>
1999
2000There are two cases:
2001
2002=over
2003
2004=item *
2005
2006the extension needs an C<HMQ> only because some API will not work otherwise.
2007Use C<serve = 0> below.
2008
2009=item *
2010
2011the extension needs an C<HMQ> since it wants to engage in a PM event loop.
2012Use C<serve = 1> below.
2013
2014=back
2015
2016To get an C<HMQ>, the extension should call C<hmq = perl_hmq_GET(serve)> in C.
2017After this call is performed, C<hmq> may be accessed as C<Perl_hmq>.
2018
2019To signal to Perl that HMQ is not needed any more, call
2020C<perl_hmq_UNSET(serve)>. Perl process will automatically morph/unmorph itself
2021into/from a PM process if HMQ is needed/not-needed. Perl will automatically
2022enable/disable C<WM_QUIT> message during shutdown if the message queue is
2023served/not-served.
2024
2025B<NOTE>. If during a shutdown there is a message queue which did not disable
2026WM_QUIT, and which did not process the received WM_QUIT message, the
2027shutdown will be automatically cancelled. Do not call C<perl_hmq_GET(1)>
2028unless you are going to process messages on an orderly basis.
2029
25417810
IZ
2030=item * Treating errors reported by OS/2 API
2031
2032There are two principal conventions (it is useful to call them C<Dos*>
2033and C<Win*> - though this part of the function signature is not always
2034determined by the name of the API) of reporting the error conditions
2035of OS/2 API. Most of C<Dos*> APIs report the error code as the result
2036of the call (so 0 means success, and there are many types of errors).
2037Most of C<Win*> API report success/fail via the result being
2038C<TRUE>/C<FALSE>; to find the reason for the failure one should call
2039WinGetLastError() API.
2040
2041Some C<Win*> entry points also overload a "meaningful" return value
2042with the error indicator; having a 0 return value indicates an error.
2043Yet some other C<Win*> entry points overload things even more, and 0
2044return value may mean a successful call returning a valid value 0, as
2045well as an error condition; in the case of a 0 return value one should
2046call WinGetLastError() API to distinguish a successful call from a
2047failing one.
2048
2049By convention, all the calls to OS/2 API should indicate their
2050failures by resetting $^E. All the Perl-accessible functions which
2051call OS/2 API may be broken into two classes: some die()s when an API
2052error is encountered, the other report the error via a false return
2053value (of course, this does not concern Perl-accessible functions
2054which I<expect> a failure of the OS/2 API call, having some workarounds
2055coded).
2056
2057Obviously, in the situation of the last type of the signature of an OS/2
2058API, it is must more convenient for the users if the failure is
2059indicated by die()ing: one does not need to check $^E to know that
2060something went wrong. If, however, this solution is not desirable by
2061some reason, the code in question should reset $^E to 0 before making
2062this OS/2 API call, so that the caller of this Perl-accessible
2063function has a chance to distinguish a success-but-0-return value from
2064a failure. (One may return undef as an alternative way of reporting
2065an error.)
2066
2067The macros to simplify this type of error propagation are
2068
2069=over
2070
2071=item C<CheckOSError(expr)>
2072
2073Returns true on error, sets $^E. Expects expr() be a call of
2074C<Dos*>-style API.
2075
2076=item C<CheckWinError(expr)>
2077
2078Returns true on error, sets $^E. Expects expr() be a call of
2079C<Win*>-style API.
2080
2081=item C<SaveWinError(expr)>
2082
2083Returns C<expr>, sets $^E from WinGetLastError() if C<expr> is false.
2084
2085=item C<SaveCroakWinError(expr,die,name1,name2)>
2086
2087Returns C<expr>, sets $^E from WinGetLastError() if C<expr> is false,
2088and die()s if C<die> and $^E are true. The message to die is the
2089concatenated strings C<name1> and C<name2>, separated by C<": "> from
2090the contents of $^E.
2091
2092=item C<WinError_2_Perl_rc>
2093
2094Sets C<Perl_rc> to the return value of WinGetLastError().
2095
2096=item C<FillWinError>
2097
2098Sets C<Perl_rc> to the return value of WinGetLastError(), and sets $^E
2099to the corresponding value.
2100
2101=item C<FillOSError(rc)>
2102
2103Sets C<Perl_rc> to C<rc>, and sets $^E to the corresponding value.
2104
2105=back
2106
2107=item * Loading DLLs and ordinals in DLLs
2108
2109Some DLLs are only present in some versions of OS/2, or in some
2110configurations of OS/2. Some exported entry points are present only
2111in DLLs shipped with some versions of OS/2. If these DLLs and entry
2112points were linked directly for a Perl executable/DLL or from a Perl
2113extensions, this binary would work only with the specified
2114versions/setups. Even if these entry points were not needed, the
2115I<load> of the executable (or DLL) would fail.
2116
2117For example, many newer useful APIs are not present in OS/2 v2; many
2118PM-related APIs require DLLs not available on floppy-boot setup.
2119
2120To make these calls fail I<only when the calls are executed>, one
2121should call these API via a dynamic linking API. There is a subsystem
2122in Perl to simplify such type of calls. A large number of entry
2123points available for such linking is provided (see C<entries_ordinals>
2124- and also C<PMWIN_entries> - in F<os2ish.h>). These ordinals can be
2125accessed via the APIs:
2126
2127 CallORD(), DeclFuncByORD(), DeclVoidFuncByORD(),
2128 DeclOSFuncByORD(), DeclWinFuncByORD(), AssignFuncPByORD(),
2129 DeclWinFuncByORD_CACHE(), DeclWinFuncByORD_CACHE_survive(),
2130 DeclWinFuncByORD_CACHE_resetError_survive(),
2131 DeclWinFunc_CACHE(), DeclWinFunc_CACHE_resetError(),
2132 DeclWinFunc_CACHE_survive(), DeclWinFunc_CACHE_resetError_survive()
2133
2134See the header files and the C code in the supplied OS/2-related
2135modules for the details on usage of these functions.
2136
2137Some of these functions also combine dynaloading semantic with the
2138error-propagation semantic discussed above.
d6fd60d6 2139
3998488b
JH
2140=back
2141
a56dbb1c 2142=head1 Perl flavors
615d1a09 2143
72ea3524 2144Because of idiosyncrasies of OS/2 one cannot have all the eggs in the
aa689395 2145same basket (though EMX environment tries hard to overcome this
a56dbb1c
PP
2146limitations, so the situation may somehow improve). There are 4
2147executables for Perl provided by the distribution:
615d1a09 2148
a56dbb1c 2149=head2 F<perl.exe>
615d1a09 2150
a56dbb1c
PP
2151The main workhorse. This is a chimera executable: it is compiled as an
2152C<a.out>-style executable, but is linked with C<omf>-style dynamic
aa689395
PP
2153library F<perl.dll>, and with dynamic CRT DLL. This executable is a
2154VIO application.
a56dbb1c 2155
3998488b 2156It can load perl dynamic extensions, and it can fork().
a56dbb1c
PP
2157
2158B<Note.> Keep in mind that fork() is needed to open a pipe to yourself.
2159
2160=head2 F<perl_.exe>
2161
3998488b
JH
2162This is a statically linked C<a.out>-style executable. It cannot
2163load dynamic Perl extensions. The executable supplied in binary
2164distributions has a lot of extensions prebuilt, thus the above restriction is
2165important only if you use custom-built extensions. This executable is a VIO
a56dbb1c
PP
2166application.
2167
3998488b 2168I<This is the only executable with does not require OS/2.> The
a56dbb1c 2169friends locked into C<M$> world would appreciate the fact that this
72ea3524 2170executable runs under DOS, Win0.3*, Win0.95 and WinNT with an
a56dbb1c
PP
2171appropriate extender. See L<"Other OSes">.
2172
2173=head2 F<perl__.exe>
2174
aa689395 2175This is the same executable as F<perl___.exe>, but it is a PM
a56dbb1c
PP
2176application.
2177
3998488b
JH
2178B<Note.> Usually (unless explicitly redirected during the startup)
2179STDIN, STDERR, and STDOUT of a PM
2180application are redirected to F<nul>. However, it is possible to I<see>
a56dbb1c 2181them if you start C<perl__.exe> from a PM program which emulates a
aa689395 2182console window, like I<Shell mode> of Emacs or EPM. Thus it I<is
a56dbb1c 2183possible> to use Perl debugger (see L<perldebug>) to debug your PM
3998488b
JH
2184application (but beware of the message loop lockups - this will not
2185work if you have a message queue to serve, unless you hook the serving
2186into the getc() function of the debugger).
a56dbb1c 2187
3998488b
JH
2188Another way to see the output of a PM program is to run it as
2189
2190 pm_prog args 2>&1 | cat -
2191
2192with a shell I<different> from F<cmd.exe>, so that it does not create
2193a link between a VIO session and the session of C<pm_porg>. (Such a link
2194closes the VIO window.) E.g., this works with F<sh.exe> - or with Perl!
2195
2196 open P, 'pm_prog args 2>&1 |' or die;
2197 print while <P>;
2198
2199The flavor F<perl__.exe> is required if you want to start your program without
2200a VIO window present, but not C<detach>ed (run C<help detach> for more info).
2201Very useful for extensions which use PM, like C<Perl/Tk> or C<OpenGL>.
a56dbb1c 2202
25417810
IZ
2203Note also that the differences between PM and VIO executables are only
2204in the I<default> behaviour. One can start I<any> executable in
2205I<any> kind of session by using the arguments C</fs>, C</pm> or
2206C</win> switches of the command C<start> (of F<CMD.EXE> or a similar
2207shell). Alternatively, one can use the numeric first argument of the
5f0135eb 2208C<system> Perl function (see L<OS2::Process>).
25417810 2209
a56dbb1c
PP
2210=head2 F<perl___.exe>
2211
2212This is an C<omf>-style executable which is dynamically linked to
aa689395 2213F<perl.dll> and CRT DLL. I know no advantages of this executable
a56dbb1c
PP
2214over C<perl.exe>, but it cannot fork() at all. Well, one advantage is
2215that the build process is not so convoluted as with C<perl.exe>.
2216
aa689395 2217It is a VIO application.
a56dbb1c
PP
2218
2219=head2 Why strange names?
2220
2221Since Perl processes the C<#!>-line (cf.
2222L<perlrun/DESCRIPTION>, L<perlrun/Switches>,
2223L<perldiag/"Not a perl script">,
2224L<perldiag/"No Perl script found in input">), it should know when a
2225program I<is a Perl>. There is some naming convention which allows
2226Perl to distinguish correct lines from wrong ones. The above names are
72ea3524 2227almost the only names allowed by this convention which do not contain
a56dbb1c
PP
2228digits (which have absolutely different semantics).
2229
2230=head2 Why dynamic linking?
2231
2232Well, having several executables dynamically linked to the same huge
2233library has its advantages, but this would not substantiate the
3998488b
JH
2234additional work to make it compile. The reason is the complicated-to-developers
2235but very quick and convenient-to-users "hard" dynamic linking used by OS/2.
2236
2237There are two distinctive features of the dyna-linking model of OS/2:
25417810
IZ
2238first, all the references to external functions are resolved at the compile time;
2239second, there is no runtime fixup of the DLLs after they are loaded into memory.
3998488b
JH
2240The first feature is an enormous advantage over other models: it avoids
2241conflicts when several DLLs used by an application export entries with
2242the same name. In such cases "other" models of dyna-linking just choose
2243between these two entry points using some random criterion - with predictable
2244disasters as results. But it is the second feature which requires the build
2245of F<perl.dll>.
a56dbb1c 2246
72ea3524 2247The address tables of DLLs are patched only once, when they are
3998488b
JH
2248loaded. The addresses of the entry points into DLLs are guaranteed to be
2249the same for all the programs which use the same DLL. This removes the
2250runtime fixup - once DLL is loaded, its code is read-only.
a56dbb1c 2251
3998488b
JH
2252While this allows some (significant?) performance advantages, this makes life
2253much harder for developers, since the above scheme makes it impossible
2254for a DLL to be "linked" to a symbol in the F<.EXE> file. Indeed, this
2255would need a DLL to have different relocations tables for the
2256(different) executables which use this DLL.
2257
2258However, a dynamically loaded Perl extension is forced to use some symbols
2259from the perl
2260executable, e.g., to know how to find the arguments to the functions:
2261the arguments live on the perl
2262internal evaluation stack. The solution is to put the main code of
2263the interpreter into a DLL, and make the F<.EXE> file which just loads
2264this DLL into memory and supplies command-arguments. The extension DLL
2265cannot link to symbols in F<.EXE>, but it has no problem linking
2266to symbols in the F<.DLL>.
a56dbb1c 2267
72ea3524 2268This I<greatly> increases the load time for the application (as well as
3998488b
JH
2269complexity of the compilation). Since interpreter is in a DLL,
2270the C RTL is basically forced to reside in a DLL as well (otherwise
2271extensions would not be able to use CRT). There are some advantages if
2272you use different flavors of perl, such as running F<perl.exe> and
2273F<perl__.exe> simultaneously: they share the memory of F<perl.dll>.
2274
2275B<NOTE>. There is one additional effect which makes DLLs more wasteful:
2276DLLs are loaded in the shared memory region, which is a scarse resource
2277given the 512M barrier of the "standard" OS/2 virtual memory. The code of
2278F<.EXE> files is also shared by all the processes which use the particular
2279F<.EXE>, but they are "shared in the private address space of the process";
2280this is possible because the address at which different sections
2281of the F<.EXE> file are loaded is decided at compile-time, thus all the
2282processes have these sections loaded at same addresses, and no fixup
2283of internal links inside the F<.EXE> is needed.
2284
d1be9408 2285Since DLLs may be loaded at run time, to have the same mechanism for DLLs
3998488b
JH
2286one needs to have the address range of I<any of the loaded> DLLs in the
2287system to be available I<in all the processes> which did not load a particular
2288DLL yet. This is why the DLLs are mapped to the shared memory region.
a56dbb1c
PP
2289
2290=head2 Why chimera build?
2291
aa689395 2292Current EMX environment does not allow DLLs compiled using Unixish
3998488b
JH
2293C<a.out> format to export symbols for data (or at least some types of
2294data). This forces C<omf>-style compile of F<perl.dll>.
a56dbb1c 2295
aa689395 2296Current EMX environment does not allow F<.EXE> files compiled in
a56dbb1c
PP
2297C<omf> format to fork(). fork() is needed for exactly three Perl
2298operations:
2299
2300=over 4
2301
3998488b 2302=item *
a56dbb1c 2303
3998488b 2304explicit fork() in the script,
a56dbb1c 2305
3998488b 2306=item *
a56dbb1c 2307
3998488b
JH
2308C<open FH, "|-">
2309
2310=item *
a56dbb1c 2311
3998488b 2312C<open FH, "-|">, in other words, opening pipes to itself.
a56dbb1c
PP
2313
2314=back
2315
3998488b
JH
2316While these operations are not questions of life and death, they are
2317needed for a lot of
2318useful scripts. This forces C<a.out>-style compile of
a56dbb1c
PP
2319F<perl.exe>.
2320
2321
2322=head1 ENVIRONMENT
2323
aa689395
PP
2324Here we list environment variables with are either OS/2- and DOS- and
2325Win*-specific, or are more important under OS/2 than under other OSes.
a56dbb1c
PP
2326
2327=head2 C<PERLLIB_PREFIX>
2328
aa689395 2329Specific for EMX port. Should have the form
a56dbb1c
PP
2330
2331 path1;path2
2332
2333or
2334
2335 path1 path2
2336
2337If the beginning of some prebuilt path matches F<path1>, it is
2338substituted with F<path2>.
2339
2340Should be used if the perl library is moved from the default
2341location in preference to C<PERL(5)LIB>, since this would not leave wrong
3998488b 2342entries in @INC. For example, if the compiled version of perl looks for @INC
eb447b86
IZ
2343in F<f:/perllib/lib>, and you want to install the library in
2344F<h:/opt/gnu>, do
2345
2346 set PERLLIB_PREFIX=f:/perllib/lib;h:/opt/gnu
a56dbb1c 2347
3998488b
JH
2348This will cause Perl with the prebuilt @INC of
2349
2350 f:/perllib/lib/5.00553/os2
2351 f:/perllib/lib/5.00553
2352 f:/perllib/lib/site_perl/5.00553/os2
2353 f:/perllib/lib/site_perl/5.00553
2354 .
2355
2356to use the following @INC:
2357
2358 h:/opt/gnu/5.00553/os2
2359 h:/opt/gnu/5.00553
2360 h:/opt/gnu/site_perl/5.00553/os2
2361 h:/opt/gnu/site_perl/5.00553
2362 .
2363
a56dbb1c
PP
2364=head2 C<PERL_BADLANG>
2365
3998488b 2366If 0, perl ignores setlocale() failing. May be useful with some
a56dbb1c
PP
2367strange I<locale>s.
2368
2369=head2 C<PERL_BADFREE>
2370
3998488b
JH
2371If 0, perl would not warn of in case of unwarranted free(). With older
2372perls this might be
2373useful in conjunction with the module DB_File, which was buggy when
2374dynamically linked and OMF-built.
2375
2376Should not be set with newer Perls, since this may hide some I<real> problems.
a56dbb1c
PP
2377
2378=head2 C<PERL_SH_DIR>
2379
aa689395 2380Specific for EMX port. Gives the directory part of the location for
a56dbb1c
PP
2381F<sh.exe>.
2382
367f3c24
IZ
2383=head2 C<USE_PERL_FLOCK>
2384
2385Specific for EMX port. Since L<flock(3)> is present in EMX, but is not
2386functional, it is emulated by perl. To disable the emulations, set
2387environment variable C<USE_PERL_FLOCK=0>.
2388
a56dbb1c
PP
2389=head2 C<TMP> or C<TEMP>
2390
3998488b 2391Specific for EMX port. Used as storage place for temporary files.
a56dbb1c
PP
2392
2393=head1 Evolution
2394
2395Here we list major changes which could make you by surprise.
2396
25417810
IZ
2397=head2 Text-mode filehandles
2398
2399Starting from version 5.8, Perl uses a builtin translation layer for
2400text-mode files. This replaces the efficient well-tested EMX layer by
2401some code which should be best characterized as a "quick hack".
2402
2403In addition to possible bugs and an inability to follow changes to the
2404translation policy with off/on switches of TERMIO translation, this
2405introduces a serious incompatible change: before sysread() on
2406text-mode filehandles would go through the translation layer, now it
2407would not.
2408
a56dbb1c
PP
2409=head2 Priorities
2410
2411C<setpriority> and C<getpriority> are not compatible with earlier
2412ports by Andreas Kaiser. See C<"setpriority, getpriority">.
2413
d88df687 2414=head2 DLL name mangling: pre 5.6.2
a56dbb1c
PP
2415
2416With the release 5.003_01 the dynamically loadable libraries
3998488b
JH
2417should be rebuilt when a different version of Perl is compiled. In particular,
2418DLLs (including F<perl.dll>) are now created with the names
a56dbb1c
PP
2419which contain a checksum, thus allowing workaround for OS/2 scheme of
2420caching DLLs.
2421
3998488b
JH
2422It may be possible to code a simple workaround which would
2423
2424=over
2425
2426=item *
2427
2428find the old DLLs looking through the old @INC;
2429
2430=item *
2431
2432mangle the names according to the scheme of new perl and copy the DLLs to
2433these names;
2434
2435=item *
2436
2437edit the internal C<LX> tables of DLL to reflect the change of the name
2438(probably not needed for Perl extension DLLs, since the internally coded names
2439are not used for "specific" DLLs, they used only for "global" DLLs).
2440
2441=item *
2442
2443edit the internal C<IMPORT> tables and change the name of the "old"
2444F<perl????.dll> to the "new" F<perl????.dll>.
2445
2446=back
2447
354a27bf 2448=head2 DLL name mangling: 5.6.2 and beyond
d88df687
IZ
2449
2450In fact mangling of I<extension> DLLs was done due to misunderstanding
2451of the OS/2 dynaloading model. OS/2 (effectively) maintains two
2452different tables of loaded DLL:
2453
2454=over
2455
2456=item Global DLLs
2457
2458those loaded by the base name from C<LIBPATH>; including those
2459associated at link time;
2460
2461=item specific DLLs
2462
2463loaded by the full name.
2464
2465=back
2466
2467When resolving a request for a global DLL, the table of already-loaded
2468specific DLLs is (effectively) ignored; moreover, specific DLLs are
2469I<always> loaded from the prescribed path.
2470
2471There is/was a minor twist which makes this scheme fragile: what to do
2472with DLLs loaded from
2473
2474=over
2475
2476=item C<BEGINLIBPATH> and C<ENDLIBPATH>
2477
2478(which depend on the process)
2479
2480=item F<.> from C<LIBPATH>
2481
2482which I<effectively> depends on the process (although C<LIBPATH> is the
2483same for all the processes).
2484
2485=back
2486
2487Unless C<LIBPATHSTRICT> is set to C<T> (and the kernel is after
24882000/09/01), such DLLs are considered to be global. When loading a
2489global DLL it is first looked in the table of already-loaded global
2490DLLs. Because of this the fact that one executable loaded a DLL from
2491C<BEGINLIBPATH> and C<ENDLIBPATH>, or F<.> from C<LIBPATH> may affect
2492I<which> DLL is loaded when I<another> executable requests a DLL with
2493the same name. I<This> is the reason for version-specific mangling of
2494the DLL name for perl DLL.
2495
2496Since the Perl extension DLLs are always loaded with the full path,
2497there is no need to mangle their names in a version-specific ways:
2498their directory already reflects the corresponding version of perl,
2499and @INC takes into account binary compatibility with older version.
2500Starting from C<5.6.2> the name mangling scheme is fixed to be the
2501same as for Perl 5.005_53 (same as in a popular binary release). Thus
2502new Perls will be able to I<resolve the names> of old extension DLLs
2503if @INC allows finding their directories.
2504
210b36aa 2505However, this still does not guarantee that these DLL may be loaded.
d88df687
IZ
2506The reason is the mangling of the name of the I<Perl DLL>. And since
2507the extension DLLs link with the Perl DLL, extension DLLs for older
2508versions would load an older Perl DLL, and would most probably
2509segfault (since the data in this DLL is not properly initialized).
2510
2511There is a partial workaround (which can be made complete with newer
2512OS/2 kernels): create a forwarder DLL with the same name as the DLL of
2513the older version of Perl, which forwards the entry points to the
2514newer Perl's DLL. Make this DLL accessible on (say) the C<BEGINLIBPATH> of
2515the new Perl executable. When the new executable accesses old Perl's
2516extension DLLs, they would request the old Perl's DLL by name, get the
2517forwarder instead, so effectively will link with the currently running
2518(new) Perl DLL.
2519
2520This may break in two ways:
2521
2522=over
2523
2524=item *
2525
2526Old perl executable is started when a new executable is running has
2527loaded an extension compiled for the old executable (ouph!). In this
2528case the old executable will get a forwarder DLL instead of the old
2529perl DLL, so would link with the new perl DLL. While not directly
210b36aa 2530fatal, it will behave the same as new executable. This beats the whole
d88df687
IZ
2531purpose of explicitly starting an old executable.
2532
2533=item *
2534
2535A new executable loads an extension compiled for the old executable
2536when an old perl executable is running. In this case the extension
2537will not pick up the forwarder - with fatal results.
2538
2539=back
2540
2541With support for C<LIBPATHSTRICT> this may be circumvented - unless
2542one of DLLs is started from F<.> from C<LIBPATH> (I do not know
2543whether C<LIBPATHSTRICT> affects this case).
2544
2545B<REMARK>. Unless newer kernels allow F<.> in C<BEGINLIBPATH> (older
25417810
IZ
2546do not), this mess cannot be completely cleaned. (It turns out that
2547as of the beginning of 2002, F<.> is not allowed, but F<.\.> is - and
2548it has the same effect.)
d88df687
IZ
2549
2550
2551B<REMARK>. C<LIBPATHSTRICT>, C<BEGINLIBPATH> and C<ENDLIBPATH> are
2552not environment variables, although F<cmd.exe> emulates them on C<SET
2553...> lines. From Perl they may be accessed by L<Cwd::extLibpath> and
2554L<Cwd::extLibpath_set>.
2555
2556=head2 DLL forwarder generation
2557
2558Assume that the old DLL is named F<perlE0AC.dll> (as is one for
25595.005_53), and the new version is 5.6.1. Create a file
2560F<perl5shim.def-leader> with
2561
2562 LIBRARY 'perlE0AC' INITINSTANCE TERMINSTANCE
2563 DESCRIPTION '@#perl5-porters@perl.org:5.006001#@ Perl module for 5.00553 -> Perl 5.6.1 forwarder'
2564 CODE LOADONCALL
2565 DATA LOADONCALL NONSHARED MULTIPLE
2566 EXPORTS
2567
2568modifying the versions/names as needed. Run
2569
2570 perl -wnle "next if 0../EXPORTS/; print qq( \"$1\") if /\"(\w+)\"/" perl5.def >lst
2571
2572in the Perl build directory (to make the DLL smaller replace perl5.def
2573with the definition file for the older version of Perl if present).
2574
2575 cat perl5shim.def-leader lst >perl5shim.def
2576 gcc -Zomf -Zdll -o perlE0AC.dll perl5shim.def -s -llibperl
2577
2578(ignore multiple C<warning L4085>).
2579
a56dbb1c
PP
2580=head2 Threading
2581
3998488b
JH
2582As of release 5.003_01 perl is linked to multithreaded C RTL
2583DLL. If perl itself is not compiled multithread-enabled, so will not be perl's
a56dbb1c
PP
2584malloc(). However, extensions may use multiple thread on their own
2585risk.
2586
3998488b
JH
2587This was needed to compile C<Perl/Tk> for XFree86-OS/2 out-of-the-box, and
2588link with DLLs for other useful libraries, which typically are compiled
2589with C<-Zmt -Zcrtdll>.
a56dbb1c
PP
2590
2591=head2 Calls to external programs
2592
2593Due to a popular demand the perl external program calling has been
72ea3524 2594changed wrt Andreas Kaiser's port. I<If> perl needs to call an
a56dbb1c
PP
2595external program I<via shell>, the F<f:/bin/sh.exe> will be called, or
2596whatever is the override, see L<"PERL_SH_DIR">.
2597
2598Thus means that you need to get some copy of a F<sh.exe> as well (I
3998488b 2599use one from pdksh). The path F<F:/bin> above is set up automatically during
a56dbb1c
PP
2600the build to a correct value on the builder machine, but is
2601overridable at runtime,
2602
2603B<Reasons:> a consensus on C<perl5-porters> was that perl should use
2604one non-overridable shell per platform. The obvious choices for OS/2
2605are F<cmd.exe> and F<sh.exe>. Having perl build itself would be impossible
3998488b 2606with F<cmd.exe> as a shell, thus I picked up C<sh.exe>. This assures almost
aa689395
PP
2607100% compatibility with the scripts coming from *nix. As an added benefit
2608this works as well under DOS if you use DOS-enabled port of pdksh
2609(see L<"Prerequisites">).
a56dbb1c 2610
aa689395 2611B<Disadvantages:> currently F<sh.exe> of pdksh calls external programs
a56dbb1c 2612via fork()/exec(), and there is I<no> functioning exec() on
3998488b 2613OS/2. exec() is emulated by EMX by an asynchronous call while the caller
72ea3524 2614waits for child completion (to pretend that the C<pid> did not change). This
a56dbb1c
PP
2615means that 1 I<extra> copy of F<sh.exe> is made active via fork()/exec(),
2616which may lead to some resources taken from the system (even if we do
2617not count extra work needed for fork()ing).
2618
72ea3524
IZ
2619Note that this a lesser issue now when we do not spawn F<sh.exe>
2620unless needed (metachars found).
2621
2622One can always start F<cmd.exe> explicitly via
a56dbb1c
PP
2623
2624 system 'cmd', '/c', 'mycmd', 'arg1', 'arg2', ...
2625
72ea3524 2626If you need to use F<cmd.exe>, and do not want to hand-edit thousands of your
a56dbb1c
PP
2627scripts, the long-term solution proposed on p5-p is to have a directive
2628
2629 use OS2::Cmd;
2630
2631which will override system(), exec(), C<``>, and
2632C<open(,'...|')>. With current perl you may override only system(),
2633readpipe() - the explicit version of C<``>, and maybe exec(). The code
2634will substitute the one-argument call to system() by
2635C<CORE::system('cmd.exe', '/c', shift)>.
2636
2637If you have some working code for C<OS2::Cmd>, please send it to me,
2638I will include it into distribution. I have no need for such a module, so
2639cannot test it.
2640
2c2e0e8c 2641For the details of the current situation with calling external programs,
3998488b
JH
2642see L<Starting OS/2 (and DOS) programs under Perl>. Set us mention a couple
2643of features:
2c2e0e8c 2644
13a2d996 2645=over 4
2c2e0e8c 2646
13a2d996 2647=item *
2c2e0e8c 2648
3998488b
JH
2649External scripts may be called by their basename. Perl will try the same
2650extensions as when processing B<-S> command-line switch.
2651
2652=item *
2653
2654External scripts starting with C<#!> or C<extproc > will be executed directly,
2655without calling the shell, by calling the program specified on the rest of
2656the first line.
2c2e0e8c
IZ
2657
2658=back
2659
df3ef7a9
IZ
2660=head2 Memory allocation
2661
2662Perl uses its own malloc() under OS/2 - interpreters are usually malloc-bound
ec40c0cd 2663for speed, but perl is not, since its malloc is lightning-fast.
4375e838
GS
2664Perl-memory-usage-tuned benchmarks show that Perl's malloc is 5 times quicker
2665than EMX one. I do not have convincing data about memory footprint, but
3998488b 2666a (pretty random) benchmark showed that Perl's one is 5% better.
df3ef7a9
IZ
2667
2668Combination of perl's malloc() and rigid DLL name resolution creates
2669a special problem with library functions which expect their return value to
2670be free()d by system's free(). To facilitate extensions which need to call
2671such functions, system memory-allocation functions are still available with
2672the prefix C<emx_> added. (Currently only DLL perl has this, it should
2673propagate to F<perl_.exe> shortly.)
2674
ec40c0cd
IZ
2675=head2 Threads
2676
2677One can build perl with thread support enabled by providing C<-D usethreads>
2678option to F<Configure>. Currently OS/2 support of threads is very
2679preliminary.
2680
2681Most notable problems:
2682
13a2d996 2683=over 4
ec40c0cd
IZ
2684
2685=item C<COND_WAIT>
2686
25417810
IZ
2687may have a race condition (but probably does not due to edge-triggered
2688nature of OS/2 Event semaphores). (Needs a reimplementation (in terms of chaining
2689waiting threads, with the linked list stored in per-thread structure?)?)
ec40c0cd
IZ
2690
2691=item F<os2.c>
2692
2693has a couple of static variables used in OS/2-specific functions. (Need to be
2694moved to per-thread structure, or serialized?)
2695
2696=back
2697
2698Note that these problems should not discourage experimenting, since they
2699have a low probability of affecting small programs.
2700
d88df687
IZ
2701=head1 BUGS
2702
1933e12c
IZ
2703This description is not updated often (since 5.6.1?), see F<./os2/Changes>
2704(L<perlos2delta>) for more info.
d88df687 2705
a56dbb1c
PP
2706=cut
2707
2708OS/2 extensions
2709~~~~~~~~~~~~~~~
72ea3524 2710I include 3 extensions by Andreas Kaiser, OS2::REXX, OS2::UPM, and OS2::FTP,
a56dbb1c
PP
2711into my ftp directory, mirrored on CPAN. I made
2712some minor changes needed to compile them by standard tools. I cannot
2713test UPM and FTP, so I will appreciate your feedback. Other extensions
2714there are OS2::ExtAttr, OS2::PrfDB for tied access to EAs and .INI
2715files - and maybe some other extensions at the time you read it.
2716
2717Note that OS2 perl defines 2 pseudo-extension functions
aa689395
PP
2718OS2::Copy::copy and DynaLoader::mod2fname (many more now, see
2719L<Prebuilt methods>).
a56dbb1c
PP
2720
2721The -R switch of older perl is deprecated. If you need to call a REXX code
2722which needs access to variables, include the call into a REXX compartment
2723created by
2724 REXX_call {...block...};
2725
2726Two new functions are supported by REXX code,
2727 REXX_eval 'string';
2728 REXX_eval_with 'string', REXX_function_name => \&perl_sub_reference;
2729
2730If you have some other extensions you want to share, send the code to
2731me. At least two are available: tied access to EA's, and tied access
2732to system databases.
615d1a09 2733
a56dbb1c 2734=head1 AUTHOR
615d1a09 2735
25417810 2736Ilya Zakharevich, cpan@ilyaz.org
615d1a09 2737
a56dbb1c 2738=head1 SEE ALSO
615d1a09 2739
a56dbb1c 2740perl(1).
615d1a09 2741
a56dbb1c 2742=cut
615d1a09 2743