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"
24 package
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
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
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 The current state is quite close to this target. Known limitations:
46 · 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 · You need a separate perl executable perl__.exe (see perl__.exe) if
55 you want to use PM code in your application (as Perl/Tk or OpenGL
56 Perl modules do) without having a text-mode window present.
57 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 · 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 Please keep this list up-to-date by informing me about other items.
72 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 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 Cf. Prerequisites.
85 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 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 One can get different parts of EMX from, say
101 http://www.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/
103 http://powerusersbbs.com/pub/os2/dev/ [EMX+GCC Development]
104 http://hobbes.nmsu.edu/pub/os2/dev/emx/v0.9d/
105 The runtime component should have the name emxrt.zip.
107 NOTE. When using emx.exe/rsx.exe, it is enough to have them on
109 your path. One does not need to specify them explicitly (though
110 this
111 emx perl_.exe -de 0
113 will work as well.)
115 RSX To run Perl on DPMI platforms one needs RSX runtime. This is
117 needed under DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT (see
118 "Other OSes"). RSX would not work with VCPI only, as EMX would,
119 it requires DMPI.
120 Having RSX and the latest sh.exe one gets a fully functional
122 *nix-ish environment under DOS, say, "fork", "``" and pipe-"open"
123 work. In fact, MakeMaker works (for static build), so one can
124 have Perl development environment under DOS.
125 One can get RSX from, say
127 ftp://ftp.cdrom.com/pub/os2/emx09c/contrib
129 ftp://ftp.uni-bielefeld.de/pub/systems/msdos/misc
130 ftp://ftp.leo.org/pub/comp/os/os2/leo/devtools/emx+gcc/contrib
131 Contact the author on "rainer@mathematik.uni-bielefeld.de".
133 The latest sh.exe with DOS hooks is available in
135 http://www.ilyaz.org/software/os2/
137 as sh_dos.zip or under similar names starting with "sh", "pdksh"
139 etc.
140 HPFS Perl does not care about file systems, but the perl library
142 contains many files with long names, so to install it intact one
143 needs a file system which supports long file names.
144 Note that if you do not plan to build the perl itself, it may be
146 possible to fool EMX to truncate file names. This is not
147 supported, read EMX docs to see how to do it.
148 pdksh To start external programs with complicated command lines (like
150 with pipes in between, and/or quoting of arguments), Perl uses an
151 external shell. With EMX port such shell should be named sh.exe,
152 and located either in the wired-in-during-compile locations
153 (usually F:/bin), or in configurable location (see
154 "PERL_SH_DIR").
155 For best results use EMX pdksh. The standard binary (5.2.14 or
157 later) runs under DOS (with RSX) as well, see
158 http://www.ilyaz.org/software/os2/
160 Starting Perl programs under OS/2 (and DOS and...)
162 Start your Perl program foo.pl with arguments "arg1 arg2 arg3" the same
163 way as on any other platform, by
164 perl foo.pl arg1 arg2 arg3
166 If you want to specify perl options "-my_opts" to the perl itself (as
168 opposed to your program), use
169 perl -my_opts foo.pl arg1 arg2 arg3
171 Alternately, if you use OS/2-ish shell, like CMD or 4os2, put the
173 following at the start of your perl script:
174 extproc perl -S -my_opts
176 rename your program to foo.cmd, and start it by typing
178 foo arg1 arg2 arg3
180 Note that because of stupid OS/2 limitations the full path of the perl
182 script is not available when you use "extproc", thus you are forced to
183 use "-S" perl switch, and your script should be on the "PATH". As a
184 plus side, if you know a full path to your script, you may still start
185 it with
186 perl ../../blah/foo.cmd arg1 arg2 arg3
188 (note that the argument "-my_opts" is taken care of by the "extproc"
190 line in your script, see ""extproc" on the first line").
191 To understand what the above magic does, read perl docs about "-S"
193 switch - see perlrun, and cmdref about "extproc":
194 view perl perlrun
196 man perlrun
197 view cmdref extproc
198 help extproc
199 or whatever method you prefer.
201 There are also endless possibilities to use executable extensions of
203 4os2, associations of WPS and so on... However, if you use *nixish
204 shell (like sh.exe supplied in the binary distribution), you need to
205 follow the syntax specified in "Switches" in perlrun.
206 Note that -S switch supports scripts with additional extensions .cmd,
208 .btm, .bat, .pl as well.
209 Starting OS/2 (and DOS) programs under Perl
211 This is what system() (see "system" in perlfunc), "``" (see "I/O
212 Operators" in perlop), and open pipe (see "open" in perlfunc) are for.
213 (Avoid exec() (see "exec" in perlfunc) unless you know what you do).
214 Note however that to use some of these operators you need to have a sh-
216 syntax shell installed (see "Pdksh", "Frequently asked questions"), and
217 perl should be able to find it (see "PERL_SH_DIR").
218 The cases when the shell is used are:
220 1. One-argument system() (see "system" in perlfunc), exec() (see
222 "exec" in perlfunc) with redirection or shell meta-characters;
223 2. Pipe-open (see "open" in perlfunc) with the command which contains
225 redirection or shell meta-characters;
226 3. Backticks "``" (see "I/O Operators" in perlop) with the command
228 which contains redirection or shell meta-characters;
229 4. If the executable called by system()/exec()/pipe-open()/"``" is a
231 script with the "magic" "#!" line or "extproc" line which specifies
232 shell;
233 5. If the executable called by system()/exec()/pipe-open()/"``" is a
235 script without "magic" line, and $ENV{EXECSHELL} is set to shell;
236 6. If the executable called by system()/exec()/pipe-open()/"``" is not
238 found (is not this remark obsolete?);
239 7. For globbing (see "glob" in perlfunc, "I/O Operators" in perlop)
241 (obsolete? Perl uses builtin globbing nowadays...).
242 For the sake of speed for a common case, in the above algorithms
244 backslashes in the command name are not considered as shell
245 metacharacters.
246 Perl starts scripts which begin with cookies "extproc" or "#!"
248 directly, without an intervention of shell. Perl uses the same
249 algorithm to find the executable as pdksh: if the path on "#!" line
250 does not work, and contains "/", then the directory part of the
251 executable is ignored, and the executable is searched in . and on
252 "PATH". To find arguments for these scripts Perl uses a different
253 algorithm than pdksh: up to 3 arguments are recognized, and trailing
254 whitespace is stripped.
255 If a script does not contain such a cooky, then to avoid calling
257 sh.exe, Perl uses the same algorithm as pdksh: if $ENV{EXECSHELL} is
258 set, the script is given as the first argument to this command, if not
259 set, then "$ENV{COMSPEC} /c" is used (or a hardwired guess if
260 $ENV{COMSPEC} is not set).
261 When starting scripts directly, Perl uses exactly the same algorithm as
263 for the search of script given by -S command-line option: it will look
264 in the current directory, then on components of $ENV{PATH} using the
265 following order of appended extensions: no extension, .cmd, .btm, .bat,
266 .pl.
267 Note that Perl will start to look for scripts only if OS/2 cannot start
269 the specified application, thus "system 'blah'" will not look for a
270 script if there is an executable file blah.exe anywhere on "PATH". In
271 other words, "PATH" is essentially searched twice: once by the OS for
272 an executable, then by Perl for scripts.
273 Note also that executable files on OS/2 can have an arbitrary
275 extension, but .exe will be automatically appended if no dot is present
276 in the name. The workaround is as simple as that: since blah. and
277 blah denote the same file (at list on FAT and HPFS file systems), to
278 start an executable residing in file n:/bin/blah (no extension) give an
279 argument "n:/bin/blah." (dot appended) to system().
280 Perl will start PM programs from VIO (=text-mode) Perl process in a
282 separate PM session; the opposite is not true: when you start a non-PM
283 program from a PM Perl process, Perl would not run it in a separate
284 session. If a separate session is desired, either ensure that shell
285 will be used, as in "system 'cmd /c myprog'", or start it using
286 optional arguments to system() documented in "OS2::Process" module.
287 This is considered to be a feature.
288
290 "It does not work"
291 Perl binary distributions come with a testperl.cmd script which tries
292 to detect common problems with misconfigured installations. There is a
293 pretty large chance it will discover which step of the installation you
294 managed to goof. ";-)"
295 I cannot run external programs
297 · Did you run your programs with "-w" switch? See "2 (and DOS)
298 programs under Perl" in Starting OS.
299 · Do you try to run internal shell commands, like "`copy a b`"
301 (internal for cmd.exe), or "`glob a*b`" (internal for ksh)? You
302 need to specify your shell explicitly, like "`cmd /c copy a b`",
303 since Perl cannot deduce which commands are internal to your shell.
304 I cannot embed perl into my program, or use perl.dll from my program.
306 Is your program EMX-compiled with "-Zmt -Zcrtdll"?
307 Well, nowadays Perl DLL should be usable from a differently
308 compiled program too... If you can run Perl code from REXX scripts
309 (see OS2::REXX), then there are some other aspect of interaction
310 which are overlooked by the current hackish code to support
311 differently-compiled principal programs.
312 If everything else fails, you need to build a stand-alone DLL for
314 perl. Contact me, I did it once. Sockets would not work, as a lot
315 of other stuff.
316 Did you use ExtUtils::Embed?
318 Some time ago I had reports it does not work. Nowadays it is
319 checked in the Perl test suite, so grep ./t subdirectory of the
320 build tree (as well as *.t files in the ./lib subdirectory) to find
321 how it should be done "correctly".
322 "``" and pipe-"open" do not work under DOS.
324 This may a variant of just "I cannot run external programs", or a
325 deeper problem. Basically: you need RSX (see "Prerequisites") for these
326 commands to work, and you may need a port of sh.exe which understands
327 command arguments. One of such ports is listed in "Prerequisites" under
328 RSX. Do not forget to set variable "PERL_SH_DIR" as well.
329 DPMI is required for RSX.
331 Cannot start "find.exe "pattern" file"
333 The whole idea of the "standard C API to start applications" is that
334 the forms "foo" and "foo" of program arguments are completely
335 interchangable. find breaks this paradigm;
336 find "pattern" file
338 find pattern file
339 are not equivalent; find cannot be started directly using the above
341 API. One needs a way to surround the doublequotes in some other
342 quoting construction, necessarily having an extra non-Unixish shell in
343 between.
344 Use one of
346 system 'cmd', '/c', 'find "pattern" file';
348 `cmd /c 'find "pattern" file'`
349 This would start find.exe via cmd.exe via "sh.exe" via "perl.exe", but
351 this is a price to pay if you want to use non-conforming program.
352
354 Automatic binary installation
355 The most convenient way of installing a binary distribution of perl is
356 via perl installer install.exe. Just follow the instructions, and 99%
357 of the installation blues would go away.
358 Note however, that you need to have unzip.exe on your path, and EMX
360 environment running. The latter means that if you just installed EMX,
361 and made all the needed changes to Config.sys, you may need to reboot
362 in between. Check EMX runtime by running
363 emxrev
365 Binary installer also creates a folder on your desktop with some useful
367 objects. If you need to change some aspects of the work of the binary
368 installer, feel free to edit the file Perl.pkg. This may be useful
369 e.g., if you need to run the installer many times and do not want to
370 make many interactive changes in the GUI.
371 Things not taken care of by automatic binary installation:
373 "PERL_BADLANG" may be needed if you change your codepage after perl
375 installation, and the new value is not supported by EMX.
376 See "PERL_BADLANG".
377 "PERL_BADFREE" see "PERL_BADFREE".
379 Config.pm This file resides somewhere deep in the location you
381 installed your perl library, find it out by
382 perl -MConfig -le "print $INC{'Config.pm'}"
384 While most important values in this file are updated by
386 the binary installer, some of them may need to be hand-
387 edited. I know no such data, please keep me informed if
388 you find one. Moreover, manual changes to the installed
389 version may need to be accompanied by an edit of this
390 file.
391 NOTE. Because of a typo the binary installer of 5.00305 would install a
393 variable "PERL_SHPATH" into Config.sys. Please remove this variable and
394 put "PERL_SH_DIR" instead.
395 Manual binary installation
397 As of version 5.00305, OS/2 perl binary distribution comes split into
398 11 components. Unfortunately, to enable configurable binary
399 installation, the file paths in the zip files are not absolute, but
400 relative to some directory.
401 Note that the extraction with the stored paths is still necessary
403 (default with unzip, specify "-d" to pkunzip). However, you need to
404 know where to extract the files. You need also to manually change
405 entries in Config.sys to reflect where did you put the files. Note that
406 if you have some primitive unzipper (like "pkunzip"), you may get a lot
407 of warnings/errors during unzipping. Upgrade to "(w)unzip".
408 Below is the sample of what to do to reproduce the configuration on my
410 machine. In VIEW.EXE you can press "Ctrl-Insert" now, and cut-and-
411 paste from the resulting file - created in the directory you started
412 VIEW.EXE from.
413 For each component, we mention environment variables related to each
415 installation directory. Either choose directories to match your values
416 of the variables, or create/append-to variables to take into account
417 the directories.
418 Perl VIO and PM executables (dynamically linked)
420 unzip perl_exc.zip *.exe *.ico -d f:/emx.add/bin
421 unzip perl_exc.zip *.dll -d f:/emx.add/dll
422 (have the directories with "*.exe" on PATH, and "*.dll" on LIBPATH);
424 Perl_ VIO executable (statically linked)
426 unzip perl_aou.zip -d f:/emx.add/bin
427 (have the directory on PATH);
429 Executables for Perl utilities
431 unzip perl_utl.zip -d f:/emx.add/bin
432 (have the directory on PATH);
434 Main Perl library
436 unzip perl_mlb.zip -d f:/perllib/lib
437 If this directory is exactly the same as the prefix which was
439 compiled into perl.exe, you do not need to change anything. However,
440 for perl to find the library if you use a different path, you need
441 to "set PERLLIB_PREFIX" in Config.sys, see "PERLLIB_PREFIX".
442 Additional Perl modules
444 unzip perl_ste.zip -d f:/perllib/lib/site_perl/5.10.1/
445 Same remark as above applies. Additionally, if this directory is
447 not one of directories on @INC (and @INC is influenced by
448 "PERLLIB_PREFIX"), you need to put this directory and subdirectory
449 ./os2 in "PERLLIB" or "PERL5LIB" variable. Do not use "PERL5LIB"
450 unless you have it set already. See "ENVIRONMENT" in perl.
451 [Check whether this extraction directory is still applicable with
453 the new directory structure layout!]
454 Tools to compile Perl modules
456 unzip perl_blb.zip -d f:/perllib/lib
457 Same remark as for perl_ste.zip.
459 Manpages for Perl and utilities
461 unzip perl_man.zip -d f:/perllib/man
462 This directory should better be on "MANPATH". You need to have a
464 working man to access these files.
465 Manpages for Perl modules
467 unzip perl_mam.zip -d f:/perllib/man
468 This directory should better be on "MANPATH". You need to have a
470 working man to access these files.
471 Source for Perl documentation
473 unzip perl_pod.zip -d f:/perllib/lib
474 This is used by the "perldoc" program (see perldoc), and may be used
476 to generate HTML documentation usable by WWW browsers, and
477 documentation in zillions of other formats: "info", "LaTeX",
478 "Acrobat", "FrameMaker" and so on. [Use programs such as pod2latex
479 etc.]
480 Perl manual in .INF format
482 unzip perl_inf.zip -d d:/os2/book
483 This directory should better be on "BOOKSHELF".
485 Pdksh
487 unzip perl_sh.zip -d f:/bin
488 This is used by perl to run external commands which explicitly
490 require shell, like the commands using redirection and shell
491 metacharacters. It is also used instead of explicit /bin/sh.
492 Set "PERL_SH_DIR" (see "PERL_SH_DIR") if you move sh.exe from the
494 above location.
495 Note. It may be possible to use some other sh-compatible shell
497 (untested).
498 After you installed the components you needed and updated the
500 Config.sys correspondingly, you need to hand-edit Config.pm. This file
501 resides somewhere deep in the location you installed your perl library,
502 find it out by
503 perl -MConfig -le "print $INC{'Config.pm'}"
505 You need to correct all the entries which look like file paths (they
507 currently start with "f:/").
508 Warning
510 The automatic and manual perl installation leave precompiled paths
511 inside perl executables. While these paths are overwriteable (see
512 "PERLLIB_PREFIX", "PERL_SH_DIR"), some people may prefer binary editing
513 of paths inside the executables/DLLs.
514
516 Depending on how you built/installed perl you may have (otherwise
517 identical) Perl documentation in the following formats:
518 OS/2 .INF file
520 Most probably the most convenient form. Under OS/2 view it as
521 view perl
523 view perl perlfunc
524 view perl less
525 view perl ExtUtils::MakeMaker
526 (currently the last two may hit a wrong location, but this may improve
528 soon). Under Win* see "SYNOPSIS".
529 If you want to build the docs yourself, and have OS/2 toolkit, run
531 pod2ipf > perl.ipf
533 in /perllib/lib/pod directory, then
535 ipfc /inf perl.ipf
537 (Expect a lot of errors during the both steps.) Now move it on your
539 BOOKSHELF path.
540 Plain text
542 If you have perl documentation in the source form, perl utilities
543 installed, and GNU groff installed, you may use
544 perldoc perlfunc
546 perldoc less
547 perldoc ExtUtils::MakeMaker
548 to access the perl documentation in the text form (note that you may
550 get better results using perl manpages).
551 Alternately, try running pod2text on .pod files.
553 Manpages
555 If you have man installed on your system, and you installed perl
556 manpages, use something like this:
557 man perlfunc
559 man 3 less
560 man ExtUtils.MakeMaker
561 to access documentation for different components of Perl. Start with
563 man perl
565 Note that dot (.) is used as a package separator for documentation for
567 packages, and as usual, sometimes you need to give the section - 3
568 above - to avoid shadowing by the less(1) manpage.
569 Make sure that the directory above the directory with manpages is on
571 our "MANPATH", like this
572 set MANPATH=c:/man;f:/perllib/man
574 for Perl manpages in "f:/perllib/man/man1/" etc.
576 HTML
578 If you have some WWW browser available, installed the Perl
579 documentation in the source form, and Perl utilities, you can build
580 HTML docs. Cd to directory with .pod files, and do like this
581 cd f:/perllib/lib/pod
583 pod2html
584 After this you can direct your browser the file perl.html in this
586 directory, and go ahead with reading docs, like this:
587 explore file:///f:/perllib/lib/pod/perl.html
589 Alternatively you may be able to get these docs prebuilt from CPAN.
591 GNU "info" files
593 Users of Emacs would appreciate it very much, especially with "CPerl"
594 mode loaded. You need to get latest "pod2texi" from "CPAN", or,
595 alternately, the prebuilt info pages.
596 PDF files
598 for "Acrobat" are available on CPAN (may be for slightly older version
599 of perl).
600 "LaTeX" docs
602 can be constructed using "pod2latex".
603
605 Here we discuss how to build Perl under OS/2. There is an alternative
606 (but maybe older) view on <http://www.shadow.net/~troc/os2perl.html>.
607 The short story
609 Assume that you are a seasoned porter, so are sure that all the
610 necessary tools are already present on your system, and you know how to
611 get the Perl source distribution. Untar it, change to the extract
612 directory, and
613 gnupatch -p0 < os2\diff.configure
615 sh Configure -des -D prefix=f:/perllib
616 make
617 make test
618 make install
619 make aout_test
620 make aout_install
621 This puts the executables in f:/perllib/bin. Manually move them to the
623 "PATH", manually move the built perl*.dll to "LIBPATH" (here for Perl
624 DLL * is a not-very-meaningful hex checksum), and run
625 make installcmd INSTALLCMDDIR=d:/ir/on/path
627 Assuming that the "man"-files were put on an appropriate location, this
629 completes the installation of minimal Perl system. (The binary
630 distribution contains also a lot of additional modules, and the
631 documentation in INF format.)
632 What follows is a detailed guide through these steps.
634 Prerequisites
636 You need to have the latest EMX development environment, the full GNU
637 tool suite (gawk renamed to awk, and GNU find.exe earlier on path than
638 the OS/2 find.exe, same with sort.exe, to check use
639 find --version
641 sort --version
642 ). You need the latest version of pdksh installed as sh.exe.
644 Check that you have BSD libraries and headers installed, and -
646 optionally - Berkeley DB headers and libraries, and crypt.
647 Possible locations to get the files:
649 ftp://hobbes.nmsu.edu/os2/unix/
651 ftp://ftp.cdrom.com/pub/os2/unix/
652 ftp://ftp.cdrom.com/pub/os2/dev32/
653 ftp://ftp.cdrom.com/pub/os2/emx09c/
654 It is reported that the following archives contain enough utils to
656 build perl: gnufutil.zip, gnusutil.zip, gnututil.zip, gnused.zip,
657 gnupatch.zip, gnuawk.zip, gnumake.zip, gnugrep.zip, bsddev.zip and
658 ksh527rt.zip (or a later version). Note that all these utilities are
659 known to be available from LEO:
660 ftp://ftp.leo.org/pub/comp/os/os2/leo/gnu
662 Note also that the db.lib and db.a from the EMX distribution are not
664 suitable for multi-threaded compile (even single-threaded flavor of
665 Perl uses multi-threaded C RTL, for compatibility with XFree86-OS/2).
666 Get a corrected one from
667 http://www.ilyaz.org/software/os2/db_mt.zip
669 If you have exactly the same version of Perl installed already, make
671 sure that no copies or perl are currently running. Later steps of the
672 build may fail since an older version of perl.dll loaded into memory
673 may be found. Running "make test" becomes meaningless, since the test
674 are checking a previous build of perl (this situation is detected and
675 reported by lib/os2_base.t test). Do not forget to unset
676 "PERL_EMXLOAD_SEC" in environment.
677 Also make sure that you have /tmp directory on the current drive, and .
679 directory in your "LIBPATH". One may try to correct the latter
680 condition by
681 set BEGINLIBPATH .\.
683 if you use something like CMD.EXE or latest versions of 4os2.exe.
685 (Setting BEGINLIBPATH to just "." is ignored by the OS/2 kernel.)
686 Make sure your gcc is good for "-Zomf" linking: run "omflibs" script in
688 /emx/lib directory.
689 Check that you have link386 installed. It comes standard with OS/2, but
691 may be not installed due to customization. If typing
692 link386
694 shows you do not have it, do Selective install, and choose "Link object
696 modules" in Optional system utilities/More. If you get into link386
697 prompts, press "Ctrl-C" to exit.
698 Getting perl source
700 You need to fetch the latest perl source (including developers
701 releases). With some probability it is located in
702 http://www.cpan.org/src/5.0
704 http://www.cpan.org/src/5.0/unsupported
705 If not, you may need to dig in the indices to find it in the directory
707 of the current maintainer.
708 Quick cycle of developers release may break the OS/2 build time to
710 time, looking into
711 http://www.cpan.org/ports/os2/
713 may indicate the latest release which was publicly released by the
715 maintainer. Note that the release may include some additional patches
716 to apply to the current source of perl.
717 Extract it like this
719 tar vzxf perl5.00409.tar.gz
721 You may see a message about errors while extracting Configure. This is
723 because there is a conflict with a similarly-named file configure.
724 Change to the directory of extraction.
726 Application of the patches
728 You need to apply the patches in ./os2/diff.* like this:
729 gnupatch -p0 < os2\diff.configure
731 You may also need to apply the patches supplied with the binary
733 distribution of perl. It also makes sense to look on the perl5-porters
734 mailing list for the latest OS/2-related patches (see
735 <http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/>). Such
736 patches usually contain strings "/os2/" and "patch", so it makes sense
737 looking for these strings.
738 Hand-editing
740 You may look into the file ./hints/os2.sh and correct anything wrong
741 you find there. I do not expect it is needed anywhere.
742 Making
744 sh Configure -des -D prefix=f:/perllib
745 "prefix" means: where to install the resulting perl library. Giving
747 correct prefix you may avoid the need to specify "PERLLIB_PREFIX", see
748 "PERLLIB_PREFIX".
749 Ignore the message about missing "ln", and about "-c" option to tr. The
751 latter is most probably already fixed, if you see it and can trace
752 where the latter spurious warning comes from, please inform me.
753 Now
755 make
757 At some moment the built may die, reporting a version mismatch or
759 unable to run perl. This means that you do not have . in your LIBPATH,
760 so perl.exe cannot find the needed perl67B2.dll (treat these hex digits
761 as line noise). After this is fixed the build should finish without a
762 lot of fuss.
763 Testing
765 Now run
766 make test
768 All tests should succeed (with some of them skipped). If you have the
770 same version of Perl installed, it is crucial that you have "." early
771 in your LIBPATH (or in BEGINLIBPATH), otherwise your tests will most
772 probably test the wrong version of Perl.
773 Some tests may generate extra messages similar to
775 A lot of "bad free"
777 in database tests related to Berkeley DB. This should be fixed
778 already. If it persists, you may disable this warnings, see
779 "PERL_BADFREE".
780 Process terminated by SIGTERM/SIGINT
782 This is a standard message issued by OS/2 applications. *nix
783 applications die in silence. It is considered to be a feature. One
784 can easily disable this by appropriate sighandlers.
785 However the test engine bleeds these message to screen in
787 unexpected moments. Two messages of this kind should be present
788 during testing.
789 To get finer test reports, call
791 perl t/harness
793 The report with io/pipe.t failing may look like this:
795 Failed Test Status Wstat Total Fail Failed List of failed
797 ------------------------------------------------------------
798 io/pipe.t 12 1 8.33% 9
799 7 tests skipped, plus 56 subtests skipped.
800 Failed 1/195 test scripts, 99.49% okay. 1/6542 subtests failed, 99.98% okay.
801 The reasons for most important skipped tests are:
803 op/fs.t
805 18 Checks "atime" and "mtime" of "stat()" - unfortunately,
806 HPFS provides only 2sec time granularity (for compatibility
807 with FAT?).
808 25 Checks "truncate()" on a filehandle just opened for write -
810 I do not know why this should or should not work.
811 op/stat.t
813 Checks "stat()". Tests:
814 4 Checks "atime" and "mtime" of "stat()" - unfortunately,
816 HPFS provides only 2sec time granularity (for compatibility
817 with FAT?).
818 Installing the built perl
820 If you haven't yet moved "perl*.dll" onto LIBPATH, do it now.
821 Run
823 make install
825 It would put the generated files into needed locations. Manually put
827 perl.exe, perl__.exe and perl___.exe to a location on your PATH,
828 perl.dll to a location on your LIBPATH.
829 Run
831 make installcmd INSTALLCMDDIR=d:/ir/on/path
833 to convert perl utilities to .cmd files and put them on PATH. You need
835 to put .EXE-utilities on path manually. They are installed in
836 "$prefix/bin", here $prefix is what you gave to Configure, see Making.
837 If you use "man", either move the installed */man/ directories to your
839 "MANPATH", or modify "MANPATH" to match the location. (One could have
840 avoided this by providing a correct "manpath" option to ./Configure, or
841 editing ./config.sh between configuring and making steps.)
842 "a.out"-style build
844 Proceed as above, but make perl_.exe (see "perl_.exe") by
845 make perl_
847 test and install by
849 make aout_test
851 make aout_install
852 Manually put perl_.exe to a location on your PATH.
854 Note. The build process for "perl_" does not know about all the
856 dependencies, so you should make sure that anything is up-to-date, say,
857 by doing
858 make perl_dll
860 first.
862
864 [This section provides a short overview only...]
865 Building should proceed differently depending on whether the version of
867 perl you install is already present and used on your system, or is a
868 new version not yet used. The description below assumes that the
869 version is new, so installing its DLLs and .pm files will not disrupt
870 the operation of your system even if some intermediate steps are not
871 yet fully working.
872 The other cases require a little bit more convoluted procedures. Below
874 I suppose that the current version of Perl is 5.8.2, so the executables
875 are named accordingly.
876 1. Fully build and test the Perl distribution. Make sure that no
878 tests are failing with "test" and "aout_test" targets; fix the bugs
879 in Perl and the Perl test suite detected by these tests. Make sure
880 that "all_test" make target runs as clean as possible. Check that
881 "os2/perlrexx.cmd" runs fine.
882 2. Fully install Perl, including "installcmd" target. Copy the
884 generated DLLs to "LIBPATH"; copy the numbered Perl executables (as
885 in perl5.8.2.exe) to "PATH"; copy "perl_.exe" to "PATH" as
886 "perl_5.8.2.exe". Think whether you need backward-compatibility
887 DLLs. In most cases you do not need to install them yet; but
888 sometime this may simplify the following steps.
889 3. Make sure that "CPAN.pm" can download files from CPAN. If not, you
891 may need to manually install "Net::FTP".
892 4. Install the bundle "Bundle::OS2_default"
894 perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_1
896 This may take a couple of hours on 1GHz processor (when run the
898 first time). And this should not be necessarily a smooth
899 procedure. Some modules may not specify required dependencies, so
900 one may need to repeat this procedure several times until the
901 results stabilize.
902 perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_2
904 perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_3
905 Even after they stabilize, some tests may fail.
907 Fix as many discovered bugs as possible. Document all the bugs
909 which are not fixed, and all the failures with unknown reasons.
910 Inspect the produced logs 00cpan_i_1 to find suspiciously skipped
911 tests, and other fishy events.
912 Keep in mind that installation of some modules may fail too: for
914 example, the DLLs to update may be already loaded by CPAN.pm.
915 Inspect the "install" logs (in the example above 00cpan_i_1 etc)
916 for errors, and install things manually, as in
917 cd $CPANHOME/.cpan/build/Digest-MD5-2.31
919 make install
920 Some distributions may fail some tests, but you may want to install
922 them anyway (as above, or via "force install" command of "CPAN.pm"
923 shell-mode).
924 Since this procedure may take quite a long time to complete, it
926 makes sense to "freeze" your CPAN configuration by disabling
927 periodic updates of the local copy of CPAN index: set
928 "index_expire" to some big value (I use 365), then save the
929 settings
930 CPAN> o conf index_expire 365
932 CPAN> o conf commit
933 Reset back to the default value 1 when you are finished.
935 5. When satisfied with the results, rerun the "installcmd" target.
937 Now you can copy "perl5.8.2.exe" to "perl.exe", and install the
938 other OMF-build executables: "perl__.exe" etc. They are ready to
939 be used.
940 6. Change to the "./pod" directory of the build tree, download the
942 Perl logo CamelGrayBig.BMP, and run
943 ( perl2ipf > perl.ipf ) |& tee 00ipf
945 ipfc /INF perl.ipf |& tee 00inf
946 This produces the Perl docs online book "perl.INF". Install in on
948 "BOOKSHELF" path.
949 7. Now is the time to build statically linked executable perl_.exe
951 which includes newly-installed via "Bundle::OS2_default" modules.
952 Doing testing via "CPAN.pm" is going to be painfully slow, since it
953 statically links a new executable per XS extension.
954 Here is a possible workaround: create a toplevel Makefile.PL in
956 $CPANHOME/.cpan/build/ with contents being (compare with "Making
957 executables with a custom collection of statically loaded
958 extensions")
959 use ExtUtils::MakeMaker;
961 WriteMakefile NAME => 'dummy';
962 execute this as
964 perl_5.8.2.exe Makefile.PL <nul |& tee 00aout_c1
966 make -k all test <nul |& 00aout_t1
967 Again, this procedure should not be absolutely smooth. Some
969 "Makefile.PL"'s in subdirectories may be buggy, and would not run
970 as "child" scripts. The interdependency of modules can strike you;
971 however, since non-XS modules are already installed, the
972 prerequisites of most modules have a very good chance to be
973 present.
974 If you discover some glitches, move directories of problematic
976 modules to a different location; if these modules are non-XS
977 modules, you may just ignore them - they are already installed; the
978 remaining, XS, modules you need to install manually one by one.
979 After each such removal you need to rerun the "Makefile.PL"/"make"
981 process; usually this procedure converges soon. (But be sure to
982 convert all the necessary external C libraries from .lib format to
983 .a format: run one of
984 emxaout foo.lib
986 emximp -o foo.a foo.lib
987 whichever is appropriate.) Also, make sure that the DLLs for
989 external libraries are usable with with executables compiled
990 without "-Zmtd" options.
991 When you are sure that only a few subdirectories lead to failures,
993 you may want to add "-j4" option to "make" to speed up skipping
994 subdirectories with already finished build.
995 When you are satisfied with the results of tests, install the build
997 C libraries for extensions:
998 make install |& tee 00aout_i
1000 Now you can rename the file ./perl.exe generated during the last
1002 phase to perl_5.8.2.exe; place it on "PATH"; if there is an inter-
1003 dependency between some XS modules, you may need to repeat the
1004 "test"/"install" loop with this new executable and some excluded
1005 modules - until the procedure converges.
1006 Now you have all the necessary .a libraries for these Perl modules
1008 in the places where Perl builder can find it. Use the perl
1009 builder: change to an empty directory, create a "dummy" Makefile.PL
1010 again, and run
1011 perl_5.8.2.exe Makefile.PL |& tee 00c
1013 make perl |& tee 00p
1014 This should create an executable ./perl.exe with all the statically
1016 loaded extensions built in. Compare the generated perlmain.c files
1017 to make sure that during the iterations the number of loaded
1018 extensions only increases. Rename ./perl.exe to perl_5.8.2.exe on
1019 "PATH".
1020 When it converges, you got a functional variant of perl_5.8.2.exe;
1022 copy it to "perl_.exe". You are done with generation of the local
1023 Perl installation.
1024 8. Make sure that the installed modules are actually installed in the
1026 location of the new Perl, and are not inherited from entries of
1027 @INC given for inheritance from the older versions of Perl: set
1028 "PERLLIB_582_PREFIX" to redirect the new version of Perl to a new
1029 location, and copy the installed files to this new location. Redo
1030 the tests to make sure that the versions of modules inherited from
1031 older versions of Perl are not needed.
1032 Actually, the log output of pod2ipf during the step 6 gives a very
1034 detailed info about which modules are loaded from which place; so
1035 you may use it as an additional verification tool.
1036 Check that some temporary files did not make into the perl install
1038 tree. Run something like this
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
1041 in the install tree (both top one and sitelib one).
1043 Compress all the DLLs with lxlite. The tiny .exe can be compressed
1045 with "/c:max" (the bug only appears when there is a fixup in the
1046 last 6 bytes of a page (?); since the tiny executables are much
1047 smaller than a page, the bug will not hit). Do not compress
1048 "perl_.exe" - it would not work under DOS.
1049 9. Now you can generate the binary distribution. This is done by
1051 running the test of the CPAN distribution "OS2::SoftInstaller".
1052 Tune up the file test.pl to suit the layout of current version of
1053 Perl first. Do not forget to pack the necessary external DLLs
1054 accordingly. Include the description of the bugs and test suite
1055 failures you could not fix. Include the small-stack versions of
1056 Perl executables from Perl build directory.
1057 Include perl5.def so that people can relink the perl DLL preserving
1059 the binary compatibility, or can create compatibility DLLs.
1060 Include the diff files ("diff -pu old new") of fixes you did so
1061 that people can rebuild your version. Include perl5.map so that
1062 one can use remote debugging.
1063 10. Share what you did with the other people. Relax. Enjoy fruits of
1065 your work.
1066 11. Brace yourself for thanks, bug reports, hate mail and spam coming
1068 as result of the previous step. No good deed should remain
1069 unpunished!
1070
1072 The Perl executables can be easily rebuilt at any moment. Moreover,
1073 one can use the embedding interface (see perlembed) to make very
1074 customized executables.
1075 Making executables with a custom collection of statically loaded extensions
1077 It is a little bit easier to do so while decreasing the list of
1078 statically loaded extensions. We discuss this case only here.
1079 1. Change to an empty directory, and create a placeholder
1081 <Makefile.PL>:
1082 use ExtUtils::MakeMaker;
1084 WriteMakefile NAME => 'dummy';
1085 2. Run it with the flavor of Perl (perl.exe or perl_.exe) you want to
1087 rebuild.
1088 perl_ Makefile.PL
1090 3. Ask it to create new Perl executable:
1092 make perl
1094 (you may need to manually add "PERLTYPE=-DPERL_CORE" to this
1096 commandline on some versions of Perl; the symptom is that the
1097 command-line globbing does not work from OS/2 shells with the
1098 newly-compiled executable; check with
1099 .\perl.exe -wle "print for @ARGV" *
1101 ).
1103 4. The previous step created perlmain.c which contains a list of
1105 newXS() calls near the end. Removing unnecessary calls, and
1106 rerunning
1107 make perl
1109 will produce a customized executable.
1111 Making executables with a custom search-paths
1113 The default perl executable is flexible enough to support most usages.
1114 However, one may want something yet more flexible; for example, one may
1115 want to find Perl DLL relatively to the location of the EXE file; or
1116 one may want to ignore the environment when setting the Perl-library
1117 search patch, etc.
1118 If you fill comfortable with embedding interface (see perlembed), such
1120 things are easy to do repeating the steps outlined in "Making
1121 executables with a custom collection of statically loaded extensions",
1122 and doing more comprehensive edits to main() of perlmain.c. The people
1123 with little desire to understand Perl can just rename main(), and do
1124 necessary modification in a custom main() which calls the renamed
1125 function in appropriate time.
1126 However, there is a third way: perl DLL exports the main() function and
1128 several callbacks to customize the search path. Below is a complete
1129 example of a "Perl loader" which
1130 1. Looks for Perl DLL in the directory "$exedir/../dll";
1132 2. Prepends the above directory to "BEGINLIBPATH";
1134 3. Fails if the Perl DLL found via "BEGINLIBPATH" is different from
1136 what was loaded on step 1; e.g., another process could have loaded
1137 it from "LIBPATH" or from a different value of "BEGINLIBPATH". In
1138 these cases one needs to modify the setting of the system so that
1139 this other process either does not run, or loads the DLL from
1140 "BEGINLIBPATH" with "LIBPATHSTRICT=T" (available with kernels after
1141 September 2000).
1142 4. Loads Perl library from "$exedir/../dll/lib/".
1144 5. Uses Bourne shell from "$exedir/../dll/sh/ksh.exe".
1146 For best results compile the C file below with the same options as the
1148 Perl DLL. However, a lot of functionality will work even if the
1149 executable is not an EMX applications, e.g., if compiled with
1150 gcc -Wall -DDOSISH -DOS2=1 -O2 -s -Zomf -Zsys perl-starter.c -DPERL_DLL_BASENAME=\"perl312F\" -Zstack 8192 -Zlinker /PM:VIO
1152 Here is the sample C file:
1154 #define INCL_DOS
1156 #define INCL_NOPM
1157 /* These are needed for compile if os2.h includes os2tk.h, not os2emx.h */
1158 #define INCL_DOSPROCESS
1159 #include <os2.h>
1160 #include "EXTERN.h"
1162 #define PERL_IN_MINIPERLMAIN_C
1163 #include "perl.h"
1164 static char *me;
1166 HMODULE handle;
1167 static void
1169 die_with(char *msg1, char *msg2, char *msg3, char *msg4)
1170 {
1171 ULONG c;
1172 char *s = " error: ";
1173 DosWrite(2, me, strlen(me), &c);
1175 DosWrite(2, s, strlen(s), &c);
1176 DosWrite(2, msg1, strlen(msg1), &c);
1177 DosWrite(2, msg2, strlen(msg2), &c);
1178 DosWrite(2, msg3, strlen(msg3), &c);
1179 DosWrite(2, msg4, strlen(msg4), &c);
1180 DosWrite(2, "\r\n", 2, &c);
1181 exit(255);
1182 }
1183 typedef ULONG (*fill_extLibpath_t)(int type, char *pre, char *post, int replace, char *msg);
1185 typedef int (*main_t)(int type, char *argv[], char *env[]);
1186 typedef int (*handler_t)(void* data, int which);
1187 #ifndef PERL_DLL_BASENAME
1189 # define PERL_DLL_BASENAME "perl"
1190 #endif
1191 static HMODULE
1193 load_perl_dll(char *basename)
1194 {
1195 char buf[300], fail[260];
1196 STRLEN l, dirl;
1197 fill_extLibpath_t f;
1198 ULONG rc_fullname;
1199 HMODULE handle, handle1;
1200 if (_execname(buf, sizeof(buf) - 13) != 0)
1202 die_with("Can't find full path: ", strerror(errno), "", "");
1203 /* XXXX Fill `me' with new value */
1204 l = strlen(buf);
1205 while (l && buf[l-1] != '/' && buf[l-1] != '\\')
1206 l--;
1207 dirl = l - 1;
1208 strcpy(buf + l, basename);
1209 l += strlen(basename);
1210 strcpy(buf + l, ".dll");
1211 if ( (rc_fullname = DosLoadModule(fail, sizeof fail, buf, &handle)) != 0
1212 && DosLoadModule(fail, sizeof fail, basename, &handle) != 0 )
1213 die_with("Can't load DLL ", buf, "", "");
1214 if (rc_fullname)
1215 return handle; /* was loaded with short name; all is fine */
1216 if (DosQueryProcAddr(handle, 0, "fill_extLibpath", (PFN*)&f))
1217 die_with(buf, ": DLL exports no symbol ", "fill_extLibpath", "");
1218 buf[dirl] = 0;
1219 if (f(0 /*BEGINLIBPATH*/, buf /* prepend */, NULL /* append */,
1220 0 /* keep old value */, me))
1221 die_with(me, ": prepending BEGINLIBPATH", "", "");
1222 if (DosLoadModule(fail, sizeof fail, basename, &handle1) != 0)
1223 die_with(me, ": finding perl DLL again via BEGINLIBPATH", "", "");
1224 buf[dirl] = '\\';
1225 if (handle1 != handle) {
1226 if (DosQueryModuleName(handle1, sizeof(fail), fail))
1227 strcpy(fail, "???");
1228 die_with(buf, ":\n\tperl DLL via BEGINLIBPATH is different: \n\t",
1229 fail,
1230 "\n\tYou may need to manipulate global BEGINLIBPATH and LIBPATHSTRICT"
1231 "\n\tso that the other copy is loaded via BEGINLIBPATH.");
1232 }
1233 return handle;
1234 }
1235 int
1237 main(int argc, char **argv, char **env)
1238 {
1239 main_t f;
1240 handler_t h;
1241 me = argv[0];
1243 /**/
1244 handle = load_perl_dll(PERL_DLL_BASENAME);
1245 if (DosQueryProcAddr(handle, 0, "Perl_OS2_handler_install", (PFN*)&h))
1247 die_with(PERL_DLL_BASENAME, ": DLL exports no symbol ", "Perl_OS2_handler_install", "");
1248 if ( !h((void *)"~installprefix", Perlos2_handler_perllib_from)
1249 || !h((void *)"~dll", Perlos2_handler_perllib_to)
1250 || !h((void *)"~dll/sh/ksh.exe", Perlos2_handler_perl_sh) )
1251 die_with(PERL_DLL_BASENAME, ": Can't install @INC manglers", "", "");
1252 if (DosQueryProcAddr(handle, 0, "dll_perlmain", (PFN*)&f))
1254 die_with(PERL_DLL_BASENAME, ": DLL exports no symbol ", "dll_perlmain", "");
1255 return f(argc, argv, env);
1256 }
1257
1259 Some "/" became "\" in pdksh.
1260 You have a very old pdksh. See Prerequisites.
1261 'errno' - unresolved external
1263 You do not have MT-safe db.lib. See Prerequisites.
1264 Problems with tr or sed
1266 reported with very old version of tr and sed.
1267 Some problem (forget which ;-)
1269 You have an older version of perl.dll on your LIBPATH, which broke the
1270 build of extensions.
1271 Library ... not found
1273 You did not run "omflibs". See Prerequisites.
1274 Segfault in make
1276 You use an old version of GNU make. See Prerequisites.
1277 op/sprintf test failure
1279 This can result from a bug in emx sprintf which was fixed in 0.9d fix
1280 03.
1281
1283 "setpriority", "getpriority"
1284 Note that these functions are compatible with *nix, not with the older
1285 ports of '94 - 95. The priorities are absolute, go from 32 to -95,
1286 lower is quicker. 0 is the default priority.
1287 WARNING. Calling "getpriority" on a non-existing process could lock
1289 the system before Warp3 fixpak22. Starting with Warp3, Perl will use a
1290 workaround: it aborts getpriority() if the process is not present.
1291 This is not possible on older versions "2.*", and has a race condition
1292 anyway.
1293 "system()"
1295 Multi-argument form of "system()" allows an additional numeric
1296 argument. The meaning of this argument is described in OS2::Process.
1297 When finding a program to run, Perl first asks the OS to look for
1299 executables on "PATH" (OS/2 adds extension .exe if no extension is
1300 present). If not found, it looks for a script with possible extensions
1301 added in this order: no extension, .cmd, .btm, .bat, .pl. If found,
1302 Perl checks the start of the file for magic strings "#!" and "extproc
1303 ". If found, Perl uses the rest of the first line as the beginning of
1304 the command line to run this script. The only mangling done to the
1305 first line is extraction of arguments (currently up to 3), and ignoring
1306 of the path-part of the "interpreter" name if it can't be found using
1307 the full path.
1308 E.g., "system 'foo', 'bar', 'baz'" may lead Perl to finding
1310 C:/emx/bin/foo.cmd with the first line being
1311 extproc /bin/bash -x -c
1313 If /bin/bash.exe is not found, then Perl looks for an executable
1315 bash.exe on "PATH". If found in C:/emx.add/bin/bash.exe, then the
1316 above system() is translated to
1317 system qw(C:/emx.add/bin/bash.exe -x -c C:/emx/bin/foo.cmd bar baz)
1319 One additional translation is performed: instead of /bin/sh Perl uses
1321 the hardwired-or-customized shell (see "PERL_SH_DIR").
1322 The above search for "interpreter" is recursive: if bash executable is
1324 not found, but bash.btm is found, Perl will investigate its first line
1325 etc. The only hardwired limit on the recursion depth is implicit:
1326 there is a limit 4 on the number of additional arguments inserted
1327 before the actual arguments given to system(). In particular, if no
1328 additional arguments are specified on the "magic" first lines, then the
1329 limit on the depth is 4.
1330 If Perl finds that the found executable is of PM type when the current
1332 session is not, it will start the new process in a separate session of
1333 necessary type. Call via "OS2::Process" to disable this magic.
1334 WARNING. Due to the described logic, you need to explicitly specify
1336 .com extension if needed. Moreover, if the executable perl5.6.1 is
1337 requested, Perl will not look for perl5.6.1.exe. [This may change in
1338 the future.]
1339 "extproc" on the first line
1341 If the first chars of a Perl script are "extproc ", this line is
1342 treated as "#!"-line, thus all the switches on this line are processed
1343 (twice if script was started via cmd.exe). See "DESCRIPTION" in
1344 perlrun.
1345 Additional modules:
1347 OS2::Process, OS2::DLL, OS2::REXX, OS2::PrfDB, OS2::ExtAttr. These
1348 modules provide access to additional numeric argument for "system" and
1349 to the information about the running process, to DLLs having functions
1350 with REXX signature and to the REXX runtime, to OS/2 databases in the
1351 .INI format, and to Extended Attributes.
1352 Two additional extensions by Andreas Kaiser, "OS2::UPM", and
1354 "OS2::FTP", are included into "ILYAZ" directory, mirrored on CPAN.
1355 Other OS/2-related extensions are available too.
1356 Prebuilt methods:
1358 "File::Copy::syscopy"
1359 used by "File::Copy::copy", see File::Copy.
1360 "DynaLoader::mod2fname"
1362 used by "DynaLoader" for DLL name mangling.
1363 "Cwd::current_drive()"
1365 Self explanatory.
1366 "Cwd::sys_chdir(name)"
1368 leaves drive as it is.
1369 "Cwd::change_drive(name)"
1371 chanes the "current" drive.
1372 "Cwd::sys_is_absolute(name)"
1374 means has drive letter and is_rooted.
1375 "Cwd::sys_is_rooted(name)"
1377 means has leading "[/\\]" (maybe after a drive-letter:).
1378 "Cwd::sys_is_relative(name)"
1380 means changes with current dir.
1381 "Cwd::sys_cwd(name)"
1383 Interface to cwd from EMX. Used by "Cwd::cwd".
1384 "Cwd::sys_abspath(name, dir)"
1386 Really really odious function to implement. Returns absolute name
1387 of file which would have "name" if CWD were "dir". "Dir" defaults
1388 to the current dir.
1389 "Cwd::extLibpath([type])"
1391 Get current value of extended library search path. If "type" is
1392 present and positive, works with "END_LIBPATH", if negative, works
1393 with "LIBPATHSTRICT", otherwise with "BEGIN_LIBPATH".
1394 "Cwd::extLibpath_set( path [, type ] )"
1396 Set current value of extended library search path. If "type" is
1397 present and positive, works with <END_LIBPATH>, if negative, works
1398 with "LIBPATHSTRICT", otherwise with "BEGIN_LIBPATH".
1399 "OS2::Error(do_harderror,do_exception)"
1401 Returns "undef" if it was not called yet, otherwise bit 1 is set
1402 if on the previous call do_harderror was enabled, bit 2 is set if
1403 on previous call do_exception was enabled.
1404 This function enables/disables error popups associated with
1406 hardware errors (Disk not ready etc.) and software exceptions.
1407 I know of no way to find out the state of popups before the first
1409 call to this function.
1410 "OS2::Errors2Drive(drive)"
1412 Returns "undef" if it was not called yet, otherwise return false if
1413 errors were not requested to be written to a hard drive, or the
1414 drive letter if this was requested.
1415 This function may redirect error popups associated with hardware
1417 errors (Disk not ready etc.) and software exceptions to the file
1418 POPUPLOG.OS2 at the root directory of the specified drive.
1419 Overrides OS2::Error() specified by individual programs. Given
1420 argument undef will disable redirection.
1421 Has global effect, persists after the application exits.
1423 I know of no way to find out the state of redirection of popups to
1425 the disk before the first call to this function.
1426 OS2::SysInfo()
1428 Returns a hash with system information. The keys of the hash are
1429 MAX_PATH_LENGTH, MAX_TEXT_SESSIONS, MAX_PM_SESSIONS,
1431 MAX_VDM_SESSIONS, BOOT_DRIVE, DYN_PRI_VARIATION,
1432 MAX_WAIT, MIN_SLICE, MAX_SLICE, PAGE_SIZE,
1433 VERSION_MAJOR, VERSION_MINOR, VERSION_REVISION,
1434 MS_COUNT, TIME_LOW, TIME_HIGH, TOTPHYSMEM, TOTRESMEM,
1435 TOTAVAILMEM, MAXPRMEM, MAXSHMEM, TIMER_INTERVAL,
1436 MAX_COMP_LENGTH, FOREGROUND_FS_SESSION,
1437 FOREGROUND_PROCESS
1438 OS2::BootDrive()
1440 Returns a letter without colon.
1441 "OS2::MorphPM(serve)", "OS2::UnMorphPM(serve)"
1443 Transforms the current application into a PM application and back.
1444 The argument true means that a real message loop is going to be
1445 served. OS2::MorphPM() returns the PM message queue handle as an
1446 integer.
1447 See "Centralized management of resources" for additional details.
1449 "OS2::Serve_Messages(force)"
1451 Fake on-demand retrieval of outstanding PM messages. If "force" is
1452 false, will not dispatch messages if a real message loop is known
1453 to be present. Returns number of messages retrieved.
1454 Dies with "QUITing..." if WM_QUIT message is obtained.
1456 "OS2::Process_Messages(force [, cnt])"
1458 Retrieval of PM messages until window creation/destruction. If
1459 "force" is false, will not dispatch messages if a real message loop
1460 is known to be present.
1461 Returns change in number of windows. If "cnt" is given, it is
1463 incremented by the number of messages retrieved.
1464 Dies with "QUITing..." if WM_QUIT message is obtained.
1466 "OS2::_control87(new,mask)"
1468 the same as _control87(3) of EMX. Takes integers as arguments,
1469 returns the previous coprocessor control word as an integer. Only
1470 bits in "new" which are present in "mask" are changed in the
1471 control word.
1472 OS2::get_control87()
1474 gets the coprocessor control word as an integer.
1475 "OS2::set_control87_em(new=MCW_EM,mask=MCW_EM)"
1477 The variant of OS2::_control87() with default values good for
1478 handling exception mask: if no "mask", uses exception mask part of
1479 "new" only. If no "new", disables all the floating point
1480 exceptions.
1481 See "Misfeatures" for details.
1483 "OS2::DLLname([how [, \&xsub]])"
1485 Gives the information about the Perl DLL or the DLL containing the
1486 C function bound to by &xsub. The meaning of "how" is: default
1487 (2): full name; 0: handle; 1: module name.
1488 (Note that some of these may be moved to different libraries -
1490 eventually).
1491 Prebuilt variables:
1493 $OS2::emx_rev
1494 numeric value is the same as _emx_rev of EMX, a string value the
1495 same as _emx_vprt (similar to "0.9c").
1496 $OS2::emx_env
1498 same as _emx_env of EMX, a number similar to 0x8001.
1499 $OS2::os_ver
1501 a number "OS_MAJOR + 0.001 * OS_MINOR".
1502 $OS2::is_aout
1504 true if the Perl library was compiled in AOUT format.
1505 $OS2::can_fork
1507 true if the current executable is an AOUT EMX executable, so Perl
1508 can fork. Do not use this, use the portable check for
1509 $Config::Config{dfork}.
1510 $OS2::nsyserror
1512 This variable (default is 1) controls whether to enforce the
1513 contents of $^E to start with "SYS0003"-like id. If set to 0, then
1514 the string value of $^E is what is available from the OS/2 message
1515 file. (Some messages in this file have an "SYS0003"-like id
1516 prepended, some not.)
1517 Misfeatures
1519 · Since flock(3) is present in EMX, but is not functional, it is
1520 emulated by perl. To disable the emulations, set environment
1521 variable "USE_PERL_FLOCK=0".
1522 · Here is the list of things which may be "broken" on EMX (from EMX
1524 docs):
1525 · The functions recvmsg(3), sendmsg(3), and socketpair(3) are not
1527 implemented.
1528 · sock_init(3) is not required and not implemented.
1530 · flock(3) is not yet implemented (dummy function). (Perl has a
1532 workaround.)
1533 · kill(3): Special treatment of PID=0, PID=1 and PID=-1 is not
1535 implemented.
1536 · waitpid(3):
1538 WUNTRACED
1540 Not implemented.
1541 waitpid() is not implemented for negative values of PID.
1542 Note that "kill -9" does not work with the current version of EMX.
1544 · See "Text-mode filehandles".
1546 · Unix-domain sockets on OS/2 live in a pseudo-file-system
1548 "/sockets/...". To avoid a failure to create a socket with a name
1549 of a different form, "/socket/" is prepended to the socket name
1550 (unless it starts with this already).
1551 This may lead to problems later in case the socket is accessed via
1553 the "usual" file-system calls using the "initial" name.
1554 · Apparently, IBM used a compiler (for some period of time around
1556 '95?) which changes FP mask right and left. This is not that bad
1557 for IBM's programs, but the same compiler was used for DLLs which
1558 are used with general-purpose applications. When these DLLs are
1559 used, the state of floating-point flags in the application is not
1560 predictable.
1561 What is much worse, some DLLs change the floating point flags when
1563 in _DLLInitTerm() (e.g., TCP32IP). This means that even if you do
1564 not call any function in the DLL, just the act of loading this DLL
1565 will reset your flags. What is worse, the same compiler was used
1566 to compile some HOOK DLLs. Given that HOOK dlls are executed in
1567 the context of all the applications in the system, this means a
1568 complete unpredictablity of floating point flags on systems using
1569 such HOOK DLLs. E.g., GAMESRVR.DLL of DIVE origin changes the
1570 floating point flags on each write to the TTY of a VIO (windowed
1571 text-mode) applications.
1572 Some other (not completely debugged) situations when FP flags
1574 change include some video drivers (?), and some operations related
1575 to creation of the windows. People who code OpenGL may have more
1576 experience on this.
1577 Perl is generally used in the situation when all the floating-point
1579 exceptions are ignored, as is the default under EMX. If they are
1580 not ignored, some benign Perl programs would get a "SIGFPE" and
1581 would die a horrible death.
1582 To circumvent this, Perl uses two hacks. They help against one
1584 type of damage only: FP flags changed when loading a DLL.
1585 One of the hacks is to disable floating point exceptions on Perl
1587 startup (as is the default with EMX). This helps only with
1588 compile-time-linked DLLs changing the flags before main() had a
1589 chance to be called.
1590 The other hack is to restore FP flags after a call to dlopen().
1592 This helps against similar damage done by DLLs _DLLInitTerm() at
1593 runtime. Currently no way to switch these hacks off is provided.
1594 Modifications
1596 Perl modifies some standard C library calls in the following ways:
1597 "popen" "my_popen" uses sh.exe if shell is required, cf.
1599 "PERL_SH_DIR".
1600 "tmpnam" is created using "TMP" or "TEMP" environment variable, via
1602 "tempnam".
1603 "tmpfile"
1605 If the current directory is not writable, file is created
1606 using modified "tmpnam", so there may be a race condition.
1607 "ctermid"
1609 a dummy implementation.
1610 "stat" "os2_stat" special-cases /dev/tty and /dev/con.
1612 "mkdir", "rmdir"
1614 these EMX functions do not work if the path contains a
1615 trailing "/". Perl contains a workaround for this.
1616 "flock" Since flock(3) is present in EMX, but is not functional, it is
1618 emulated by perl. To disable the emulations, set environment
1619 variable "USE_PERL_FLOCK=0".
1620 Identifying DLLs
1622 All the DLLs built with the current versions of Perl have ID strings
1623 identifying the name of the extension, its version, and the version of
1624 Perl required for this DLL. Run "bldlevel DLL-name" to find this info.
1625 Centralized management of resources
1627 Since to call certain OS/2 API one needs to have a correctly
1628 initialized "Win" subsystem, OS/2-specific extensions may require
1629 getting "HAB"s and "HMQ"s. If an extension would do it on its own,
1630 another extension could fail to initialize.
1631 Perl provides a centralized management of these resources:
1633 "HAB"
1635 To get the HAB, the extension should call "hab = perl_hab_GET()" in
1636 C. After this call is performed, "hab" may be accessed as
1637 "Perl_hab". There is no need to release the HAB after it is used.
1638 If by some reasons perl.h cannot be included, use
1640 extern int Perl_hab_GET(void);
1642 instead.
1644 "HMQ"
1646 There are two cases:
1647 · the extension needs an "HMQ" only because some API will not
1649 work otherwise. Use "serve = 0" below.
1650 · the extension needs an "HMQ" since it wants to engage in a PM
1652 event loop. Use "serve = 1" below.
1653 To get an "HMQ", the extension should call "hmq =
1655 perl_hmq_GET(serve)" in C. After this call is performed, "hmq" may
1656 be accessed as "Perl_hmq".
1657 To signal to Perl that HMQ is not needed any more, call
1659 "perl_hmq_UNSET(serve)". Perl process will automatically
1660 morph/unmorph itself into/from a PM process if HMQ is
1661 needed/not-needed. Perl will automatically enable/disable
1662 "WM_QUIT" message during shutdown if the message queue is
1663 served/not-served.
1664 NOTE. If during a shutdown there is a message queue which did not
1666 disable WM_QUIT, and which did not process the received WM_QUIT
1667 message, the shutdown will be automatically cancelled. Do not call
1668 perl_hmq_GET(1) unless you are going to process messages on an
1669 orderly basis.
1670 * Treating errors reported by OS/2 API
1672 There are two principal conventions (it is useful to call them
1673 "Dos*" and "Win*" - though this part of the function signature is
1674 not always determined by the name of the API) of reporting the
1675 error conditions of OS/2 API. Most of "Dos*" APIs report the error
1676 code as the result of the call (so 0 means success, and there are
1677 many types of errors). Most of "Win*" API report success/fail via
1678 the result being "TRUE"/"FALSE"; to find the reason for the failure
1679 one should call WinGetLastError() API.
1680 Some "Win*" entry points also overload a "meaningful" return value
1682 with the error indicator; having a 0 return value indicates an
1683 error. Yet some other "Win*" entry points overload things even
1684 more, and 0 return value may mean a successful call returning a
1685 valid value 0, as well as an error condition; in the case of a 0
1686 return value one should call WinGetLastError() API to distinguish a
1687 successful call from a failing one.
1688 By convention, all the calls to OS/2 API should indicate their
1690 failures by resetting $^E. All the Perl-accessible functions which
1691 call OS/2 API may be broken into two classes: some die()s when an
1692 API error is encountered, the other report the error via a false
1693 return value (of course, this does not concern Perl-accessible
1694 functions which expect a failure of the OS/2 API call, having some
1695 workarounds coded).
1696 Obviously, in the situation of the last type of the signature of an
1698 OS/2 API, it is must more convenient for the users if the failure
1699 is indicated by die()ing: one does not need to check $^E to know
1700 that something went wrong. If, however, this solution is not
1701 desirable by some reason, the code in question should reset $^E to
1702 0 before making this OS/2 API call, so that the caller of this
1703 Perl-accessible function has a chance to distinguish a
1704 success-but-0-return value from a failure. (One may return undef
1705 as an alternative way of reporting an error.)
1706 The macros to simplify this type of error propagation are
1708 "CheckOSError(expr)"
1710 Returns true on error, sets $^E. Expects expr() be a call of
1711 "Dos*"-style API.
1712 "CheckWinError(expr)"
1714 Returns true on error, sets $^E. Expects expr() be a call of
1715 "Win*"-style API.
1716 "SaveWinError(expr)"
1718 Returns "expr", sets $^E from WinGetLastError() if "expr" is
1719 false.
1720 "SaveCroakWinError(expr,die,name1,name2)"
1722 Returns "expr", sets $^E from WinGetLastError() if "expr" is
1723 false, and die()s if "die" and $^E are true. The message to
1724 die is the concatenated strings "name1" and "name2", separated
1725 by ": " from the contents of $^E.
1726 "WinError_2_Perl_rc"
1728 Sets "Perl_rc" to the return value of WinGetLastError().
1729 "FillWinError"
1731 Sets "Perl_rc" to the return value of WinGetLastError(), and
1732 sets $^E to the corresponding value.
1733 "FillOSError(rc)"
1735 Sets "Perl_rc" to "rc", and sets $^E to the corresponding
1736 value.
1737 * Loading DLLs and ordinals in DLLs
1739 Some DLLs are only present in some versions of OS/2, or in some
1740 configurations of OS/2. Some exported entry points are present
1741 only in DLLs shipped with some versions of OS/2. If these DLLs and
1742 entry points were linked directly for a Perl executable/DLL or from
1743 a Perl extensions, this binary would work only with the specified
1744 versions/setups. Even if these entry points were not needed, the
1745 load of the executable (or DLL) would fail.
1746 For example, many newer useful APIs are not present in OS/2 v2;
1748 many PM-related APIs require DLLs not available on floppy-boot
1749 setup.
1750 To make these calls fail only when the calls are executed, one
1752 should call these API via a dynamic linking API. There is a
1753 subsystem in Perl to simplify such type of calls. A large number
1754 of entry points available for such linking is provided (see
1755 "entries_ordinals" - and also "PMWIN_entries" - in os2ish.h).
1756 These ordinals can be accessed via the APIs:
1757 CallORD(), DeclFuncByORD(), DeclVoidFuncByORD(),
1759 DeclOSFuncByORD(), DeclWinFuncByORD(), AssignFuncPByORD(),
1760 DeclWinFuncByORD_CACHE(), DeclWinFuncByORD_CACHE_survive(),
1761 DeclWinFuncByORD_CACHE_resetError_survive(),
1762 DeclWinFunc_CACHE(), DeclWinFunc_CACHE_resetError(),
1763 DeclWinFunc_CACHE_survive(), DeclWinFunc_CACHE_resetError_survive()
1764 See the header files and the C code in the supplied OS/2-related
1766 modules for the details on usage of these functions.
1767 Some of these functions also combine dynaloading semantic with the
1769 error-propagation semantic discussed above.
1770
1772 Because of idiosyncrasies of OS/2 one cannot have all the eggs in the
1773 same basket (though EMX environment tries hard to overcome this
1774 limitations, so the situation may somehow improve). There are 4
1775 executables for Perl provided by the distribution:
1776 perl.exe
1778 The main workhorse. This is a chimera executable: it is compiled as an
1779 "a.out"-style executable, but is linked with "omf"-style dynamic
1780 library perl.dll, and with dynamic CRT DLL. This executable is a VIO
1781 application.
1782 It can load perl dynamic extensions, and it can fork().
1784 Note. Keep in mind that fork() is needed to open a pipe to yourself.
1786 perl_.exe
1788 This is a statically linked "a.out"-style executable. It cannot load
1789 dynamic Perl extensions. The executable supplied in binary
1790 distributions has a lot of extensions prebuilt, thus the above
1791 restriction is important only if you use custom-built extensions. This
1792 executable is a VIO application.
1793 This is the only executable with does not require OS/2. The friends
1795 locked into "M$" world would appreciate the fact that this executable
1796 runs under DOS, Win0.3*, Win0.95 and WinNT with an appropriate
1797 extender. See "Other OSes".
1798 perl__.exe
1800 This is the same executable as perl___.exe, but it is a PM application.
1801 Note. Usually (unless explicitly redirected during the startup) STDIN,
1803 STDERR, and STDOUT of a PM application are redirected to nul. However,
1804 it is possible to see them if you start "perl__.exe" from a PM program
1805 which emulates a console window, like Shell mode of Emacs or EPM. Thus
1806 it is possible to use Perl debugger (see perldebug) to debug your PM
1807 application (but beware of the message loop lockups - this will not
1808 work if you have a message queue to serve, unless you hook the serving
1809 into the getc() function of the debugger).
1810 Another way to see the output of a PM program is to run it as
1812 pm_prog args 2>&1 | cat -
1814 with a shell different from cmd.exe, so that it does not create a link
1816 between a VIO session and the session of "pm_porg". (Such a link
1817 closes the VIO window.) E.g., this works with sh.exe - or with Perl!
1818 open P, 'pm_prog args 2>&1 |' or die;
1820 print while <P>;
1821 The flavor perl__.exe is required if you want to start your program
1823 without a VIO window present, but not "detach"ed (run "help detach" for
1824 more info). Very useful for extensions which use PM, like "Perl/Tk" or
1825 "OpenGL".
1826 Note also that the differences between PM and VIO executables are only
1828 in the default behaviour. One can start any executable in any kind of
1829 session by using the arguments "/fs", "/pm" or "/win" switches of the
1830 command "start" (of CMD.EXE or a similar shell). Alternatively, one
1831 can use the numeric first argument of the "system" Perl function (see
1832 OS2::Process).
1833 perl___.exe
1835 This is an "omf"-style executable which is dynamically linked to
1836 perl.dll and CRT DLL. I know no advantages of this executable over
1837 "perl.exe", but it cannot fork() at all. Well, one advantage is that
1838 the build process is not so convoluted as with "perl.exe".
1839 It is a VIO application.
1841 Why strange names?
1843 Since Perl processes the "#!"-line (cf. "DESCRIPTION" in perlrun,
1844 "Switches" in perlrun, "Not a perl script" in perldiag, "No Perl script
1845 found in input" in perldiag), it should know when a program is a Perl.
1846 There is some naming convention which allows Perl to distinguish
1847 correct lines from wrong ones. The above names are almost the only
1848 names allowed by this convention which do not contain digits (which
1849 have absolutely different semantics).
1850 Why dynamic linking?
1852 Well, having several executables dynamically linked to the same huge
1853 library has its advantages, but this would not substantiate the
1854 additional work to make it compile. The reason is the complicated-to-
1855 developers but very quick and convenient-to-users "hard" dynamic
1856 linking used by OS/2.
1857 There are two distinctive features of the dyna-linking model of OS/2:
1859 first, all the references to external functions are resolved at the
1860 compile time; second, there is no runtime fixup of the DLLs after they
1861 are loaded into memory. The first feature is an enormous advantage
1862 over other models: it avoids conflicts when several DLLs used by an
1863 application export entries with the same name. In such cases "other"
1864 models of dyna-linking just choose between these two entry points using
1865 some random criterion - with predictable disasters as results. But it
1866 is the second feature which requires the build of perl.dll.
1867 The address tables of DLLs are patched only once, when they are loaded.
1869 The addresses of the entry points into DLLs are guaranteed to be the
1870 same for all the programs which use the same DLL. This removes the
1871 runtime fixup - once DLL is loaded, its code is read-only.
1872 While this allows some (significant?) performance advantages, this
1874 makes life much harder for developers, since the above scheme makes it
1875 impossible for a DLL to be "linked" to a symbol in the .EXE file.
1876 Indeed, this would need a DLL to have different relocations tables for
1877 the (different) executables which use this DLL.
1878 However, a dynamically loaded Perl extension is forced to use some
1880 symbols from the perl executable, e.g., to know how to find the
1881 arguments to the functions: the arguments live on the perl internal
1882 evaluation stack. The solution is to put the main code of the
1883 interpreter into a DLL, and make the .EXE file which just loads this
1884 DLL into memory and supplies command-arguments. The extension DLL
1885 cannot link to symbols in .EXE, but it has no problem linking to
1886 symbols in the .DLL.
1887 This greatly increases the load time for the application (as well as
1889 complexity of the compilation). Since interpreter is in a DLL, the C
1890 RTL is basically forced to reside in a DLL as well (otherwise
1891 extensions would not be able to use CRT). There are some advantages if
1892 you use different flavors of perl, such as running perl.exe and
1893 perl__.exe simultaneously: they share the memory of perl.dll.
1894 NOTE. There is one additional effect which makes DLLs more wasteful:
1896 DLLs are loaded in the shared memory region, which is a scarse resource
1897 given the 512M barrier of the "standard" OS/2 virtual memory. The code
1898 of .EXE files is also shared by all the processes which use the
1899 particular .EXE, but they are "shared in the private address space of
1900 the process"; this is possible because the address at which different
1901 sections of the .EXE file are loaded is decided at compile-time, thus
1902 all the processes have these sections loaded at same addresses, and no
1903 fixup of internal links inside the .EXE is needed.
1904 Since DLLs may be loaded at run time, to have the same mechanism for
1906 DLLs one needs to have the address range of any of the loaded DLLs in
1907 the system to be available in all the processes which did not load a
1908 particular DLL yet. This is why the DLLs are mapped to the shared
1909 memory region.
1910 Why chimera build?
1912 Current EMX environment does not allow DLLs compiled using Unixish
1913 "a.out" format to export symbols for data (or at least some types of
1914 data). This forces "omf"-style compile of perl.dll.
1915 Current EMX environment does not allow .EXE files compiled in "omf"
1917 format to fork(). fork() is needed for exactly three Perl operations:
1918 · explicit fork() in the script,
1920 · "open FH, "|-""
1922 · "open FH, "-|"", in other words, opening pipes to itself.
1924 While these operations are not questions of life and death, they are
1926 needed for a lot of useful scripts. This forces "a.out"-style compile
1927 of perl.exe.
1928
1930 Here we list environment variables with are either OS/2- and DOS- and
1931 Win*-specific, or are more important under OS/2 than under other OSes.
1932 "PERLLIB_PREFIX"
1934 Specific for EMX port. Should have the form
1935 path1;path2
1937 or
1939 path1 path2
1941 If the beginning of some prebuilt path matches path1, it is substituted
1943 with path2.
1944 Should be used if the perl library is moved from the default location
1946 in preference to "PERL(5)LIB", since this would not leave wrong entries
1947 in @INC. For example, if the compiled version of perl looks for @INC
1948 in f:/perllib/lib, and you want to install the library in h:/opt/gnu,
1949 do
1950 set PERLLIB_PREFIX=f:/perllib/lib;h:/opt/gnu
1952 This will cause Perl with the prebuilt @INC of
1954 f:/perllib/lib/5.00553/os2
1956 f:/perllib/lib/5.00553
1957 f:/perllib/lib/site_perl/5.00553/os2
1958 f:/perllib/lib/site_perl/5.00553
1959 .
1960 to use the following @INC:
1962 h:/opt/gnu/5.00553/os2
1964 h:/opt/gnu/5.00553
1965 h:/opt/gnu/site_perl/5.00553/os2
1966 h:/opt/gnu/site_perl/5.00553
1967 .
1968 "PERL_BADLANG"
1970 If 0, perl ignores setlocale() failing. May be useful with some strange
1971 locales.
1972 "PERL_BADFREE"
1974 If 0, perl would not warn of in case of unwarranted free(). With older
1975 perls this might be useful in conjunction with the module DB_File,
1976 which was buggy when dynamically linked and OMF-built.
1977 Should not be set with newer Perls, since this may hide some real
1979 problems.
1980 "PERL_SH_DIR"
1982 Specific for EMX port. Gives the directory part of the location for
1983 sh.exe.
1984 "USE_PERL_FLOCK"
1986 Specific for EMX port. Since flock(3) is present in EMX, but is not
1987 functional, it is emulated by perl. To disable the emulations, set
1988 environment variable "USE_PERL_FLOCK=0".
1989 "TMP" or "TEMP"
1991 Specific for EMX port. Used as storage place for temporary files.
1992
1994 Here we list major changes which could make you by surprise.
1995 Text-mode filehandles
1997 Starting from version 5.8, Perl uses a builtin translation layer for
1998 text-mode files. This replaces the efficient well-tested EMX layer by
1999 some code which should be best characterized as a "quick hack".
2000 In addition to possible bugs and an inability to follow changes to the
2002 translation policy with off/on switches of TERMIO translation, this
2003 introduces a serious incompatible change: before sysread() on text-mode
2004 filehandles would go through the translation layer, now it would not.
2005 Priorities
2007 "setpriority" and "getpriority" are not compatible with earlier ports
2008 by Andreas Kaiser. See "setpriority, getpriority".
2009 DLL name mangling: pre 5.6.2
2011 With the release 5.003_01 the dynamically loadable libraries should be
2012 rebuilt when a different version of Perl is compiled. In particular,
2013 DLLs (including perl.dll) are now created with the names which contain
2014 a checksum, thus allowing workaround for OS/2 scheme of caching DLLs.
2015 It may be possible to code a simple workaround which would
2017 · find the old DLLs looking through the old @INC;
2019 · mangle the names according to the scheme of new perl and copy the
2021 DLLs to these names;
2022 · edit the internal "LX" tables of DLL to reflect the change of the
2024 name (probably not needed for Perl extension DLLs, since the
2025 internally coded names are not used for "specific" DLLs, they used
2026 only for "global" DLLs).
2027 · edit the internal "IMPORT" tables and change the name of the "old"
2029 perl????.dll to the "new" perl????.dll.
2030 DLL name mangling: 5.6.2 and beyond
2032 In fact mangling of extension DLLs was done due to misunderstanding of
2033 the OS/2 dynaloading model. OS/2 (effectively) maintains two different
2034 tables of loaded DLL:
2035 Global DLLs
2037 those loaded by the base name from "LIBPATH"; including those
2038 associated at link time;
2039 specific DLLs
2041 loaded by the full name.
2042 When resolving a request for a global DLL, the table of already-loaded
2044 specific DLLs is (effectively) ignored; moreover, specific DLLs are
2045 always loaded from the prescribed path.
2046 There is/was a minor twist which makes this scheme fragile: what to do
2048 with DLLs loaded from
2049 "BEGINLIBPATH" and "ENDLIBPATH"
2051 (which depend on the process)
2052 . from "LIBPATH"
2054 which effectively depends on the process (although "LIBPATH" is the
2055 same for all the processes).
2056 Unless "LIBPATHSTRICT" is set to "T" (and the kernel is after
2058 2000/09/01), such DLLs are considered to be global. When loading a
2059 global DLL it is first looked in the table of already-loaded global
2060 DLLs. Because of this the fact that one executable loaded a DLL from
2061 "BEGINLIBPATH" and "ENDLIBPATH", or . from "LIBPATH" may affect which
2062 DLL is loaded when another executable requests a DLL with the same
2063 name. This is the reason for version-specific mangling of the DLL name
2064 for perl DLL.
2065 Since the Perl extension DLLs are always loaded with the full path,
2067 there is no need to mangle their names in a version-specific ways:
2068 their directory already reflects the corresponding version of perl, and
2069 @INC takes into account binary compatibility with older version.
2070 Starting from 5.6.2 the name mangling scheme is fixed to be the same as
2071 for Perl 5.005_53 (same as in a popular binary release). Thus new
2072 Perls will be able to resolve the names of old extension DLLs if @INC
2073 allows finding their directories.
2074 However, this still does not guarantee that these DLL may be loaded.
2076 The reason is the mangling of the name of the Perl DLL. And since the
2077 extension DLLs link with the Perl DLL, extension DLLs for older
2078 versions would load an older Perl DLL, and would most probably segfault
2079 (since the data in this DLL is not properly initialized).
2080 There is a partial workaround (which can be made complete with newer
2082 OS/2 kernels): create a forwarder DLL with the same name as the DLL of
2083 the older version of Perl, which forwards the entry points to the newer
2084 Perl's DLL. Make this DLL accessible on (say) the "BEGINLIBPATH" of
2085 the new Perl executable. When the new executable accesses old Perl's
2086 extension DLLs, they would request the old Perl's DLL by name, get the
2087 forwarder instead, so effectively will link with the currently running
2088 (new) Perl DLL.
2089 This may break in two ways:
2091 · Old perl executable is started when a new executable is running has
2093 loaded an extension compiled for the old executable (ouph!). In
2094 this case the old executable will get a forwarder DLL instead of
2095 the old perl DLL, so would link with the new perl DLL. While not
2096 directly fatal, it will behave the same as new executable. This
2097 beats the whole purpose of explicitly starting an old executable.
2098 · A new executable loads an extension compiled for the old executable
2100 when an old perl executable is running. In this case the extension
2101 will not pick up the forwarder - with fatal results.
2102 With support for "LIBPATHSTRICT" this may be circumvented - unless one
2104 of DLLs is started from . from "LIBPATH" (I do not know whether
2105 "LIBPATHSTRICT" affects this case).
2106 REMARK. Unless newer kernels allow . in "BEGINLIBPATH" (older do not),
2108 this mess cannot be completely cleaned. (It turns out that as of the
2109 beginning of 2002, . is not allowed, but .\. is - and it has the same
2110 effect.)
2111 REMARK. "LIBPATHSTRICT", "BEGINLIBPATH" and "ENDLIBPATH" are not
2113 environment variables, although cmd.exe emulates them on "SET ..."
2114 lines. From Perl they may be accessed by Cwd::extLibpath and
2115 Cwd::extLibpath_set.
2116 DLL forwarder generation
2118 Assume that the old DLL is named perlE0AC.dll (as is one for 5.005_53),
2119 and the new version is 5.6.1. Create a file perl5shim.def-leader with
2120 LIBRARY 'perlE0AC' INITINSTANCE TERMINSTANCE
2122 DESCRIPTION '@#perl5-porters@perl.org:5.006001#@ Perl module for 5.00553 -> Perl 5.6.1 forwarder'
2123 CODE LOADONCALL
2124 DATA LOADONCALL NONSHARED MULTIPLE
2125 EXPORTS
2126 modifying the versions/names as needed. Run
2128 perl -wnle "next if 0../EXPORTS/; print qq( \"$1\") if /\"(\w+)\"/" perl5.def >lst
2130 in the Perl build directory (to make the DLL smaller replace perl5.def
2132 with the definition file for the older version of Perl if present).
2133 cat perl5shim.def-leader lst >perl5shim.def
2135 gcc -Zomf -Zdll -o perlE0AC.dll perl5shim.def -s -llibperl
2136 (ignore multiple "warning L4085").
2138 Threading
2140 As of release 5.003_01 perl is linked to multithreaded C RTL DLL. If
2141 perl itself is not compiled multithread-enabled, so will not be perl's
2142 malloc(). However, extensions may use multiple thread on their own
2143 risk.
2144 This was needed to compile "Perl/Tk" for XFree86-OS/2 out-of-the-box,
2146 and link with DLLs for other useful libraries, which typically are
2147 compiled with "-Zmt -Zcrtdll".
2148 Calls to external programs
2150 Due to a popular demand the perl external program calling has been
2151 changed wrt Andreas Kaiser's port. If perl needs to call an external
2152 program via shell, the f:/bin/sh.exe will be called, or whatever is the
2153 override, see "PERL_SH_DIR".
2154 Thus means that you need to get some copy of a sh.exe as well (I use
2156 one from pdksh). The path F:/bin above is set up automatically during
2157 the build to a correct value on the builder machine, but is overridable
2158 at runtime,
2159 Reasons: a consensus on "perl5-porters" was that perl should use one
2161 non-overridable shell per platform. The obvious choices for OS/2 are
2162 cmd.exe and sh.exe. Having perl build itself would be impossible with
2163 cmd.exe as a shell, thus I picked up "sh.exe". This assures almost 100%
2164 compatibility with the scripts coming from *nix. As an added benefit
2165 this works as well under DOS if you use DOS-enabled port of pdksh (see
2166 "Prerequisites").
2167 Disadvantages: currently sh.exe of pdksh calls external programs via
2169 fork()/exec(), and there is no functioning exec() on OS/2. exec() is
2170 emulated by EMX by an asynchronous call while the caller waits for
2171 child completion (to pretend that the "pid" did not change). This means
2172 that 1 extra copy of sh.exe is made active via fork()/exec(), which may
2173 lead to some resources taken from the system (even if we do not count
2174 extra work needed for fork()ing).
2175 Note that this a lesser issue now when we do not spawn sh.exe unless
2177 needed (metachars found).
2178 One can always start cmd.exe explicitly via
2180 system 'cmd', '/c', 'mycmd', 'arg1', 'arg2', ...
2182 If you need to use cmd.exe, and do not want to hand-edit thousands of
2184 your scripts, the long-term solution proposed on p5-p is to have a
2185 directive
2186 use OS2::Cmd;
2188 which will override system(), exec(), "``", and "open(,'...|')". With
2190 current perl you may override only system(), readpipe() - the explicit
2191 version of "``", and maybe exec(). The code will substitute the one-
2192 argument call to system() by "CORE::system('cmd.exe', '/c', shift)".
2193 If you have some working code for "OS2::Cmd", please send it to me, I
2195 will include it into distribution. I have no need for such a module, so
2196 cannot test it.
2197 For the details of the current situation with calling external
2199 programs, see "2 (and DOS) programs under Perl" in Starting OS. Set us
2200 mention a couple of features:
2201 · External scripts may be called by their basename. Perl will try
2203 the same extensions as when processing -S command-line switch.
2204 · External scripts starting with "#!" or "extproc " will be executed
2206 directly, without calling the shell, by calling the program
2207 specified on the rest of the first line.
2208 Memory allocation
2210 Perl uses its own malloc() under OS/2 - interpreters are usually
2211 malloc-bound for speed, but perl is not, since its malloc is lightning-
2212 fast. Perl-memory-usage-tuned benchmarks show that Perl's malloc is 5
2213 times quicker than EMX one. I do not have convincing data about memory
2214 footprint, but a (pretty random) benchmark showed that Perl's one is 5%
2215 better.
2216 Combination of perl's malloc() and rigid DLL name resolution creates a
2218 special problem with library functions which expect their return value
2219 to be free()d by system's free(). To facilitate extensions which need
2220 to call such functions, system memory-allocation functions are still
2221 available with the prefix "emx_" added. (Currently only DLL perl has
2222 this, it should propagate to perl_.exe shortly.)
2223 Threads
2225 One can build perl with thread support enabled by providing "-D
2226 usethreads" option to Configure. Currently OS/2 support of threads is
2227 very preliminary.
2228 Most notable problems:
2230 "COND_WAIT"
2232 may have a race condition (but probably does not due to edge-
2233 triggered nature of OS/2 Event semaphores). (Needs a
2234 reimplementation (in terms of chaining waiting threads, with the
2235 linked list stored in per-thread structure?)?)
2236 os2.c
2238 has a couple of static variables used in OS/2-specific functions.
2239 (Need to be moved to per-thread structure, or serialized?)
2240 Note that these problems should not discourage experimenting, since
2242 they have a low probability of affecting small programs.
2243
2245 This description is not updated often (since 5.6.1?), see ./os2/Changes
2246 (perlos2delta) for more info.
2247
2249 Ilya Zakharevich, cpan@ilyaz.org
2250
2252 perl(1).
2253perl v5.10.1 2009-07-14 PERLOS2(1)