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