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")
55 if you want to use PM code in your application (as Perl/Tk or
56 OpenGL Perl modules do) without having a text-mode window present.
57 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 "Command 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 "Starting OS/2 (and
296 DOS) programs under Perl".
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 interchangeable. 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.16.3/
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
835 "Making".
836 If you use "man", either move the installed */man/ directories to your
838 "MANPATH", or modify "MANPATH" to match the location. (One could have
839 avoided this by providing a correct "manpath" option to ./Configure, or
840 editing ./config.sh between configuring and making steps.)
841 "a.out"-style build
843 Proceed as above, but make perl_.exe (see "perl_.exe") by
844 make perl_
846 test and install by
848 make aout_test
850 make aout_install
851 Manually put perl_.exe to a location on your PATH.
853 Note. The build process for "perl_" does not know about all the
855 dependencies, so you should make sure that anything is up-to-date, say,
856 by doing
857 make perl_dll
859 first.
861
863 [This section provides a short overview only...]
864 Building should proceed differently depending on whether the version of
866 perl you install is already present and used on your system, or is a
867 new version not yet used. The description below assumes that the
868 version is new, so installing its DLLs and .pm files will not disrupt
869 the operation of your system even if some intermediate steps are not
870 yet fully working.
871 The other cases require a little bit more convoluted procedures. Below
873 I suppose that the current version of Perl is 5.8.2, so the executables
874 are named accordingly.
875 1. Fully build and test the Perl distribution. Make sure that no
877 tests are failing with "test" and "aout_test" targets; fix the bugs
878 in Perl and the Perl test suite detected by these tests. Make sure
879 that "all_test" make target runs as clean as possible. Check that
880 os2/perlrexx.cmd runs fine.
881 2. Fully install Perl, including "installcmd" target. Copy the
883 generated DLLs to "LIBPATH"; copy the numbered Perl executables (as
884 in perl5.8.2.exe) to "PATH"; copy "perl_.exe" to "PATH" as
885 "perl_5.8.2.exe". Think whether you need backward-compatibility
886 DLLs. In most cases you do not need to install them yet; but
887 sometime this may simplify the following steps.
888 3. Make sure that "CPAN.pm" can download files from CPAN. If not, you
890 may need to manually install "Net::FTP".
891 4. Install the bundle "Bundle::OS2_default"
893 perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_1
895 This may take a couple of hours on 1GHz processor (when run the
897 first time). And this should not be necessarily a smooth
898 procedure. Some modules may not specify required dependencies, so
899 one may need to repeat this procedure several times until the
900 results stabilize.
901 perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_2
903 perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_3
904 Even after they stabilize, some tests may fail.
906 Fix as many discovered bugs as possible. Document all the bugs
908 which are not fixed, and all the failures with unknown reasons.
909 Inspect the produced logs 00cpan_i_1 to find suspiciously skipped
910 tests, and other fishy events.
911 Keep in mind that installation of some modules may fail too: for
913 example, the DLLs to update may be already loaded by CPAN.pm.
914 Inspect the "install" logs (in the example above 00cpan_i_1 etc)
915 for errors, and install things manually, as in
916 cd $CPANHOME/.cpan/build/Digest-MD5-2.31
918 make install
919 Some distributions may fail some tests, but you may want to install
921 them anyway (as above, or via "force install" command of "CPAN.pm"
922 shell-mode).
923 Since this procedure may take quite a long time to complete, it
925 makes sense to "freeze" your CPAN configuration by disabling
926 periodic updates of the local copy of CPAN index: set
927 "index_expire" to some big value (I use 365), then save the
928 settings
929 CPAN> o conf index_expire 365
931 CPAN> o conf commit
932 Reset back to the default value 1 when you are finished.
934 5. When satisfied with the results, rerun the "installcmd" target.
936 Now you can copy "perl5.8.2.exe" to "perl.exe", and install the
937 other OMF-build executables: "perl__.exe" etc. They are ready to
938 be used.
939 6. Change to the "./pod" directory of the build tree, download the
941 Perl logo CamelGrayBig.BMP, and run
942 ( perl2ipf > perl.ipf ) |& tee 00ipf
944 ipfc /INF perl.ipf |& tee 00inf
945 This produces the Perl docs online book "perl.INF". Install in on
947 "BOOKSHELF" path.
948 7. Now is the time to build statically linked executable perl_.exe
950 which includes newly-installed via "Bundle::OS2_default" modules.
951 Doing testing via "CPAN.pm" is going to be painfully slow, since it
952 statically links a new executable per XS extension.
953 Here is a possible workaround: create a toplevel Makefile.PL in
955 $CPANHOME/.cpan/build/ with contents being (compare with "Making
956 executables with a custom collection of statically loaded
957 extensions")
958 use ExtUtils::MakeMaker;
960 WriteMakefile NAME => 'dummy';
961 execute this as
963 perl_5.8.2.exe Makefile.PL <nul |& tee 00aout_c1
965 make -k all test <nul |& 00aout_t1
966 Again, this procedure should not be absolutely smooth. Some
968 "Makefile.PL"'s in subdirectories may be buggy, and would not run
969 as "child" scripts. The interdependency of modules can strike you;
970 however, since non-XS modules are already installed, the
971 prerequisites of most modules have a very good chance to be
972 present.
973 If you discover some glitches, move directories of problematic
975 modules to a different location; if these modules are non-XS
976 modules, you may just ignore them - they are already installed; the
977 remaining, XS, modules you need to install manually one by one.
978 After each such removal you need to rerun the "Makefile.PL"/"make"
980 process; usually this procedure converges soon. (But be sure to
981 convert all the necessary external C libraries from .lib format to
982 .a format: run one of
983 emxaout foo.lib
985 emximp -o foo.a foo.lib
986 whichever is appropriate.) Also, make sure that the DLLs for
988 external libraries are usable with with executables compiled
989 without "-Zmtd" options.
990 When you are sure that only a few subdirectories lead to failures,
992 you may want to add "-j4" option to "make" to speed up skipping
993 subdirectories with already finished build.
994 When you are satisfied with the results of tests, install the build
996 C libraries for extensions:
997 make install |& tee 00aout_i
999 Now you can rename the file ./perl.exe generated during the last
1001 phase to perl_5.8.2.exe; place it on "PATH"; if there is an inter-
1002 dependency between some XS modules, you may need to repeat the
1003 "test"/"install" loop with this new executable and some excluded
1004 modules - until the procedure converges.
1005 Now you have all the necessary .a libraries for these Perl modules
1007 in the places where Perl builder can find it. Use the perl
1008 builder: change to an empty directory, create a "dummy" Makefile.PL
1009 again, and run
1010 perl_5.8.2.exe Makefile.PL |& tee 00c
1012 make perl |& tee 00p
1013 This should create an executable ./perl.exe with all the statically
1015 loaded extensions built in. Compare the generated perlmain.c files
1016 to make sure that during the iterations the number of loaded
1017 extensions only increases. Rename ./perl.exe to perl_5.8.2.exe on
1018 "PATH".
1019 When it converges, you got a functional variant of perl_5.8.2.exe;
1021 copy it to "perl_.exe". You are done with generation of the local
1022 Perl installation.
1023 8. Make sure that the installed modules are actually installed in the
1025 location of the new Perl, and are not inherited from entries of
1026 @INC given for inheritance from the older versions of Perl: set
1027 "PERLLIB_582_PREFIX" to redirect the new version of Perl to a new
1028 location, and copy the installed files to this new location. Redo
1029 the tests to make sure that the versions of modules inherited from
1030 older versions of Perl are not needed.
1031 Actually, the log output of pod2ipf(1) during the step 6 gives a
1033 very detailed info about which modules are loaded from which place;
1034 so you may use it as an additional verification tool.
1035 Check that some temporary files did not make into the perl install
1037 tree. Run something like this
1038 pfind . -f "!(/\.(pm|pl|ix|al|h|a|lib|txt|pod|imp|bs|dll|ld|bs|inc|xbm|yml|cgi|uu|e2x|skip|packlist|eg|cfg|html|pub|enc|all|ini|po|pot)$/i or /^\w+$/") | less
1040 in the install tree (both top one and sitelib one).
1042 Compress all the DLLs with lxlite. The tiny .exe can be compressed
1044 with "/c:max" (the bug only appears when there is a fixup in the
1045 last 6 bytes of a page (?); since the tiny executables are much
1046 smaller than a page, the bug will not hit). Do not compress
1047 "perl_.exe" - it would not work under DOS.
1048 9. Now you can generate the binary distribution. This is done by
1050 running the test of the CPAN distribution "OS2::SoftInstaller".
1051 Tune up the file test.pl to suit the layout of current version of
1052 Perl first. Do not forget to pack the necessary external DLLs
1053 accordingly. Include the description of the bugs and test suite
1054 failures you could not fix. Include the small-stack versions of
1055 Perl executables from Perl build directory.
1056 Include perl5.def so that people can relink the perl DLL preserving
1058 the binary compatibility, or can create compatibility DLLs.
1059 Include the diff files ("diff -pu old new") of fixes you did so
1060 that people can rebuild your version. Include perl5.map so that
1061 one can use remote debugging.
1062 10. Share what you did with the other people. Relax. Enjoy fruits of
1064 your work.
1065 11. Brace yourself for thanks, bug reports, hate mail and spam coming
1067 as result of the previous step. No good deed should remain
1068 unpunished!
1069
1071 The Perl executables can be easily rebuilt at any moment. Moreover,
1072 one can use the embedding interface (see perlembed) to make very
1073 customized executables.
1074 Making executables with a custom collection of statically loaded extensions
1076 It is a little bit easier to do so while decreasing the list of
1077 statically loaded extensions. We discuss this case only here.
1078 1. Change to an empty directory, and create a placeholder
1080 <Makefile.PL>:
1081 use ExtUtils::MakeMaker;
1083 WriteMakefile NAME => 'dummy';
1084 2. Run it with the flavor of Perl (perl.exe or perl_.exe) you want to
1086 rebuild.
1087 perl_ Makefile.PL
1089 3. Ask it to create new Perl executable:
1091 make perl
1093 (you may need to manually add "PERLTYPE=-DPERL_CORE" to this
1095 commandline on some versions of Perl; the symptom is that the
1096 command-line globbing does not work from OS/2 shells with the
1097 newly-compiled executable; check with
1098 .\perl.exe -wle "print for @ARGV" *
1100 ).
1102 4. The previous step created perlmain.c which contains a list of
1104 newXS() calls near the end. Removing unnecessary calls, and
1105 rerunning
1106 make perl
1108 will produce a customized executable.
1110 Making executables with a custom search-paths
1112 The default perl executable is flexible enough to support most usages.
1113 However, one may want something yet more flexible; for example, one may
1114 want to find Perl DLL relatively to the location of the EXE file; or
1115 one may want to ignore the environment when setting the Perl-library
1116 search patch, etc.
1117 If you fill comfortable with embedding interface (see perlembed), such
1119 things are easy to do repeating the steps outlined in "Making
1120 executables with a custom collection of statically loaded extensions",
1121 and doing more comprehensive edits to main() of perlmain.c. The people
1122 with little desire to understand Perl can just rename main(), and do
1123 necessary modification in a custom main() which calls the renamed
1124 function in appropriate time.
1125 However, there is a third way: perl DLL exports the main() function and
1127 several callbacks to customize the search path. Below is a complete
1128 example of a "Perl loader" which
1129 1. Looks for Perl DLL in the directory "$exedir/../dll";
1131 2. Prepends the above directory to "BEGINLIBPATH";
1133 3. Fails if the Perl DLL found via "BEGINLIBPATH" is different from
1135 what was loaded on step 1; e.g., another process could have loaded
1136 it from "LIBPATH" or from a different value of "BEGINLIBPATH". In
1137 these cases one needs to modify the setting of the system so that
1138 this other process either does not run, or loads the DLL from
1139 "BEGINLIBPATH" with "LIBPATHSTRICT=T" (available with kernels after
1140 September 2000).
1141 4. Loads Perl library from "$exedir/../dll/lib/".
1143 5. Uses Bourne shell from "$exedir/../dll/sh/ksh.exe".
1145 For best results compile the C file below with the same options as the
1147 Perl DLL. However, a lot of functionality will work even if the
1148 executable is not an EMX applications, e.g., if compiled with
1149 gcc -Wall -DDOSISH -DOS2=1 -O2 -s -Zomf -Zsys perl-starter.c -DPERL_DLL_BASENAME=\"perl312F\" -Zstack 8192 -Zlinker /PM:VIO
1151 Here is the sample C file:
1153 #define INCL_DOS
1155 #define INCL_NOPM
1156 /* These are needed for compile if os2.h includes os2tk.h, not os2emx.h */
1157 #define INCL_DOSPROCESS
1158 #include <os2.h>
1159 #include "EXTERN.h"
1161 #define PERL_IN_MINIPERLMAIN_C
1162 #include "perl.h"
1163 static char *me;
1165 HMODULE handle;
1166 static void
1168 die_with(char *msg1, char *msg2, char *msg3, char *msg4)
1169 {
1170 ULONG c;
1171 char *s = " error: ";
1172 DosWrite(2, me, strlen(me), &c);
1174 DosWrite(2, s, strlen(s), &c);
1175 DosWrite(2, msg1, strlen(msg1), &c);
1176 DosWrite(2, msg2, strlen(msg2), &c);
1177 DosWrite(2, msg3, strlen(msg3), &c);
1178 DosWrite(2, msg4, strlen(msg4), &c);
1179 DosWrite(2, "\r\n", 2, &c);
1180 exit(255);
1181 }
1182 typedef ULONG (*fill_extLibpath_t)(int type, char *pre, char *post, int replace, char *msg);
1184 typedef int (*main_t)(int type, char *argv[], char *env[]);
1185 typedef int (*handler_t)(void* data, int which);
1186 #ifndef PERL_DLL_BASENAME
1188 # define PERL_DLL_BASENAME "perl"
1189 #endif
1190 static HMODULE
1192 load_perl_dll(char *basename)
1193 {
1194 char buf[300], fail[260];
1195 STRLEN l, dirl;
1196 fill_extLibpath_t f;
1197 ULONG rc_fullname;
1198 HMODULE handle, handle1;
1199 if (_execname(buf, sizeof(buf) - 13) != 0)
1201 die_with("Can't find full path: ", strerror(errno), "", "");
1202 /* XXXX Fill 'me' with new value */
1203 l = strlen(buf);
1204 while (l && buf[l-1] != '/' && buf[l-1] != '\\')
1205 l--;
1206 dirl = l - 1;
1207 strcpy(buf + l, basename);
1208 l += strlen(basename);
1209 strcpy(buf + l, ".dll");
1210 if ( (rc_fullname = DosLoadModule(fail, sizeof fail, buf, &handle)) != 0
1211 && DosLoadModule(fail, sizeof fail, basename, &handle) != 0 )
1212 die_with("Can't load DLL ", buf, "", "");
1213 if (rc_fullname)
1214 return handle; /* was loaded with short name; all is fine */
1215 if (DosQueryProcAddr(handle, 0, "fill_extLibpath", (PFN*)&f))
1216 die_with(buf, ": DLL exports no symbol ", "fill_extLibpath", "");
1217 buf[dirl] = 0;
1218 if (f(0 /*BEGINLIBPATH*/, buf /* prepend */, NULL /* append */,
1219 0 /* keep old value */, me))
1220 die_with(me, ": prepending BEGINLIBPATH", "", "");
1221 if (DosLoadModule(fail, sizeof fail, basename, &handle1) != 0)
1222 die_with(me, ": finding perl DLL again via BEGINLIBPATH", "", "");
1223 buf[dirl] = '\\';
1224 if (handle1 != handle) {
1225 if (DosQueryModuleName(handle1, sizeof(fail), fail))
1226 strcpy(fail, "???");
1227 die_with(buf, ":\n\tperl DLL via BEGINLIBPATH is different: \n\t",
1228 fail,
1229 "\n\tYou may need to manipulate global BEGINLIBPATH and LIBPATHSTRICT"
1230 "\n\tso that the other copy is loaded via BEGINLIBPATH.");
1231 }
1232 return handle;
1233 }
1234 int
1236 main(int argc, char **argv, char **env)
1237 {
1238 main_t f;
1239 handler_t h;
1240 me = argv[0];
1242 /**/
1243 handle = load_perl_dll(PERL_DLL_BASENAME);
1244 if (DosQueryProcAddr(handle, 0, "Perl_OS2_handler_install", (PFN*)&h))
1246 die_with(PERL_DLL_BASENAME, ": DLL exports no symbol ", "Perl_OS2_handler_install", "");
1247 if ( !h((void *)"~installprefix", Perlos2_handler_perllib_from)
1248 || !h((void *)"~dll", Perlos2_handler_perllib_to)
1249 || !h((void *)"~dll/sh/ksh.exe", Perlos2_handler_perl_sh) )
1250 die_with(PERL_DLL_BASENAME, ": Can't install @INC manglers", "", "");
1251 if (DosQueryProcAddr(handle, 0, "dll_perlmain", (PFN*)&f))
1253 die_with(PERL_DLL_BASENAME, ": DLL exports no symbol ", "dll_perlmain", "");
1254 return f(argc, argv, env);
1255 }
1256
1258 Some "/" became "\" in pdksh.
1259 You have a very old pdksh. See "Prerequisites".
1260 'errno' - unresolved external
1262 You do not have MT-safe db.lib. See "Prerequisites".
1263 Problems with tr or sed
1265 reported with very old version of tr and sed.
1266 Some problem (forget which ;-)
1268 You have an older version of perl.dll on your LIBPATH, which broke the
1269 build of extensions.
1270 Library ... not found
1272 You did not run "omflibs". See "Prerequisites".
1273 Segfault in make
1275 You use an old version of GNU make. See "Prerequisites".
1276 op/sprintf test failure
1278 This can result from a bug in emx sprintf which was fixed in 0.9d fix
1279 03.
1280
1282 "setpriority", "getpriority"
1283 Note that these functions are compatible with *nix, not with the older
1284 ports of '94 - 95. The priorities are absolute, go from 32 to -95,
1285 lower is quicker. 0 is the default priority.
1286 WARNING. Calling "getpriority" on a non-existing process could lock
1288 the system before Warp3 fixpak22. Starting with Warp3, Perl will use a
1289 workaround: it aborts getpriority() if the process is not present.
1290 This is not possible on older versions "2.*", and has a race condition
1291 anyway.
1292 "system()"
1294 Multi-argument form of "system()" allows an additional numeric
1295 argument. The meaning of this argument is described in OS2::Process.
1296 When finding a program to run, Perl first asks the OS to look for
1298 executables on "PATH" (OS/2 adds extension .exe if no extension is
1299 present). If not found, it looks for a script with possible extensions
1300 added in this order: no extension, .cmd, .btm, .bat, .pl. If found,
1301 Perl checks the start of the file for magic strings "#!" and "extproc
1302 ". If found, Perl uses the rest of the first line as the beginning of
1303 the command line to run this script. The only mangling done to the
1304 first line is extraction of arguments (currently up to 3), and ignoring
1305 of the path-part of the "interpreter" name if it can't be found using
1306 the full path.
1307 E.g., "system 'foo', 'bar', 'baz'" may lead Perl to finding
1309 C:/emx/bin/foo.cmd with the first line being
1310 extproc /bin/bash -x -c
1312 If /bin/bash.exe is not found, then Perl looks for an executable
1314 bash.exe on "PATH". If found in C:/emx.add/bin/bash.exe, then the
1315 above system() is translated to
1316 system qw(C:/emx.add/bin/bash.exe -x -c C:/emx/bin/foo.cmd bar baz)
1318 One additional translation is performed: instead of /bin/sh Perl uses
1320 the hardwired-or-customized shell (see "PERL_SH_DIR").
1321 The above search for "interpreter" is recursive: if bash executable is
1323 not found, but bash.btm is found, Perl will investigate its first line
1324 etc. The only hardwired limit on the recursion depth is implicit:
1325 there is a limit 4 on the number of additional arguments inserted
1326 before the actual arguments given to system(). In particular, if no
1327 additional arguments are specified on the "magic" first lines, then the
1328 limit on the depth is 4.
1329 If Perl finds that the found executable is of PM type when the current
1331 session is not, it will start the new process in a separate session of
1332 necessary type. Call via "OS2::Process" to disable this magic.
1333 WARNING. Due to the described logic, you need to explicitly specify
1335 .com extension if needed. Moreover, if the executable perl5.6.1 is
1336 requested, Perl will not look for perl5.6.1.exe. [This may change in
1337 the future.]
1338 "extproc" on the first line
1340 If the first chars of a Perl script are "extproc ", this line is
1341 treated as "#!"-line, thus all the switches on this line are processed
1342 (twice if script was started via cmd.exe). See "DESCRIPTION" in
1343 perlrun.
1344 Additional modules:
1346 OS2::Process, OS2::DLL, OS2::REXX, OS2::PrfDB, OS2::ExtAttr. These
1347 modules provide access to additional numeric argument for "system" and
1348 to the information about the running process, to DLLs having functions
1349 with REXX signature and to the REXX runtime, to OS/2 databases in the
1350 .INI format, and to Extended Attributes.
1351 Two additional extensions by Andreas Kaiser, "OS2::UPM", and
1353 "OS2::FTP", are included into "ILYAZ" directory, mirrored on CPAN.
1354 Other OS/2-related extensions are available too.
1355 Prebuilt methods:
1357 "File::Copy::syscopy"
1358 used by "File::Copy::copy", see File::Copy.
1359 "DynaLoader::mod2fname"
1361 used by "DynaLoader" for DLL name mangling.
1362 "Cwd::current_drive()"
1364 Self explanatory.
1365 "Cwd::sys_chdir(name)"
1367 leaves drive as it is.
1368 "Cwd::change_drive(name)"
1370 changes the "current" drive.
1371 "Cwd::sys_is_absolute(name)"
1373 means has drive letter and is_rooted.
1374 "Cwd::sys_is_rooted(name)"
1376 means has leading "[/\\]" (maybe after a drive-letter:).
1377 "Cwd::sys_is_relative(name)"
1379 means changes with current dir.
1380 "Cwd::sys_cwd(name)"
1382 Interface to cwd from EMX. Used by "Cwd::cwd".
1383 "Cwd::sys_abspath(name, dir)"
1385 Really really odious function to implement. Returns absolute name
1386 of file which would have "name" if CWD were "dir". "Dir" defaults
1387 to the current dir.
1388 "Cwd::extLibpath([type])"
1390 Get current value of extended library search path. If "type" is
1391 present and positive, works with "END_LIBPATH", if negative, works
1392 with "LIBPATHSTRICT", otherwise with "BEGIN_LIBPATH".
1393 "Cwd::extLibpath_set( path [, type ] )"
1395 Set current value of extended library search path. If "type" is
1396 present and positive, works with <END_LIBPATH>, if negative, works
1397 with "LIBPATHSTRICT", otherwise with "BEGIN_LIBPATH".
1398 "OS2::Error(do_harderror,do_exception)"
1400 Returns "undef" if it was not called yet, otherwise bit 1 is set
1401 if on the previous call do_harderror was enabled, bit 2 is set if
1402 on previous call do_exception was enabled.
1403 This function enables/disables error popups associated with
1405 hardware errors (Disk not ready etc.) and software exceptions.
1406 I know of no way to find out the state of popups before the first
1408 call to this function.
1409 "OS2::Errors2Drive(drive)"
1411 Returns "undef" if it was not called yet, otherwise return false if
1412 errors were not requested to be written to a hard drive, or the
1413 drive letter if this was requested.
1414 This function may redirect error popups associated with hardware
1416 errors (Disk not ready etc.) and software exceptions to the file
1417 POPUPLOG.OS2 at the root directory of the specified drive.
1418 Overrides OS2::Error() specified by individual programs. Given
1419 argument undef will disable redirection.
1420 Has global effect, persists after the application exits.
1422 I know of no way to find out the state of redirection of popups to
1424 the disk before the first call to this function.
1425 OS2::SysInfo()
1427 Returns a hash with system information. The keys of the hash are
1428 MAX_PATH_LENGTH, MAX_TEXT_SESSIONS, MAX_PM_SESSIONS,
1430 MAX_VDM_SESSIONS, BOOT_DRIVE, DYN_PRI_VARIATION,
1431 MAX_WAIT, MIN_SLICE, MAX_SLICE, PAGE_SIZE,
1432 VERSION_MAJOR, VERSION_MINOR, VERSION_REVISION,
1433 MS_COUNT, TIME_LOW, TIME_HIGH, TOTPHYSMEM, TOTRESMEM,
1434 TOTAVAILMEM, MAXPRMEM, MAXSHMEM, TIMER_INTERVAL,
1435 MAX_COMP_LENGTH, FOREGROUND_FS_SESSION,
1436 FOREGROUND_PROCESS
1437 OS2::BootDrive()
1439 Returns a letter without colon.
1440 "OS2::MorphPM(serve)", "OS2::UnMorphPM(serve)"
1442 Transforms the current application into a PM application and back.
1443 The argument true means that a real message loop is going to be
1444 served. OS2::MorphPM() returns the PM message queue handle as an
1445 integer.
1446 See "Centralized management of resources" for additional details.
1448 "OS2::Serve_Messages(force)"
1450 Fake on-demand retrieval of outstanding PM messages. If "force" is
1451 false, will not dispatch messages if a real message loop is known
1452 to be present. Returns number of messages retrieved.
1453 Dies with "QUITing..." if WM_QUIT message is obtained.
1455 "OS2::Process_Messages(force [, cnt])"
1457 Retrieval of PM messages until window creation/destruction. If
1458 "force" is false, will not dispatch messages if a real message loop
1459 is known to be present.
1460 Returns change in number of windows. If "cnt" is given, it is
1462 incremented by the number of messages retrieved.
1463 Dies with "QUITing..." if WM_QUIT message is obtained.
1465 "OS2::_control87(new,mask)"
1467 the same as _control87(3) of EMX. Takes integers as arguments,
1468 returns the previous coprocessor control word as an integer. Only
1469 bits in "new" which are present in "mask" are changed in the
1470 control word.
1471 OS2::get_control87()
1473 gets the coprocessor control word as an integer.
1474 "OS2::set_control87_em(new=MCW_EM,mask=MCW_EM)"
1476 The variant of OS2::_control87() with default values good for
1477 handling exception mask: if no "mask", uses exception mask part of
1478 "new" only. If no "new", disables all the floating point
1479 exceptions.
1480 See "Misfeatures" for details.
1482 "OS2::DLLname([how [, \&xsub]])"
1484 Gives the information about the Perl DLL or the DLL containing the
1485 C function bound to by &xsub. The meaning of "how" is: default
1486 (2): full name; 0: handle; 1: module name.
1487 (Note that some of these may be moved to different libraries -
1489 eventually).
1490 Prebuilt variables:
1492 $OS2::emx_rev
1493 numeric value is the same as _emx_rev of EMX, a string value the
1494 same as _emx_vprt (similar to "0.9c").
1495 $OS2::emx_env
1497 same as _emx_env of EMX, a number similar to 0x8001.
1498 $OS2::os_ver
1500 a number "OS_MAJOR + 0.001 * OS_MINOR".
1501 $OS2::is_aout
1503 true if the Perl library was compiled in AOUT format.
1504 $OS2::can_fork
1506 true if the current executable is an AOUT EMX executable, so Perl
1507 can fork. Do not use this, use the portable check for
1508 $Config::Config{dfork}.
1509 $OS2::nsyserror
1511 This variable (default is 1) controls whether to enforce the
1512 contents of $^E to start with "SYS0003"-like id. If set to 0, then
1513 the string value of $^E is what is available from the OS/2 message
1514 file. (Some messages in this file have an "SYS0003"-like id
1515 prepended, some not.)
1516 Misfeatures
1518 · Since flock(3) is present in EMX, but is not functional, it is
1519 emulated by perl. To disable the emulations, set environment
1520 variable "USE_PERL_FLOCK=0".
1521 · Here is the list of things which may be "broken" on EMX (from EMX
1523 docs):
1524 · The functions recvmsg(3), sendmsg(3), and socketpair(3) are not
1526 implemented.
1527 · sock_init(3) is not required and not implemented.
1529 · flock(3) is not yet implemented (dummy function). (Perl has a
1531 workaround.)
1532 · kill(3): Special treatment of PID=0, PID=1 and PID=-1 is not
1534 implemented.
1535 · waitpid(3):
1537 WUNTRACED
1539 Not implemented.
1540 waitpid() is not implemented for negative values of PID.
1541 Note that "kill -9" does not work with the current version of EMX.
1543 · See "Text-mode filehandles".
1545 · Unix-domain sockets on OS/2 live in a pseudo-file-system
1547 "/sockets/...". To avoid a failure to create a socket with a name
1548 of a different form, "/socket/" is prepended to the socket name
1549 (unless it starts with this already).
1550 This may lead to problems later in case the socket is accessed via
1552 the "usual" file-system calls using the "initial" name.
1553 · Apparently, IBM used a compiler (for some period of time around
1555 '95?) which changes FP mask right and left. This is not that bad
1556 for IBM's programs, but the same compiler was used for DLLs which
1557 are used with general-purpose applications. When these DLLs are
1558 used, the state of floating-point flags in the application is not
1559 predictable.
1560 What is much worse, some DLLs change the floating point flags when
1562 in _DLLInitTerm() (e.g., TCP32IP). This means that even if you do
1563 not call any function in the DLL, just the act of loading this DLL
1564 will reset your flags. What is worse, the same compiler was used
1565 to compile some HOOK DLLs. Given that HOOK dlls are executed in
1566 the context of all the applications in the system, this means a
1567 complete unpredictability of floating point flags on systems using
1568 such HOOK DLLs. E.g., GAMESRVR.DLL of DIVE origin changes the
1569 floating point flags on each write to the TTY of a VIO (windowed
1570 text-mode) applications.
1571 Some other (not completely debugged) situations when FP flags
1573 change include some video drivers (?), and some operations related
1574 to creation of the windows. People who code OpenGL may have more
1575 experience on this.
1576 Perl is generally used in the situation when all the floating-point
1578 exceptions are ignored, as is the default under EMX. If they are
1579 not ignored, some benign Perl programs would get a "SIGFPE" and
1580 would die a horrible death.
1581 To circumvent this, Perl uses two hacks. They help against one
1583 type of damage only: FP flags changed when loading a DLL.
1584 One of the hacks is to disable floating point exceptions on Perl
1586 startup (as is the default with EMX). This helps only with
1587 compile-time-linked DLLs changing the flags before main() had a
1588 chance to be called.
1589 The other hack is to restore FP flags after a call to dlopen().
1591 This helps against similar damage done by DLLs _DLLInitTerm() at
1592 runtime. Currently no way to switch these hacks off is provided.
1593 Modifications
1595 Perl modifies some standard C library calls in the following ways:
1596 "popen" "my_popen" uses sh.exe if shell is required, cf.
1598 "PERL_SH_DIR".
1599 "tmpnam" is created using "TMP" or "TEMP" environment variable, via
1601 "tempnam".
1602 "tmpfile"
1604 If the current directory is not writable, file is created
1605 using modified "tmpnam", so there may be a race condition.
1606 "ctermid"
1608 a dummy implementation.
1609 "stat" "os2_stat" special-cases /dev/tty and /dev/con.
1611 "mkdir", "rmdir"
1613 these EMX functions do not work if the path contains a
1614 trailing "/". Perl contains a workaround for this.
1615 "flock" Since flock(3) is present in EMX, but is not functional, it is
1617 emulated by perl. To disable the emulations, set environment
1618 variable "USE_PERL_FLOCK=0".
1619 Identifying DLLs
1621 All the DLLs built with the current versions of Perl have ID strings
1622 identifying the name of the extension, its version, and the version of
1623 Perl required for this DLL. Run "bldlevel DLL-name" to find this info.
1624 Centralized management of resources
1626 Since to call certain OS/2 API one needs to have a correctly
1627 initialized "Win" subsystem, OS/2-specific extensions may require
1628 getting "HAB"s and "HMQ"s. If an extension would do it on its own,
1629 another extension could fail to initialize.
1630 Perl provides a centralized management of these resources:
1632 "HAB"
1634 To get the HAB, the extension should call "hab = perl_hab_GET()" in
1635 C. After this call is performed, "hab" may be accessed as
1636 "Perl_hab". There is no need to release the HAB after it is used.
1637 If by some reasons perl.h cannot be included, use
1639 extern int Perl_hab_GET(void);
1641 instead.
1643 "HMQ"
1645 There are two cases:
1646 · the extension needs an "HMQ" only because some API will not
1648 work otherwise. Use "serve = 0" below.
1649 · the extension needs an "HMQ" since it wants to engage in a PM
1651 event loop. Use "serve = 1" below.
1652 To get an "HMQ", the extension should call "hmq =
1654 perl_hmq_GET(serve)" in C. After this call is performed, "hmq" may
1655 be accessed as "Perl_hmq".
1656 To signal to Perl that HMQ is not needed any more, call
1658 "perl_hmq_UNSET(serve)". Perl process will automatically
1659 morph/unmorph itself into/from a PM process if HMQ is
1660 needed/not-needed. Perl will automatically enable/disable
1661 "WM_QUIT" message during shutdown if the message queue is
1662 served/not-served.
1663 NOTE. If during a shutdown there is a message queue which did not
1665 disable WM_QUIT, and which did not process the received WM_QUIT
1666 message, the shutdown will be automatically cancelled. Do not call
1667 perl_hmq_GET(1) unless you are going to process messages on an
1668 orderly basis.
1669 Treating errors reported by OS/2 API
1671 There are two principal conventions (it is useful to call them
1672 "Dos*" and "Win*" - though this part of the function signature is
1673 not always determined by the name of the API) of reporting the
1674 error conditions of OS/2 API. Most of "Dos*" APIs report the error
1675 code as the result of the call (so 0 means success, and there are
1676 many types of errors). Most of "Win*" API report success/fail via
1677 the result being "TRUE"/"FALSE"; to find the reason for the failure
1678 one should call WinGetLastError() API.
1679 Some "Win*" entry points also overload a "meaningful" return value
1681 with the error indicator; having a 0 return value indicates an
1682 error. Yet some other "Win*" entry points overload things even
1683 more, and 0 return value may mean a successful call returning a
1684 valid value 0, as well as an error condition; in the case of a 0
1685 return value one should call WinGetLastError() API to distinguish a
1686 successful call from a failing one.
1687 By convention, all the calls to OS/2 API should indicate their
1689 failures by resetting $^E. All the Perl-accessible functions which
1690 call OS/2 API may be broken into two classes: some die()s when an
1691 API error is encountered, the other report the error via a false
1692 return value (of course, this does not concern Perl-accessible
1693 functions which expect a failure of the OS/2 API call, having some
1694 workarounds coded).
1695 Obviously, in the situation of the last type of the signature of an
1697 OS/2 API, it is must more convenient for the users if the failure
1698 is indicated by die()ing: one does not need to check $^E to know
1699 that something went wrong. If, however, this solution is not
1700 desirable by some reason, the code in question should reset $^E to
1701 0 before making this OS/2 API call, so that the caller of this
1702 Perl-accessible function has a chance to distinguish a
1703 success-but-0-return value from a failure. (One may return undef
1704 as an alternative way of reporting an error.)
1705 The macros to simplify this type of error propagation are
1707 "CheckOSError(expr)"
1709 Returns true on error, sets $^E. Expects expr() be a call of
1710 "Dos*"-style API.
1711 "CheckWinError(expr)"
1713 Returns true on error, sets $^E. Expects expr() be a call of
1714 "Win*"-style API.
1715 "SaveWinError(expr)"
1717 Returns "expr", sets $^E from WinGetLastError() if "expr" is
1718 false.
1719 "SaveCroakWinError(expr,die,name1,name2)"
1721 Returns "expr", sets $^E from WinGetLastError() if "expr" is
1722 false, and die()s if "die" and $^E are true. The message to
1723 die is the concatenated strings "name1" and "name2", separated
1724 by ": " from the contents of $^E.
1725 "WinError_2_Perl_rc"
1727 Sets "Perl_rc" to the return value of WinGetLastError().
1728 "FillWinError"
1730 Sets "Perl_rc" to the return value of WinGetLastError(), and
1731 sets $^E to the corresponding value.
1732 "FillOSError(rc)"
1734 Sets "Perl_rc" to "rc", and sets $^E to the corresponding
1735 value.
1736 Loading DLLs and ordinals in DLLs
1738 Some DLLs are only present in some versions of OS/2, or in some
1739 configurations of OS/2. Some exported entry points are present
1740 only in DLLs shipped with some versions of OS/2. If these DLLs and
1741 entry points were linked directly for a Perl executable/DLL or from
1742 a Perl extensions, this binary would work only with the specified
1743 versions/setups. Even if these entry points were not needed, the
1744 load of the executable (or DLL) would fail.
1745 For example, many newer useful APIs are not present in OS/2 v2;
1747 many PM-related APIs require DLLs not available on floppy-boot
1748 setup.
1749 To make these calls fail only when the calls are executed, one
1751 should call these API via a dynamic linking API. There is a
1752 subsystem in Perl to simplify such type of calls. A large number
1753 of entry points available for such linking is provided (see
1754 "entries_ordinals" - and also "PMWIN_entries" - in os2ish.h).
1755 These ordinals can be accessed via the APIs:
1756 CallORD(), DeclFuncByORD(), DeclVoidFuncByORD(),
1758 DeclOSFuncByORD(), DeclWinFuncByORD(), AssignFuncPByORD(),
1759 DeclWinFuncByORD_CACHE(), DeclWinFuncByORD_CACHE_survive(),
1760 DeclWinFuncByORD_CACHE_resetError_survive(),
1761 DeclWinFunc_CACHE(), DeclWinFunc_CACHE_resetError(),
1762 DeclWinFunc_CACHE_survive(), DeclWinFunc_CACHE_resetError_survive()
1763 See the header files and the C code in the supplied OS/2-related
1765 modules for the details on usage of these functions.
1766 Some of these functions also combine dynaloading semantic with the
1768 error-propagation semantic discussed above.
1769
1771 Because of idiosyncrasies of OS/2 one cannot have all the eggs in the
1772 same basket (though EMX environment tries hard to overcome this
1773 limitations, so the situation may somehow improve). There are 4
1774 executables for Perl provided by the distribution:
1775 perl.exe
1777 The main workhorse. This is a chimera executable: it is compiled as an
1778 "a.out"-style executable, but is linked with "omf"-style dynamic
1779 library perl.dll, and with dynamic CRT DLL. This executable is a VIO
1780 application.
1781 It can load perl dynamic extensions, and it can fork().
1783 Note. Keep in mind that fork() is needed to open a pipe to yourself.
1785 perl_.exe
1787 This is a statically linked "a.out"-style executable. It cannot load
1788 dynamic Perl extensions. The executable supplied in binary
1789 distributions has a lot of extensions prebuilt, thus the above
1790 restriction is important only if you use custom-built extensions. This
1791 executable is a VIO application.
1792 This is the only executable with does not require OS/2. The friends
1794 locked into "M$" world would appreciate the fact that this executable
1795 runs under DOS, Win0.3*, Win0.95 and WinNT with an appropriate
1796 extender. See "Other OSes".
1797 perl__.exe
1799 This is the same executable as perl___.exe, but it is a PM application.
1800 Note. Usually (unless explicitly redirected during the startup) STDIN,
1802 STDERR, and STDOUT of a PM application are redirected to nul. However,
1803 it is possible to see them if you start "perl__.exe" from a PM program
1804 which emulates a console window, like Shell mode of Emacs or EPM. Thus
1805 it is possible to use Perl debugger (see perldebug) to debug your PM
1806 application (but beware of the message loop lockups - this will not
1807 work if you have a message queue to serve, unless you hook the serving
1808 into the getc() function of the debugger).
1809 Another way to see the output of a PM program is to run it as
1811 pm_prog args 2>&1 | cat -
1813 with a shell different from cmd.exe, so that it does not create a link
1815 between a VIO session and the session of "pm_porg". (Such a link
1816 closes the VIO window.) E.g., this works with sh.exe - or with Perl!
1817 open P, 'pm_prog args 2>&1 |' or die;
1819 print while <P>;
1820 The flavor perl__.exe is required if you want to start your program
1822 without a VIO window present, but not "detach"ed (run "help detach" for
1823 more info). Very useful for extensions which use PM, like "Perl/Tk" or
1824 "OpenGL".
1825 Note also that the differences between PM and VIO executables are only
1827 in the default behaviour. One can start any executable in any kind of
1828 session by using the arguments "/fs", "/pm" or "/win" switches of the
1829 command "start" (of CMD.EXE or a similar shell). Alternatively, one
1830 can use the numeric first argument of the "system" Perl function (see
1831 OS2::Process).
1832 perl___.exe
1834 This is an "omf"-style executable which is dynamically linked to
1835 perl.dll and CRT DLL. I know no advantages of this executable over
1836 "perl.exe", but it cannot fork() at all. Well, one advantage is that
1837 the build process is not so convoluted as with "perl.exe".
1838 It is a VIO application.
1840 Why strange names?
1842 Since Perl processes the "#!"-line (cf. "DESCRIPTION" in perlrun,
1843 "Command Switches" in perlrun, "No Perl script found in input" in
1844 perldiag), it should know when a program is a Perl. There is some
1845 naming convention which allows Perl to distinguish correct lines from
1846 wrong ones. The above names are almost the only names allowed by this
1847 convention which do not contain digits (which have absolutely different
1848 semantics).
1849 Why dynamic linking?
1851 Well, having several executables dynamically linked to the same huge
1852 library has its advantages, but this would not substantiate the
1853 additional work to make it compile. The reason is the complicated-to-
1854 developers but very quick and convenient-to-users "hard" dynamic
1855 linking used by OS/2.
1856 There are two distinctive features of the dyna-linking model of OS/2:
1858 first, all the references to external functions are resolved at the
1859 compile time; second, there is no runtime fixup of the DLLs after they
1860 are loaded into memory. The first feature is an enormous advantage
1861 over other models: it avoids conflicts when several DLLs used by an
1862 application export entries with the same name. In such cases "other"
1863 models of dyna-linking just choose between these two entry points using
1864 some random criterion - with predictable disasters as results. But it
1865 is the second feature which requires the build of perl.dll.
1866 The address tables of DLLs are patched only once, when they are loaded.
1868 The addresses of the entry points into DLLs are guaranteed to be the
1869 same for all the programs which use the same DLL. This removes the
1870 runtime fixup - once DLL is loaded, its code is read-only.
1871 While this allows some (significant?) performance advantages, this
1873 makes life much harder for developers, since the above scheme makes it
1874 impossible for a DLL to be "linked" to a symbol in the .EXE file.
1875 Indeed, this would need a DLL to have different relocations tables for
1876 the (different) executables which use this DLL.
1877 However, a dynamically loaded Perl extension is forced to use some
1879 symbols from the perl executable, e.g., to know how to find the
1880 arguments to the functions: the arguments live on the perl internal
1881 evaluation stack. The solution is to put the main code of the
1882 interpreter into a DLL, and make the .EXE file which just loads this
1883 DLL into memory and supplies command-arguments. The extension DLL
1884 cannot link to symbols in .EXE, but it has no problem linking to
1885 symbols in the .DLL.
1886 This greatly increases the load time for the application (as well as
1888 complexity of the compilation). Since interpreter is in a DLL, the C
1889 RTL is basically forced to reside in a DLL as well (otherwise
1890 extensions would not be able to use CRT). There are some advantages if
1891 you use different flavors of perl, such as running perl.exe and
1892 perl__.exe simultaneously: they share the memory of perl.dll.
1893 NOTE. There is one additional effect which makes DLLs more wasteful:
1895 DLLs are loaded in the shared memory region, which is a scarse resource
1896 given the 512M barrier of the "standard" OS/2 virtual memory. The code
1897 of .EXE files is also shared by all the processes which use the
1898 particular .EXE, but they are "shared in the private address space of
1899 the process"; this is possible because the address at which different
1900 sections of the .EXE file are loaded is decided at compile-time, thus
1901 all the processes have these sections loaded at same addresses, and no
1902 fixup of internal links inside the .EXE is needed.
1903 Since DLLs may be loaded at run time, to have the same mechanism for
1905 DLLs one needs to have the address range of any of the loaded DLLs in
1906 the system to be available in all the processes which did not load a
1907 particular DLL yet. This is why the DLLs are mapped to the shared
1908 memory region.
1909 Why chimera build?
1911 Current EMX environment does not allow DLLs compiled using Unixish
1912 "a.out" format to export symbols for data (or at least some types of
1913 data). This forces "omf"-style compile of perl.dll.
1914 Current EMX environment does not allow .EXE files compiled in "omf"
1916 format to fork(). fork() is needed for exactly three Perl operations:
1917 · explicit fork() in the script,
1919 · "open FH, "|-""
1921 · "open FH, "-|"", in other words, opening pipes to itself.
1923 While these operations are not questions of life and death, they are
1925 needed for a lot of useful scripts. This forces "a.out"-style compile
1926 of perl.exe.
1927
1929 Here we list environment variables with are either OS/2- and DOS- and
1930 Win*-specific, or are more important under OS/2 than under other OSes.
1931 "PERLLIB_PREFIX"
1933 Specific for EMX port. Should have the form
1934 path1;path2
1936 or
1938 path1 path2
1940 If the beginning of some prebuilt path matches path1, it is substituted
1942 with path2.
1943 Should be used if the perl library is moved from the default location
1945 in preference to "PERL(5)LIB", since this would not leave wrong entries
1946 in @INC. For example, if the compiled version of perl looks for @INC
1947 in f:/perllib/lib, and you want to install the library in h:/opt/gnu,
1948 do
1949 set PERLLIB_PREFIX=f:/perllib/lib;h:/opt/gnu
1951 This will cause Perl with the prebuilt @INC of
1953 f:/perllib/lib/5.00553/os2
1955 f:/perllib/lib/5.00553
1956 f:/perllib/lib/site_perl/5.00553/os2
1957 f:/perllib/lib/site_perl/5.00553
1958 .
1959 to use the following @INC:
1961 h:/opt/gnu/5.00553/os2
1963 h:/opt/gnu/5.00553
1964 h:/opt/gnu/site_perl/5.00553/os2
1965 h:/opt/gnu/site_perl/5.00553
1966 .
1967 "PERL_BADLANG"
1969 If 0, perl ignores setlocale() failing. May be useful with some strange
1970 locales.
1971 "PERL_BADFREE"
1973 If 0, perl would not warn of in case of unwarranted free(). With older
1974 perls this might be useful in conjunction with the module DB_File,
1975 which was buggy when dynamically linked and OMF-built.
1976 Should not be set with newer Perls, since this may hide some real
1978 problems.
1979 "PERL_SH_DIR"
1981 Specific for EMX port. Gives the directory part of the location for
1982 sh.exe.
1983 "USE_PERL_FLOCK"
1985 Specific for EMX port. Since flock(3) is present in EMX, but is not
1986 functional, it is emulated by perl. To disable the emulations, set
1987 environment variable "USE_PERL_FLOCK=0".
1988 "TMP" or "TEMP"
1990 Specific for EMX port. Used as storage place for temporary files.
1991
1993 Here we list major changes which could make you by surprise.
1994 Text-mode filehandles
1996 Starting from version 5.8, Perl uses a builtin translation layer for
1997 text-mode files. This replaces the efficient well-tested EMX layer by
1998 some code which should be best characterized as a "quick hack".
1999 In addition to possible bugs and an inability to follow changes to the
2001 translation policy with off/on switches of TERMIO translation, this
2002 introduces a serious incompatible change: before sysread() on text-mode
2003 filehandles would go through the translation layer, now it would not.
2004 Priorities
2006 "setpriority" and "getpriority" are not compatible with earlier ports
2007 by Andreas Kaiser. See "setpriority, getpriority".
2008 DLL name mangling: pre 5.6.2
2010 With the release 5.003_01 the dynamically loadable libraries should be
2011 rebuilt when a different version of Perl is compiled. In particular,
2012 DLLs (including perl.dll) are now created with the names which contain
2013 a checksum, thus allowing workaround for OS/2 scheme of caching DLLs.
2014 It may be possible to code a simple workaround which would
2016 · find the old DLLs looking through the old @INC;
2018 · mangle the names according to the scheme of new perl and copy the
2020 DLLs to these names;
2021 · edit the internal "LX" tables of DLL to reflect the change of the
2023 name (probably not needed for Perl extension DLLs, since the
2024 internally coded names are not used for "specific" DLLs, they used
2025 only for "global" DLLs).
2026 · edit the internal "IMPORT" tables and change the name of the "old"
2028 perl????.dll to the "new" perl????.dll.
2029 DLL name mangling: 5.6.2 and beyond
2031 In fact mangling of extension DLLs was done due to misunderstanding of
2032 the OS/2 dynaloading model. OS/2 (effectively) maintains two different
2033 tables of loaded DLL:
2034 Global DLLs
2036 those loaded by the base name from "LIBPATH"; including those
2037 associated at link time;
2038 specific DLLs
2040 loaded by the full name.
2041 When resolving a request for a global DLL, the table of already-loaded
2043 specific DLLs is (effectively) ignored; moreover, specific DLLs are
2044 always loaded from the prescribed path.
2045 There is/was a minor twist which makes this scheme fragile: what to do
2047 with DLLs loaded from
2048 "BEGINLIBPATH" and "ENDLIBPATH"
2050 (which depend on the process)
2051 . from "LIBPATH"
2053 which effectively depends on the process (although "LIBPATH" is the
2054 same for all the processes).
2055 Unless "LIBPATHSTRICT" is set to "T" (and the kernel is after
2057 2000/09/01), such DLLs are considered to be global. When loading a
2058 global DLL it is first looked in the table of already-loaded global
2059 DLLs. Because of this the fact that one executable loaded a DLL from
2060 "BEGINLIBPATH" and "ENDLIBPATH", or . from "LIBPATH" may affect which
2061 DLL is loaded when another executable requests a DLL with the same
2062 name. This is the reason for version-specific mangling of the DLL name
2063 for perl DLL.
2064 Since the Perl extension DLLs are always loaded with the full path,
2066 there is no need to mangle their names in a version-specific ways:
2067 their directory already reflects the corresponding version of perl, and
2068 @INC takes into account binary compatibility with older version.
2069 Starting from 5.6.2 the name mangling scheme is fixed to be the same as
2070 for Perl 5.005_53 (same as in a popular binary release). Thus new
2071 Perls will be able to resolve the names of old extension DLLs if @INC
2072 allows finding their directories.
2073 However, this still does not guarantee that these DLL may be loaded.
2075 The reason is the mangling of the name of the Perl DLL. And since the
2076 extension DLLs link with the Perl DLL, extension DLLs for older
2077 versions would load an older Perl DLL, and would most probably segfault
2078 (since the data in this DLL is not properly initialized).
2079 There is a partial workaround (which can be made complete with newer
2081 OS/2 kernels): create a forwarder DLL with the same name as the DLL of
2082 the older version of Perl, which forwards the entry points to the newer
2083 Perl's DLL. Make this DLL accessible on (say) the "BEGINLIBPATH" of
2084 the new Perl executable. When the new executable accesses old Perl's
2085 extension DLLs, they would request the old Perl's DLL by name, get the
2086 forwarder instead, so effectively will link with the currently running
2087 (new) Perl DLL.
2088 This may break in two ways:
2090 · Old perl executable is started when a new executable is running has
2092 loaded an extension compiled for the old executable (ouph!). In
2093 this case the old executable will get a forwarder DLL instead of
2094 the old perl DLL, so would link with the new perl DLL. While not
2095 directly fatal, it will behave the same as new executable. This
2096 beats the whole purpose of explicitly starting an old executable.
2097 · A new executable loads an extension compiled for the old executable
2099 when an old perl executable is running. In this case the extension
2100 will not pick up the forwarder - with fatal results.
2101 With support for "LIBPATHSTRICT" this may be circumvented - unless one
2103 of DLLs is started from . from "LIBPATH" (I do not know whether
2104 "LIBPATHSTRICT" affects this case).
2105 REMARK. Unless newer kernels allow . in "BEGINLIBPATH" (older do not),
2107 this mess cannot be completely cleaned. (It turns out that as of the
2108 beginning of 2002, . is not allowed, but .\. is - and it has the same
2109 effect.)
2110 REMARK. "LIBPATHSTRICT", "BEGINLIBPATH" and "ENDLIBPATH" are not
2112 environment variables, although cmd.exe emulates them on "SET ..."
2113 lines. From Perl they may be accessed by Cwd::extLibpath and
2114 Cwd::extLibpath_set.
2115 DLL forwarder generation
2117 Assume that the old DLL is named perlE0AC.dll (as is one for 5.005_53),
2118 and the new version is 5.6.1. Create a file perl5shim.def-leader with
2119 LIBRARY 'perlE0AC' INITINSTANCE TERMINSTANCE
2121 DESCRIPTION '@#perl5-porters@perl.org:5.006001#@ Perl module for 5.00553 -> Perl 5.6.1 forwarder'
2122 CODE LOADONCALL
2123 DATA LOADONCALL NONSHARED MULTIPLE
2124 EXPORTS
2125 modifying the versions/names as needed. Run
2127 perl -wnle "next if 0../EXPORTS/; print qq( \"$1\") if /\"(\w+)\"/" perl5.def >lst
2129 in the Perl build directory (to make the DLL smaller replace perl5.def
2131 with the definition file for the older version of Perl if present).
2132 cat perl5shim.def-leader lst >perl5shim.def
2134 gcc -Zomf -Zdll -o perlE0AC.dll perl5shim.def -s -llibperl
2135 (ignore multiple "warning L4085").
2137 Threading
2139 As of release 5.003_01 perl is linked to multithreaded C RTL DLL. If
2140 perl itself is not compiled multithread-enabled, so will not be perl's
2141 malloc(). However, extensions may use multiple thread on their own
2142 risk.
2143 This was needed to compile "Perl/Tk" for XFree86-OS/2 out-of-the-box,
2145 and link with DLLs for other useful libraries, which typically are
2146 compiled with "-Zmt -Zcrtdll".
2147 Calls to external programs
2149 Due to a popular demand the perl external program calling has been
2150 changed wrt Andreas Kaiser's port. If perl needs to call an external
2151 program via shell, the f:/bin/sh.exe will be called, or whatever is the
2152 override, see "PERL_SH_DIR".
2153 Thus means that you need to get some copy of a sh.exe as well (I use
2155 one from pdksh). The path F:/bin above is set up automatically during
2156 the build to a correct value on the builder machine, but is overridable
2157 at runtime,
2158 Reasons: a consensus on "perl5-porters" was that perl should use one
2160 non-overridable shell per platform. The obvious choices for OS/2 are
2161 cmd.exe and sh.exe. Having perl build itself would be impossible with
2162 cmd.exe as a shell, thus I picked up "sh.exe". This assures almost 100%
2163 compatibility with the scripts coming from *nix. As an added benefit
2164 this works as well under DOS if you use DOS-enabled port of pdksh (see
2165 "Prerequisites").
2166 Disadvantages: currently sh.exe of pdksh calls external programs via
2168 fork()/exec(), and there is no functioning exec() on OS/2. exec() is
2169 emulated by EMX by an asynchronous call while the caller waits for
2170 child completion (to pretend that the "pid" did not change). This means
2171 that 1 extra copy of sh.exe is made active via fork()/exec(), which may
2172 lead to some resources taken from the system (even if we do not count
2173 extra work needed for fork()ing).
2174 Note that this a lesser issue now when we do not spawn sh.exe unless
2176 needed (metachars found).
2177 One can always start cmd.exe explicitly via
2179 system 'cmd', '/c', 'mycmd', 'arg1', 'arg2', ...
2181 If you need to use cmd.exe, and do not want to hand-edit thousands of
2183 your scripts, the long-term solution proposed on p5-p is to have a
2184 directive
2185 use OS2::Cmd;
2187 which will override system(), exec(), "``", and "open(,'...|')". With
2189 current perl you may override only system(), readpipe() - the explicit
2190 version of "``", and maybe exec(). The code will substitute the one-
2191 argument call to system() by "CORE::system('cmd.exe', '/c', shift)".
2192 If you have some working code for "OS2::Cmd", please send it to me, I
2194 will include it into distribution. I have no need for such a module, so
2195 cannot test it.
2196 For the details of the current situation with calling external
2198 programs, see "Starting OS/2 (and DOS) programs under Perl". Set us
2199 mention a couple of features:
2200 · External scripts may be called by their basename. Perl will try
2202 the same extensions as when processing -S command-line switch.
2203 · External scripts starting with "#!" or "extproc " will be executed
2205 directly, without calling the shell, by calling the program
2206 specified on the rest of the first line.
2207 Memory allocation
2209 Perl uses its own malloc() under OS/2 - interpreters are usually
2210 malloc-bound for speed, but perl is not, since its malloc is lightning-
2211 fast. Perl-memory-usage-tuned benchmarks show that Perl's malloc is 5
2212 times quicker than EMX one. I do not have convincing data about memory
2213 footprint, but a (pretty random) benchmark showed that Perl's one is 5%
2214 better.
2215 Combination of perl's malloc() and rigid DLL name resolution creates a
2217 special problem with library functions which expect their return value
2218 to be free()d by system's free(). To facilitate extensions which need
2219 to call such functions, system memory-allocation functions are still
2220 available with the prefix "emx_" added. (Currently only DLL perl has
2221 this, it should propagate to perl_.exe shortly.)
2222 Threads
2224 One can build perl with thread support enabled by providing "-D
2225 usethreads" option to Configure. Currently OS/2 support of threads is
2226 very preliminary.
2227 Most notable problems:
2229 "COND_WAIT"
2231 may have a race condition (but probably does not due to edge-
2232 triggered nature of OS/2 Event semaphores). (Needs a
2233 reimplementation (in terms of chaining waiting threads, with the
2234 linked list stored in per-thread structure?)?)
2235 os2.c
2237 has a couple of static variables used in OS/2-specific functions.
2238 (Need to be moved to per-thread structure, or serialized?)
2239 Note that these problems should not discourage experimenting, since
2241 they have a low probability of affecting small programs.
2242
2244 This description is not updated often (since 5.6.1?), see ./os2/Changes
2245 for more info.
2246
2248 Ilya Zakharevich, cpan@ilyaz.org
2249
2251 perl(1).
2252perl v5.16.3 2013-03-06 PERLOS2(1)