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