1PERLOS2(1)             Perl Programmers Reference Guide             PERLOS2(1)
2
3
4

NAME

6       perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT.
7

SYNOPSIS

9       One can read this document in the following formats:
10
11               man perlos2
12               view perl perlos2
13               explorer perlos2.html
14               info perlos2
15
16       to list some (not all may be available simultaneously), or it may be
17       read as is: either as README.os2, or pod/perlos2.pod.
18
19       To read the .INF version of documentation (very recommended) outside of
20       OS/2, one needs an IBM's reader (may be available on IBM ftp sites (?)
21       (URL anyone?)) or shipped with PC DOS 7.0 and IBM's Visual Age C++ 3.5.
22
23       A copy of a Win* viewer is contained in the "Just add OS/2 Warp"
24       package
25
26         ftp://ftp.software.ibm.com/ps/products/os2/tools/jaow/jaow.zip
27
28       in ?:\JUST_ADD\view.exe. This gives one an access to EMX's .INF docs as
29       well (text form is available in /emx/doc in EMX's distribution).  There
30       is also a different viewer named xview.
31
32       Note that if you have lynx.exe or netscape.exe installed, you can
33       follow WWW links from this document in .INF format. If you have EMX
34       docs installed correctly, you can follow library links (you need to
35       have "view emxbook" working by setting "EMXBOOK" environment variable
36       as it is described in EMX docs).
37

DESCRIPTION

39   Target
40       The target is to make OS/2 one of the best supported platform for
41       using/building/developing Perl and Perl applications, as well as make
42       Perl the best language to use under OS/2. The secondary target is to
43       try to make this work under DOS and Win* as well (but not too hard).
44
45       The current state is quite close to this target. Known limitations:
46
47       ·    Some *nix programs use fork() a lot; with the mostly useful
48            flavors of perl for OS/2 (there are several built simultaneously)
49            this is supported; but some flavors do not support this (e.g.,
50            when Perl is called from inside REXX).  Using fork() after useing
51            dynamically loading extensions would not work with very old
52            versions of EMX.
53
54       ·    You need a separate perl executable perl__.exe (see "perl__.exe")
55            if you want to use PM code in your application (as Perl/Tk or
56            OpenGL Perl modules do) without having a text-mode window present.
57
58            While using the standard perl.exe from a text-mode window is
59            possible too, I have seen cases when this causes degradation of
60            the system stability.  Using perl__.exe avoids such a degradation.
61
62       ·    There is no simple way to access WPS objects. The only way I know
63            is via "OS2::REXX" and "SOM" extensions (see OS2::REXX, SOM).
64            However, we do not have access to convenience methods of Object-
65            REXX. (Is it possible at all? I know of no Object-REXX API.)  The
66            "SOM" extension (currently in alpha-text) may eventually remove
67            this shortcoming; however, due to the fact that DII is not
68            supported by the "SOM" module, using "SOM" is not as convenient as
69            one would like it.
70
71       Please keep this list up-to-date by informing me about other items.
72
73   Other OSes
74       Since OS/2 port of perl uses a remarkable EMX environment, it can run
75       (and build extensions, and - possibly - be built itself) under any
76       environment which can run EMX. The current list is DOS,
77       DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT. Out of many perl flavors,
78       only one works, see "perl_.exe".
79
80       Note that not all features of Perl are available under these
81       environments. This depends on the features the extender - most probably
82       RSX - decided to implement.
83
84       Cf. "Prerequisites".
85
86   Prerequisites
87       EMX   EMX runtime is required (may be substituted by RSX). Note that it
88             is possible to make perl_.exe to run under DOS without any
89             external support by binding emx.exe/rsx.exe to it, see "emxbind".
90             Note that under DOS for best results one should use RSX runtime,
91             which has much more functions working (like "fork", "popen" and
92             so on). In fact RSX is required if there is no VCPI present. Note
93             the RSX requires DPMI.  Many implementations of DPMI are known to
94             be very buggy, beware!
95
96             Only the latest runtime is supported, currently "0.9d fix 03".
97             Perl may run under earlier versions of EMX, but this is not
98             tested.
99
100             One can get different parts of EMX from, say
101
102               ftp://crydee.sai.msu.ru/pub/comp/os/os2/leo/gnu/emx+gcc/
103               http://hobbes.nmsu.edu/h-browse.php?dir=/pub/os2/dev/emx/v0.9d/
104
105             The runtime component should have the name emxrt.zip.
106
107             NOTE. When using emx.exe/rsx.exe, it is enough to have them on
108             your path. One does not need to specify them explicitly (though
109             this
110
111               emx perl_.exe -de 0
112
113             will work as well.)
114
115       RSX   To run Perl on DPMI platforms one needs RSX runtime. This is
116             needed under DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT (see
117             "Other OSes"). RSX would not work with VCPI only, as EMX would,
118             it requires DMPI.
119
120             Having RSX and the latest sh.exe one gets a fully functional
121             *nix-ish environment under DOS, say, "fork", "``" and pipe-"open"
122             work. In fact, MakeMaker works (for static build), so one can
123             have Perl development environment under DOS.
124
125             One can get RSX from, say
126
127               http://cd.textfiles.com/hobbesos29804/disk1/EMX09C/
128               ftp://crydee.sai.msu.ru/pub/comp/os/os2/leo/gnu/emx+gcc/contrib/
129
130             Contact the author on "rainer@mathematik.uni-bielefeld.de".
131
132             The latest sh.exe with DOS hooks is available in
133
134               http://www.ilyaz.org/software/os2/
135
136             as sh_dos.zip or under similar names starting with "sh", "pdksh"
137             etc.
138
139       HPFS  Perl does not care about file systems, but the perl library
140             contains many files with long names, so to install it intact one
141             needs a file system which supports long file names.
142
143             Note that if you do not plan to build the perl itself, it may be
144             possible to fool EMX to truncate file names. This is not
145             supported, read EMX docs to see how to do it.
146
147       pdksh To start external programs with complicated command lines (like
148             with pipes in between, and/or quoting of arguments), Perl uses an
149             external shell. With EMX port such shell should be named sh.exe,
150             and located either in the wired-in-during-compile locations
151             (usually F:/bin), or in configurable location (see
152             ""PERL_SH_DIR"").
153
154             For best results use EMX pdksh. The standard binary (5.2.14 or
155             later) runs under DOS (with "RSX") as well, see
156
157               http://www.ilyaz.org/software/os2/
158
159   Starting Perl programs under OS/2 (and DOS and...)
160       Start your Perl program foo.pl with arguments "arg1 arg2 arg3" the same
161       way as on any other platform, by
162
163               perl foo.pl arg1 arg2 arg3
164
165       If you want to specify perl options "-my_opts" to the perl itself (as
166       opposed to your program), use
167
168               perl -my_opts foo.pl arg1 arg2 arg3
169
170       Alternately, if you use OS/2-ish shell, like CMD or 4os2, put the
171       following at the start of your perl script:
172
173               extproc perl -S -my_opts
174
175       rename your program to foo.cmd, and start it by typing
176
177               foo arg1 arg2 arg3
178
179       Note that because of stupid OS/2 limitations the full path of the perl
180       script is not available when you use "extproc", thus you are forced to
181       use "-S" perl switch, and your script should be on the "PATH". As a
182       plus side, if you know a full path to your script, you may still start
183       it with
184
185               perl ../../blah/foo.cmd arg1 arg2 arg3
186
187       (note that the argument "-my_opts" is taken care of by the "extproc"
188       line in your script, see ""extproc" on the first line").
189
190       To understand what the above magic does, read perl docs about "-S"
191       switch - see perlrun, and cmdref about "extproc":
192
193               view perl perlrun
194               man perlrun
195               view cmdref extproc
196               help extproc
197
198       or whatever method you prefer.
199
200       There are also endless possibilities to use executable extensions of
201       4os2, associations of WPS and so on... However, if you use *nixish
202       shell (like sh.exe supplied in the binary distribution), you need to
203       follow the syntax specified in "Command Switches" in perlrun.
204
205       Note that -S switch supports scripts with additional extensions .cmd,
206       .btm, .bat, .pl as well.
207
208   Starting OS/2 (and DOS) programs under Perl
209       This is what system() (see "system" in perlfunc), "``" (see "I/O
210       Operators" in perlop), and open pipe (see "open" in perlfunc) are for.
211       (Avoid exec() (see "exec" in perlfunc) unless you know what you do).
212
213       Note however that to use some of these operators you need to have a sh-
214       syntax shell installed (see "Pdksh", "Frequently asked questions"), and
215       perl should be able to find it (see ""PERL_SH_DIR"").
216
217       The cases when the shell is used are:
218
219       1.  One-argument system() (see "system" in perlfunc), exec() (see
220           "exec" in perlfunc) with redirection or shell meta-characters;
221
222       2.  Pipe-open (see "open" in perlfunc) with the command which contains
223           redirection or shell meta-characters;
224
225       3.  Backticks "``" (see "I/O Operators" in perlop) with the command
226           which contains redirection or shell meta-characters;
227
228       4.  If the executable called by system()/exec()/pipe-open()/"``" is a
229           script with the "magic" "#!" line or "extproc" line which specifies
230           shell;
231
232       5.  If the executable called by system()/exec()/pipe-open()/"``" is a
233           script without "magic" line, and $ENV{EXECSHELL} is set to shell;
234
235       6.  If the executable called by system()/exec()/pipe-open()/"``" is not
236           found (is not this remark obsolete?);
237
238       7.  For globbing (see "glob" in perlfunc, "I/O Operators" in perlop)
239           (obsolete? Perl uses builtin globbing nowadays...).
240
241       For the sake of speed for a common case, in the above algorithms
242       backslashes in the command name are not considered as shell
243       metacharacters.
244
245       Perl starts scripts which begin with cookies "extproc" or "#!"
246       directly, without an intervention of shell.  Perl uses the same
247       algorithm to find the executable as pdksh: if the path on "#!" line
248       does not work, and contains "/", then the directory part of the
249       executable is ignored, and the executable is searched in . and on
250       "PATH".  To find arguments for these scripts Perl uses a different
251       algorithm than pdksh: up to 3 arguments are recognized, and trailing
252       whitespace is stripped.
253
254       If a script does not contain such a cooky, then to avoid calling
255       sh.exe, Perl uses the same algorithm as pdksh: if $ENV{EXECSHELL} is
256       set, the script is given as the first argument to this command, if not
257       set, then "$ENV{COMSPEC} /c" is used (or a hardwired guess if
258       $ENV{COMSPEC} is not set).
259
260       When starting scripts directly, Perl uses exactly the same algorithm as
261       for the search of script given by -S command-line option: it will look
262       in the current directory, then on components of $ENV{PATH} using the
263       following order of appended extensions: no extension, .cmd, .btm, .bat,
264       .pl.
265
266       Note that Perl will start to look for scripts only if OS/2 cannot start
267       the specified application, thus "system 'blah'" will not look for a
268       script if there is an executable file blah.exe anywhere on "PATH".  In
269       other words, "PATH" is essentially searched twice: once by the OS for
270       an executable, then by Perl for scripts.
271
272       Note also that executable files on OS/2 can have an arbitrary
273       extension, but .exe will be automatically appended if no dot is present
274       in the name.  The workaround is as simple as that:  since blah. and
275       blah denote the same file (at list on FAT and HPFS file systems), to
276       start an executable residing in file n:/bin/blah (no extension) give an
277       argument "n:/bin/blah." (dot appended) to system().
278
279       Perl will start PM programs from VIO (=text-mode) Perl process in a
280       separate PM session; the opposite is not true: when you start a non-PM
281       program from a PM Perl process, Perl would not run it in a separate
282       session.  If a separate session is desired, either ensure that shell
283       will be used, as in "system 'cmd /c myprog'", or start it using
284       optional arguments to system() documented in "OS2::Process" module.
285       This is considered to be a feature.
286

Frequently asked questions

288   "It does not work"
289       Perl binary distributions come with a testperl.cmd script which tries
290       to detect common problems with misconfigured installations.  There is a
291       pretty large chance it will discover which step of the installation you
292       managed to goof.  ";-)"
293
294   I cannot run external programs
295       ·   Did you run your programs with "-w" switch? See "Starting OS/2 (and
296           DOS) programs under Perl".
297
298       ·   Do you try to run internal shell commands, like "`copy a b`"
299           (internal for cmd.exe), or "`glob a*b`" (internal for ksh)? You
300           need to specify your shell explicitly, like "`cmd /c copy a b`",
301           since Perl cannot deduce which commands are internal to your shell.
302
303   I cannot embed perl into my program, or use perl.dll from my program.
304       Is your program EMX-compiled with "-Zmt -Zcrtdll"?
305           Well, nowadays Perl DLL should be usable from a differently
306           compiled program too...  If you can run Perl code from REXX scripts
307           (see OS2::REXX), then there are some other aspect of interaction
308           which are overlooked by the current hackish code to support
309           differently-compiled principal programs.
310
311           If everything else fails, you need to build a stand-alone DLL for
312           perl. Contact me, I did it once. Sockets would not work, as a lot
313           of other stuff.
314
315       Did you use ExtUtils::Embed?
316           Some time ago I had reports it does not work.  Nowadays it is
317           checked in the Perl test suite, so grep ./t subdirectory of the
318           build tree (as well as *.t files in the ./lib subdirectory) to find
319           how it should be done "correctly".
320
321   "``" and pipe-"open" do not work under DOS.
322       This may a variant of just "I cannot run external programs", or a
323       deeper problem. Basically: you need RSX (see "Prerequisites") for these
324       commands to work, and you may need a port of sh.exe which understands
325       command arguments. One of such ports is listed in "Prerequisites" under
326       RSX. Do not forget to set variable ""PERL_SH_DIR"" as well.
327
328       DPMI is required for RSX.
329
330   Cannot start "find.exe "pattern" file"
331       The whole idea of the "standard C API to start applications" is that
332       the forms "foo" and "foo" of program arguments are completely
333       interchangeable.  find breaks this paradigm;
334
335         find "pattern" file
336         find pattern file
337
338       are not equivalent; find cannot be started directly using the above
339       API.  One needs a way to surround the doublequotes in some other
340       quoting construction, necessarily having an extra non-Unixish shell in
341       between.
342
343       Use one of
344
345         system 'cmd', '/c', 'find "pattern" file';
346         `cmd /c 'find "pattern" file'`
347
348       This would start find.exe via cmd.exe via "sh.exe" via "perl.exe", but
349       this is a price to pay if you want to use non-conforming program.
350

INSTALLATION

352   Automatic binary installation
353       The most convenient way of installing a binary distribution of perl is
354       via perl installer install.exe. Just follow the instructions, and 99%
355       of the installation blues would go away.
356
357       Note however, that you need to have unzip.exe on your path, and EMX
358       environment running. The latter means that if you just installed EMX,
359       and made all the needed changes to Config.sys, you may need to reboot
360       in between. Check EMX runtime by running
361
362               emxrev
363
364       Binary installer also creates a folder on your desktop with some useful
365       objects.  If you need to change some aspects of the work of the binary
366       installer, feel free to edit the file Perl.pkg.  This may be useful
367       e.g., if you need to run the installer many times and do not want to
368       make many interactive changes in the GUI.
369
370       Things not taken care of by automatic binary installation:
371
372       "PERL_BADLANG" may be needed if you change your codepage after perl
373                      installation, and the new value is not supported by EMX.
374                      See ""PERL_BADLANG"".
375
376       "PERL_BADFREE" see ""PERL_BADFREE"".
377
378       Config.pm      This file resides somewhere deep in the location you
379                      installed your perl library, find it out by
380
381                        perl -MConfig -le "print $INC{'Config.pm'}"
382
383                      While most important values in this file are updated by
384                      the binary installer, some of them may need to be hand-
385                      edited. I know no such data, please keep me informed if
386                      you find one.  Moreover, manual changes to the installed
387                      version may need to be accompanied by an edit of this
388                      file.
389
390       NOTE. Because of a typo the binary installer of 5.00305 would install a
391       variable "PERL_SHPATH" into Config.sys. Please remove this variable and
392       put ""PERL_SH_DIR"" instead.
393
394   Manual binary installation
395       As of version 5.00305, OS/2 perl binary distribution comes split into
396       11 components. Unfortunately, to enable configurable binary
397       installation, the file paths in the zip files are not absolute, but
398       relative to some directory.
399
400       Note that the extraction with the stored paths is still necessary
401       (default with unzip, specify "-d" to pkunzip). However, you need to
402       know where to extract the files. You need also to manually change
403       entries in Config.sys to reflect where did you put the files. Note that
404       if you have some primitive unzipper (like "pkunzip"), you may get a lot
405       of warnings/errors during unzipping. Upgrade to "(w)unzip".
406
407       Below is the sample of what to do to reproduce the configuration on my
408       machine.  In VIEW.EXE you can press "Ctrl-Insert" now, and cut-and-
409       paste from the resulting file - created in the directory you started
410       VIEW.EXE from.
411
412       For each component, we mention environment variables related to each
413       installation directory.  Either choose directories to match your values
414       of the variables, or create/append-to variables to take into account
415       the directories.
416
417       Perl VIO and PM executables (dynamically linked)
418            unzip perl_exc.zip *.exe *.ico -d f:/emx.add/bin
419            unzip perl_exc.zip *.dll -d f:/emx.add/dll
420
421          (have the directories with "*.exe" on PATH, and "*.dll" on LIBPATH);
422
423       Perl_ VIO executable (statically linked)
424            unzip perl_aou.zip -d f:/emx.add/bin
425
426          (have the directory on PATH);
427
428       Executables for Perl utilities
429            unzip perl_utl.zip -d f:/emx.add/bin
430
431          (have the directory on PATH);
432
433       Main Perl library
434            unzip perl_mlb.zip -d f:/perllib/lib
435
436          If this directory is exactly the same as the prefix which was
437          compiled into perl.exe, you do not need to change anything. However,
438          for perl to find the library if you use a different path, you need
439          to "set PERLLIB_PREFIX" in Config.sys, see ""PERLLIB_PREFIX"".
440
441       Additional Perl modules
442            unzip perl_ste.zip -d f:/perllib/lib/site_perl/5.30.2/
443
444          Same remark as above applies.  Additionally, if this directory is
445          not one of directories on @INC (and @INC is influenced by
446          "PERLLIB_PREFIX"), you need to put this directory and subdirectory
447          ./os2 in "PERLLIB" or "PERL5LIB" variable. Do not use "PERL5LIB"
448          unless you have it set already. See "ENVIRONMENT" in perl.
449
450          [Check whether this extraction directory is still applicable with
451          the new directory structure layout!]
452
453       Tools to compile Perl modules
454            unzip perl_blb.zip -d f:/perllib/lib
455
456          Same remark as for perl_ste.zip.
457
458       Manpages for Perl and utilities
459            unzip perl_man.zip -d f:/perllib/man
460
461          This directory should better be on "MANPATH". You need to have a
462          working man to access these files.
463
464       Manpages for Perl modules
465            unzip perl_mam.zip -d f:/perllib/man
466
467          This directory should better be on "MANPATH". You need to have a
468          working man to access these files.
469
470       Source for Perl documentation
471            unzip perl_pod.zip -d f:/perllib/lib
472
473          This is used by the "perldoc" program (see perldoc), and may be used
474          to generate HTML documentation usable by WWW browsers, and
475          documentation in zillions of other formats: "info", "LaTeX",
476          "Acrobat", "FrameMaker" and so on.  [Use programs such as pod2latex
477          etc.]
478
479       Perl manual in .INF format
480            unzip perl_inf.zip -d d:/os2/book
481
482          This directory should better be on "BOOKSHELF".
483
484       Pdksh
485            unzip perl_sh.zip -d f:/bin
486
487          This is used by perl to run external commands which explicitly
488          require shell, like the commands using redirection and shell
489          metacharacters. It is also used instead of explicit /bin/sh.
490
491          Set "PERL_SH_DIR" (see ""PERL_SH_DIR"") if you move sh.exe from the
492          above location.
493
494          Note. It may be possible to use some other sh-compatible shell
495          (untested).
496
497       After you installed the components you needed and updated the
498       Config.sys correspondingly, you need to hand-edit Config.pm. This file
499       resides somewhere deep in the location you installed your perl library,
500       find it out by
501
502         perl -MConfig -le "print $INC{'Config.pm'}"
503
504       You need to correct all the entries which look like file paths (they
505       currently start with "f:/").
506
507   Warning
508       The automatic and manual perl installation leave precompiled paths
509       inside perl executables. While these paths are overwritable (see
510       ""PERLLIB_PREFIX"", ""PERL_SH_DIR""), some people may prefer binary
511       editing of paths inside the executables/DLLs.
512

Accessing documentation

514       Depending on how you built/installed perl you may have (otherwise
515       identical) Perl documentation in the following formats:
516
517   OS/2 .INF file
518       Most probably the most convenient form. Under OS/2 view it as
519
520         view perl
521         view perl perlfunc
522         view perl less
523         view perl ExtUtils::MakeMaker
524
525       (currently the last two may hit a wrong location, but this may improve
526       soon). Under Win* see "SYNOPSIS".
527
528       If you want to build the docs yourself, and have OS/2 toolkit, run
529
530               pod2ipf > perl.ipf
531
532       in /perllib/lib/pod directory, then
533
534               ipfc /inf perl.ipf
535
536       (Expect a lot of errors during the both steps.) Now move it on your
537       BOOKSHELF path.
538
539   Plain text
540       If you have perl documentation in the source form, perl utilities
541       installed, and GNU groff installed, you may use
542
543               perldoc perlfunc
544               perldoc less
545               perldoc ExtUtils::MakeMaker
546
547       to access the perl documentation in the text form (note that you may
548       get better results using perl manpages).
549
550       Alternately, try running pod2text on .pod files.
551
552   Manpages
553       If you have man installed on your system, and you installed perl
554       manpages, use something like this:
555
556               man perlfunc
557               man 3 less
558               man ExtUtils.MakeMaker
559
560       to access documentation for different components of Perl. Start with
561
562               man perl
563
564       Note that dot (.) is used as a package separator for documentation for
565       packages, and as usual, sometimes you need to give the section - 3
566       above - to avoid shadowing by the less(1) manpage.
567
568       Make sure that the directory above the directory with manpages is on
569       our "MANPATH", like this
570
571         set MANPATH=c:/man;f:/perllib/man
572
573       for Perl manpages in "f:/perllib/man/man1/" etc.
574
575   HTML
576       If you have some WWW browser available, installed the Perl
577       documentation in the source form, and Perl utilities, you can build
578       HTML docs. Cd to directory with .pod files, and do like this
579
580               cd f:/perllib/lib/pod
581               pod2html
582
583       After this you can direct your browser the file perl.html in this
584       directory, and go ahead with reading docs, like this:
585
586               explore file:///f:/perllib/lib/pod/perl.html
587
588       Alternatively you may be able to get these docs prebuilt from CPAN.
589
590   GNU "info" files
591       Users of Emacs would appreciate it very much, especially with "CPerl"
592       mode loaded. You need to get latest "pod2texi" from "CPAN", or,
593       alternately, the prebuilt info pages.
594
595   PDF files
596       for "Acrobat" are available on CPAN (may be for slightly older version
597       of perl).
598
599   "LaTeX" docs
600       can be constructed using "pod2latex".
601

BUILD

603       Here we discuss how to build Perl under OS/2.
604
605   The short story
606       Assume that you are a seasoned porter, so are sure that all the
607       necessary tools are already present on your system, and you know how to
608       get the Perl source distribution.  Untar it, change to the extract
609       directory, and
610
611         gnupatch -p0 < os2\diff.configure
612         sh Configure -des -D prefix=f:/perllib
613         make
614         make test
615         make install
616         make aout_test
617         make aout_install
618
619       This puts the executables in f:/perllib/bin.  Manually move them to the
620       "PATH", manually move the built perl*.dll to "LIBPATH" (here for Perl
621       DLL * is a not-very-meaningful hex checksum), and run
622
623         make installcmd INSTALLCMDDIR=d:/ir/on/path
624
625       Assuming that the "man"-files were put on an appropriate location, this
626       completes the installation of minimal Perl system.  (The binary
627       distribution contains also a lot of additional modules, and the
628       documentation in INF format.)
629
630       What follows is a detailed guide through these steps.
631
632   Prerequisites
633       You need to have the latest EMX development environment, the full GNU
634       tool suite (gawk renamed to awk, and GNU find.exe earlier on path than
635       the OS/2 find.exe, same with sort.exe, to check use
636
637         find --version
638         sort --version
639
640       ). You need the latest version of pdksh installed as sh.exe.
641
642       Check that you have BSD libraries and headers installed, and -
643       optionally - Berkeley DB headers and libraries, and crypt.
644
645       Possible locations to get the files:
646
647         ftp://ftp.uni-heidelberg.de/pub/os2/unix/
648         http://hobbes.nmsu.edu/h-browse.php?dir=/pub/os2
649         http://cd.textfiles.com/hobbesos29804/disk1/DEV32/
650         http://cd.textfiles.com/hobbesos29804/disk1/EMX09C/
651
652       It is reported that the following archives contain enough utils to
653       build perl: gnufutil.zip, gnusutil.zip, gnututil.zip, gnused.zip,
654       gnupatch.zip, gnuawk.zip, gnumake.zip, gnugrep.zip, bsddev.zip and
655       ksh527rt.zip (or a later version).  Note that all these utilities are
656       known to be available from LEO:
657
658         ftp://crydee.sai.msu.ru/pub/comp/os/os2/leo/gnu/
659
660       Note also that the db.lib and db.a from the EMX distribution are not
661       suitable for multi-threaded compile (even single-threaded flavor of
662       Perl uses multi-threaded C RTL, for compatibility with XFree86-OS/2).
663       Get a corrected one from
664
665         http://www.ilyaz.org/software/os2/db_mt.zip
666
667       If you have exactly the same version of Perl installed already, make
668       sure that no copies or perl are currently running.  Later steps of the
669       build may fail since an older version of perl.dll loaded into memory
670       may be found.  Running "make test" becomes meaningless, since the test
671       are checking a previous build of perl (this situation is detected and
672       reported by os2/os2_base.t test).  Do not forget to unset
673       "PERL_EMXLOAD_SEC" in environment.
674
675       Also make sure that you have /tmp directory on the current drive, and .
676       directory in your "LIBPATH". One may try to correct the latter
677       condition by
678
679         set BEGINLIBPATH .\.
680
681       if you use something like CMD.EXE or latest versions of 4os2.exe.
682       (Setting BEGINLIBPATH to just "." is ignored by the OS/2 kernel.)
683
684       Make sure your gcc is good for "-Zomf" linking: run "omflibs" script in
685       /emx/lib directory.
686
687       Check that you have link386 installed. It comes standard with OS/2, but
688       may be not installed due to customization. If typing
689
690         link386
691
692       shows you do not have it, do Selective install, and choose "Link object
693       modules" in Optional system utilities/More. If you get into link386
694       prompts, press "Ctrl-C" to exit.
695
696   Getting perl source
697       You need to fetch the latest perl source (including developers
698       releases). With some probability it is located in
699
700         http://www.cpan.org/src/
701         http://www.cpan.org/src/unsupported
702
703       If not, you may need to dig in the indices to find it in the directory
704       of the current maintainer.
705
706       Quick cycle of developers release may break the OS/2 build time to
707       time, looking into
708
709         http://www.cpan.org/ports/os2/
710
711       may indicate the latest release which was publicly released by the
712       maintainer. Note that the release may include some additional patches
713       to apply to the current source of perl.
714
715       Extract it like this
716
717         tar vzxf perl5.00409.tar.gz
718
719       You may see a message about errors while extracting Configure. This is
720       because there is a conflict with a similarly-named file configure.
721
722       Change to the directory of extraction.
723
724   Application of the patches
725       You need to apply the patches in ./os2/diff.* like this:
726
727         gnupatch -p0 < os2\diff.configure
728
729       You may also need to apply the patches supplied with the binary
730       distribution of perl.  It also makes sense to look on the perl5-porters
731       mailing list for the latest OS/2-related patches (see
732       <http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/>).  Such
733       patches usually contain strings "/os2/" and "patch", so it makes sense
734       looking for these strings.
735
736   Hand-editing
737       You may look into the file ./hints/os2.sh and correct anything wrong
738       you find there. I do not expect it is needed anywhere.
739
740   Making
741         sh Configure -des -D prefix=f:/perllib
742
743       "prefix" means: where to install the resulting perl library. Giving
744       correct prefix you may avoid the need to specify "PERLLIB_PREFIX", see
745       ""PERLLIB_PREFIX"".
746
747       Ignore the message about missing "ln", and about "-c" option to tr. The
748       latter is most probably already fixed, if you see it and can trace
749       where the latter spurious warning comes from, please inform me.
750
751       Now
752
753         make
754
755       At some moment the built may die, reporting a version mismatch or
756       unable to run perl.  This means that you do not have . in your LIBPATH,
757       so perl.exe cannot find the needed perl67B2.dll (treat these hex digits
758       as line noise).  After this is fixed the build should finish without a
759       lot of fuss.
760
761   Testing
762       Now run
763
764         make test
765
766       All tests should succeed (with some of them skipped).  If you have the
767       same version of Perl installed, it is crucial that you have "." early
768       in your LIBPATH (or in BEGINLIBPATH), otherwise your tests will most
769       probably test the wrong version of Perl.
770
771       Some tests may generate extra messages similar to
772
773       A lot of "bad free"
774           in database tests related to Berkeley DB. This should be fixed
775           already.  If it persists, you may disable this warnings, see
776           ""PERL_BADFREE"".
777
778       Process terminated by SIGTERM/SIGINT
779           This is a standard message issued by OS/2 applications. *nix
780           applications die in silence. It is considered to be a feature. One
781           can easily disable this by appropriate sighandlers.
782
783           However the test engine bleeds these message to screen in
784           unexpected moments. Two messages of this kind should be present
785           during testing.
786
787       To get finer test reports, call
788
789         perl t/harness
790
791       The report with io/pipe.t failing may look like this:
792
793        Failed Test  Status Wstat Total Fail  Failed  List of failed
794        ------------------------------------------------------------
795        io/pipe.t                    12    1   8.33%  9
796        7 tests skipped, plus 56 subtests skipped.
797        Failed 1/195 test scripts, 99.49% okay. 1/6542 subtests failed,
798           99.98% okay.
799
800       The reasons for most important skipped tests are:
801
802       op/fs.t
803               18  Checks "atime" and "mtime" of "stat()" - unfortunately,
804                   HPFS provides only 2sec time granularity (for compatibility
805                   with FAT?).
806
807               25  Checks "truncate()" on a filehandle just opened for write -
808                   I do not know why this should or should not work.
809
810       op/stat.t
811               Checks "stat()". Tests:
812
813               4   Checks "atime" and "mtime" of "stat()" - unfortunately,
814                   HPFS provides only 2sec time granularity (for compatibility
815                   with FAT?).
816
817   Installing the built perl
818       If you haven't yet moved "perl*.dll" onto LIBPATH, do it now.
819
820       Run
821
822         make install
823
824       It would put the generated files into needed locations. Manually put
825       perl.exe, perl__.exe and perl___.exe to a location on your PATH,
826       perl.dll to a location on your LIBPATH.
827
828       Run
829
830         make installcmd INSTALLCMDDIR=d:/ir/on/path
831
832       to convert perl utilities to .cmd files and put them on PATH. You need
833       to put .EXE-utilities on path manually. They are installed in
834       "$prefix/bin", here $prefix is what you gave to Configure, see
835       "Making".
836
837       If you use "man", either move the installed */man/ directories to your
838       "MANPATH", or modify "MANPATH" to match the location.  (One could have
839       avoided this by providing a correct "manpath" option to ./Configure, or
840       editing ./config.sh between configuring and making steps.)
841
842   "a.out"-style build
843       Proceed as above, but make perl_.exe (see "perl_.exe") by
844
845         make perl_
846
847       test and install by
848
849         make aout_test
850         make aout_install
851
852       Manually put perl_.exe to a location on your PATH.
853
854       Note. The build process for "perl_" does not know about all the
855       dependencies, so you should make sure that anything is up-to-date, say,
856       by doing
857
858         make perl_dll
859
860       first.
861

Building a binary distribution

863       [This section provides a short overview only...]
864
865       Building should proceed differently depending on whether the version of
866       perl you install is already present and used on your system, or is a
867       new version not yet used.  The description below assumes that the
868       version is new, so installing its DLLs and .pm files will not disrupt
869       the operation of your system even if some intermediate steps are not
870       yet fully working.
871
872       The other cases require a little bit more convoluted procedures.  Below
873       I suppose that the current version of Perl is 5.8.2, so the executables
874       are named accordingly.
875
876       1.  Fully build and test the Perl distribution.  Make sure that no
877           tests are failing with "test" and "aout_test" targets; fix the bugs
878           in Perl and the Perl test suite detected by these tests.  Make sure
879           that "all_test" make target runs as clean as possible.  Check that
880           os2/perlrexx.cmd runs fine.
881
882       2.  Fully install Perl, including "installcmd" target.  Copy the
883           generated DLLs to "LIBPATH"; copy the numbered Perl executables (as
884           in perl5.8.2.exe) to "PATH"; copy "perl_.exe" to "PATH" as
885           "perl_5.8.2.exe".  Think whether you need backward-compatibility
886           DLLs.  In most cases you do not need to install them yet; but
887           sometime this may simplify the following steps.
888
889       3.  Make sure that "CPAN.pm" can download files from CPAN.  If not, you
890           may need to manually install "Net::FTP".
891
892       4.  Install the bundle "Bundle::OS2_default"
893
894            perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_1
895
896           This may take a couple of hours on 1GHz processor (when run the
897           first time).  And this should not be necessarily a smooth
898           procedure.  Some modules may not specify required dependencies, so
899           one may need to repeat this procedure several times until the
900           results stabilize.
901
902            perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_2
903            perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_3
904
905           Even after they stabilize, some tests may fail.
906
907           Fix as many discovered bugs as possible.  Document all the bugs
908           which are not fixed, and all the failures with unknown reasons.
909           Inspect the produced logs 00cpan_i_1 to find suspiciously skipped
910           tests, and other fishy events.
911
912           Keep in mind that installation of some modules may fail too: for
913           example, the DLLs to update may be already loaded by CPAN.pm.
914           Inspect the "install" logs (in the example above 00cpan_i_1 etc)
915           for errors, and install things manually, as in
916
917             cd $CPANHOME/.cpan/build/Digest-MD5-2.31
918             make install
919
920           Some distributions may fail some tests, but you may want to install
921           them anyway (as above, or via "force install" command of "CPAN.pm"
922           shell-mode).
923
924           Since this procedure may take quite a long time to complete, it
925           makes sense to "freeze" your CPAN configuration by disabling
926           periodic updates of the local copy of CPAN index: set
927           "index_expire" to some big value (I use 365), then save the
928           settings
929
930             CPAN> o conf index_expire 365
931             CPAN> o conf commit
932
933           Reset back to the default value 1 when you are finished.
934
935       5.  When satisfied with the results, rerun the "installcmd" target.
936           Now you can copy "perl5.8.2.exe" to "perl.exe", and install the
937           other OMF-build executables: "perl__.exe" etc.  They are ready to
938           be used.
939
940       6.  Change to the "./pod" directory of the build tree, download the
941           Perl logo CamelGrayBig.BMP, and run
942
943             ( perl2ipf > perl.ipf ) |& tee 00ipf
944             ipfc /INF perl.ipf |& tee 00inf
945
946           This produces the Perl docs online book "perl.INF".  Install in on
947           "BOOKSHELF" path.
948
949       7.  Now is the time to build statically linked executable perl_.exe
950           which includes newly-installed via "Bundle::OS2_default" modules.
951           Doing testing via "CPAN.pm" is going to be painfully slow, since it
952           statically links a new executable per XS extension.
953
954           Here is a possible workaround: create a toplevel Makefile.PL in
955           $CPANHOME/.cpan/build/ with contents being (compare with "Making
956           executables with a custom collection of statically loaded
957           extensions")
958
959             use ExtUtils::MakeMaker;
960             WriteMakefile NAME => 'dummy';
961
962           execute this as
963
964             perl_5.8.2.exe Makefile.PL <nul |& tee 00aout_c1
965             make -k all test <nul |& 00aout_t1
966
967           Again, this procedure should not be absolutely smooth.  Some
968           "Makefile.PL"'s in subdirectories may be buggy, and would not run
969           as "child" scripts.  The interdependency of modules can strike you;
970           however, since non-XS modules are already installed, the
971           prerequisites of most modules have a very good chance to be
972           present.
973
974           If you discover some glitches, move directories of problematic
975           modules to a different location; if these modules are non-XS
976           modules, you may just ignore them - they are already installed; the
977           remaining, XS, modules you need to install manually one by one.
978
979           After each such removal you need to rerun the "Makefile.PL"/"make"
980           process; usually this procedure converges soon.  (But be sure to
981           convert all the necessary external C libraries from .lib format to
982           .a format: run one of
983
984             emxaout foo.lib
985             emximp -o foo.a foo.lib
986
987           whichever is appropriate.)  Also, make sure that the DLLs for
988           external libraries are usable with with executables compiled
989           without "-Zmtd" options.
990
991           When you are sure that only a few subdirectories lead to failures,
992           you may want to add "-j4" option to "make" to speed up skipping
993           subdirectories with already finished build.
994
995           When you are satisfied with the results of tests, install the build
996           C libraries for extensions:
997
998             make install |& tee 00aout_i
999
1000           Now you can rename the file ./perl.exe generated during the last
1001           phase to perl_5.8.2.exe; place it on "PATH"; if there is an inter-
1002           dependency between some XS modules, you may need to repeat the
1003           "test"/"install" loop with this new executable and some excluded
1004           modules - until the procedure converges.
1005
1006           Now you have all the necessary .a libraries for these Perl modules
1007           in the places where Perl builder can find it.  Use the perl
1008           builder: change to an empty directory, create a "dummy" Makefile.PL
1009           again, and run
1010
1011             perl_5.8.2.exe Makefile.PL |& tee 00c
1012             make perl                  |& tee 00p
1013
1014           This should create an executable ./perl.exe with all the statically
1015           loaded extensions built in.  Compare the generated perlmain.c files
1016           to make sure that during the iterations the number of loaded
1017           extensions only increases.  Rename ./perl.exe to perl_5.8.2.exe on
1018           "PATH".
1019
1020           When it converges, you got a functional variant of perl_5.8.2.exe;
1021           copy it to "perl_.exe".  You are done with generation of the local
1022           Perl installation.
1023
1024       8.  Make sure that the installed modules are actually installed in the
1025           location of the new Perl, and are not inherited from entries of
1026           @INC given for inheritance from the older versions of Perl: set
1027           "PERLLIB_582_PREFIX" to redirect the new version of Perl to a new
1028           location, and copy the installed files to this new location.  Redo
1029           the tests to make sure that the versions of modules inherited from
1030           older versions of Perl are not needed.
1031
1032           Actually, the log output of pod2ipf(1) during the step 6 gives a
1033           very detailed info about which modules are loaded from which place;
1034           so you may use it as an additional verification tool.
1035
1036           Check that some temporary files did not make into the perl install
1037           tree.  Run something like this
1038
1039             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
1040
1041           in the install tree (both top one and sitelib one).
1042
1043           Compress all the DLLs with lxlite.  The tiny .exe can be compressed
1044           with "/c:max" (the bug only appears when there is a fixup in the
1045           last 6 bytes of a page (?); since the tiny executables are much
1046           smaller than a page, the bug will not hit).  Do not compress
1047           "perl_.exe" - it would not work under DOS.
1048
1049       9.  Now you can generate the binary distribution.  This is done by
1050           running the test of the CPAN distribution "OS2::SoftInstaller".
1051           Tune up the file test.pl to suit the layout of current version of
1052           Perl first.  Do not forget to pack the necessary external DLLs
1053           accordingly.  Include the description of the bugs and test suite
1054           failures you could not fix.  Include the small-stack versions of
1055           Perl executables from Perl build directory.
1056
1057           Include perl5.def so that people can relink the perl DLL preserving
1058           the binary compatibility, or can create compatibility DLLs.
1059           Include the diff files ("diff -pu old new") of fixes you did so
1060           that people can rebuild your version.  Include perl5.map so that
1061           one can use remote debugging.
1062
1063       10. Share what you did with the other people.  Relax.  Enjoy fruits of
1064           your work.
1065
1066       11. Brace yourself for thanks, bug reports, hate mail and spam coming
1067           as result of the previous step.  No good deed should remain
1068           unpunished!
1069

Building custom .EXE files

1071       The Perl executables can be easily rebuilt at any moment.  Moreover,
1072       one can use the embedding interface (see perlembed) to make very
1073       customized executables.
1074
1075   Making executables with a custom collection of statically loaded extensions
1076       It is a little bit easier to do so while decreasing the list of
1077       statically loaded extensions.  We discuss this case only here.
1078
1079       1.  Change to an empty directory, and create a placeholder
1080           <Makefile.PL>:
1081
1082             use ExtUtils::MakeMaker;
1083             WriteMakefile NAME => 'dummy';
1084
1085       2.  Run it with the flavor of Perl (perl.exe or perl_.exe) you want to
1086           rebuild.
1087
1088             perl_ Makefile.PL
1089
1090       3.  Ask it to create new Perl executable:
1091
1092             make perl
1093
1094           (you may need to manually add "PERLTYPE=-DPERL_CORE" to this
1095           commandline on some versions of Perl; the symptom is that the
1096           command-line globbing does not work from OS/2 shells with the
1097           newly-compiled executable; check with
1098
1099             .\perl.exe -wle "print for @ARGV" *
1100
1101           ).
1102
1103       4.  The previous step created perlmain.c which contains a list of
1104           newXS() calls near the end.  Removing unnecessary calls, and
1105           rerunning
1106
1107             make perl
1108
1109           will produce a customized executable.
1110
1111   Making executables with a custom search-paths
1112       The default perl executable is flexible enough to support most usages.
1113       However, one may want something yet more flexible; for example, one may
1114       want to find Perl DLL relatively to the location of the EXE file; or
1115       one may want to ignore the environment when setting the Perl-library
1116       search patch, etc.
1117
1118       If you fill comfortable with embedding interface (see perlembed), such
1119       things are easy to do repeating the steps outlined in L/<Making
1120       executables with a custom collection of statically loaded extensions>,
1121       and doing more comprehensive edits to main() of perlmain.c.  The people
1122       with little desire to understand Perl can just rename main(), and do
1123       necessary modification in a custom main() which calls the renamed
1124       function in appropriate time.
1125
1126       However, there is a third way: perl DLL exports the main() function and
1127       several callbacks to customize the search path.  Below is a complete
1128       example of a "Perl loader" which
1129
1130       1.  Looks for Perl DLL in the directory "$exedir/../dll";
1131
1132       2.  Prepends the above directory to "BEGINLIBPATH";
1133
1134       3.  Fails if the Perl DLL found via "BEGINLIBPATH" is different from
1135           what was loaded on step 1; e.g., another process could have loaded
1136           it from "LIBPATH" or from a different value of "BEGINLIBPATH".  In
1137           these cases one needs to modify the setting of the system so that
1138           this other process either does not run, or loads the DLL from
1139           "BEGINLIBPATH" with "LIBPATHSTRICT=T" (available with kernels after
1140           September 2000).
1141
1142       4.  Loads Perl library from "$exedir/../dll/lib/".
1143
1144       5.  Uses Bourne shell from "$exedir/../dll/sh/ksh.exe".
1145
1146       For best results compile the C file below with the same options as the
1147       Perl DLL.  However, a lot of functionality will work even if the
1148       executable is not an EMX applications, e.g., if compiled with
1149
1150         gcc -Wall -DDOSISH -DOS2=1 -O2 -s -Zomf -Zsys perl-starter.c \
1151           -DPERL_DLL_BASENAME=\"perl312F\" -Zstack 8192 -Zlinker /PM:VIO
1152
1153       Here is the sample C file:
1154
1155        #define INCL_DOS
1156        #define INCL_NOPM
1157        /* These are needed for compile if os2.h includes os2tk.h, not
1158         * os2emx.h */
1159        #define INCL_DOSPROCESS
1160        #include <os2.h>
1161
1162        #include "EXTERN.h"
1163        #define PERL_IN_MINIPERLMAIN_C
1164        #include "perl.h"
1165
1166        static char *me;
1167        HMODULE handle;
1168
1169        static void
1170        die_with(char *msg1, char *msg2, char *msg3, char *msg4)
1171        {
1172           ULONG c;
1173           char *s = " error: ";
1174
1175           DosWrite(2, me, strlen(me), &c);
1176           DosWrite(2, s, strlen(s), &c);
1177           DosWrite(2, msg1, strlen(msg1), &c);
1178           DosWrite(2, msg2, strlen(msg2), &c);
1179           DosWrite(2, msg3, strlen(msg3), &c);
1180           DosWrite(2, msg4, strlen(msg4), &c);
1181           DosWrite(2, "\r\n", 2, &c);
1182           exit(255);
1183        }
1184
1185        typedef ULONG (*fill_extLibpath_t)(int type,
1186                                           char *pre,
1187                                           char *post,
1188                                           int replace,
1189                                           char *msg);
1190        typedef int (*main_t)(int type, char *argv[], char *env[]);
1191        typedef int (*handler_t)(void* data, int which);
1192
1193        #ifndef PERL_DLL_BASENAME
1194        #  define PERL_DLL_BASENAME "perl"
1195        #endif
1196
1197        static HMODULE
1198        load_perl_dll(char *basename)
1199        {
1200            char buf[300], fail[260];
1201            STRLEN l, dirl;
1202            fill_extLibpath_t f;
1203            ULONG rc_fullname;
1204            HMODULE handle, handle1;
1205
1206            if (_execname(buf, sizeof(buf) - 13) != 0)
1207                die_with("Can't find full path: ", strerror(errno), "", "");
1208            /* XXXX Fill 'me' with new value */
1209            l = strlen(buf);
1210            while (l && buf[l-1] != '/' && buf[l-1] != '\\')
1211                l--;
1212            dirl = l - 1;
1213            strcpy(buf + l, basename);
1214            l += strlen(basename);
1215            strcpy(buf + l, ".dll");
1216            if ( (rc_fullname = DosLoadModule(fail, sizeof fail, buf, &handle))
1217                                                                           != 0
1218                 && DosLoadModule(fail, sizeof fail, basename, &handle) != 0 )
1219                die_with("Can't load DLL ", buf, "", "");
1220            if (rc_fullname)
1221                return handle;    /* was loaded with short name; all is fine */
1222            if (DosQueryProcAddr(handle, 0, "fill_extLibpath", (PFN*)&f))
1223                die_with(buf,
1224                         ": DLL exports no symbol ",
1225                         "fill_extLibpath",
1226                         "");
1227            buf[dirl] = 0;
1228            if (f(0 /*BEGINLIBPATH*/, buf /* prepend */, NULL /* append */,
1229                  0 /* keep old value */, me))
1230                die_with(me, ": prepending BEGINLIBPATH", "", "");
1231            if (DosLoadModule(fail, sizeof fail, basename, &handle1) != 0)
1232                die_with(me,
1233                         ": finding perl DLL again via BEGINLIBPATH",
1234                         "",
1235                         "");
1236            buf[dirl] = '\\';
1237            if (handle1 != handle) {
1238                if (DosQueryModuleName(handle1, sizeof(fail), fail))
1239                    strcpy(fail, "???");
1240                die_with(buf,
1241                         ":\n\tperl DLL via BEGINLIBPATH is different: \n\t",
1242                         fail,
1243                         "\n\tYou may need to manipulate global BEGINLIBPATH"
1244                            " and LIBPATHSTRICT"
1245                            "\n\tso that the other copy is loaded via"
1246                            BEGINLIBPATH.");
1247            }
1248            return handle;
1249        }
1250
1251        int
1252        main(int argc, char **argv, char **env)
1253        {
1254            main_t f;
1255            handler_t h;
1256
1257            me = argv[0];
1258            /**/
1259            handle = load_perl_dll(PERL_DLL_BASENAME);
1260
1261            if (DosQueryProcAddr(handle,
1262                                 0,
1263                                 "Perl_OS2_handler_install",
1264                                 (PFN*)&h))
1265                die_with(PERL_DLL_BASENAME,
1266                         ": DLL exports no symbol ",
1267                         "Perl_OS2_handler_install",
1268                         "");
1269            if ( !h((void *)"~installprefix", Perlos2_handler_perllib_from)
1270                 || !h((void *)"~dll", Perlos2_handler_perllib_to)
1271                 || !h((void *)"~dll/sh/ksh.exe", Perlos2_handler_perl_sh) )
1272                die_with(PERL_DLL_BASENAME,
1273                         ": Can't install @INC manglers",
1274                         "",
1275                         "");
1276            if (DosQueryProcAddr(handle, 0, "dll_perlmain", (PFN*)&f))
1277                die_with(PERL_DLL_BASENAME,
1278                         ": DLL exports no symbol ",
1279                         "dll_perlmain",
1280                         "");
1281            return f(argc, argv, env);
1282        }
1283

Build FAQ

1285   Some "/" became "\" in pdksh.
1286       You have a very old pdksh. See "Prerequisites".
1287
1288   'errno' - unresolved external
1289       You do not have MT-safe db.lib. See "Prerequisites".
1290
1291   Problems with tr or sed
1292       reported with very old version of tr and sed.
1293
1294   Some problem (forget which ;-)
1295       You have an older version of perl.dll on your LIBPATH, which broke the
1296       build of extensions.
1297
1298   Library ... not found
1299       You did not run "omflibs". See "Prerequisites".
1300
1301   Segfault in make
1302       You use an old version of GNU make. See "Prerequisites".
1303
1304   op/sprintf test failure
1305       This can result from a bug in emx sprintf which was fixed in 0.9d fix
1306       03.
1307

Specific (mis)features of OS/2 port

1309   "setpriority", "getpriority"
1310       Note that these functions are compatible with *nix, not with the older
1311       ports of '94 - 95. The priorities are absolute, go from 32 to -95,
1312       lower is quicker. 0 is the default priority.
1313
1314       WARNING.  Calling "getpriority" on a non-existing process could lock
1315       the system before Warp3 fixpak22.  Starting with Warp3, Perl will use a
1316       workaround: it aborts getpriority() if the process is not present.
1317       This is not possible on older versions "2.*", and has a race condition
1318       anyway.
1319
1320   "system()"
1321       Multi-argument form of "system()" allows an additional numeric
1322       argument. The meaning of this argument is described in OS2::Process.
1323
1324       When finding a program to run, Perl first asks the OS to look for
1325       executables on "PATH" (OS/2 adds extension .exe if no extension is
1326       present).  If not found, it looks for a script with possible extensions
1327       added in this order: no extension, .cmd, .btm, .bat, .pl.  If found,
1328       Perl checks the start of the file for magic strings "#!" and "extproc
1329       ".  If found, Perl uses the rest of the first line as the beginning of
1330       the command line to run this script.  The only mangling done to the
1331       first line is extraction of arguments (currently up to 3), and ignoring
1332       of the path-part of the "interpreter" name if it can't be found using
1333       the full path.
1334
1335       E.g., "system 'foo', 'bar', 'baz'" may lead Perl to finding
1336       C:/emx/bin/foo.cmd with the first line being
1337
1338        extproc /bin/bash    -x   -c
1339
1340       If /bin/bash.exe is not found, then Perl looks for an executable
1341       bash.exe on "PATH".  If found in C:/emx.add/bin/bash.exe, then the
1342       above system() is translated to
1343
1344         system qw(C:/emx.add/bin/bash.exe -x -c C:/emx/bin/foo.cmd bar baz)
1345
1346       One additional translation is performed: instead of /bin/sh Perl uses
1347       the hardwired-or-customized shell (see ""PERL_SH_DIR"").
1348
1349       The above search for "interpreter" is recursive: if bash executable is
1350       not found, but bash.btm is found, Perl will investigate its first line
1351       etc.  The only hardwired limit on the recursion depth is implicit:
1352       there is a limit 4 on the number of additional arguments inserted
1353       before the actual arguments given to system().  In particular, if no
1354       additional arguments are specified on the "magic" first lines, then the
1355       limit on the depth is 4.
1356
1357       If Perl finds that the found executable is of PM type when the current
1358       session is not, it will start the new process in a separate session of
1359       necessary type.  Call via "OS2::Process" to disable this magic.
1360
1361       WARNING.  Due to the described logic, you need to explicitly specify
1362       .com extension if needed.  Moreover, if the executable perl5.6.1 is
1363       requested, Perl will not look for perl5.6.1.exe.  [This may change in
1364       the future.]
1365
1366   "extproc" on the first line
1367       If the first chars of a Perl script are "extproc ", this line is
1368       treated as "#!"-line, thus all the switches on this line are processed
1369       (twice if script was started via cmd.exe).  See "DESCRIPTION" in
1370       perlrun.
1371
1372   Additional modules:
1373       OS2::Process, OS2::DLL, OS2::REXX, OS2::PrfDB, OS2::ExtAttr. These
1374       modules provide access to additional numeric argument for "system" and
1375       to the information about the running process, to DLLs having functions
1376       with REXX signature and to the REXX runtime, to OS/2 databases in the
1377       .INI format, and to Extended Attributes.
1378
1379       Two additional extensions by Andreas Kaiser, "OS2::UPM", and
1380       "OS2::FTP", are included into "ILYAZ" directory, mirrored on CPAN.
1381       Other OS/2-related extensions are available too.
1382
1383   Prebuilt methods:
1384       "File::Copy::syscopy"
1385           used by "File::Copy::copy", see File::Copy.
1386
1387       "DynaLoader::mod2fname"
1388           used by "DynaLoader" for DLL name mangling.
1389
1390       "Cwd::current_drive()"
1391           Self explanatory.
1392
1393       "Cwd::sys_chdir(name)"
1394           leaves drive as it is.
1395
1396       "Cwd::change_drive(name)"
1397           changes the "current" drive.
1398
1399       "Cwd::sys_is_absolute(name)"
1400           means has drive letter and is_rooted.
1401
1402       "Cwd::sys_is_rooted(name)"
1403           means has leading "[/\\]" (maybe after a drive-letter:).
1404
1405       "Cwd::sys_is_relative(name)"
1406           means changes with current dir.
1407
1408       "Cwd::sys_cwd(name)"
1409           Interface to cwd from EMX. Used by "Cwd::cwd".
1410
1411       "Cwd::sys_abspath(name, dir)"
1412           Really really odious function to implement. Returns absolute name
1413           of file which would have "name" if CWD were "dir".  "Dir" defaults
1414           to the current dir.
1415
1416       "Cwd::extLibpath([type])"
1417           Get current value of extended library search path. If "type" is
1418           present and positive, works with "END_LIBPATH", if negative, works
1419           with "LIBPATHSTRICT", otherwise with "BEGIN_LIBPATH".
1420
1421       "Cwd::extLibpath_set( path [, type ] )"
1422           Set current value of extended library search path. If "type" is
1423           present and positive, works with <END_LIBPATH>, if negative, works
1424           with "LIBPATHSTRICT", otherwise with "BEGIN_LIBPATH".
1425
1426       "OS2::Error(do_harderror,do_exception)"
1427           Returns   "undef" if it was not called yet, otherwise bit 1 is set
1428           if on the previous call do_harderror was enabled, bit 2 is set if
1429           on previous call do_exception was enabled.
1430
1431           This function enables/disables error popups associated with
1432           hardware errors (Disk not ready etc.) and software exceptions.
1433
1434           I know of no way to find out the state of popups before the first
1435           call to this function.
1436
1437       "OS2::Errors2Drive(drive)"
1438           Returns "undef" if it was not called yet, otherwise return false if
1439           errors were not requested to be written to a hard drive, or the
1440           drive letter if this was requested.
1441
1442           This function may redirect error popups associated with hardware
1443           errors (Disk not ready etc.) and software exceptions to the file
1444           POPUPLOG.OS2 at the root directory of the specified drive.
1445           Overrides OS2::Error() specified by individual programs.  Given
1446           argument undef will disable redirection.
1447
1448           Has global effect, persists after the application exits.
1449
1450           I know of no way to find out the state of redirection of popups to
1451           the disk before the first call to this function.
1452
1453       OS2::SysInfo()
1454           Returns a hash with system information. The keys of the hash are
1455
1456                   MAX_PATH_LENGTH, MAX_TEXT_SESSIONS, MAX_PM_SESSIONS,
1457                   MAX_VDM_SESSIONS, BOOT_DRIVE, DYN_PRI_VARIATION,
1458                   MAX_WAIT, MIN_SLICE, MAX_SLICE, PAGE_SIZE,
1459                   VERSION_MAJOR, VERSION_MINOR, VERSION_REVISION,
1460                   MS_COUNT, TIME_LOW, TIME_HIGH, TOTPHYSMEM, TOTRESMEM,
1461                   TOTAVAILMEM, MAXPRMEM, MAXSHMEM, TIMER_INTERVAL,
1462                   MAX_COMP_LENGTH, FOREGROUND_FS_SESSION,
1463                   FOREGROUND_PROCESS
1464
1465       OS2::BootDrive()
1466           Returns a letter without colon.
1467
1468       "OS2::MorphPM(serve)", "OS2::UnMorphPM(serve)"
1469           Transforms the current application into a PM application and back.
1470           The argument true means that a real message loop is going to be
1471           served.  OS2::MorphPM() returns the PM message queue handle as an
1472           integer.
1473
1474           See "Centralized management of resources" for additional details.
1475
1476       "OS2::Serve_Messages(force)"
1477           Fake on-demand retrieval of outstanding PM messages.  If "force" is
1478           false, will not dispatch messages if a real message loop is known
1479           to be present.  Returns number of messages retrieved.
1480
1481           Dies with "QUITing..." if WM_QUIT message is obtained.
1482
1483       "OS2::Process_Messages(force [, cnt])"
1484           Retrieval of PM messages until window creation/destruction.  If
1485           "force" is false, will not dispatch messages if a real message loop
1486           is known to be present.
1487
1488           Returns change in number of windows.  If "cnt" is given, it is
1489           incremented by the number of messages retrieved.
1490
1491           Dies with "QUITing..." if WM_QUIT message is obtained.
1492
1493       "OS2::_control87(new,mask)"
1494           the same as _control87(3) of EMX.  Takes integers as arguments,
1495           returns the previous coprocessor control word as an integer.  Only
1496           bits in "new" which are present in "mask" are changed in the
1497           control word.
1498
1499       OS2::get_control87()
1500           gets the coprocessor control word as an integer.
1501
1502       "OS2::set_control87_em(new=MCW_EM,mask=MCW_EM)"
1503           The variant of OS2::_control87() with default values good for
1504           handling exception mask: if no "mask", uses exception mask part of
1505           "new" only.  If no "new", disables all the floating point
1506           exceptions.
1507
1508           See "Misfeatures" for details.
1509
1510       "OS2::DLLname([how [, \&xsub]])"
1511           Gives the information about the Perl DLL or the DLL containing the
1512           C function bound to by &xsub.  The meaning of "how" is: default
1513           (2): full name; 0: handle; 1: module name.
1514
1515       (Note that some of these may be moved to different libraries -
1516       eventually).
1517
1518   Prebuilt variables:
1519       $OS2::emx_rev
1520           numeric value is the same as _emx_rev of EMX, a string value the
1521           same as _emx_vprt (similar to "0.9c").
1522
1523       $OS2::emx_env
1524           same as _emx_env of EMX, a number similar to 0x8001.
1525
1526       $OS2::os_ver
1527           a number "OS_MAJOR + 0.001 * OS_MINOR".
1528
1529       $OS2::is_aout
1530           true if the Perl library was compiled in AOUT format.
1531
1532       $OS2::can_fork
1533           true if the current executable is an AOUT EMX executable, so Perl
1534           can fork.  Do not use this, use the portable check for
1535           $Config::Config{dfork}.
1536
1537       $OS2::nsyserror
1538           This variable (default is 1) controls whether to enforce the
1539           contents of $^E to start with "SYS0003"-like id.  If set to 0, then
1540           the string value of $^E is what is available from the OS/2 message
1541           file.  (Some messages in this file have an "SYS0003"-like id
1542           prepended, some not.)
1543
1544   Misfeatures
1545       ·   Since flock(3) is present in EMX, but is not functional, it is
1546           emulated by perl.  To disable the emulations, set environment
1547           variable "USE_PERL_FLOCK=0".
1548
1549       ·   Here is the list of things which may be "broken" on EMX (from EMX
1550           docs):
1551
1552           ·   The functions recvmsg(3), sendmsg(3), and socketpair(3) are not
1553               implemented.
1554
1555           ·   sock_init(3) is not required and not implemented.
1556
1557           ·   flock(3) is not yet implemented (dummy function).  (Perl has a
1558               workaround.)
1559
1560           ·   kill(3):  Special treatment of PID=0, PID=1 and PID=-1 is not
1561               implemented.
1562
1563           ·   waitpid(3):
1564
1565                     WUNTRACED
1566                             Not implemented.
1567                     waitpid() is not implemented for negative values of PID.
1568
1569           Note that "kill -9" does not work with the current version of EMX.
1570
1571       ·   See "Text-mode filehandles".
1572
1573       ·   Unix-domain sockets on OS/2 live in a pseudo-file-system
1574           "/sockets/...".  To avoid a failure to create a socket with a name
1575           of a different form, "/socket/" is prepended to the socket name
1576           (unless it starts with this already).
1577
1578           This may lead to problems later in case the socket is accessed via
1579           the "usual" file-system calls using the "initial" name.
1580
1581       ·   Apparently, IBM used a compiler (for some period of time around
1582           '95?) which changes FP mask right and left.  This is not that bad
1583           for IBM's programs, but the same compiler was used for DLLs which
1584           are used with general-purpose applications.  When these DLLs are
1585           used, the state of floating-point flags in the application is not
1586           predictable.
1587
1588           What is much worse, some DLLs change the floating point flags when
1589           in _DLLInitTerm() (e.g., TCP32IP).  This means that even if you do
1590           not call any function in the DLL, just the act of loading this DLL
1591           will reset your flags.  What is worse, the same compiler was used
1592           to compile some HOOK DLLs.  Given that HOOK dlls are executed in
1593           the context of all the applications in the system, this means a
1594           complete unpredictability of floating point flags on systems using
1595           such HOOK DLLs.  E.g., GAMESRVR.DLL of DIVE origin changes the
1596           floating point flags on each write to the TTY of a VIO (windowed
1597           text-mode) applications.
1598
1599           Some other (not completely debugged) situations when FP flags
1600           change include some video drivers (?), and some operations related
1601           to creation of the windows.  People who code OpenGL may have more
1602           experience on this.
1603
1604           Perl is generally used in the situation when all the floating-point
1605           exceptions are ignored, as is the default under EMX.  If they are
1606           not ignored, some benign Perl programs would get a "SIGFPE" and
1607           would die a horrible death.
1608
1609           To circumvent this, Perl uses two hacks.  They help against one
1610           type of damage only: FP flags changed when loading a DLL.
1611
1612           One of the hacks is to disable floating point exceptions on Perl
1613           startup (as is the default with EMX).  This helps only with
1614           compile-time-linked DLLs changing the flags before main() had a
1615           chance to be called.
1616
1617           The other hack is to restore FP flags after a call to dlopen().
1618           This helps against similar damage done by DLLs _DLLInitTerm() at
1619           runtime.  Currently no way to switch these hacks off is provided.
1620
1621   Modifications
1622       Perl modifies some standard C library calls in the following ways:
1623
1624       "popen"  "my_popen" uses sh.exe if shell is required, cf.
1625                ""PERL_SH_DIR"".
1626
1627       "tmpnam" is created using "TMP" or "TEMP" environment variable, via
1628                "tempnam".
1629
1630       "tmpfile"
1631                If the current directory is not writable, file is created
1632                using modified "tmpnam", so there may be a race condition.
1633
1634       "ctermid"
1635                a dummy implementation.
1636
1637       "stat"   "os2_stat" special-cases /dev/tty and /dev/con.
1638
1639       "mkdir", "rmdir"
1640                these EMX functions do not work if the path contains a
1641                trailing "/".  Perl contains a workaround for this.
1642
1643       "flock"  Since flock(3) is present in EMX, but is not functional, it is
1644                emulated by perl.  To disable the emulations, set environment
1645                variable "USE_PERL_FLOCK=0".
1646
1647   Identifying DLLs
1648       All the DLLs built with the current versions of Perl have ID strings
1649       identifying the name of the extension, its version, and the version of
1650       Perl required for this DLL.  Run "bldlevel DLL-name" to find this info.
1651
1652   Centralized management of resources
1653       Since to call certain OS/2 API one needs to have a correctly
1654       initialized "Win" subsystem, OS/2-specific extensions may require
1655       getting "HAB"s and "HMQ"s.  If an extension would do it on its own,
1656       another extension could fail to initialize.
1657
1658       Perl provides a centralized management of these resources:
1659
1660       "HAB"
1661           To get the HAB, the extension should call "hab = perl_hab_GET()" in
1662           C.  After this call is performed, "hab" may be accessed as
1663           "Perl_hab".  There is no need to release the HAB after it is used.
1664
1665           If by some reasons perl.h cannot be included, use
1666
1667             extern int Perl_hab_GET(void);
1668
1669           instead.
1670
1671       "HMQ"
1672           There are two cases:
1673
1674           ·   the extension needs an "HMQ" only because some API will not
1675               work otherwise.  Use "serve = 0" below.
1676
1677           ·   the extension needs an "HMQ" since it wants to engage in a PM
1678               event loop.  Use "serve = 1" below.
1679
1680           To get an "HMQ", the extension should call "hmq =
1681           perl_hmq_GET(serve)" in C.  After this call is performed, "hmq" may
1682           be accessed as "Perl_hmq".
1683
1684           To signal to Perl that HMQ is not needed any more, call
1685           "perl_hmq_UNSET(serve)".  Perl process will automatically
1686           morph/unmorph itself into/from a PM process if HMQ is
1687           needed/not-needed.  Perl will automatically enable/disable
1688           "WM_QUIT" message during shutdown if the message queue is
1689           served/not-served.
1690
1691           NOTE.  If during a shutdown there is a message queue which did not
1692           disable WM_QUIT, and which did not process the received WM_QUIT
1693           message, the shutdown will be automatically cancelled.  Do not call
1694           perl_hmq_GET(1) unless you are going to process messages on an
1695           orderly basis.
1696
1697       Treating errors reported by OS/2 API
1698           There are two principal conventions (it is useful to call them
1699           "Dos*" and "Win*" - though this part of the function signature is
1700           not always determined by the name of the API) of reporting the
1701           error conditions of OS/2 API.  Most of "Dos*" APIs report the error
1702           code as the result of the call (so 0 means success, and there are
1703           many types of errors).  Most of "Win*" API report success/fail via
1704           the result being "TRUE"/"FALSE"; to find the reason for the failure
1705           one should call WinGetLastError() API.
1706
1707           Some "Win*" entry points also overload a "meaningful" return value
1708           with the error indicator; having a 0 return value indicates an
1709           error.  Yet some other "Win*" entry points overload things even
1710           more, and 0 return value may mean a successful call returning a
1711           valid value 0, as well as an error condition; in the case of a 0
1712           return value one should call WinGetLastError() API to distinguish a
1713           successful call from a failing one.
1714
1715           By convention, all the calls to OS/2 API should indicate their
1716           failures by resetting $^E.  All the Perl-accessible functions which
1717           call OS/2 API may be broken into two classes: some die()s when an
1718           API error is encountered, the other report the error via a false
1719           return value (of course, this does not concern Perl-accessible
1720           functions which expect a failure of the OS/2 API call, having some
1721           workarounds coded).
1722
1723           Obviously, in the situation of the last type of the signature of an
1724           OS/2 API, it is must more convenient for the users if the failure
1725           is indicated by die()ing: one does not need to check $^E to know
1726           that something went wrong.  If, however, this solution is not
1727           desirable by some reason, the code in question should reset $^E to
1728           0 before making this OS/2 API call, so that the caller of this
1729           Perl-accessible function has a chance to distinguish a
1730           success-but-0-return value from a failure.  (One may return undef
1731           as an alternative way of reporting an error.)
1732
1733           The macros to simplify this type of error propagation are
1734
1735           "CheckOSError(expr)"
1736               Returns true on error, sets $^E.  Expects expr() be a call of
1737               "Dos*"-style API.
1738
1739           "CheckWinError(expr)"
1740               Returns true on error, sets $^E.  Expects expr() be a call of
1741               "Win*"-style API.
1742
1743           "SaveWinError(expr)"
1744               Returns "expr", sets $^E from WinGetLastError() if "expr" is
1745               false.
1746
1747           "SaveCroakWinError(expr,die,name1,name2)"
1748               Returns "expr", sets $^E from WinGetLastError() if "expr" is
1749               false, and die()s if "die" and $^E are true.  The message to
1750               die is the concatenated strings "name1" and "name2", separated
1751               by ": " from the contents of $^E.
1752
1753           "WinError_2_Perl_rc"
1754               Sets "Perl_rc" to the return value of WinGetLastError().
1755
1756           "FillWinError"
1757               Sets "Perl_rc" to the return value of WinGetLastError(), and
1758               sets $^E to the corresponding value.
1759
1760           "FillOSError(rc)"
1761               Sets "Perl_rc" to "rc", and sets $^E to the corresponding
1762               value.
1763
1764       Loading DLLs and ordinals in DLLs
1765           Some DLLs are only present in some versions of OS/2, or in some
1766           configurations of OS/2.  Some exported entry points are present
1767           only in DLLs shipped with some versions of OS/2.  If these DLLs and
1768           entry points were linked directly for a Perl executable/DLL or from
1769           a Perl extensions, this binary would work only with the specified
1770           versions/setups.  Even if these entry points were not needed, the
1771           load of the executable (or DLL) would fail.
1772
1773           For example, many newer useful APIs are not present in OS/2 v2;
1774           many PM-related APIs require DLLs not available on floppy-boot
1775           setup.
1776
1777           To make these calls fail only when the calls are executed, one
1778           should call these API via a dynamic linking API.  There is a
1779           subsystem in Perl to simplify such type of calls.  A large number
1780           of entry points available for such linking is provided (see
1781           "entries_ordinals" - and also "PMWIN_entries" - in os2ish.h).
1782           These ordinals can be accessed via the APIs:
1783
1784            CallORD(), DeclFuncByORD(), DeclVoidFuncByORD(),
1785            DeclOSFuncByORD(), DeclWinFuncByORD(), AssignFuncPByORD(),
1786            DeclWinFuncByORD_CACHE(), DeclWinFuncByORD_CACHE_survive(),
1787            DeclWinFuncByORD_CACHE_resetError_survive(),
1788            DeclWinFunc_CACHE(), DeclWinFunc_CACHE_resetError(),
1789            DeclWinFunc_CACHE_survive(), DeclWinFunc_CACHE_resetError_survive()
1790
1791           See the header files and the C code in the supplied OS/2-related
1792           modules for the details on usage of these functions.
1793
1794           Some of these functions also combine dynaloading semantic with the
1795           error-propagation semantic discussed above.
1796

Perl flavors

1798       Because of idiosyncrasies of OS/2 one cannot have all the eggs in the
1799       same basket (though EMX environment tries hard to overcome this
1800       limitations, so the situation may somehow improve). There are 4
1801       executables for Perl provided by the distribution:
1802
1803   perl.exe
1804       The main workhorse. This is a chimera executable: it is compiled as an
1805       "a.out"-style executable, but is linked with "omf"-style dynamic
1806       library perl.dll, and with dynamic CRT DLL. This executable is a VIO
1807       application.
1808
1809       It can load perl dynamic extensions, and it can fork().
1810
1811       Note. Keep in mind that fork() is needed to open a pipe to yourself.
1812
1813   perl_.exe
1814       This is a statically linked "a.out"-style executable. It cannot load
1815       dynamic Perl extensions. The executable supplied in binary
1816       distributions has a lot of extensions prebuilt, thus the above
1817       restriction is important only if you use custom-built extensions. This
1818       executable is a VIO application.
1819
1820       This is the only executable with does not require OS/2. The friends
1821       locked into "M$" world would appreciate the fact that this executable
1822       runs under DOS, Win0.3*, Win0.95 and WinNT with an appropriate
1823       extender. See "Other OSes".
1824
1825   perl__.exe
1826       This is the same executable as perl___.exe, but it is a PM application.
1827
1828       Note. Usually (unless explicitly redirected during the startup) STDIN,
1829       STDERR, and STDOUT of a PM application are redirected to nul. However,
1830       it is possible to see them if you start "perl__.exe" from a PM program
1831       which emulates a console window, like Shell mode of Emacs or EPM. Thus
1832       it is possible to use Perl debugger (see perldebug) to debug your PM
1833       application (but beware of the message loop lockups - this will not
1834       work if you have a message queue to serve, unless you hook the serving
1835       into the getc() function of the debugger).
1836
1837       Another way to see the output of a PM program is to run it as
1838
1839         pm_prog args 2>&1 | cat -
1840
1841       with a shell different from cmd.exe, so that it does not create a link
1842       between a VIO session and the session of "pm_porg".  (Such a link
1843       closes the VIO window.)  E.g., this works with sh.exe - or with Perl!
1844
1845         open P, 'pm_prog args 2>&1 |' or die;
1846         print while <P>;
1847
1848       The flavor perl__.exe is required if you want to start your program
1849       without a VIO window present, but not "detach"ed (run "help detach" for
1850       more info).  Very useful for extensions which use PM, like "Perl/Tk" or
1851       "OpenGL".
1852
1853       Note also that the differences between PM and VIO executables are only
1854       in the default behaviour.  One can start any executable in any kind of
1855       session by using the arguments "/fs", "/pm" or "/win" switches of the
1856       command "start" (of CMD.EXE or a similar shell).  Alternatively, one
1857       can use the numeric first argument of the "system" Perl function (see
1858       OS2::Process).
1859
1860   perl___.exe
1861       This is an "omf"-style executable which is dynamically linked to
1862       perl.dll and CRT DLL. I know no advantages of this executable over
1863       "perl.exe", but it cannot fork() at all. Well, one advantage is that
1864       the build process is not so convoluted as with "perl.exe".
1865
1866       It is a VIO application.
1867
1868   Why strange names?
1869       Since Perl processes the "#!"-line (cf.  "DESCRIPTION" in perlrun,
1870       "Command Switches" in perlrun, "No Perl script found in input" in
1871       perldiag), it should know when a program is a Perl. There is some
1872       naming convention which allows Perl to distinguish correct lines from
1873       wrong ones. The above names are almost the only names allowed by this
1874       convention which do not contain digits (which have absolutely different
1875       semantics).
1876
1877   Why dynamic linking?
1878       Well, having several executables dynamically linked to the same huge
1879       library has its advantages, but this would not substantiate the
1880       additional work to make it compile. The reason is the complicated-to-
1881       developers but very quick and convenient-to-users "hard" dynamic
1882       linking used by OS/2.
1883
1884       There are two distinctive features of the dyna-linking model of OS/2:
1885       first, all the references to external functions are resolved at the
1886       compile time; second, there is no runtime fixup of the DLLs after they
1887       are loaded into memory.  The first feature is an enormous advantage
1888       over other models: it avoids conflicts when several DLLs used by an
1889       application export entries with the same name.  In such cases "other"
1890       models of dyna-linking just choose between these two entry points using
1891       some random criterion - with predictable disasters as results.  But it
1892       is the second feature which requires the build of perl.dll.
1893
1894       The address tables of DLLs are patched only once, when they are loaded.
1895       The addresses of the entry points into DLLs are guaranteed to be the
1896       same for all the programs which use the same DLL.  This removes the
1897       runtime fixup - once DLL is loaded, its code is read-only.
1898
1899       While this allows some (significant?) performance advantages, this
1900       makes life much harder for developers, since the above scheme makes it
1901       impossible for a DLL to be "linked" to a symbol in the .EXE file.
1902       Indeed, this would need a DLL to have different relocations tables for
1903       the (different) executables which use this DLL.
1904
1905       However, a dynamically loaded Perl extension is forced to use some
1906       symbols from the perl executable, e.g., to know how to find the
1907       arguments to the functions: the arguments live on the perl internal
1908       evaluation stack. The solution is to put the main code of the
1909       interpreter into a DLL, and make the .EXE file which just loads this
1910       DLL into memory and supplies command-arguments.  The extension DLL
1911       cannot link to symbols in .EXE, but it has no problem linking to
1912       symbols in the .DLL.
1913
1914       This greatly increases the load time for the application (as well as
1915       complexity of the compilation). Since interpreter is in a DLL, the C
1916       RTL is basically forced to reside in a DLL as well (otherwise
1917       extensions would not be able to use CRT).  There are some advantages if
1918       you use different flavors of perl, such as running perl.exe and
1919       perl__.exe simultaneously: they share the memory of perl.dll.
1920
1921       NOTE.  There is one additional effect which makes DLLs more wasteful:
1922       DLLs are loaded in the shared memory region, which is a scarse resource
1923       given the 512M barrier of the "standard" OS/2 virtual memory.  The code
1924       of .EXE files is also shared by all the processes which use the
1925       particular .EXE, but they are "shared in the private address space of
1926       the process"; this is possible because the address at which different
1927       sections of the .EXE file are loaded is decided at compile-time, thus
1928       all the processes have these sections loaded at same addresses, and no
1929       fixup of internal links inside the .EXE is needed.
1930
1931       Since DLLs may be loaded at run time, to have the same mechanism for
1932       DLLs one needs to have the address range of any of the loaded DLLs in
1933       the system to be available in all the processes which did not load a
1934       particular DLL yet.  This is why the DLLs are mapped to the shared
1935       memory region.
1936
1937   Why chimera build?
1938       Current EMX environment does not allow DLLs compiled using Unixish
1939       "a.out" format to export symbols for data (or at least some types of
1940       data). This forces "omf"-style compile of perl.dll.
1941
1942       Current EMX environment does not allow .EXE files compiled in "omf"
1943       format to fork(). fork() is needed for exactly three Perl operations:
1944
1945       ·   explicit fork() in the script,
1946
1947       ·   "open FH, "|-""
1948
1949       ·   "open FH, "-|"", in other words, opening pipes to itself.
1950
1951       While these operations are not questions of life and death, they are
1952       needed for a lot of useful scripts. This forces "a.out"-style compile
1953       of perl.exe.
1954

ENVIRONMENT

1956       Here we list environment variables with are either OS/2- and DOS- and
1957       Win*-specific, or are more important under OS/2 than under other OSes.
1958
1959   "PERLLIB_PREFIX"
1960       Specific for EMX port. Should have the form
1961
1962         path1;path2
1963
1964       or
1965
1966         path1 path2
1967
1968       If the beginning of some prebuilt path matches path1, it is substituted
1969       with path2.
1970
1971       Should be used if the perl library is moved from the default location
1972       in preference to "PERL(5)LIB", since this would not leave wrong entries
1973       in @INC.  For example, if the compiled version of perl looks for @INC
1974       in f:/perllib/lib, and you want to install the library in h:/opt/gnu,
1975       do
1976
1977         set PERLLIB_PREFIX=f:/perllib/lib;h:/opt/gnu
1978
1979       This will cause Perl with the prebuilt @INC of
1980
1981         f:/perllib/lib/5.00553/os2
1982         f:/perllib/lib/5.00553
1983         f:/perllib/lib/site_perl/5.00553/os2
1984         f:/perllib/lib/site_perl/5.00553
1985         .
1986
1987       to use the following @INC:
1988
1989         h:/opt/gnu/5.00553/os2
1990         h:/opt/gnu/5.00553
1991         h:/opt/gnu/site_perl/5.00553/os2
1992         h:/opt/gnu/site_perl/5.00553
1993         .
1994
1995   "PERL_BADLANG"
1996       If 0, perl ignores setlocale() failing. May be useful with some strange
1997       locales.
1998
1999   "PERL_BADFREE"
2000       If 0, perl would not warn of in case of unwarranted free(). With older
2001       perls this might be useful in conjunction with the module DB_File,
2002       which was buggy when dynamically linked and OMF-built.
2003
2004       Should not be set with newer Perls, since this may hide some real
2005       problems.
2006
2007   "PERL_SH_DIR"
2008       Specific for EMX port. Gives the directory part of the location for
2009       sh.exe.
2010
2011   "USE_PERL_FLOCK"
2012       Specific for EMX port. Since flock(3) is present in EMX, but is not
2013       functional, it is emulated by perl.  To disable the emulations, set
2014       environment variable "USE_PERL_FLOCK=0".
2015
2016   "TMP" or "TEMP"
2017       Specific for EMX port. Used as storage place for temporary files.
2018

Evolution

2020       Here we list major changes which could make you by surprise.
2021
2022   Text-mode filehandles
2023       Starting from version 5.8, Perl uses a builtin translation layer for
2024       text-mode files.  This replaces the efficient well-tested EMX layer by
2025       some code which should be best characterized as a "quick hack".
2026
2027       In addition to possible bugs and an inability to follow changes to the
2028       translation policy with off/on switches of TERMIO translation, this
2029       introduces a serious incompatible change: before sysread() on text-mode
2030       filehandles would go through the translation layer, now it would not.
2031
2032   Priorities
2033       "setpriority" and "getpriority" are not compatible with earlier ports
2034       by Andreas Kaiser. See "setpriority, getpriority".
2035
2036   DLL name mangling: pre 5.6.2
2037       With the release 5.003_01 the dynamically loadable libraries should be
2038       rebuilt when a different version of Perl is compiled. In particular,
2039       DLLs (including perl.dll) are now created with the names which contain
2040       a checksum, thus allowing workaround for OS/2 scheme of caching DLLs.
2041
2042       It may be possible to code a simple workaround which would
2043
2044       ·   find the old DLLs looking through the old @INC;
2045
2046       ·   mangle the names according to the scheme of new perl and copy the
2047           DLLs to these names;
2048
2049       ·   edit the internal "LX" tables of DLL to reflect the change of the
2050           name (probably not needed for Perl extension DLLs, since the
2051           internally coded names are not used for "specific" DLLs, they used
2052           only for "global" DLLs).
2053
2054       ·   edit the internal "IMPORT" tables and change the name of the "old"
2055           perl????.dll to the "new" perl????.dll.
2056
2057   DLL name mangling: 5.6.2 and beyond
2058       In fact mangling of extension DLLs was done due to misunderstanding of
2059       the OS/2 dynaloading model.  OS/2 (effectively) maintains two different
2060       tables of loaded DLL:
2061
2062       Global DLLs
2063           those loaded by the base name from "LIBPATH"; including those
2064           associated at link time;
2065
2066       specific DLLs
2067           loaded by the full name.
2068
2069       When resolving a request for a global DLL, the table of already-loaded
2070       specific DLLs is (effectively) ignored; moreover, specific DLLs are
2071       always loaded from the prescribed path.
2072
2073       There is/was a minor twist which makes this scheme fragile: what to do
2074       with DLLs loaded from
2075
2076       "BEGINLIBPATH" and "ENDLIBPATH"
2077           (which depend on the process)
2078
2079       . from "LIBPATH"
2080           which effectively depends on the process (although "LIBPATH" is the
2081           same for all the processes).
2082
2083       Unless "LIBPATHSTRICT" is set to "T" (and the kernel is after
2084       2000/09/01), such DLLs are considered to be global.  When loading a
2085       global DLL it is first looked in the table of already-loaded global
2086       DLLs.  Because of this the fact that one executable loaded a DLL from
2087       "BEGINLIBPATH" and "ENDLIBPATH", or . from "LIBPATH" may affect which
2088       DLL is loaded when another executable requests a DLL with the same
2089       name.  This is the reason for version-specific mangling of the DLL name
2090       for perl DLL.
2091
2092       Since the Perl extension DLLs are always loaded with the full path,
2093       there is no need to mangle their names in a version-specific ways:
2094       their directory already reflects the corresponding version of perl, and
2095       @INC takes into account binary compatibility with older version.
2096       Starting from 5.6.2 the name mangling scheme is fixed to be the same as
2097       for Perl 5.005_53 (same as in a popular binary release).  Thus new
2098       Perls will be able to resolve the names of old extension DLLs if @INC
2099       allows finding their directories.
2100
2101       However, this still does not guarantee that these DLL may be loaded.
2102       The reason is the mangling of the name of the Perl DLL.  And since the
2103       extension DLLs link with the Perl DLL, extension DLLs for older
2104       versions would load an older Perl DLL, and would most probably segfault
2105       (since the data in this DLL is not properly initialized).
2106
2107       There is a partial workaround (which can be made complete with newer
2108       OS/2 kernels): create a forwarder DLL with the same name as the DLL of
2109       the older version of Perl, which forwards the entry points to the newer
2110       Perl's DLL.  Make this DLL accessible on (say) the "BEGINLIBPATH" of
2111       the new Perl executable.  When the new executable accesses old Perl's
2112       extension DLLs, they would request the old Perl's DLL by name, get the
2113       forwarder instead, so effectively will link with the currently running
2114       (new) Perl DLL.
2115
2116       This may break in two ways:
2117
2118       ·   Old perl executable is started when a new executable is running has
2119           loaded an extension compiled for the old executable (ouph!).  In
2120           this case the old executable will get a forwarder DLL instead of
2121           the old perl DLL, so would link with the new perl DLL.  While not
2122           directly fatal, it will behave the same as new executable.  This
2123           beats the whole purpose of explicitly starting an old executable.
2124
2125       ·   A new executable loads an extension compiled for the old executable
2126           when an old perl executable is running.  In this case the extension
2127           will not pick up the forwarder - with fatal results.
2128
2129       With support for "LIBPATHSTRICT" this may be circumvented - unless one
2130       of DLLs is started from . from "LIBPATH" (I do not know whether
2131       "LIBPATHSTRICT" affects this case).
2132
2133       REMARK.  Unless newer kernels allow . in "BEGINLIBPATH" (older do not),
2134       this mess cannot be completely cleaned.  (It turns out that as of the
2135       beginning of 2002, . is not allowed, but .\. is - and it has the same
2136       effect.)
2137
2138       REMARK.  "LIBPATHSTRICT", "BEGINLIBPATH" and "ENDLIBPATH" are not
2139       environment variables, although cmd.exe emulates them on "SET ..."
2140       lines.  From Perl they may be accessed by Cwd::extLibpath and
2141       Cwd::extLibpath_set.
2142
2143   DLL forwarder generation
2144       Assume that the old DLL is named perlE0AC.dll (as is one for 5.005_53),
2145       and the new version is 5.6.1.  Create a file perl5shim.def-leader with
2146
2147         LIBRARY 'perlE0AC' INITINSTANCE TERMINSTANCE
2148         DESCRIPTION '@#perl5-porters@perl.org:5.006001#@ Perl module for 5.00553 -> Perl 5.6.1 forwarder'
2149         CODE LOADONCALL
2150         DATA LOADONCALL NONSHARED MULTIPLE
2151         EXPORTS
2152
2153       modifying the versions/names as needed.  Run
2154
2155        perl -wnle "next if 0../EXPORTS/; print qq(  \"$1\")
2156                                                 if /\"(\w+)\"/" perl5.def >lst
2157
2158       in the Perl build directory (to make the DLL smaller replace perl5.def
2159       with the definition file for the older version of Perl if present).
2160
2161        cat perl5shim.def-leader lst >perl5shim.def
2162        gcc -Zomf -Zdll -o perlE0AC.dll perl5shim.def -s -llibperl
2163
2164       (ignore multiple "warning L4085").
2165
2166   Threading
2167       As of release 5.003_01 perl is linked to multithreaded C RTL DLL.  If
2168       perl itself is not compiled multithread-enabled, so will not be perl's
2169       malloc(). However, extensions may use multiple thread on their own
2170       risk.
2171
2172       This was needed to compile "Perl/Tk" for XFree86-OS/2 out-of-the-box,
2173       and link with DLLs for other useful libraries, which typically are
2174       compiled with "-Zmt -Zcrtdll".
2175
2176   Calls to external programs
2177       Due to a popular demand the perl external program calling has been
2178       changed wrt Andreas Kaiser's port.  If perl needs to call an external
2179       program via shell, the f:/bin/sh.exe will be called, or whatever is the
2180       override, see ""PERL_SH_DIR"".
2181
2182       Thus means that you need to get some copy of a sh.exe as well (I use
2183       one from pdksh). The path F:/bin above is set up automatically during
2184       the build to a correct value on the builder machine, but is overridable
2185       at runtime,
2186
2187       Reasons: a consensus on "perl5-porters" was that perl should use one
2188       non-overridable shell per platform. The obvious choices for OS/2 are
2189       cmd.exe and sh.exe. Having perl build itself would be impossible with
2190       cmd.exe as a shell, thus I picked up "sh.exe". This assures almost 100%
2191       compatibility with the scripts coming from *nix. As an added benefit
2192       this works as well under DOS if you use DOS-enabled port of pdksh (see
2193       "Prerequisites").
2194
2195       Disadvantages: currently sh.exe of pdksh calls external programs via
2196       fork()/exec(), and there is no functioning exec() on OS/2. exec() is
2197       emulated by EMX by an asynchronous call while the caller waits for
2198       child completion (to pretend that the "pid" did not change). This means
2199       that 1 extra copy of sh.exe is made active via fork()/exec(), which may
2200       lead to some resources taken from the system (even if we do not count
2201       extra work needed for fork()ing).
2202
2203       Note that this a lesser issue now when we do not spawn sh.exe unless
2204       needed (metachars found).
2205
2206       One can always start cmd.exe explicitly via
2207
2208         system 'cmd', '/c', 'mycmd', 'arg1', 'arg2', ...
2209
2210       If you need to use cmd.exe, and do not want to hand-edit thousands of
2211       your scripts, the long-term solution proposed on p5-p is to have a
2212       directive
2213
2214         use OS2::Cmd;
2215
2216       which will override system(), exec(), "``", and "open(,'...|')". With
2217       current perl you may override only system(), readpipe() - the explicit
2218       version of "``", and maybe exec(). The code will substitute the one-
2219       argument call to system() by "CORE::system('cmd.exe', '/c', shift)".
2220
2221       If you have some working code for "OS2::Cmd", please send it to me, I
2222       will include it into distribution. I have no need for such a module, so
2223       cannot test it.
2224
2225       For the details of the current situation with calling external
2226       programs, see "Starting OS/2 (and DOS) programs under Perl".  Set us
2227       mention a couple of features:
2228
2229       ·   External scripts may be called by their basename.  Perl will try
2230           the same extensions as when processing -S command-line switch.
2231
2232       ·   External scripts starting with "#!" or "extproc " will be executed
2233           directly, without calling the shell, by calling the program
2234           specified on the rest of the first line.
2235
2236   Memory allocation
2237       Perl uses its own malloc() under OS/2 - interpreters are usually
2238       malloc-bound for speed, but perl is not, since its malloc is lightning-
2239       fast.  Perl-memory-usage-tuned benchmarks show that Perl's malloc is 5
2240       times quicker than EMX one.  I do not have convincing data about memory
2241       footprint, but a (pretty random) benchmark showed that Perl's one is 5%
2242       better.
2243
2244       Combination of perl's malloc() and rigid DLL name resolution creates a
2245       special problem with library functions which expect their return value
2246       to be free()d by system's free(). To facilitate extensions which need
2247       to call such functions, system memory-allocation functions are still
2248       available with the prefix "emx_" added. (Currently only DLL perl has
2249       this, it should propagate to perl_.exe shortly.)
2250
2251   Threads
2252       One can build perl with thread support enabled by providing "-D
2253       usethreads" option to Configure.  Currently OS/2 support of threads is
2254       very preliminary.
2255
2256       Most notable problems:
2257
2258       "COND_WAIT"
2259           may have a race condition (but probably does not due to edge-
2260           triggered nature of OS/2 Event semaphores).  (Needs a
2261           reimplementation (in terms of chaining waiting threads, with the
2262           linked list stored in per-thread structure?)?)
2263
2264       os2.c
2265           has a couple of static variables used in OS/2-specific functions.
2266           (Need to be moved to per-thread structure, or serialized?)
2267
2268       Note that these problems should not discourage experimenting, since
2269       they have a low probability of affecting small programs.
2270

BUGS

2272       This description is not updated often (since 5.6.1?), see ./os2/Changes
2273       for more info.
2274

AUTHOR

2276       Ilya Zakharevich, cpan@ilyaz.org
2277

SEE ALSO

2279       perl(1).
2280
2281
2282
2283perl v5.30.2                      2020-03-27                        PERLOS2(1)
Impressum