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