1PERLOS2(1) Perl Programmers Reference Guide PERLOS2(1)
2
6 perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT.
7
9 One can read this document in the following formats:
10 man perlos2
12 view perl perlos2
13 explorer perlos2.html
14 info perlos2
15 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 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 A copy of a Win* viewer is contained in the "Just add OS/2 Warp" pack‐
24 age
25 ftp://ftp.software.ibm.com/ps/products/os2/tools/jaow/jaow.zip
27 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 Note that if you have lynx.exe or netscape.exe installed, you can fol‐
33 low WWW links from this document in .INF format. If you have EMX docs
34 installed correctly, you can follow library links (you need to have
35 "view emxbook" working by setting "EMXBOOK" environment variable as it
36 is described in EMX docs).
37
39 Target
40 The target is to make OS/2 one of the best supported platform for
42 using/building/developing Perl and Perl applications, as well as make
43 Perl the best language to use under OS/2. The secondary target is to
44 try to make this work under DOS and Win* as well (but not too hard).
45 The current state is quite close to this target. Known limitations:
47 · Some *nix programs use fork() a lot; with the mostly useful fla‐
49 vors of perl for OS/2 (there are several built simultaneously)
50 this is supported; but some flavors do not support this (e.g.,
51 when Perl is called from inside REXX). Using fork() after useing
52 dynamically loading extensions would not work with very old ver‐
53 sions of EMX.
54 · You need a separate perl executable perl__.exe (see perl__.exe) if
56 you want to use PM code in your application (as Perl/Tk or OpenGL
57 Perl modules do) without having a text-mode window present.
58 While using the standard perl.exe from a text-mode window is pos‐
60 sible too, I have seen cases when this causes degradation of the
61 system stability. Using perl__.exe avoids such a degradation.
62 · There is no simple way to access WPS objects. The only way I know
64 is via "OS2::REXX" and "SOM" extensions (see OS2::REXX, Som).
65 However, we do not have access to convenience methods of
66 Object-REXX. (Is it possible at all? I know of no Object-REXX
67 API.) The "SOM" extension (currently in alpha-text) may eventu‐
68 ally remove this shortcoming; however, due to the fact that DII is
69 not supported by the "SOM" module, using "SOM" is not as conve‐
70 nient as one would like it.
71 Please keep this list up-to-date by informing me about other items.
73 Other OSes
75 Since OS/2 port of perl uses a remarkable EMX environment, it can run
77 (and build extensions, and - possibly - be built itself) under any
78 environment which can run EMX. The current list is DOS,
79 DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT. Out of many perl flavors,
80 only one works, see "perl_.exe".
81 Note that not all features of Perl are available under these environ‐
83 ments. This depends on the features the extender - most probably RSX -
84 decided to implement.
85 Cf. Prerequisites.
87 Prerequisites
89 EMX EMX runtime is required (may be substituted by RSX). Note that it
91 is possible to make perl_.exe to run under DOS without any exter‐
92 nal support by binding emx.exe/rsx.exe to it, see emxbind. Note
93 that under DOS for best results one should use RSX runtime, which
94 has much more functions working (like "fork", "popen" and so on).
95 In fact RSX is required if there is no VCPI present. Note the RSX
96 requires DPMI. Many implementations of DPMI are known to be very
97 buggy, beware!
98 Only the latest runtime is supported, currently "0.9d fix 03".
100 Perl may run under earlier versions of EMX, but this is not
101 tested.
102 One can get different parts of EMX from, say
104 http://www.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/
106 http://powerusersbbs.com/pub/os2/dev/ [EMX+GCC Development]
107 http://hobbes.nmsu.edu/pub/os2/dev/emx/v0.9d/
108 The runtime component should have the name emxrt.zip.
110 NOTE. When using emx.exe/rsx.exe, it is enough to have them on
112 your path. One does not need to specify them explicitly (though
113 this
114 emx perl_.exe -de 0
116 will work as well.)
118 RSX To run Perl on DPMI platforms one needs RSX runtime. This is
120 needed under DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT (see
121 "Other OSes"). RSX would not work with VCPI only, as EMX would,
122 it requires DMPI.
123 Having RSX and the latest sh.exe one gets a fully functional
125 *nix-ish environment under DOS, say, "fork", `` and pipe-"open"
126 work. In fact, MakeMaker works (for static build), so one can
127 have Perl development environment under DOS.
128 One can get RSX from, say
130 ftp://ftp.cdrom.com/pub/os2/emx09c/contrib
132 ftp://ftp.uni-bielefeld.de/pub/systems/msdos/misc
133 ftp://ftp.leo.org/pub/comp/os/os2/leo/devtools/emx+gcc/contrib
134 Contact the author on "rainer@mathematik.uni-bielefeld.de".
136 The latest sh.exe with DOS hooks is available in
138 http://www.ilyaz.org/software/os2/
140 as sh_dos.zip or under similar names starting with "sh", "pdksh"
142 etc.
143 HPFS Perl does not care about file systems, but the perl library con‐
145 tains many files with long names, so to install it intact one
146 needs a file system which supports long file names.
147 Note that if you do not plan to build the perl itself, it may be
149 possible to fool EMX to truncate file names. This is not sup‐
150 ported, read EMX docs to see how to do it.
151 pdksh To start external programs with complicated command lines (like
153 with pipes in between, and/or quoting of arguments), Perl uses an
154 external shell. With EMX port such shell should be named sh.exe,
155 and located either in the wired-in-during-compile locations (usu‐
156 ally F:/bin), or in configurable location (see "PERL_SH_DIR").
157 For best results use EMX pdksh. The standard binary (5.2.14 or
159 later) runs under DOS (with RSX) as well, see
160 http://www.ilyaz.org/software/os2/
162 Starting Perl programs under OS/2 (and DOS and...)
164 Start your Perl program foo.pl with arguments "arg1 arg2 arg3" the same
166 way as on any other platform, by
167 perl foo.pl arg1 arg2 arg3
169 If you want to specify perl options "-my_opts" to the perl itself (as
171 opposed to your program), use
172 perl -my_opts foo.pl arg1 arg2 arg3
174 Alternately, if you use OS/2-ish shell, like CMD or 4os2, put the fol‐
176 lowing at the start of your perl script:
177 extproc perl -S -my_opts
179 rename your program to foo.cmd, and start it by typing
181 foo arg1 arg2 arg3
183 Note that because of stupid OS/2 limitations the full path of the perl
185 script is not available when you use "extproc", thus you are forced to
186 use "-S" perl switch, and your script should be on the "PATH". As a
187 plus side, if you know a full path to your script, you may still start
188 it with
189 perl ../../blah/foo.cmd arg1 arg2 arg3
191 (note that the argument "-my_opts" is taken care of by the "extproc"
193 line in your script, see ""extproc" on the first line").
194 To understand what the above magic does, read perl docs about "-S"
196 switch - see perlrun, and cmdref about "extproc":
197 view perl perlrun
199 man perlrun
200 view cmdref extproc
201 help extproc
202 or whatever method you prefer.
204 There are also endless possibilities to use executable extensions of
206 4os2, associations of WPS and so on... However, if you use *nixish
207 shell (like sh.exe supplied in the binary distribution), you need to
208 follow the syntax specified in "Switches" in perlrun.
209 Note that -S switch supports scripts with additional extensions .cmd,
211 .btm, .bat, .pl as well.
212 Starting OS/2 (and DOS) programs under Perl
214 This is what system() (see "system" in perlfunc), `` (see "I/O Opera‐
216 tors" in perlop), and open pipe (see "open" in perlfunc) are for.
217 (Avoid exec() (see "exec" in perlfunc) unless you know what you do).
218 Note however that to use some of these operators you need to have a sh-
220 syntax shell installed (see "Pdksh", "Frequently asked questions"), and
221 perl should be able to find it (see "PERL_SH_DIR").
222 The cases when the shell is used are:
224 1 One-argument system() (see "system" in perlfunc), exec() (see
226 "exec" in perlfunc) with redirection or shell meta-characters;
227 2 Pipe-open (see "open" in perlfunc) with the command which contains
229 redirection or shell meta-characters;
230 3 Backticks `` (see "I/O Operators" in perlop) with the command which
232 contains redirection or shell meta-characters;
233 4 If the executable called by system()/exec()/pipe-open()/`` is a
235 script with the "magic" "#!" line or "extproc" line which specifies
236 shell;
237 5 If the executable called by system()/exec()/pipe-open()/`` is a
239 script without "magic" line, and $ENV{EXECSHELL} is set to shell;
240 6 If the executable called by system()/exec()/pipe-open()/`` is not
242 found (is not this remark obsolete?);
243 7 For globbing (see "glob" in perlfunc, "I/O Operators" in perlop)
245 (obsolete? Perl uses builtin globbing nowadays...).
246 For the sake of speed for a common case, in the above algorithms back‐
248 slashes in the command name are not considered as shell metacharacters.
249 Perl starts scripts which begin with cookies "extproc" or "#!"
251 directly, without an intervention of shell. Perl uses the same algo‐
252 rithm to find the executable as pdksh: if the path on "#!" line does
253 not work, and contains "/", then the directory part of the executable
254 is ignored, and the executable is searched in . and on "PATH". To find
255 arguments for these scripts Perl uses a different algorithm than pdksh:
256 up to 3 arguments are recognized, and trailing whitespace is stripped.
257 If a script does not contain such a cooky, then to avoid calling
259 sh.exe, Perl uses the same algorithm as pdksh: if $ENV{EXECSHELL} is
260 set, the script is given as the first argument to this command, if not
261 set, then "$ENV{COMSPEC} /c" is used (or a hardwired guess if $ENV{COM‐
262 SPEC} is not set).
263 When starting scripts directly, Perl uses exactly the same algorithm as
265 for the search of script given by -S command-line option: it will look
266 in the current directory, then on components of $ENV{PATH} using the
267 following order of appended extensions: no extension, .cmd, .btm, .bat,
268 .pl.
269 Note that Perl will start to look for scripts only if OS/2 cannot start
271 the specified application, thus "system 'blah'" will not look for a
272 script if there is an executable file blah.exe anywhere on "PATH". In
273 other words, "PATH" is essentially searched twice: once by the OS for
274 an executable, then by Perl for scripts.
275 Note also that executable files on OS/2 can have an arbitrary exten‐
277 sion, but .exe will be automatically appended if no dot is present in
278 the name. The workaround is as simple as that: since blah. and blah
279 denote the same file (at list on FAT and HPFS file systems), to start
280 an executable residing in file n:/bin/blah (no extension) give an argu‐
281 ment "n:/bin/blah." (dot appended) to system().
282 Perl will start PM programs from VIO (=text-mode) Perl process in a
284 separate PM session; the opposite is not true: when you start a non-PM
285 program from a PM Perl process, Perl would not run it in a separate
286 session. If a separate session is desired, either ensure that shell
287 will be used, as in "system 'cmd /c myprog'", or start it using
288 optional arguments to system() documented in "OS2::Process" module.
289 This is considered to be a feature.
290
292 "It does not work"
293 Perl binary distributions come with a testperl.cmd script which tries
295 to detect common problems with misconfigured installations. There is a
296 pretty large chance it will discover which step of the installation you
297 managed to goof. ";-)"
298 I cannot run external programs
300 · Did you run your programs with "-w" switch? See "2 (and DOS) pro‐
302 grams under Perl" in Starting OS.
303 · Do you try to run internal shell commands, like `copy a b` (inter‐
305 nal for cmd.exe), or `glob a*b` (internal for ksh)? You need to
306 specify your shell explicitly, like `cmd /c copy a b`, since Perl
307 cannot deduce which commands are internal to your shell.
308 I cannot embed perl into my program, or use perl.dll from my program.
310 Is your program EMX-compiled with "-Zmt -Zcrtdll"?
312 Well, nowadays Perl DLL should be usable from a differently com‐
313 piled program too... If you can run Perl code from REXX scripts
314 (see OS2::REXX), then there are some other aspect of interaction
315 which are overlooked by the current hackish code to support differ‐
316 ently-compiled principal programs.
317 If everything else fails, you need to build a stand-alone DLL for
319 perl. Contact me, I did it once. Sockets would not work, as a lot
320 of other stuff.
321 Did you use ExtUtils::Embed?
323 Some time ago I had reports it does not work. Nowadays it is
324 checked in the Perl test suite, so grep ./t subdirectory of the
325 build tree (as well as *.t files in the ./lib subdirectory) to find
326 how it should be done "correctly".
327 `` and pipe-"open" do not work under DOS.
329 This may a variant of just "I cannot run external programs", or a
331 deeper problem. Basically: you need RSX (see "Prerequisites") for these
332 commands to work, and you may need a port of sh.exe which understands
333 command arguments. One of such ports is listed in "Prerequisites" under
334 RSX. Do not forget to set variable ""PERL_SH_DIR"" as well.
335 DPMI is required for RSX.
337 Cannot start "find.exe "pattern" file"
339 The whole idea of the "standard C API to start applications" is that
341 the forms "foo" and "foo" of program arguments are completely inter‐
342 changable. find breaks this paradigm;
343 find "pattern" file
345 find pattern file
346 are not equivalent; find cannot be started directly using the above
348 API. One needs a way to surround the doublequotes in some other quot‐
349 ing construction, necessarily having an extra non-Unixish shell in
350 between.
351 Use one of
353 system 'cmd', '/c', 'find "pattern" file';
355 `cmd /c 'find "pattern" file'`
356 This would start find.exe via cmd.exe via "sh.exe" via "perl.exe", but
358 this is a price to pay if you want to use non-conforming program.
359
361 Automatic binary installation
362 The most convenient way of installing a binary distribution of perl is
364 via perl installer install.exe. Just follow the instructions, and 99%
365 of the installation blues would go away.
366 Note however, that you need to have unzip.exe on your path, and EMX
368 environment running. The latter means that if you just installed EMX,
369 and made all the needed changes to Config.sys, you may need to reboot
370 in between. Check EMX runtime by running
371 emxrev
373 Binary installer also creates a folder on your desktop with some useful
375 objects. If you need to change some aspects of the work of the binary
376 installer, feel free to edit the file Perl.pkg. This may be useful
377 e.g., if you need to run the installer many times and do not want to
378 make many interactive changes in the GUI.
379 Things not taken care of by automatic binary installation:
381 "PERL_BADLANG" may be needed if you change your codepage after perl
383 installation, and the new value is not supported by EMX.
384 See "PERL_BADLANG".
385 "PERL_BADFREE" see "PERL_BADFREE".
387 Config.pm This file resides somewhere deep in the location you
389 installed your perl library, find it out by
390 perl -MConfig -le "print $INC{'Config.pm'}"
392 While most important values in this file are updated by
394 the binary installer, some of them may need to be
395 hand-edited. I know no such data, please keep me
396 informed if you find one. Moreover, manual changes to
397 the installed version may need to be accompanied by an
398 edit of this file.
399 NOTE. Because of a typo the binary installer of 5.00305 would install a
401 variable "PERL_SHPATH" into Config.sys. Please remove this variable and
402 put "PERL_SH_DIR" instead.
403 Manual binary installation
405 As of version 5.00305, OS/2 perl binary distribution comes split into
407 11 components. Unfortunately, to enable configurable binary installa‐
408 tion, the file paths in the zip files are not absolute, but relative to
409 some directory.
410 Note that the extraction with the stored paths is still necessary
412 (default with unzip, specify "-d" to pkunzip). However, you need to
413 know where to extract the files. You need also to manually change
414 entries in Config.sys to reflect where did you put the files. Note that
415 if you have some primitive unzipper (like "pkunzip"), you may get a lot
416 of warnings/errors during unzipping. Upgrade to "(w)unzip".
417 Below is the sample of what to do to reproduce the configuration on my
419 machine. In VIEW.EXE you can press "Ctrl-Insert" now, and cut-and-
420 paste from the resulting file - created in the directory you started
421 VIEW.EXE from.
422 For each component, we mention environment variables related to each
424 installation directory. Either choose directories to match your values
425 of the variables, or create/append-to variables to take into account
426 the directories.
427 Perl VIO and PM executables (dynamically linked)
429 unzip perl_exc.zip *.exe *.ico -d f:/emx.add/bin
430 unzip perl_exc.zip *.dll -d f:/emx.add/dll
431 (have the directories with "*.exe" on PATH, and "*.dll" on LIBPATH);
433 Perl_ VIO executable (statically linked)
435 unzip perl_aou.zip -d f:/emx.add/bin
436 (have the directory on PATH);
438 Executables for Perl utilities
440 unzip perl_utl.zip -d f:/emx.add/bin
441 (have the directory on PATH);
443 Main Perl library
445 unzip perl_mlb.zip -d f:/perllib/lib
446 If this directory is exactly the same as the prefix which was com‐
448 piled into perl.exe, you do not need to change anything. However,
449 for perl to find the library if you use a different path, you need
450 to "set PERLLIB_PREFIX" in Config.sys, see "PERLLIB_PREFIX".
451 Additional Perl modules
453 unzip perl_ste.zip -d f:/perllib/lib/site_perl/5.8.8/
454 Same remark as above applies. Additionally, if this directory is
456 not one of directories on @INC (and @INC is influenced by "PERL‐
457 LIB_PREFIX"), you need to put this directory and subdirectory ./os2
458 in "PERLLIB" or "PERL5LIB" variable. Do not use "PERL5LIB" unless
459 you have it set already. See "ENVIRONMENT" in perl.
460 [Check whether this extraction directory is still applicable with
462 the new directory structure layout!]
463 Tools to compile Perl modules
465 unzip perl_blb.zip -d f:/perllib/lib
466 Same remark as for perl_ste.zip.
468 Manpages for Perl and utilities
470 unzip perl_man.zip -d f:/perllib/man
471 This directory should better be on "MANPATH". You need to have a
473 working man to access these files.
474 Manpages for Perl modules
476 unzip perl_mam.zip -d f:/perllib/man
477 This directory should better be on "MANPATH". You need to have a
479 working man to access these files.
480 Source for Perl documentation
482 unzip perl_pod.zip -d f:/perllib/lib
483 This is used by the "perldoc" program (see perldoc), and may be used
485 to generate HTML documentation usable by WWW browsers, and documen‐
486 tation in zillions of other formats: "info", "LaTeX", "Acrobat",
487 "FrameMaker" and so on. [Use programs such as pod2latex etc.]
488 Perl manual in .INF format
490 unzip perl_inf.zip -d d:/os2/book
491 This directory should better be on "BOOKSHELF".
493 Pdksh
495 unzip perl_sh.zip -d f:/bin
496 This is used by perl to run external commands which explicitly
498 require shell, like the commands using redirection and shell
499 metacharacters. It is also used instead of explicit /bin/sh.
500 Set "PERL_SH_DIR" (see "PERL_SH_DIR") if you move sh.exe from the
502 above location.
503 Note. It may be possible to use some other sh-compatible shell
505 (untested).
506 After you installed the components you needed and updated the Con‐
508 fig.sys correspondingly, you need to hand-edit Config.pm. This file
509 resides somewhere deep in the location you installed your perl library,
510 find it out by
511 perl -MConfig -le "print $INC{'Config.pm'}"
513 You need to correct all the entries which look like file paths (they
515 currently start with "f:/").
516 Warning
518 The automatic and manual perl installation leave precompiled paths
520 inside perl executables. While these paths are overwriteable (see "PER‐
521 LLIB_PREFIX", "PERL_SH_DIR"), some people may prefer binary editing of
522 paths inside the executables/DLLs.
523
525 Depending on how you built/installed perl you may have (otherwise iden‐
526 tical) Perl documentation in the following formats:
527 OS/2 .INF file
529 Most probably the most convenient form. Under OS/2 view it as
531 view perl
533 view perl perlfunc
534 view perl less
535 view perl ExtUtils::MakeMaker
536 (currently the last two may hit a wrong location, but this may improve
538 soon). Under Win* see "SYNOPSIS".
539 If you want to build the docs yourself, and have OS/2 toolkit, run
541 pod2ipf > perl.ipf
543 in /perllib/lib/pod directory, then
545 ipfc /inf perl.ipf
547 (Expect a lot of errors during the both steps.) Now move it on your
549 BOOKSHELF path.
550 Plain text
552 If you have perl documentation in the source form, perl utilities
554 installed, and GNU groff installed, you may use
555 perldoc perlfunc
557 perldoc less
558 perldoc ExtUtils::MakeMaker
559 to access the perl documentation in the text form (note that you may
561 get better results using perl manpages).
562 Alternately, try running pod2text on .pod files.
564 Manpages
566 If you have man installed on your system, and you installed perl man‐
568 pages, use something like this:
569 man perlfunc
571 man 3 less
572 man ExtUtils.MakeMaker
573 to access documentation for different components of Perl. Start with
575 man perl
577 Note that dot (.) is used as a package separator for documentation for
579 packages, and as usual, sometimes you need to give the section - 3
580 above - to avoid shadowing by the less(1) manpage.
581 Make sure that the directory above the directory with manpages is on
583 our "MANPATH", like this
584 set MANPATH=c:/man;f:/perllib/man
586 for Perl manpages in "f:/perllib/man/man1/" etc.
588 HTML
590 If you have some WWW browser available, installed the Perl documenta‐
592 tion in the source form, and Perl utilities, you can build HTML docs.
593 Cd to directory with .pod files, and do like this
594 cd f:/perllib/lib/pod
596 pod2html
597 After this you can direct your browser the file perl.html in this
599 directory, and go ahead with reading docs, like this:
600 explore file:///f:/perllib/lib/pod/perl.html
602 Alternatively you may be able to get these docs prebuilt from CPAN.
604 GNU "info" files
606 Users of Emacs would appreciate it very much, especially with "CPerl"
608 mode loaded. You need to get latest "pod2texi" from "CPAN", or, alter‐
609 nately, the prebuilt info pages.
610 PDF files
612 for "Acrobat" are available on CPAN (may be for slightly older version
614 of perl).
615 "LaTeX" docs
617 can be constructed using "pod2latex".
619
621 Here we discuss how to build Perl under OS/2. There is an alternative
622 (but maybe older) view on <http://www.shadow.net/~troc/os2perl.html>.
623 The short story
625 Assume that you are a seasoned porter, so are sure that all the neces‐
627 sary tools are already present on your system, and you know how to get
628 the Perl source distribution. Untar it, change to the extract direc‐
629 tory, and
630 gnupatch -p0 < os2\diff.configure
632 sh Configure -des -D prefix=f:/perllib
633 make
634 make test
635 make install
636 make aout_test
637 make aout_install
638 This puts the executables in f:/perllib/bin. Manually move them to the
640 "PATH", manually move the built perl*.dll to "LIBPATH" (here for Perl
641 DLL * is a not-very-meaningful hex checksum), and run
642 make installcmd INSTALLCMDDIR=d:/ir/on/path
644 Assuming that the "man"-files were put on an appropriate location, this
646 completes the installation of minimal Perl system. (The binary distri‐
647 bution contains also a lot of additional modules, and the documentation
648 in INF format.)
649 What follows is a detailed guide through these steps.
651 Prerequisites
653 You need to have the latest EMX development environment, the full GNU
655 tool suite (gawk renamed to awk, and GNU find.exe earlier on path than
656 the OS/2 find.exe, same with sort.exe, to check use
657 find --version
659 sort --version
660 ). You need the latest version of pdksh installed as sh.exe.
662 Check that you have BSD libraries and headers installed, and - option‐
664 ally - Berkeley DB headers and libraries, and crypt.
665 Possible locations to get the files:
667 ftp://hobbes.nmsu.edu/os2/unix/
669 ftp://ftp.cdrom.com/pub/os2/unix/
670 ftp://ftp.cdrom.com/pub/os2/dev32/
671 ftp://ftp.cdrom.com/pub/os2/emx09c/
672 It is reported that the following archives contain enough utils to
674 build perl: gnufutil.zip, gnusutil.zip, gnututil.zip, gnused.zip, gnu‐
675 patch.zip, gnuawk.zip, gnumake.zip, gnugrep.zip, bsddev.zip and
676 ksh527rt.zip (or a later version). Note that all these utilities are
677 known to be available from LEO:
678 ftp://ftp.leo.org/pub/comp/os/os2/leo/gnu
680 Note also that the db.lib and db.a from the EMX distribution are not
682 suitable for multi-threaded compile (even single-threaded flavor of
683 Perl uses multi-threaded C RTL, for compatibility with XFree86-OS/2).
684 Get a corrected one from
685 http://www.ilyaz.org/software/os2/db_mt.zip
687 If you have exactly the same version of Perl installed already, make
689 sure that no copies or perl are currently running. Later steps of the
690 build may fail since an older version of perl.dll loaded into memory
691 may be found. Running "make test" becomes meaningless, since the test
692 are checking a previous build of perl (this situation is detected and
693 reported by lib/os2_base.t test). Do not forget to unset
694 "PERL_EMXLOAD_SEC" in environment.
695 Also make sure that you have /tmp directory on the current drive, and .
697 directory in your "LIBPATH". One may try to correct the latter condi‐
698 tion by
699 set BEGINLIBPATH .\.
701 if you use something like CMD.EXE or latest versions of 4os2.exe.
703 (Setting BEGINLIBPATH to just "." is ignored by the OS/2 kernel.)
704 Make sure your gcc is good for "-Zomf" linking: run "omflibs" script in
706 /emx/lib directory.
707 Check that you have link386 installed. It comes standard with OS/2, but
709 may be not installed due to customization. If typing
710 link386
712 shows you do not have it, do Selective install, and choose "Link object
714 modules" in Optional system utilities/More. If you get into link386
715 prompts, press "Ctrl-C" to exit.
716 Getting perl source
718 You need to fetch the latest perl source (including developers
720 releases). With some probability it is located in
721 http://www.cpan.org/src/5.0
723 http://www.cpan.org/src/5.0/unsupported
724 If not, you may need to dig in the indices to find it in the directory
726 of the current maintainer.
727 Quick cycle of developers release may break the OS/2 build time to
729 time, looking into
730 http://www.cpan.org/ports/os2/
732 may indicate the latest release which was publicly released by the
734 maintainer. Note that the release may include some additional patches
735 to apply to the current source of perl.
736 Extract it like this
738 tar vzxf perl5.00409.tar.gz
740 You may see a message about errors while extracting Configure. This is
742 because there is a conflict with a similarly-named file configure.
743 Change to the directory of extraction.
745 Application of the patches
747 You need to apply the patches in ./os2/diff.* like this:
749 gnupatch -p0 < os2\diff.configure
751 You may also need to apply the patches supplied with the binary distri‐
753 bution of perl. It also makes sense to look on the perl5-porters mail‐
754 ing list for the latest OS/2-related patches (see
755 <http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/>). Such
756 patches usually contain strings "/os2/" and "patch", so it makes sense
757 looking for these strings.
758 Hand-editing
760 You may look into the file ./hints/os2.sh and correct anything wrong
762 you find there. I do not expect it is needed anywhere.
763 Making
765 sh Configure -des -D prefix=f:/perllib
767 "prefix" means: where to install the resulting perl library. Giving
769 correct prefix you may avoid the need to specify "PERLLIB_PREFIX", see
770 "PERLLIB_PREFIX".
771 Ignore the message about missing "ln", and about "-c" option to tr. The
773 latter is most probably already fixed, if you see it and can trace
774 where the latter spurious warning comes from, please inform me.
775 Now
777 make
779 At some moment the built may die, reporting a version mismatch or
781 unable to run perl. This means that you do not have . in your LIBPATH,
782 so perl.exe cannot find the needed perl67B2.dll (treat these hex digits
783 as line noise). After this is fixed the build should finish without a
784 lot of fuss.
785 Testing
787 Now run
789 make test
791 All tests should succeed (with some of them skipped). If you have the
793 same version of Perl installed, it is crucial that you have "." early
794 in your LIBPATH (or in BEGINLIBPATH), otherwise your tests will most
795 probably test the wrong version of Perl.
796 Some tests may generate extra messages similar to
798 A lot of "bad free"
800 in database tests related to Berkeley DB. This should be fixed
801 already. If it persists, you may disable this warnings, see
802 "PERL_BADFREE".
803 Process terminated by SIGTERM/SIGINT
805 This is a standard message issued by OS/2 applications. *nix appli‐
806 cations die in silence. It is considered to be a feature. One can
807 easily disable this by appropriate sighandlers.
808 However the test engine bleeds these message to screen in unex‐
810 pected moments. Two messages of this kind should be present during
811 testing.
812 To get finer test reports, call
814 perl t/harness
816 The report with io/pipe.t failing may look like this:
818 Failed Test Status Wstat Total Fail Failed List of failed
820 ------------------------------------------------------------
821 io/pipe.t 12 1 8.33% 9
822 7 tests skipped, plus 56 subtests skipped.
823 Failed 1/195 test scripts, 99.49% okay. 1/6542 subtests failed, 99.98% okay.
824 The reasons for most important skipped tests are:
826 op/fs.t
828 18 Checks "atime" and "mtime" of "stat()" - unfortunately,
829 HPFS provides only 2sec time granularity (for compatibility
830 with FAT?).
831 25 Checks "truncate()" on a filehandle just opened for write -
833 I do not know why this should or should not work.
834 op/stat.t
836 Checks "stat()". Tests:
837 4 Checks "atime" and "mtime" of "stat()" - unfortunately,
839 HPFS provides only 2sec time granularity (for compatibility
840 with FAT?).
841 Installing the built perl
843 If you haven't yet moved "perl*.dll" onto LIBPATH, do it now.
845 Run
847 make install
849 It would put the generated files into needed locations. Manually put
851 perl.exe, perl__.exe and perl___.exe to a location on your PATH,
852 perl.dll to a location on your LIBPATH.
853 Run
855 make installcmd INSTALLCMDDIR=d:/ir/on/path
857 to convert perl utilities to .cmd files and put them on PATH. You need
859 to put .EXE-utilities on path manually. They are installed in "$pre‐
860 fix/bin", here $prefix is what you gave to Configure, see Making.
861 If you use "man", either move the installed */man/ directories to your
863 "MANPATH", or modify "MANPATH" to match the location. (One could have
864 avoided this by providing a correct "manpath" option to ./Configure, or
865 editing ./config.sh between configuring and making steps.)
866 "a.out"-style build
868 Proceed as above, but make perl_.exe (see "perl_.exe") by
870 make perl_
872 test and install by
874 make aout_test
876 make aout_install
877 Manually put perl_.exe to a location on your PATH.
879 Note. The build process for "perl_" does not know about all the depen‐
881 dencies, so you should make sure that anything is up-to-date, say, by
882 doing
883 make perl_dll
885 first.
887
889 [This section provides a short overview only...]
890 Building should proceed differently depending on whether the version of
892 perl you install is already present and used on your system, or is a
893 new version not yet used. The description below assumes that the ver‐
894 sion is new, so installing its DLLs and .pm files will not disrupt the
895 operation of your system even if some intermediate steps are not yet
896 fully working.
897 The other cases require a little bit more convoluted procedures. Below
899 I suppose that the current version of Perl is 5.8.2, so the executables
900 are named accordingly.
901 1. Fully build and test the Perl distribution. Make sure that no
903 tests are failing with "test" and "aout_test" targets; fix the bugs
904 in Perl and the Perl test suite detected by these tests. Make sure
905 that "all_test" make target runs as clean as possible. Check that
906 "os2/perlrexx.cmd" runs fine.
907 2. Fully install Perl, including "installcmd" target. Copy the gener‐
909 ated DLLs to "LIBPATH"; copy the numbered Perl executables (as in
910 perl5.8.2.exe) to "PATH"; copy "perl_.exe" to "PATH" as
911 "perl_5.8.2.exe". Think whether you need backward-compatibility
912 DLLs. In most cases you do not need to install them yet; but some‐
913 time this may simplify the following steps.
914 3. Make sure that "CPAN.pm" can download files from CPAN. If not, you
916 may need to manually install "Net::FTP".
917 4. Install the bundle "Bundle::OS2_default"
919 perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul ⎪& tee 00cpan_i_1
921 This may take a couple of hours on 1GHz processor (when run the
923 first time). And this should not be necessarily a smooth proce‐
924 dure. Some modules may not specify required dependencies, so one
925 may need to repeat this procedure several times until the results
926 stabilize.
927 perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul ⎪& tee 00cpan_i_2
929 perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul ⎪& tee 00cpan_i_3
930 Even after they stabilize, some tests may fail.
932 Fix as many discovered bugs as possible. Document all the bugs
934 which are not fixed, and all the failures with unknown reasons.
935 Inspect the produced logs 00cpan_i_1 to find suspiciously skipped
936 tests, and other fishy events.
937 Keep in mind that installation of some modules may fail too: for
939 example, the DLLs to update may be already loaded by CPAN.pm.
940 Inspect the "install" logs (in the example above 00cpan_i_1 etc)
941 for errors, and install things manually, as in
942 cd $CPANHOME/.cpan/build/Digest-MD5-2.31
944 make install
945 Some distributions may fail some tests, but you may want to install
947 them anyway (as above, or via "force install" command of "CPAN.pm"
948 shell-mode).
949 Since this procedure may take quite a long time to complete, it
951 makes sense to "freeze" your CPAN configuration by disabling peri‐
952 odic updates of the local copy of CPAN index: set "index_expire" to
953 some big value (I use 365), then save the settings
954 CPAN> o conf index_expire 365
956 CPAN> o conf commit
957 Reset back to the default value 1 when you are finished.
959 5. When satisfied with the results, rerun the "installcmd" target.
961 Now you can copy "perl5.8.2.exe" to "perl.exe", and install the
962 other OMF-build executables: "perl__.exe" etc. They are ready to
963 be used.
964 6. Change to the "./pod" directory of the build tree, download the
966 Perl logo CamelGrayBig.BMP, and run
967 ( perl2ipf > perl.ipf ) ⎪& tee 00ipf
969 ipfc /INF perl.ipf ⎪& tee 00inf
970 This produces the Perl docs online book "perl.INF". Install in on
972 "BOOKSHELF" path.
973 7. Now is the time to build statically linked executable perl_.exe
975 which includes newly-installed via "Bundle::OS2_default" modules.
976 Doing testing via "CPAN.pm" is going to be painfully slow, since it
977 statically links a new executable per XS extension.
978 Here is a possible workaround: create a toplevel Makefile.PL in
980 $CPANHOME/.cpan/build/ with contents being (compare with "Making
981 executables with a custom collection of statically loaded exten‐
982 sions")
983 use ExtUtils::MakeMaker;
985 WriteMakefile NAME => 'dummy';
986 execute this as
988 perl_5.8.2.exe Makefile.PL <nul ⎪& tee 00aout_c1
990 make -k all test <nul ⎪& 00aout_t1
991 Again, this procedure should not be absolutely smooth. Some "Make‐
993 file.PL"'s in subdirectories may be buggy, and would not run as
994 "child" scripts. The interdependency of modules can strike you;
995 however, since non-XS modules are already installed, the prerequi‐
996 sites of most modules have a very good chance to be present.
997 If you discover some glitches, move directories of problematic mod‐
999 ules to a different location; if these modules are non-XS modules,
1000 you may just ignore them - they are already installed; the remain‐
1001 ing, XS, modules you need to install manually one by one.
1002 After each such removal you need to rerun the "Makefile.PL"/"make"
1004 process; usually this procedure converges soon. (But be sure to
1005 convert all the necessary external C libraries from .lib format to
1006 .a format: run one of
1007 emxaout foo.lib
1009 emximp -o foo.a foo.lib
1010 whichever is appropriate.) Also, make sure that the DLLs for
1012 external libraries are usable with with executables compiled with‐
1013 out "-Zmtd" options.
1014 When you are sure that only a few subdirectories lead to failures,
1016 you may want to add "-j4" option to "make" to speed up skipping
1017 subdirectories with already finished build.
1018 When you are satisfied with the results of tests, install the build
1020 C libraries for extensions:
1021 make install ⎪& tee 00aout_i
1023 Now you can rename the file ./perl.exe generated during the last
1025 phase to perl_5.8.2.exe; place it on "PATH"; if there is an inter-
1026 dependency between some XS modules, you may need to repeat the
1027 "test"/"install" loop with this new executable and some excluded
1028 modules - until the procedure converges.
1029 Now you have all the necessary .a libraries for these Perl modules
1031 in the places where Perl builder can find it. Use the perl
1032 builder: change to an empty directory, create a "dummy" Makefile.PL
1033 again, and run
1034 perl_5.8.2.exe Makefile.PL ⎪& tee 00c
1036 make perl ⎪& tee 00p
1037 This should create an executable ./perl.exe with all the statically
1039 loaded extensions built in. Compare the generated perlmain.c files
1040 to make sure that during the iterations the number of loaded exten‐
1041 sions only increases. Rename ./perl.exe to perl_5.8.2.exe on
1042 "PATH".
1043 When it converges, you got a functional variant of perl_5.8.2.exe;
1045 copy it to "perl_.exe". You are done with generation of the local
1046 Perl installation.
1047 8. Make sure that the installed modules are actually installed in the
1049 location of the new Perl, and are not inherited from entries of
1050 @INC given for inheritance from the older versions of Perl: set
1051 "PERLLIB_582_PREFIX" to redirect the new version of Perl to a new
1052 location, and copy the installed files to this new location. Redo
1053 the tests to make sure that the versions of modules inherited from
1054 older versions of Perl are not needed.
1055 Actually, the log output of pod2ipf during the step 6 gives a very
1057 detailed info about which modules are loaded from which place; so
1058 you may use it as an additional verification tool.
1059 Check that some temporary files did not make into the perl install
1061 tree. Run something like this
1062 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
1064 in the install tree (both top one and sitelib one).
1066 Compress all the DLLs with lxlite. The tiny .exe can be compressed
1068 with "/c:max" (the bug only appears when there is a fixup in the
1069 last 6 bytes of a page (?); since the tiny executables are much
1070 smaller than a page, the bug will not hit). Do not compress
1071 "perl_.exe" - it would not work under DOS.
1072 9. Now you can generate the binary distribution. This is done by run‐
1074 ning the test of the CPAN distribution "OS2::SoftInstaller". Tune
1075 up the file test.pl to suit the layout of current version of Perl
1076 first. Do not forget to pack the necessary external DLLs accord‐
1077 ingly. Include the description of the bugs and test suite failures
1078 you could not fix. Include the small-stack versions of Perl exe‐
1079 cutables from Perl build directory.
1080 Include perl5.def so that people can relink the perl DLL preserving
1082 the binary compatibility, or can create compatibility DLLs.
1083 Include the diff files ("diff -pu old new") of fixes you did so
1084 that people can rebuild your version. Include perl5.map so that
1085 one can use remote debugging.
1086 10. Share what you did with the other people. Relax. Enjoy fruits of
1088 your work.
1089 11. Brace yourself for thanks, bug reports, hate mail and spam coming
1091 as result of the previous step. No good deed should remain unpun‐
1092 ished!
1093
1095 The Perl executables can be easily rebuilt at any moment. Moreover,
1096 one can use the embedding interface (see perlembed) to make very cus‐
1097 tomized executables.
1098 Making executables with a custom collection of statically loaded exten‐
1100 sions
1101 It is a little bit easier to do so while decreasing the list of stati‐
1103 cally loaded extensions. We discuss this case only here.
1104 1. Change to an empty directory, and create a placeholder <Make‐
1106 file.PL>:
1107 use ExtUtils::MakeMaker;
1109 WriteMakefile NAME => 'dummy';
1110 2. Run it with the flavor of Perl (perl.exe or perl_.exe) you want to
1112 rebuild.
1113 perl_ Makefile.PL
1115 3. Ask it to create new Perl executable:
1117 make perl
1119 (you may need to manually add "PERLTYPE=-DPERL_CORE" to this com‐
1121 mandline on some versions of Perl; the symptom is that the command-
1122 line globbing does not work from OS/2 shells with the newly-com‐
1123 piled executable; check with
1124 .\perl.exe -wle "print for @ARGV" *
1126 ).
1128 4. The previous step created perlmain.c which contains a list of
1130 newXS() calls near the end. Removing unnecessary calls, and rerun‐
1131 ning
1132 make perl
1134 will produce a customized executable.
1136 Making executables with a custom search-paths
1138 The default perl executable is flexible enough to support most usages.
1140 However, one may want something yet more flexible; for example, one may
1141 want to find Perl DLL relatively to the location of the EXE file; or
1142 one may want to ignore the environment when setting the Perl-library
1143 search patch, etc.
1144 If you fill comfortable with embedding interface (see perlembed), such
1146 things are easy to do repeating the steps outlined in "Making executa‐
1147 bles with a custom collection of statically loaded extensions", and
1148 doing more comprehensive edits to main() of perlmain.c. The people
1149 with little desire to understand Perl can just rename main(), and do
1150 necessary modification in a custom main() which calls the renamed func‐
1151 tion in appropriate time.
1152 However, there is a third way: perl DLL exports the main() function and
1154 several callbacks to customize the search path. Below is a complete
1155 example of a "Perl loader" which
1156 1. Looks for Perl DLL in the directory "$exedir/../dll";
1158 2. Prepends the above directory to "BEGINLIBPATH";
1160 3. Fails if the Perl DLL found via "BEGINLIBPATH" is different from
1162 what was loaded on step 1; e.g., another process could have loaded
1163 it from "LIBPATH" or from a different value of "BEGINLIBPATH". In
1164 these cases one needs to modify the setting of the system so that
1165 this other process either does not run, or loads the DLL from
1166 "BEGINLIBPATH" with "LIBPATHSTRICT=T" (available with kernels after
1167 September 2000).
1168 4. Loads Perl library from "$exedir/../dll/lib/".
1170 5. Uses Bourne shell from "$exedir/../dll/sh/ksh.exe".
1172 For best results compile the C file below with the same options as the
1174 Perl DLL. However, a lot of functionality will work even if the exe‐
1175 cutable is not an EMX applications, e.g., if compiled with
1176 gcc -Wall -DDOSISH -DOS2=1 -O2 -s -Zomf -Zsys perl-starter.c -DPERL_DLL_BASENAME=\"perl312F\" -Zstack 8192 -Zlinker /PM:VIO
1178 Here is the sample C file:
1180 #define INCL_DOS
1182 #define INCL_NOPM
1183 /* These are needed for compile if os2.h includes os2tk.h, not os2emx.h */
1184 #define INCL_DOSPROCESS
1185 #include <os2.h>
1186 #include "EXTERN.h"
1188 #define PERL_IN_MINIPERLMAIN_C
1189 #include "perl.h"
1190 static char *me;
1192 HMODULE handle;
1193 static void
1195 die_with(char *msg1, char *msg2, char *msg3, char *msg4)
1196 {
1197 ULONG c;
1198 char *s = " error: ";
1199 DosWrite(2, me, strlen(me), &c);
1201 DosWrite(2, s, strlen(s), &c);
1202 DosWrite(2, msg1, strlen(msg1), &c);
1203 DosWrite(2, msg2, strlen(msg2), &c);
1204 DosWrite(2, msg3, strlen(msg3), &c);
1205 DosWrite(2, msg4, strlen(msg4), &c);
1206 DosWrite(2, "\r\n", 2, &c);
1207 exit(255);
1208 }
1209 typedef ULONG (*fill_extLibpath_t)(int type, char *pre, char *post, int replace, char *msg);
1211 typedef int (*main_t)(int type, char *argv[], char *env[]);
1212 typedef int (*handler_t)(void* data, int which);
1213 #ifndef PERL_DLL_BASENAME
1215 # define PERL_DLL_BASENAME "perl"
1216 #endif
1217 static HMODULE
1219 load_perl_dll(char *basename)
1220 {
1221 char buf[300], fail[260];
1222 STRLEN l, dirl;
1223 fill_extLibpath_t f;
1224 ULONG rc_fullname;
1225 HMODULE handle, handle1;
1226 if (_execname(buf, sizeof(buf) - 13) != 0)
1228 die_with("Can't find full path: ", strerror(errno), "", "");
1229 /* XXXX Fill `me' with new value */
1230 l = strlen(buf);
1231 while (l && buf[l-1] != '/' && buf[l-1] != '\\')
1232 l--;
1233 dirl = l - 1;
1234 strcpy(buf + l, basename);
1235 l += strlen(basename);
1236 strcpy(buf + l, ".dll");
1237 if ( (rc_fullname = DosLoadModule(fail, sizeof fail, buf, &handle)) != 0
1238 && DosLoadModule(fail, sizeof fail, basename, &handle) != 0 )
1239 die_with("Can't load DLL ", buf, "", "");
1240 if (rc_fullname)
1241 return handle; /* was loaded with short name; all is fine */
1242 if (DosQueryProcAddr(handle, 0, "fill_extLibpath", (PFN*)&f))
1243 die_with(buf, ": DLL exports no symbol ", "fill_extLibpath", "");
1244 buf[dirl] = 0;
1245 if (f(0 /*BEGINLIBPATH*/, buf /* prepend */, NULL /* append */,
1246 0 /* keep old value */, me))
1247 die_with(me, ": prepending BEGINLIBPATH", "", "");
1248 if (DosLoadModule(fail, sizeof fail, basename, &handle1) != 0)
1249 die_with(me, ": finding perl DLL again via BEGINLIBPATH", "", "");
1250 buf[dirl] = '\\';
1251 if (handle1 != handle) {
1252 if (DosQueryModuleName(handle1, sizeof(fail), fail))
1253 strcpy(fail, "???");
1254 die_with(buf, ":\n\tperl DLL via BEGINLIBPATH is different: \n\t",
1255 fail,
1256 "\n\tYou may need to manipulate global BEGINLIBPATH and LIBPATHSTRICT"
1257 "\n\tso that the other copy is loaded via BEGINLIBPATH.");
1258 }
1259 return handle;
1260 }
1261 int
1263 main(int argc, char **argv, char **env)
1264 {
1265 main_t f;
1266 handler_t h;
1267 me = argv[0];
1269 /**/
1270 handle = load_perl_dll(PERL_DLL_BASENAME);
1271 if (DosQueryProcAddr(handle, 0, "Perl_OS2_handler_install", (PFN*)&h))
1273 die_with(PERL_DLL_BASENAME, ": DLL exports no symbol ", "Perl_OS2_handler_install", "");
1274 if ( !h((void *)"~installprefix", Perlos2_handler_perllib_from)
1275 ⎪⎪ !h((void *)"~dll", Perlos2_handler_perllib_to)
1276 ⎪⎪ !h((void *)"~dll/sh/ksh.exe", Perlos2_handler_perl_sh) )
1277 die_with(PERL_DLL_BASENAME, ": Can't install @INC manglers", "", "");
1278 if (DosQueryProcAddr(handle, 0, "dll_perlmain", (PFN*)&f))
1280 die_with(PERL_DLL_BASENAME, ": DLL exports no symbol ", "dll_perlmain", "");
1281 return f(argc, argv, env);
1282 }
1283
1285 Some "/" became "\" in pdksh.
1286 You have a very old pdksh. See Prerequisites.
1288 'errno' - unresolved external
1290 You do not have MT-safe db.lib. See Prerequisites.
1292 Problems with tr or sed
1294 reported with very old version of tr and sed.
1296 Some problem (forget which ;-)
1298 You have an older version of perl.dll on your LIBPATH, which broke the
1300 build of extensions.
1301 Library ... not found
1303 You did not run "omflibs". See Prerequisites.
1305 Segfault in make
1307 You use an old version of GNU make. See Prerequisites.
1309 op/sprintf test failure
1311 This can result from a bug in emx sprintf which was fixed in 0.9d fix
1313 03.
1314
1316 "setpriority", "getpriority"
1317 Note that these functions are compatible with *nix, not with the older
1319 ports of '94 - 95. The priorities are absolute, go from 32 to -95,
1320 lower is quicker. 0 is the default priority.
1321 WARNING. Calling "getpriority" on a non-existing process could lock
1323 the system before Warp3 fixpak22. Starting with Warp3, Perl will use a
1324 workaround: it aborts getpriority() if the process is not present.
1325 This is not possible on older versions "2.*", and has a race condition
1326 anyway.
1327 "system()"
1329 Multi-argument form of "system()" allows an additional numeric argu‐
1331 ment. The meaning of this argument is described in OS2::Process.
1332 When finding a program to run, Perl first asks the OS to look for exe‐
1334 cutables on "PATH" (OS/2 adds extension .exe if no extension is
1335 present). If not found, it looks for a script with possible extensions
1336 added in this order: no extension, .cmd, .btm, .bat, .pl. If found,
1337 Perl checks the start of the file for magic strings "#!" and "extproc
1338 ". If found, Perl uses the rest of the first line as the beginning of
1339 the command line to run this script. The only mangling done to the
1340 first line is extraction of arguments (currently up to 3), and ignoring
1341 of the path-part of the "interpreter" name if it can't be found using
1342 the full path.
1343 E.g., "system 'foo', 'bar', 'baz'" may lead Perl to finding
1345 C:/emx/bin/foo.cmd with the first line being
1346 extproc /bin/bash -x -c
1348 If /bin/bash.exe is not found, then Perl looks for an executable
1350 bash.exe on "PATH". If found in C:/emx.add/bin/bash.exe, then the
1351 above system() is translated to
1352 system qw(C:/emx.add/bin/bash.exe -x -c C:/emx/bin/foo.cmd bar baz)
1354 One additional translation is performed: instead of /bin/sh Perl uses
1356 the hardwired-or-customized shell (see ""PERL_SH_DIR"").
1357 The above search for "interpreter" is recursive: if bash executable is
1359 not found, but bash.btm is found, Perl will investigate its first line
1360 etc. The only hardwired limit on the recursion depth is implicit:
1361 there is a limit 4 on the number of additional arguments inserted
1362 before the actual arguments given to system(). In particular, if no
1363 additional arguments are specified on the "magic" first lines, then the
1364 limit on the depth is 4.
1365 If Perl finds that the found executable is of PM type when the current
1367 session is not, it will start the new process in a separate session of
1368 necessary type. Call via "OS2::Process" to disable this magic.
1369 WARNING. Due to the described logic, you need to explicitly specify
1371 .com extension if needed. Moreover, if the executable perl5.6.1 is
1372 requested, Perl will not look for perl5.6.1.exe. [This may change in
1373 the future.]
1374 "extproc" on the first line
1376 If the first chars of a Perl script are "extproc ", this line is
1378 treated as "#!"-line, thus all the switches on this line are processed
1379 (twice if script was started via cmd.exe). See "DESCRIPTION" in perl‐
1380 run.
1381 Additional modules:
1383 OS2::Process, OS2::DLL, OS2::REXX, OS2::PrfDB, OS2::ExtAttr. These mod‐
1385 ules provide access to additional numeric argument for "system" and to
1386 the information about the running process, to DLLs having functions
1387 with REXX signature and to the REXX runtime, to OS/2 databases in the
1388 .INI format, and to Extended Attributes.
1389 Two additional extensions by Andreas Kaiser, "OS2::UPM", and
1391 "OS2::FTP", are included into "ILYAZ" directory, mirrored on CPAN.
1392 Other OS/2-related extensions are available too.
1393 Prebuilt methods:
1395 "File::Copy::syscopy"
1397 used by "File::Copy::copy", see File::Copy.
1398 "DynaLoader::mod2fname"
1400 used by "DynaLoader" for DLL name mangling.
1401 "Cwd::current_drive()"
1403 Self explanatory.
1404 "Cwd::sys_chdir(name)"
1406 leaves drive as it is.
1407 "Cwd::change_drive(name)"
1409 chanes the "current" drive.
1410 "Cwd::sys_is_absolute(name)"
1412 means has drive letter and is_rooted.
1413 "Cwd::sys_is_rooted(name)"
1415 means has leading "[/\\]" (maybe after a drive-letter:).
1416 "Cwd::sys_is_relative(name)"
1418 means changes with current dir.
1419 "Cwd::sys_cwd(name)"
1421 Interface to cwd from EMX. Used by "Cwd::cwd".
1422 "Cwd::sys_abspath(name, dir)"
1424 Really really odious function to implement. Returns absolute name
1425 of file which would have "name" if CWD were "dir". "Dir" defaults
1426 to the current dir.
1427 "Cwd::extLibpath([type])"
1429 Get current value of extended library search path. If "type" is
1430 present and positive, works with "END_LIBPATH", if negative, works
1431 with "LIBPATHSTRICT", otherwise with "BEGIN_LIBPATH".
1432 "Cwd::extLibpath_set( path [, type ] )"
1434 Set current value of extended library search path. If "type" is
1435 present and positive, works with <END_LIBPATH>, if negative, works
1436 with "LIBPATHSTRICT", otherwise with "BEGIN_LIBPATH".
1437 "OS2::Error(do_harderror,do_exception)"
1439 Returns "undef" if it was not called yet, otherwise bit 1 is set
1440 if on the previous call do_harderror was enabled, bit 2 is set if
1441 on previous call do_exception was enabled.
1442 This function enables/disables error popups associated with hard‐
1444 ware errors (Disk not ready etc.) and software exceptions.
1445 I know of no way to find out the state of popups before the first
1447 call to this function.
1448 "OS2::Errors2Drive(drive)"
1450 Returns "undef" if it was not called yet, otherwise return false if
1451 errors were not requested to be written to a hard drive, or the
1452 drive letter if this was requested.
1453 This function may redirect error popups associated with hardware
1455 errors (Disk not ready etc.) and software exceptions to the file
1456 POPUPLOG.OS2 at the root directory of the specified drive. Over‐
1457 rides OS2::Error() specified by individual programs. Given argu‐
1458 ment undef will disable redirection.
1459 Has global effect, persists after the application exits.
1461 I know of no way to find out the state of redirection of popups to
1463 the disk before the first call to this function.
1464 OS2::SysInfo()
1466 Returns a hash with system information. The keys of the hash are
1467 MAX_PATH_LENGTH, MAX_TEXT_SESSIONS, MAX_PM_SESSIONS,
1469 MAX_VDM_SESSIONS, BOOT_DRIVE, DYN_PRI_VARIATION,
1470 MAX_WAIT, MIN_SLICE, MAX_SLICE, PAGE_SIZE,
1471 VERSION_MAJOR, VERSION_MINOR, VERSION_REVISION,
1472 MS_COUNT, TIME_LOW, TIME_HIGH, TOTPHYSMEM, TOTRESMEM,
1473 TOTAVAILMEM, MAXPRMEM, MAXSHMEM, TIMER_INTERVAL,
1474 MAX_COMP_LENGTH, FOREGROUND_FS_SESSION,
1475 FOREGROUND_PROCESS
1476 OS2::BootDrive()
1478 Returns a letter without colon.
1479 "OS2::MorphPM(serve)", "OS2::UnMorphPM(serve)"
1481 Transforms the current application into a PM application and back.
1482 The argument true means that a real message loop is going to be
1483 served. OS2::MorphPM() returns the PM message queue handle as an
1484 integer.
1485 See "Centralized management of resources" for additional details.
1487 "OS2::Serve_Messages(force)"
1489 Fake on-demand retrieval of outstanding PM messages. If "force" is
1490 false, will not dispatch messages if a real message loop is known
1491 to be present. Returns number of messages retrieved.
1492 Dies with "QUITing..." if WM_QUIT message is obtained.
1494 "OS2::Process_Messages(force [, cnt])"
1496 Retrieval of PM messages until window creation/destruction. If
1497 "force" is false, will not dispatch messages if a real message loop
1498 is known to be present.
1499 Returns change in number of windows. If "cnt" is given, it is
1501 incremented by the number of messages retrieved.
1502 Dies with "QUITing..." if WM_QUIT message is obtained.
1504 "OS2::_control87(new,mask)"
1506 the same as _control87(3) of EMX. Takes integers as arguments,
1507 returns the previous coprocessor control word as an integer. Only
1508 bits in "new" which are present in "mask" are changed in the con‐
1509 trol word.
1510 OS2::get_control87()
1512 gets the coprocessor control word as an integer.
1513 "OS2::set_control87_em(new=MCW_EM,mask=MCW_EM)"
1515 The variant of OS2::_control87() with default values good for han‐
1516 dling exception mask: if no "mask", uses exception mask part of
1517 "new" only. If no "new", disables all the floating point excep‐
1518 tions.
1519 See "Misfeatures" for details.
1521 "OS2::DLLname([how [, \&xsub]])"
1523 Gives the information about the Perl DLL or the DLL containing the
1524 C function bound to by &xsub. The meaning of "how" is: default
1525 (2): full name; 0: handle; 1: module name.
1526 (Note that some of these may be moved to different libraries - eventu‐
1528 ally).
1529 Prebuilt variables:
1531 $OS2::emx_rev
1533 numeric value is the same as _emx_rev of EMX, a string value the
1534 same as _emx_vprt (similar to "0.9c").
1535 $OS2::emx_env
1537 same as _emx_env of EMX, a number similar to 0x8001.
1538 $OS2::os_ver
1540 a number "OS_MAJOR + 0.001 * OS_MINOR".
1541 $OS2::is_aout
1543 true if the Perl library was compiled in AOUT format.
1544 $OS2::can_fork
1546 true if the current executable is an AOUT EMX executable, so Perl
1547 can fork. Do not use this, use the portable check for $Con‐
1548 fig::Config{dfork}.
1549 $OS2::nsyserror
1551 This variable (default is 1) controls whether to enforce the con‐
1552 tents of $^E to start with "SYS0003"-like id. If set to 0, then
1553 the string value of $^E is what is available from the OS/2 message
1554 file. (Some messages in this file have an "SYS0003"-like id
1555 prepended, some not.)
1556 Misfeatures
1558 · Since flock(3) is present in EMX, but is not functional, it is emu‐
1560 lated by perl. To disable the emulations, set environment variable
1561 "USE_PERL_FLOCK=0".
1562 · Here is the list of things which may be "broken" on EMX (from EMX
1564 docs):
1565 · The functions recvmsg(3), sendmsg(3), and socketpair(3) are not
1567 implemented.
1568 · sock_init(3) is not required and not implemented.
1570 · flock(3) is not yet implemented (dummy function). (Perl has a
1572 workaround.)
1573 · kill(3): Special treatment of PID=0, PID=1 and PID=-1 is not
1575 implemented.
1576 · waitpid(3):
1578 WUNTRACED
1580 Not implemented.
1581 waitpid() is not implemented for negative values of PID.
1582 Note that "kill -9" does not work with the current version of EMX.
1584 · See "Text-mode filehandles".
1586 · Unix-domain sockets on OS/2 live in a pseudo-file-system "/sock‐
1588 ets/...". To avoid a failure to create a socket with a name of a
1589 different form, "/socket/" is prepended to the socket name (unless
1590 it starts with this already).
1591 This may lead to problems later in case the socket is accessed via
1593 the "usual" file-system calls using the "initial" name.
1594 · Apparently, IBM used a compiler (for some period of time around
1596 '95?) which changes FP mask right and left. This is not that bad
1597 for IBM's programs, but the same compiler was used for DLLs which
1598 are used with general-purpose applications. When these DLLs are
1599 used, the state of floating-point flags in the application is not
1600 predictable.
1601 What is much worse, some DLLs change the floating point flags when
1603 in _DLLInitTerm() (e.g., TCP32IP). This means that even if you do
1604 not call any function in the DLL, just the act of loading this DLL
1605 will reset your flags. What is worse, the same compiler was used
1606 to compile some HOOK DLLs. Given that HOOK dlls are executed in
1607 the context of all the applications in the system, this means a
1608 complete unpredictablity of floating point flags on systems using
1609 such HOOK DLLs. E.g., GAMESRVR.DLL of DIVE origin changes the
1610 floating point flags on each write to the TTY of a VIO (windowed
1611 text-mode) applications.
1612 Some other (not completely debugged) situations when FP flags
1614 change include some video drivers (?), and some operations related
1615 to creation of the windows. People who code OpenGL may have more
1616 experience on this.
1617 Perl is generally used in the situation when all the floating-point
1619 exceptions are ignored, as is the default under EMX. If they are
1620 not ignored, some benign Perl programs would get a "SIGFPE" and
1621 would die a horrible death.
1622 To circumvent this, Perl uses two hacks. They help against one
1624 type of damage only: FP flags changed when loading a DLL.
1625 One of the hacks is to disable floating point exceptions on Perl
1627 startup (as is the default with EMX). This helps only with com‐
1628 pile-time-linked DLLs changing the flags before main() had a chance
1629 to be called.
1630 The other hack is to restore FP flags after a call to dlopen().
1632 This helps against similar damage done by DLLs _DLLInitTerm() at
1633 runtime. Currently no way to switch these hacks off is provided.
1634 Modifications
1636 Perl modifies some standard C library calls in the following ways:
1638 "popen" "my_popen" uses sh.exe if shell is required, cf.
1640 "PERL_SH_DIR".
1641 "tmpnam" is created using "TMP" or "TEMP" environment variable, via
1643 "tempnam".
1644 "tmpfile"
1646 If the current directory is not writable, file is created
1647 using modified "tmpnam", so there may be a race condition.
1648 "ctermid"
1650 a dummy implementation.
1651 "stat" "os2_stat" special-cases /dev/tty and /dev/con.
1653 "mkdir", "rmdir"
1655 these EMX functions do not work if the path contains a trail‐
1656 ing "/". Perl contains a workaround for this.
1657 "flock" Since flock(3) is present in EMX, but is not functional, it is
1659 emulated by perl. To disable the emulations, set environment
1660 variable "USE_PERL_FLOCK=0".
1661 Identifying DLLs
1663 All the DLLs built with the current versions of Perl have ID strings
1665 identifying the name of the extension, its version, and the version of
1666 Perl required for this DLL. Run "bldlevel DLL-name" to find this info.
1667 Centralized management of resources
1669 Since to call certain OS/2 API one needs to have a correctly initial‐
1671 ized "Win" subsystem, OS/2-specific extensions may require getting
1672 "HAB"s and "HMQ"s. If an extension would do it on its own, another
1673 extension could fail to initialize.
1674 Perl provides a centralized management of these resources:
1676 "HAB"
1678 To get the HAB, the extension should call "hab = perl_hab_GET()" in
1679 C. After this call is performed, "hab" may be accessed as
1680 "Perl_hab". There is no need to release the HAB after it is used.
1681 If by some reasons perl.h cannot be included, use
1683 extern int Perl_hab_GET(void);
1685 instead.
1687 "HMQ"
1689 There are two cases:
1690 * the extension needs an "HMQ" only because some API will not
1692 work otherwise. Use "serve = 0" below.
1693 * the extension needs an "HMQ" since it wants to engage in a PM
1695 event loop. Use "serve = 1" below.
1696 To get an "HMQ", the extension should call "hmq =
1698 perl_hmq_GET(serve)" in C. After this call is performed, "hmq" may
1699 be accessed as "Perl_hmq".
1700 To signal to Perl that HMQ is not needed any more, call
1702 "perl_hmq_UNSET(serve)". Perl process will automatically
1703 morph/unmorph itself into/from a PM process if HMQ is
1704 needed/not-needed. Perl will automatically enable/disable
1705 "WM_QUIT" message during shutdown if the message queue is
1706 served/not-served.
1707 NOTE. If during a shutdown there is a message queue which did not
1709 disable WM_QUIT, and which did not process the received WM_QUIT
1710 message, the shutdown will be automatically cancelled. Do not call
1711 perl_hmq_GET(1) unless you are going to process messages on an
1712 orderly basis.
1713 * Treating errors reported by OS/2 API
1715 There are two principal conventions (it is useful to call them
1716 "Dos*" and "Win*" - though this part of the function signature is
1717 not always determined by the name of the API) of reporting the
1718 error conditions of OS/2 API. Most of "Dos*" APIs report the error
1719 code as the result of the call (so 0 means success, and there are
1720 many types of errors). Most of "Win*" API report success/fail via
1721 the result being "TRUE"/"FALSE"; to find the reason for the failure
1722 one should call WinGetLastError() API.
1723 Some "Win*" entry points also overload a "meaningful" return value
1725 with the error indicator; having a 0 return value indicates an
1726 error. Yet some other "Win*" entry points overload things even
1727 more, and 0 return value may mean a successful call returning a
1728 valid value 0, as well as an error condition; in the case of a 0
1729 return value one should call WinGetLastError() API to distinguish a
1730 successful call from a failing one.
1731 By convention, all the calls to OS/2 API should indicate their
1733 failures by resetting $^E. All the Perl-accessible functions which
1734 call OS/2 API may be broken into two classes: some die()s when an
1735 API error is encountered, the other report the error via a false
1736 return value (of course, this does not concern Perl-accessible
1737 functions which expect a failure of the OS/2 API call, having some
1738 workarounds coded).
1739 Obviously, in the situation of the last type of the signature of an
1741 OS/2 API, it is must more convenient for the users if the failure
1742 is indicated by die()ing: one does not need to check $^E to know
1743 that something went wrong. If, however, this solution is not
1744 desirable by some reason, the code in question should reset $^E to
1745 0 before making this OS/2 API call, so that the caller of this
1746 Perl-accessible function has a chance to distinguish a suc‐
1747 cess-but-0-return value from a failure. (One may return undef as
1748 an alternative way of reporting an error.)
1749 The macros to simplify this type of error propagation are
1751 "CheckOSError(expr)"
1753 Returns true on error, sets $^E. Expects expr() be a call of
1754 "Dos*"-style API.
1755 "CheckWinError(expr)"
1757 Returns true on error, sets $^E. Expects expr() be a call of
1758 "Win*"-style API.
1759 "SaveWinError(expr)"
1761 Returns "expr", sets $^E from WinGetLastError() if "expr" is
1762 false.
1763 "SaveCroakWinError(expr,die,name1,name2)"
1765 Returns "expr", sets $^E from WinGetLastError() if "expr" is
1766 false, and die()s if "die" and $^E are true. The message to
1767 die is the concatenated strings "name1" and "name2", separated
1768 by ": " from the contents of $^E.
1769 "WinError_2_Perl_rc"
1771 Sets "Perl_rc" to the return value of WinGetLastError().
1772 "FillWinError"
1774 Sets "Perl_rc" to the return value of WinGetLastError(), and
1775 sets $^E to the corresponding value.
1776 "FillOSError(rc)"
1778 Sets "Perl_rc" to "rc", and sets $^E to the corresponding
1779 value.
1780 * Loading DLLs and ordinals in DLLs
1782 Some DLLs are only present in some versions of OS/2, or in some
1783 configurations of OS/2. Some exported entry points are present
1784 only in DLLs shipped with some versions of OS/2. If these DLLs and
1785 entry points were linked directly for a Perl executable/DLL or from
1786 a Perl extensions, this binary would work only with the specified
1787 versions/setups. Even if these entry points were not needed, the
1788 load of the executable (or DLL) would fail.
1789 For example, many newer useful APIs are not present in OS/2 v2;
1791 many PM-related APIs require DLLs not available on floppy-boot set‐
1792 up.
1793 To make these calls fail only when the calls are executed, one
1795 should call these API via a dynamic linking API. There is a sub‐
1796 system in Perl to simplify such type of calls. A large number of
1797 entry points available for such linking is provided (see
1798 "entries_ordinals" - and also "PMWIN_entries" - in os2ish.h).
1799 These ordinals can be accessed via the APIs:
1800 CallORD(), DeclFuncByORD(), DeclVoidFuncByORD(),
1802 DeclOSFuncByORD(), DeclWinFuncByORD(), AssignFuncPByORD(),
1803 DeclWinFuncByORD_CACHE(), DeclWinFuncByORD_CACHE_survive(),
1804 DeclWinFuncByORD_CACHE_resetError_survive(),
1805 DeclWinFunc_CACHE(), DeclWinFunc_CACHE_resetError(),
1806 DeclWinFunc_CACHE_survive(), DeclWinFunc_CACHE_resetError_survive()
1807 See the header files and the C code in the supplied OS/2-related
1809 modules for the details on usage of these functions.
1810 Some of these functions also combine dynaloading semantic with the
1812 error-propagation semantic discussed above.
1813
1815 Because of idiosyncrasies of OS/2 one cannot have all the eggs in the
1816 same basket (though EMX environment tries hard to overcome this limita‐
1817 tions, so the situation may somehow improve). There are 4 executables
1818 for Perl provided by the distribution:
1819 perl.exe
1821 The main workhorse. This is a chimera executable: it is compiled as an
1823 "a.out"-style executable, but is linked with "omf"-style dynamic
1824 library perl.dll, and with dynamic CRT DLL. This executable is a VIO
1825 application.
1826 It can load perl dynamic extensions, and it can fork().
1828 Note. Keep in mind that fork() is needed to open a pipe to yourself.
1830 perl_.exe
1832 This is a statically linked "a.out"-style executable. It cannot load
1834 dynamic Perl extensions. The executable supplied in binary distribu‐
1835 tions has a lot of extensions prebuilt, thus the above restriction is
1836 important only if you use custom-built extensions. This executable is a
1837 VIO application.
1838 This is the only executable with does not require OS/2. The friends
1840 locked into "M$" world would appreciate the fact that this executable
1841 runs under DOS, Win0.3*, Win0.95 and WinNT with an appropriate exten‐
1842 der. See "Other OSes".
1843 perl__.exe
1845 This is the same executable as perl___.exe, but it is a PM application.
1847 Note. Usually (unless explicitly redirected during the startup) STDIN,
1849 STDERR, and STDOUT of a PM application are redirected to nul. However,
1850 it is possible to see them if you start "perl__.exe" from a PM program
1851 which emulates a console window, like Shell mode of Emacs or EPM. Thus
1852 it is possible to use Perl debugger (see perldebug) to debug your PM
1853 application (but beware of the message loop lockups - this will not
1854 work if you have a message queue to serve, unless you hook the serving
1855 into the getc() function of the debugger).
1856 Another way to see the output of a PM program is to run it as
1858 pm_prog args 2>&1 ⎪ cat -
1860 with a shell different from cmd.exe, so that it does not create a link
1862 between a VIO session and the session of "pm_porg". (Such a link
1863 closes the VIO window.) E.g., this works with sh.exe - or with Perl!
1864 open P, 'pm_prog args 2>&1 ⎪' or die;
1866 print while <P>;
1867 The flavor perl__.exe is required if you want to start your program
1869 without a VIO window present, but not "detach"ed (run "help detach" for
1870 more info). Very useful for extensions which use PM, like "Perl/Tk" or
1871 "OpenGL".
1872 Note also that the differences between PM and VIO executables are only
1874 in the default behaviour. One can start any executable in any kind of
1875 session by using the arguments "/fs", "/pm" or "/win" switches of the
1876 command "start" (of CMD.EXE or a similar shell). Alternatively, one
1877 can use the numeric first argument of the "system" Perl function (see
1878 OS2::Process).
1879 perl___.exe
1881 This is an "omf"-style executable which is dynamically linked to
1883 perl.dll and CRT DLL. I know no advantages of this executable over
1884 "perl.exe", but it cannot fork() at all. Well, one advantage is that
1885 the build process is not so convoluted as with "perl.exe".
1886 It is a VIO application.
1888 Why strange names?
1890 Since Perl processes the "#!"-line (cf. "DESCRIPTION" in perlrun,
1892 "Switches" in perlrun, "Not a perl script" in perldiag, "No Perl script
1893 found in input" in perldiag), it should know when a program is a Perl.
1894 There is some naming convention which allows Perl to distinguish cor‐
1895 rect lines from wrong ones. The above names are almost the only names
1896 allowed by this convention which do not contain digits (which have
1897 absolutely different semantics).
1898 Why dynamic linking?
1900 Well, having several executables dynamically linked to the same huge
1902 library has its advantages, but this would not substantiate the addi‐
1903 tional work to make it compile. The reason is the complicated-to-devel‐
1904 opers but very quick and convenient-to-users "hard" dynamic linking
1905 used by OS/2.
1906 There are two distinctive features of the dyna-linking model of OS/2:
1908 first, all the references to external functions are resolved at the
1909 compile time; second, there is no runtime fixup of the DLLs after they
1910 are loaded into memory. The first feature is an enormous advantage
1911 over other models: it avoids conflicts when several DLLs used by an
1912 application export entries with the same name. In such cases "other"
1913 models of dyna-linking just choose between these two entry points using
1914 some random criterion - with predictable disasters as results. But it
1915 is the second feature which requires the build of perl.dll.
1916 The address tables of DLLs are patched only once, when they are loaded.
1918 The addresses of the entry points into DLLs are guaranteed to be the
1919 same for all the programs which use the same DLL. This removes the
1920 runtime fixup - once DLL is loaded, its code is read-only.
1921 While this allows some (significant?) performance advantages, this
1923 makes life much harder for developers, since the above scheme makes it
1924 impossible for a DLL to be "linked" to a symbol in the .EXE file.
1925 Indeed, this would need a DLL to have different relocations tables for
1926 the (different) executables which use this DLL.
1927 However, a dynamically loaded Perl extension is forced to use some sym‐
1929 bols from the perl executable, e.g., to know how to find the arguments
1930 to the functions: the arguments live on the perl internal evaluation
1931 stack. The solution is to put the main code of the interpreter into a
1932 DLL, and make the .EXE file which just loads this DLL into memory and
1933 supplies command-arguments. The extension DLL cannot link to symbols
1934 in .EXE, but it has no problem linking to symbols in the .DLL.
1935 This greatly increases the load time for the application (as well as
1937 complexity of the compilation). Since interpreter is in a DLL, the C
1938 RTL is basically forced to reside in a DLL as well (otherwise exten‐
1939 sions would not be able to use CRT). There are some advantages if you
1940 use different flavors of perl, such as running perl.exe and perl__.exe
1941 simultaneously: they share the memory of perl.dll.
1942 NOTE. There is one additional effect which makes DLLs more wasteful:
1944 DLLs are loaded in the shared memory region, which is a scarse resource
1945 given the 512M barrier of the "standard" OS/2 virtual memory. The code
1946 of .EXE files is also shared by all the processes which use the partic‐
1947 ular .EXE, but they are "shared in the private address space of the
1948 process"; this is possible because the address at which different sec‐
1949 tions of the .EXE file are loaded is decided at compile-time, thus all
1950 the processes have these sections loaded at same addresses, and no
1951 fixup of internal links inside the .EXE is needed.
1952 Since DLLs may be loaded at run time, to have the same mechanism for
1954 DLLs one needs to have the address range of any of the loaded DLLs in
1955 the system to be available in all the processes which did not load a
1956 particular DLL yet. This is why the DLLs are mapped to the shared mem‐
1957 ory region.
1958 Why chimera build?
1960 Current EMX environment does not allow DLLs compiled using Unixish
1962 "a.out" format to export symbols for data (or at least some types of
1963 data). This forces "omf"-style compile of perl.dll.
1964 Current EMX environment does not allow .EXE files compiled in "omf"
1966 format to fork(). fork() is needed for exactly three Perl operations:
1967 · explicit fork() in the script,
1969 · "open FH, "⎪-""
1971 · "open FH, "-⎪"", in other words, opening pipes to itself.
1973 While these operations are not questions of life and death, they are
1975 needed for a lot of useful scripts. This forces "a.out"-style compile
1976 of perl.exe.
1977
1979 Here we list environment variables with are either OS/2- and DOS- and
1980 Win*-specific, or are more important under OS/2 than under other OSes.
1981 "PERLLIB_PREFIX"
1983 Specific for EMX port. Should have the form
1985 path1;path2
1987 or
1989 path1 path2
1991 If the beginning of some prebuilt path matches path1, it is substituted
1993 with path2.
1994 Should be used if the perl library is moved from the default location
1996 in preference to "PERL(5)LIB", since this would not leave wrong entries
1997 in @INC. For example, if the compiled version of perl looks for @INC
1998 in f:/perllib/lib, and you want to install the library in h:/opt/gnu,
1999 do
2000 set PERLLIB_PREFIX=f:/perllib/lib;h:/opt/gnu
2002 This will cause Perl with the prebuilt @INC of
2004 f:/perllib/lib/5.00553/os2
2006 f:/perllib/lib/5.00553
2007 f:/perllib/lib/site_perl/5.00553/os2
2008 f:/perllib/lib/site_perl/5.00553
2009 .
2010 to use the following @INC:
2012 h:/opt/gnu/5.00553/os2
2014 h:/opt/gnu/5.00553
2015 h:/opt/gnu/site_perl/5.00553/os2
2016 h:/opt/gnu/site_perl/5.00553
2017 .
2018 "PERL_BADLANG"
2020 If 0, perl ignores setlocale() failing. May be useful with some strange
2022 locales.
2023 "PERL_BADFREE"
2025 If 0, perl would not warn of in case of unwarranted free(). With older
2027 perls this might be useful in conjunction with the module DB_File,
2028 which was buggy when dynamically linked and OMF-built.
2029 Should not be set with newer Perls, since this may hide some real prob‐
2031 lems.
2032 "PERL_SH_DIR"
2034 Specific for EMX port. Gives the directory part of the location for
2036 sh.exe.
2037 "USE_PERL_FLOCK"
2039 Specific for EMX port. Since flock(3) is present in EMX, but is not
2041 functional, it is emulated by perl. To disable the emulations, set
2042 environment variable "USE_PERL_FLOCK=0".
2043 "TMP" or "TEMP"
2045 Specific for EMX port. Used as storage place for temporary files.
2047
2049 Here we list major changes which could make you by surprise.
2050 Text-mode filehandles
2052 Starting from version 5.8, Perl uses a builtin translation layer for
2054 text-mode files. This replaces the efficient well-tested EMX layer by
2055 some code which should be best characterized as a "quick hack".
2056 In addition to possible bugs and an inability to follow changes to the
2058 translation policy with off/on switches of TERMIO translation, this
2059 introduces a serious incompatible change: before sysread() on text-mode
2060 filehandles would go through the translation layer, now it would not.
2061 Priorities
2063 "setpriority" and "getpriority" are not compatible with earlier ports
2065 by Andreas Kaiser. See "setpriority, getpriority".
2066 DLL name mangling: pre 5.6.2
2068 With the release 5.003_01 the dynamically loadable libraries should be
2070 rebuilt when a different version of Perl is compiled. In particular,
2071 DLLs (including perl.dll) are now created with the names which contain
2072 a checksum, thus allowing workaround for OS/2 scheme of caching DLLs.
2073 It may be possible to code a simple workaround which would
2075 · find the old DLLs looking through the old @INC;
2077 · mangle the names according to the scheme of new perl and copy the
2079 DLLs to these names;
2080 · edit the internal "LX" tables of DLL to reflect the change of the
2082 name (probably not needed for Perl extension DLLs, since the inter‐
2083 nally coded names are not used for "specific" DLLs, they used only
2084 for "global" DLLs).
2085 · edit the internal "IMPORT" tables and change the name of the "old"
2087 perl????.dll to the "new" perl????.dll.
2088 DLL name mangling: 5.6.2 and beyond
2090 In fact mangling of extension DLLs was done due to misunderstanding of
2092 the OS/2 dynaloading model. OS/2 (effectively) maintains two different
2093 tables of loaded DLL:
2094 Global DLLs
2096 those loaded by the base name from "LIBPATH"; including those asso‐
2097 ciated at link time;
2098 specific DLLs
2100 loaded by the full name.
2101 When resolving a request for a global DLL, the table of already-loaded
2103 specific DLLs is (effectively) ignored; moreover, specific DLLs are
2104 always loaded from the prescribed path.
2105 There is/was a minor twist which makes this scheme fragile: what to do
2107 with DLLs loaded from
2108 "BEGINLIBPATH" and "ENDLIBPATH"
2110 (which depend on the process)
2111 . from "LIBPATH"
2113 which effectively depends on the process (although "LIBPATH" is the
2114 same for all the processes).
2115 Unless "LIBPATHSTRICT" is set to "T" (and the kernel is after
2117 2000/09/01), such DLLs are considered to be global. When loading a
2118 global DLL it is first looked in the table of already-loaded global
2119 DLLs. Because of this the fact that one executable loaded a DLL from
2120 "BEGINLIBPATH" and "ENDLIBPATH", or . from "LIBPATH" may affect which
2121 DLL is loaded when another executable requests a DLL with the same
2122 name. This is the reason for version-specific mangling of the DLL name
2123 for perl DLL.
2124 Since the Perl extension DLLs are always loaded with the full path,
2126 there is no need to mangle their names in a version-specific ways:
2127 their directory already reflects the corresponding version of perl, and
2128 @INC takes into account binary compatibility with older version.
2129 Starting from 5.6.2 the name mangling scheme is fixed to be the same as
2130 for Perl 5.005_53 (same as in a popular binary release). Thus new
2131 Perls will be able to resolve the names of old extension DLLs if @INC
2132 allows finding their directories.
2133 However, this still does not guarantee that these DLL may be loaded.
2135 The reason is the mangling of the name of the Perl DLL. And since the
2136 extension DLLs link with the Perl DLL, extension DLLs for older ver‐
2137 sions would load an older Perl DLL, and would most probably segfault
2138 (since the data in this DLL is not properly initialized).
2139 There is a partial workaround (which can be made complete with newer
2141 OS/2 kernels): create a forwarder DLL with the same name as the DLL of
2142 the older version of Perl, which forwards the entry points to the newer
2143 Perl's DLL. Make this DLL accessible on (say) the "BEGINLIBPATH" of
2144 the new Perl executable. When the new executable accesses old Perl's
2145 extension DLLs, they would request the old Perl's DLL by name, get the
2146 forwarder instead, so effectively will link with the currently running
2147 (new) Perl DLL.
2148 This may break in two ways:
2150 · Old perl executable is started when a new executable is running has
2152 loaded an extension compiled for the old executable (ouph!). In
2153 this case the old executable will get a forwarder DLL instead of
2154 the old perl DLL, so would link with the new perl DLL. While not
2155 directly fatal, it will behave the same as new executable. This
2156 beats the whole purpose of explicitly starting an old executable.
2157 · A new executable loads an extension compiled for the old executable
2159 when an old perl executable is running. In this case the extension
2160 will not pick up the forwarder - with fatal results.
2161 With support for "LIBPATHSTRICT" this may be circumvented - unless one
2163 of DLLs is started from . from "LIBPATH" (I do not know whether "LIB‐
2164 PATHSTRICT" affects this case).
2165 REMARK. Unless newer kernels allow . in "BEGINLIBPATH" (older do not),
2167 this mess cannot be completely cleaned. (It turns out that as of the
2168 beginning of 2002, . is not allowed, but .\. is - and it has the same
2169 effect.)
2170 REMARK. "LIBPATHSTRICT", "BEGINLIBPATH" and "ENDLIBPATH" are not envi‐
2172 ronment variables, although cmd.exe emulates them on "SET ..." lines.
2173 From Perl they may be accessed by Cwd::extLibpath and Cwd::extLib‐
2174 path_set.
2175 DLL forwarder generation
2177 Assume that the old DLL is named perlE0AC.dll (as is one for 5.005_53),
2179 and the new version is 5.6.1. Create a file perl5shim.def-leader with
2180 LIBRARY 'perlE0AC' INITINSTANCE TERMINSTANCE
2182 DESCRIPTION '@#perl5-porters@perl.org:5.006001#@ Perl module for 5.00553 -> Perl 5.6.1 forwarder'
2183 CODE LOADONCALL
2184 DATA LOADONCALL NONSHARED MULTIPLE
2185 EXPORTS
2186 modifying the versions/names as needed. Run
2188 perl -wnle "next if 0../EXPORTS/; print qq( \"$1\") if /\"(\w+)\"/" perl5.def >lst
2190 in the Perl build directory (to make the DLL smaller replace perl5.def
2192 with the definition file for the older version of Perl if present).
2193 cat perl5shim.def-leader lst >perl5shim.def
2195 gcc -Zomf -Zdll -o perlE0AC.dll perl5shim.def -s -llibperl
2196 (ignore multiple "warning L4085").
2198 Threading
2200 As of release 5.003_01 perl is linked to multithreaded C RTL DLL. If
2202 perl itself is not compiled multithread-enabled, so will not be perl's
2203 malloc(). However, extensions may use multiple thread on their own
2204 risk.
2205 This was needed to compile "Perl/Tk" for XFree86-OS/2 out-of-the-box,
2207 and link with DLLs for other useful libraries, which typically are com‐
2208 piled with "-Zmt -Zcrtdll".
2209 Calls to external programs
2211 Due to a popular demand the perl external program calling has been
2213 changed wrt Andreas Kaiser's port. If perl needs to call an external
2214 program via shell, the f:/bin/sh.exe will be called, or whatever is the
2215 override, see "PERL_SH_DIR".
2216 Thus means that you need to get some copy of a sh.exe as well (I use
2218 one from pdksh). The path F:/bin above is set up automatically during
2219 the build to a correct value on the builder machine, but is overridable
2220 at runtime,
2221 Reasons: a consensus on "perl5-porters" was that perl should use one
2223 non-overridable shell per platform. The obvious choices for OS/2 are
2224 cmd.exe and sh.exe. Having perl build itself would be impossible with
2225 cmd.exe as a shell, thus I picked up "sh.exe". This assures almost 100%
2226 compatibility with the scripts coming from *nix. As an added benefit
2227 this works as well under DOS if you use DOS-enabled port of pdksh (see
2228 "Prerequisites").
2229 Disadvantages: currently sh.exe of pdksh calls external programs via
2231 fork()/exec(), and there is no functioning exec() on OS/2. exec() is
2232 emulated by EMX by an asynchronous call while the caller waits for
2233 child completion (to pretend that the "pid" did not change). This means
2234 that 1 extra copy of sh.exe is made active via fork()/exec(), which may
2235 lead to some resources taken from the system (even if we do not count
2236 extra work needed for fork()ing).
2237 Note that this a lesser issue now when we do not spawn sh.exe unless
2239 needed (metachars found).
2240 One can always start cmd.exe explicitly via
2242 system 'cmd', '/c', 'mycmd', 'arg1', 'arg2', ...
2244 If you need to use cmd.exe, and do not want to hand-edit thousands of
2246 your scripts, the long-term solution proposed on p5-p is to have a
2247 directive
2248 use OS2::Cmd;
2250 which will override system(), exec(), ``, and "open(,'...⎪')". With
2252 current perl you may override only system(), readpipe() - the explicit
2253 version of ``, and maybe exec(). The code will substitute the one-argu‐
2254 ment call to system() by "CORE::system('cmd.exe', '/c', shift)".
2255 If you have some working code for "OS2::Cmd", please send it to me, I
2257 will include it into distribution. I have no need for such a module, so
2258 cannot test it.
2259 For the details of the current situation with calling external pro‐
2261 grams, see "2 (and DOS) programs under Perl" in Starting OS. Set us
2262 mention a couple of features:
2263 · External scripts may be called by their basename. Perl will try
2265 the same extensions as when processing -S command-line switch.
2266 · External scripts starting with "#!" or "extproc " will be executed
2268 directly, without calling the shell, by calling the program speci‐
2269 fied on the rest of the first line.
2270 Memory allocation
2272 Perl uses its own malloc() under OS/2 - interpreters are usually mal‐
2274 loc-bound for speed, but perl is not, since its malloc is light‐
2275 ning-fast. Perl-memory-usage-tuned benchmarks show that Perl's malloc
2276 is 5 times quicker than EMX one. I do not have convincing data about
2277 memory footprint, but a (pretty random) benchmark showed that Perl's
2278 one is 5% better.
2279 Combination of perl's malloc() and rigid DLL name resolution creates a
2281 special problem with library functions which expect their return value
2282 to be free()d by system's free(). To facilitate extensions which need
2283 to call such functions, system memory-allocation functions are still
2284 available with the prefix "emx_" added. (Currently only DLL perl has
2285 this, it should propagate to perl_.exe shortly.)
2286 Threads
2288 One can build perl with thread support enabled by providing "-D
2290 usethreads" option to Configure. Currently OS/2 support of threads is
2291 very preliminary.
2292 Most notable problems:
2294 "COND_WAIT"
2296 may have a race condition (but probably does not due to edge-trig‐
2297 gered nature of OS/2 Event semaphores). (Needs a reimplementation
2298 (in terms of chaining waiting threads, with the linked list stored
2299 in per-thread structure?)?)
2300 os2.c
2302 has a couple of static variables used in OS/2-specific functions.
2303 (Need to be moved to per-thread structure, or serialized?)
2304 Note that these problems should not discourage experimenting, since
2306 they have a low probability of affecting small programs.
2307
2309 This description is not updated often (since 5.6.1?), see ./os2/Changes
2310 (perlos2delta) for more info.
2311
2313 Ilya Zakharevich, cpan@ilyaz.org
2314
2316 perl(1).
2317perl v5.8.8 2006-01-07 PERLOS2(1)