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
90 emxbind(1). Note that under DOS for best results one should use
91 RSX runtime, which has much more functions working (like "fork",
92 "popen" and so on). In fact RSX is required if there is no VCPI
93 present. Note the RSX requires DPMI. Many implementations of
94 DPMI are known to 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 which
226 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 need
300 to specify your shell explicitly, like `cmd /c copy a b`, since
301 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.38.2/
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 overwritable (see
510 ""PERLLIB_PREFIX"", ""PERL_SH_DIR""), some people may prefer binary
511 editing 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 os2/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/>). Such
733 patches usually contain strings "/os2/" and "patch", so it makes sense
734 looking for these strings.
735 Hand-editing
737 You may look into the file ./hints/os2.sh and correct anything wrong
738 you find there. I do not expect it is needed anywhere.
739 Making
741 sh Configure -des -D prefix=f:/perllib
742 "prefix" means: where to install the resulting perl library. Giving
744 correct prefix you may avoid the need to specify "PERLLIB_PREFIX", see
745 ""PERLLIB_PREFIX"".
746 Ignore the message about missing "ln", and about "-c" option to tr. The
748 latter is most probably already fixed, if you see it and can trace
749 where the latter spurious warning comes from, please inform me.
750 Now
752 make
754 At some moment the built may die, reporting a version mismatch or
756 unable to run perl. This means that you do not have . in your LIBPATH,
757 so perl.exe cannot find the needed perl67B2.dll (treat these hex digits
758 as line noise). After this is fixed the build should finish without a
759 lot of fuss.
760 Testing
762 Now run
763 make test
765 All tests should succeed (with some of them skipped). If you have the
767 same version of Perl installed, it is crucial that you have "." early
768 in your LIBPATH (or in BEGINLIBPATH), otherwise your tests will most
769 probably test the wrong version of Perl.
770 Some tests may generate extra messages similar to
772 A lot of "bad free"
774 in database tests related to Berkeley DB. This should be fixed
775 already. If it persists, you may disable this warnings, see
776 ""PERL_BADFREE"".
777 Process terminated by SIGTERM/SIGINT
779 This is a standard message issued by OS/2 applications. *nix
780 applications die in silence. It is considered to be a feature. One
781 can easily disable this by appropriate sighandlers.
782 However the test engine bleeds these message to screen in
784 unexpected moments. Two messages of this kind should be present
785 during testing.
786 To get finer test reports, call
788 perl t/harness
790 The report with io/pipe.t failing may look like this:
792 Failed Test Status Wstat Total Fail Failed List of failed
794 ------------------------------------------------------------
795 io/pipe.t 12 1 8.33% 9
796 7 tests skipped, plus 56 subtests skipped.
797 Failed 1/195 test scripts, 99.49% okay. 1/6542 subtests failed,
798 99.98% okay.
799 The reasons for most important skipped tests are:
801 op/fs.t
803 18 Checks "atime" and "mtime" of stat() - unfortunately, HPFS
804 provides only 2sec time granularity (for compatibility with
805 FAT?).
806 25 Checks truncate() on a filehandle just opened for write - I
808 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, HPFS
814 provides only 2sec time granularity (for compatibility with
815 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 executables compiled without
989 "-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 \
1151 -DPERL_DLL_BASENAME=\"perl312F\" -Zstack 8192 -Zlinker /PM:VIO
1152 Here is the sample C file:
1154 #define INCL_DOS
1156 #define INCL_NOPM
1157 /* These are needed for compile if os2.h includes os2tk.h, not
1158 * os2emx.h */
1159 #define INCL_DOSPROCESS
1160 #include <os2.h>
1161 #include "EXTERN.h"
1163 #define PERL_IN_MINIPERLMAIN_C
1164 #include "perl.h"
1165 static char *me;
1167 HMODULE handle;
1168 static void
1170 die_with(char *msg1, char *msg2, char *msg3, char *msg4)
1171 {
1172 ULONG c;
1173 char *s = " error: ";
1174 DosWrite(2, me, strlen(me), &c);
1176 DosWrite(2, s, strlen(s), &c);
1177 DosWrite(2, msg1, strlen(msg1), &c);
1178 DosWrite(2, msg2, strlen(msg2), &c);
1179 DosWrite(2, msg3, strlen(msg3), &c);
1180 DosWrite(2, msg4, strlen(msg4), &c);
1181 DosWrite(2, "\r\n", 2, &c);
1182 exit(255);
1183 }
1184 typedef ULONG (*fill_extLibpath_t)(int type,
1186 char *pre,
1187 char *post,
1188 int replace,
1189 char *msg);
1190 typedef int (*main_t)(int type, char *argv[], char *env[]);
1191 typedef int (*handler_t)(void* data, int which);
1192 #ifndef PERL_DLL_BASENAME
1194 # define PERL_DLL_BASENAME "perl"
1195 #endif
1196 static HMODULE
1198 load_perl_dll(char *basename)
1199 {
1200 char buf[300], fail[260];
1201 STRLEN l, dirl;
1202 fill_extLibpath_t f;
1203 ULONG rc_fullname;
1204 HMODULE handle, handle1;
1205 if (_execname(buf, sizeof(buf) - 13) != 0)
1207 die_with("Can't find full path: ", strerror(errno), "", "");
1208 /* XXXX Fill 'me' with new value */
1209 l = strlen(buf);
1210 while (l && buf[l-1] != '/' && buf[l-1] != '\\')
1211 l--;
1212 dirl = l - 1;
1213 strcpy(buf + l, basename);
1214 l += strlen(basename);
1215 strcpy(buf + l, ".dll");
1216 if ( (rc_fullname = DosLoadModule(fail, sizeof fail, buf, &handle))
1217 != 0
1218 && DosLoadModule(fail, sizeof fail, basename, &handle) != 0 )
1219 die_with("Can't load DLL ", buf, "", "");
1220 if (rc_fullname)
1221 return handle; /* was loaded with short name; all is fine */
1222 if (DosQueryProcAddr(handle, 0, "fill_extLibpath", (PFN*)&f))
1223 die_with(buf,
1224 ": DLL exports no symbol ",
1225 "fill_extLibpath",
1226 "");
1227 buf[dirl] = 0;
1228 if (f(0 /*BEGINLIBPATH*/, buf /* prepend */, NULL /* append */,
1229 0 /* keep old value */, me))
1230 die_with(me, ": prepending BEGINLIBPATH", "", "");
1231 if (DosLoadModule(fail, sizeof fail, basename, &handle1) != 0)
1232 die_with(me,
1233 ": finding perl DLL again via BEGINLIBPATH",
1234 "",
1235 "");
1236 buf[dirl] = '\\';
1237 if (handle1 != handle) {
1238 if (DosQueryModuleName(handle1, sizeof(fail), fail))
1239 strcpy(fail, "???");
1240 die_with(buf,
1241 ":\n\tperl DLL via BEGINLIBPATH is different: \n\t",
1242 fail,
1243 "\n\tYou may need to manipulate global BEGINLIBPATH"
1244 " and LIBPATHSTRICT"
1245 "\n\tso that the other copy is loaded via"
1246 BEGINLIBPATH.");
1247 }
1248 return handle;
1249 }
1250 int
1252 main(int argc, char **argv, char **env)
1253 {
1254 main_t f;
1255 handler_t h;
1256 me = argv[0];
1258 /**/
1259 handle = load_perl_dll(PERL_DLL_BASENAME);
1260 if (DosQueryProcAddr(handle,
1262 0,
1263 "Perl_OS2_handler_install",
1264 (PFN*)&h))
1265 die_with(PERL_DLL_BASENAME,
1266 ": DLL exports no symbol ",
1267 "Perl_OS2_handler_install",
1268 "");
1269 if ( !h((void *)"~installprefix", Perlos2_handler_perllib_from)
1270 || !h((void *)"~dll", Perlos2_handler_perllib_to)
1271 || !h((void *)"~dll/sh/ksh.exe", Perlos2_handler_perl_sh) )
1272 die_with(PERL_DLL_BASENAME,
1273 ": Can't install @INC manglers",
1274 "",
1275 "");
1276 if (DosQueryProcAddr(handle, 0, "dll_perlmain", (PFN*)&f))
1277 die_with(PERL_DLL_BASENAME,
1278 ": DLL exports no symbol ",
1279 "dll_perlmain",
1280 "");
1281 return f(argc, argv, env);
1282 }
1283
1285 Some "/" became "\" in pdksh.
1286 You have a very old pdksh. See "Prerequisites".
1287 'errno' - unresolved external
1289 You do not have MT-safe db.lib. See "Prerequisites".
1290 Problems with tr or sed
1292 reported with very old version of tr and sed.
1293 Some problem (forget which ;-)
1295 You have an older version of perl.dll on your LIBPATH, which broke the
1296 build of extensions.
1297 Library ... not found
1299 You did not run "omflibs". See "Prerequisites".
1300 Segfault in make
1302 You use an old version of GNU make. See "Prerequisites".
1303 op/sprintf test failure
1305 This can result from a bug in emx sprintf which was fixed in 0.9d fix
1306 03.
1307
1309 "setpriority", "getpriority"
1310 Note that these functions are compatible with *nix, not with the older
1311 ports of '94 - 95. The priorities are absolute, go from 32 to -95,
1312 lower is quicker. 0 is the default priority.
1313 WARNING. Calling "getpriority" on a non-existing process could lock
1315 the system before Warp3 fixpak22. Starting with Warp3, Perl will use a
1316 workaround: it aborts getpriority() if the process is not present.
1317 This is not possible on older versions "2.*", and has a race condition
1318 anyway.
1319 system()
1321 Multi-argument form of system() allows an additional numeric argument.
1322 The meaning of this argument is described in OS2::Process.
1323 When finding a program to run, Perl first asks the OS to look for
1325 executables on "PATH" (OS/2 adds extension .exe if no extension is
1326 present). If not found, it looks for a script with possible extensions
1327 added in this order: no extension, .cmd, .btm, .bat, .pl. If found,
1328 Perl checks the start of the file for magic strings "#!" and "extproc
1329 ". If found, Perl uses the rest of the first line as the beginning of
1330 the command line to run this script. The only mangling done to the
1331 first line is extraction of arguments (currently up to 3), and ignoring
1332 of the path-part of the "interpreter" name if it can't be found using
1333 the full path.
1334 E.g., "system 'foo', 'bar', 'baz'" may lead Perl to finding
1336 C:/emx/bin/foo.cmd with the first line being
1337 extproc /bin/bash -x -c
1339 If /bin/bash.exe is not found, then Perl looks for an executable
1341 bash.exe on "PATH". If found in C:/emx.add/bin/bash.exe, then the
1342 above system() is translated to
1343 system qw(C:/emx.add/bin/bash.exe -x -c C:/emx/bin/foo.cmd bar baz)
1345 One additional translation is performed: instead of /bin/sh Perl uses
1347 the hardwired-or-customized shell (see ""PERL_SH_DIR"").
1348 The above search for "interpreter" is recursive: if bash executable is
1350 not found, but bash.btm is found, Perl will investigate its first line
1351 etc. The only hardwired limit on the recursion depth is implicit:
1352 there is a limit 4 on the number of additional arguments inserted
1353 before the actual arguments given to system(). In particular, if no
1354 additional arguments are specified on the "magic" first lines, then the
1355 limit on the depth is 4.
1356 If Perl finds that the found executable is of PM type when the current
1358 session is not, it will start the new process in a separate session of
1359 necessary type. Call via "OS2::Process" to disable this magic.
1360 WARNING. Due to the described logic, you need to explicitly specify
1362 .com extension if needed. Moreover, if the executable perl5.6.1 is
1363 requested, Perl will not look for perl5.6.1.exe. [This may change in
1364 the future.]
1365 "extproc" on the first line
1367 If the first chars of a Perl script are "extproc ", this line is
1368 treated as "#!"-line, thus all the switches on this line are processed
1369 (twice if script was started via cmd.exe). See "DESCRIPTION" in
1370 perlrun.
1371 Additional modules:
1373 OS2::Process, OS2::DLL, OS2::REXX, OS2::PrfDB, OS2::ExtAttr. These
1374 modules provide access to additional numeric argument for "system" and
1375 to the information about the running process, to DLLs having functions
1376 with REXX signature and to the REXX runtime, to OS/2 databases in the
1377 .INI format, and to Extended Attributes.
1378 Two additional extensions by Andreas Kaiser, "OS2::UPM", and
1380 "OS2::FTP", are included into "ILYAZ" directory, mirrored on CPAN.
1381 Other OS/2-related extensions are available too.
1382 Prebuilt methods:
1384 "File::Copy::syscopy"
1385 used by "File::Copy::copy", see File::Copy.
1386 "DynaLoader::mod2fname"
1388 used by "DynaLoader" for DLL name mangling.
1389 Cwd::current_drive()
1391 Self explanatory.
1392 Cwd::sys_chdir(name)
1394 leaves drive as it is.
1395 Cwd::change_drive(name)
1397 changes the "current" drive.
1398 Cwd::sys_is_absolute(name)
1400 means has drive letter and is_rooted.
1401 Cwd::sys_is_rooted(name)
1403 means has leading "[/\\]" (maybe after a drive-letter:).
1404 Cwd::sys_is_relative(name)
1406 means changes with current dir.
1407 Cwd::sys_cwd(name)
1409 Interface to cwd from EMX. Used by "Cwd::cwd".
1410 "Cwd::sys_abspath(name, dir)"
1412 Really really odious function to implement. Returns absolute name
1413 of file which would have "name" if CWD were "dir". "Dir" defaults
1414 to the current dir.
1415 Cwd::extLibpath([type])
1417 Get current value of extended library search path. If "type" is
1418 present and positive, works with "END_LIBPATH", if negative, works
1419 with "LIBPATHSTRICT", otherwise with "BEGIN_LIBPATH".
1420 "Cwd::extLibpath_set( path [, type ] )"
1422 Set current value of extended library search path. If "type" is
1423 present and positive, works with <END_LIBPATH>, if negative, works
1424 with "LIBPATHSTRICT", otherwise with "BEGIN_LIBPATH".
1425 "OS2::Error(do_harderror,do_exception)"
1427 Returns "undef" if it was not called yet, otherwise bit 1 is set
1428 if on the previous call do_harderror was enabled, bit 2 is set if
1429 on previous call do_exception was enabled.
1430 This function enables/disables error popups associated with
1432 hardware errors (Disk not ready etc.) and software exceptions.
1433 I know of no way to find out the state of popups before the first
1435 call to this function.
1436 OS2::Errors2Drive(drive)
1438 Returns "undef" if it was not called yet, otherwise return false if
1439 errors were not requested to be written to a hard drive, or the
1440 drive letter if this was requested.
1441 This function may redirect error popups associated with hardware
1443 errors (Disk not ready etc.) and software exceptions to the file
1444 POPUPLOG.OS2 at the root directory of the specified drive.
1445 Overrides OS2::Error() specified by individual programs. Given
1446 argument undef will disable redirection.
1447 Has global effect, persists after the application exits.
1449 I know of no way to find out the state of redirection of popups to
1451 the disk before the first call to this function.
1452 OS2::SysInfo()
1454 Returns a hash with system information. The keys of the hash are
1455 MAX_PATH_LENGTH, MAX_TEXT_SESSIONS, MAX_PM_SESSIONS,
1457 MAX_VDM_SESSIONS, BOOT_DRIVE, DYN_PRI_VARIATION,
1458 MAX_WAIT, MIN_SLICE, MAX_SLICE, PAGE_SIZE,
1459 VERSION_MAJOR, VERSION_MINOR, VERSION_REVISION,
1460 MS_COUNT, TIME_LOW, TIME_HIGH, TOTPHYSMEM, TOTRESMEM,
1461 TOTAVAILMEM, MAXPRMEM, MAXSHMEM, TIMER_INTERVAL,
1462 MAX_COMP_LENGTH, FOREGROUND_FS_SESSION,
1463 FOREGROUND_PROCESS
1464 OS2::BootDrive()
1466 Returns a letter without colon.
1467 OS2::MorphPM(serve), OS2::UnMorphPM(serve)
1469 Transforms the current application into a PM application and back.
1470 The argument true means that a real message loop is going to be
1471 served. OS2::MorphPM() returns the PM message queue handle as an
1472 integer.
1473 See "Centralized management of resources" for additional details.
1475 OS2::Serve_Messages(force)
1477 Fake on-demand retrieval of outstanding PM messages. If "force" is
1478 false, will not dispatch messages if a real message loop is known
1479 to be present. Returns number of messages retrieved.
1480 Dies with "QUITing..." if WM_QUIT message is obtained.
1482 "OS2::Process_Messages(force [, cnt])"
1484 Retrieval of PM messages until window creation/destruction. If
1485 "force" is false, will not dispatch messages if a real message loop
1486 is known to be present.
1487 Returns change in number of windows. If "cnt" is given, it is
1489 incremented by the number of messages retrieved.
1490 Dies with "QUITing..." if WM_QUIT message is obtained.
1492 "OS2::_control87(new,mask)"
1494 the same as _control87(3) of EMX. Takes integers as arguments,
1495 returns the previous coprocessor control word as an integer. Only
1496 bits in "new" which are present in "mask" are changed in the
1497 control word.
1498 OS2::get_control87()
1500 gets the coprocessor control word as an integer.
1501 "OS2::set_control87_em(new=MCW_EM,mask=MCW_EM)"
1503 The variant of OS2::_control87() with default values good for
1504 handling exception mask: if no "mask", uses exception mask part of
1505 "new" only. If no "new", disables all the floating point
1506 exceptions.
1507 See "Misfeatures" for details.
1509 "OS2::DLLname([how [, \&xsub]])"
1511 Gives the information about the Perl DLL or the DLL containing the
1512 C function bound to by &xsub. The meaning of "how" is: default
1513 (2): full name; 0: handle; 1: module name.
1514 (Note that some of these may be moved to different libraries -
1516 eventually).
1517 Prebuilt variables:
1519 $OS2::emx_rev
1520 numeric value is the same as _emx_rev of EMX, a string value the
1521 same as _emx_vprt (similar to "0.9c").
1522 $OS2::emx_env
1524 same as _emx_env of EMX, a number similar to 0x8001.
1525 $OS2::os_ver
1527 a number "OS_MAJOR + 0.001 * OS_MINOR".
1528 $OS2::is_aout
1530 true if the Perl library was compiled in AOUT format.
1531 $OS2::can_fork
1533 true if the current executable is an AOUT EMX executable, so Perl
1534 can fork. Do not use this, use the portable check for
1535 $Config::Config{dfork}.
1536 $OS2::nsyserror
1538 This variable (default is 1) controls whether to enforce the
1539 contents of $^E to start with "SYS0003"-like id. If set to 0, then
1540 the string value of $^E is what is available from the OS/2 message
1541 file. (Some messages in this file have an "SYS0003"-like id
1542 prepended, some not.)
1543 Misfeatures
1545 • Since flock(3) is present in EMX, but is not functional, it is
1546 emulated by perl. To disable the emulations, set environment
1547 variable "USE_PERL_FLOCK=0".
1548 • Here is the list of things which may be "broken" on EMX (from EMX
1550 docs):
1551 • The functions recvmsg(3), sendmsg(3), and socketpair(3) are not
1553 implemented.
1554 • sock_init(3) is not required and not implemented.
1556 • flock(3) is not yet implemented (dummy function). (Perl has a
1558 workaround.)
1559 • kill(3): Special treatment of PID=0, PID=1 and PID=-1 is not
1561 implemented.
1562 • waitpid(3):
1564 WUNTRACED
1566 Not implemented.
1567 waitpid() is not implemented for negative values of PID.
1568 Note that "kill -9" does not work with the current version of EMX.
1570 • See "Text-mode filehandles".
1572 • Unix-domain sockets on OS/2 live in a pseudo-file-system
1574 "/sockets/...". To avoid a failure to create a socket with a name
1575 of a different form, "/socket/" is prepended to the socket name
1576 (unless it starts with this already).
1577 This may lead to problems later in case the socket is accessed via
1579 the "usual" file-system calls using the "initial" name.
1580 • Apparently, IBM used a compiler (for some period of time around
1582 '95?) which changes FP mask right and left. This is not that bad
1583 for IBM's programs, but the same compiler was used for DLLs which
1584 are used with general-purpose applications. When these DLLs are
1585 used, the state of floating-point flags in the application is not
1586 predictable.
1587 What is much worse, some DLLs change the floating point flags when
1589 in _DLLInitTerm() (e.g., TCP32IP). This means that even if you do
1590 not call any function in the DLL, just the act of loading this DLL
1591 will reset your flags. What is worse, the same compiler was used
1592 to compile some HOOK DLLs. Given that HOOK dlls are executed in
1593 the context of all the applications in the system, this means a
1594 complete unpredictability of floating point flags on systems using
1595 such HOOK DLLs. E.g., GAMESRVR.DLL of DIVE origin changes the
1596 floating point flags on each write to the TTY of a VIO (windowed
1597 text-mode) applications.
1598 Some other (not completely debugged) situations when FP flags
1600 change include some video drivers (?), and some operations related
1601 to creation of the windows. People who code OpenGL may have more
1602 experience on this.
1603 Perl is generally used in the situation when all the floating-point
1605 exceptions are ignored, as is the default under EMX. If they are
1606 not ignored, some benign Perl programs would get a "SIGFPE" and
1607 would die a horrible death.
1608 To circumvent this, Perl uses two hacks. They help against one
1610 type of damage only: FP flags changed when loading a DLL.
1611 One of the hacks is to disable floating point exceptions on Perl
1613 startup (as is the default with EMX). This helps only with
1614 compile-time-linked DLLs changing the flags before main() had a
1615 chance to be called.
1616 The other hack is to restore FP flags after a call to dlopen().
1618 This helps against similar damage done by DLLs _DLLInitTerm() at
1619 runtime. Currently no way to switch these hacks off is provided.
1620 Modifications
1622 Perl modifies some standard C library calls in the following ways:
1623 "popen" "my_popen" uses sh.exe if shell is required, cf.
1625 ""PERL_SH_DIR"".
1626 "tmpnam" is created using "TMP" or "TEMP" environment variable, via
1628 "tempnam".
1629 "tmpfile"
1631 If the current directory is not writable, file is created
1632 using modified "tmpnam", so there may be a race condition.
1633 "ctermid"
1635 a dummy implementation.
1636 "stat" "os2_stat" special-cases /dev/tty and /dev/con.
1638 "mkdir", "rmdir"
1640 these EMX functions do not work if the path contains a
1641 trailing "/". Perl contains a workaround for this.
1642 "flock" Since flock(3) is present in EMX, but is not functional, it is
1644 emulated by perl. To disable the emulations, set environment
1645 variable "USE_PERL_FLOCK=0".
1646 Identifying DLLs
1648 All the DLLs built with the current versions of Perl have ID strings
1649 identifying the name of the extension, its version, and the version of
1650 Perl required for this DLL. Run "bldlevel DLL-name" to find this info.
1651 Centralized management of resources
1653 Since to call certain OS/2 API one needs to have a correctly
1654 initialized "Win" subsystem, OS/2-specific extensions may require
1655 getting "HAB"s and "HMQ"s. If an extension would do it on its own,
1656 another extension could fail to initialize.
1657 Perl provides a centralized management of these resources:
1659 "HAB"
1661 To get the HAB, the extension should call "hab = perl_hab_GET()" in
1662 C. After this call is performed, "hab" may be accessed as
1663 "Perl_hab". There is no need to release the HAB after it is used.
1664 If by some reasons perl.h cannot be included, use
1666 extern int Perl_hab_GET(void);
1668 instead.
1670 "HMQ"
1672 There are two cases:
1673 • the extension needs an "HMQ" only because some API will not
1675 work otherwise. Use "serve = 0" below.
1676 • the extension needs an "HMQ" since it wants to engage in a PM
1678 event loop. Use "serve = 1" below.
1679 To get an "HMQ", the extension should call "hmq =
1681 perl_hmq_GET(serve)" in C. After this call is performed, "hmq" may
1682 be accessed as "Perl_hmq".
1683 To signal to Perl that HMQ is not needed any more, call
1685 perl_hmq_UNSET(serve). Perl process will automatically
1686 morph/unmorph itself into/from a PM process if HMQ is
1687 needed/not-needed. Perl will automatically enable/disable
1688 "WM_QUIT" message during shutdown if the message queue is
1689 served/not-served.
1690 NOTE. If during a shutdown there is a message queue which did not
1692 disable WM_QUIT, and which did not process the received WM_QUIT
1693 message, the shutdown will be automatically cancelled. Do not call
1694 perl_hmq_GET(1) unless you are going to process messages on an
1695 orderly basis.
1696 Treating errors reported by OS/2 API
1698 There are two principal conventions (it is useful to call them
1699 "Dos*" and "Win*" - though this part of the function signature is
1700 not always determined by the name of the API) of reporting the
1701 error conditions of OS/2 API. Most of "Dos*" APIs report the error
1702 code as the result of the call (so 0 means success, and there are
1703 many types of errors). Most of "Win*" API report success/fail via
1704 the result being "TRUE"/"FALSE"; to find the reason for the failure
1705 one should call WinGetLastError() API.
1706 Some "Win*" entry points also overload a "meaningful" return value
1708 with the error indicator; having a 0 return value indicates an
1709 error. Yet some other "Win*" entry points overload things even
1710 more, and 0 return value may mean a successful call returning a
1711 valid value 0, as well as an error condition; in the case of a 0
1712 return value one should call WinGetLastError() API to distinguish a
1713 successful call from a failing one.
1714 By convention, all the calls to OS/2 API should indicate their
1716 failures by resetting $^E. All the Perl-accessible functions which
1717 call OS/2 API may be broken into two classes: some die()s when an
1718 API error is encountered, the other report the error via a false
1719 return value (of course, this does not concern Perl-accessible
1720 functions which expect a failure of the OS/2 API call, having some
1721 workarounds coded).
1722 Obviously, in the situation of the last type of the signature of an
1724 OS/2 API, it is must more convenient for the users if the failure
1725 is indicated by die()ing: one does not need to check $^E to know
1726 that something went wrong. If, however, this solution is not
1727 desirable by some reason, the code in question should reset $^E to
1728 0 before making this OS/2 API call, so that the caller of this
1729 Perl-accessible function has a chance to distinguish a
1730 success-but-0-return value from a failure. (One may return undef
1731 as an alternative way of reporting an error.)
1732 The macros to simplify this type of error propagation are
1734 CheckOSError(expr)
1736 Returns true on error, sets $^E. Expects expr() be a call of
1737 "Dos*"-style API.
1738 CheckWinError(expr)
1740 Returns true on error, sets $^E. Expects expr() be a call of
1741 "Win*"-style API.
1742 SaveWinError(expr)
1744 Returns "expr", sets $^E from WinGetLastError() if "expr" is
1745 false.
1746 "SaveCroakWinError(expr,die,name1,name2)"
1748 Returns "expr", sets $^E from WinGetLastError() if "expr" is
1749 false, and die()s if "die" and $^E are true. The message to
1750 die is the concatenated strings "name1" and "name2", separated
1751 by ": " from the contents of $^E.
1752 "WinError_2_Perl_rc"
1754 Sets "Perl_rc" to the return value of WinGetLastError().
1755 "FillWinError"
1757 Sets "Perl_rc" to the return value of WinGetLastError(), and
1758 sets $^E to the corresponding value.
1759 FillOSError(rc)
1761 Sets "Perl_rc" to "rc", and sets $^E to the corresponding
1762 value.
1763 Loading DLLs and ordinals in DLLs
1765 Some DLLs are only present in some versions of OS/2, or in some
1766 configurations of OS/2. Some exported entry points are present
1767 only in DLLs shipped with some versions of OS/2. If these DLLs and
1768 entry points were linked directly for a Perl executable/DLL or from
1769 a Perl extensions, this binary would work only with the specified
1770 versions/setups. Even if these entry points were not needed, the
1771 load of the executable (or DLL) would fail.
1772 For example, many newer useful APIs are not present in OS/2 v2;
1774 many PM-related APIs require DLLs not available on floppy-boot
1775 setup.
1776 To make these calls fail only when the calls are executed, one
1778 should call these API via a dynamic linking API. There is a
1779 subsystem in Perl to simplify such type of calls. A large number
1780 of entry points available for such linking is provided (see
1781 "entries_ordinals" - and also "PMWIN_entries" - in os2ish.h).
1782 These ordinals can be accessed via the APIs:
1783 CallORD(), DeclFuncByORD(), DeclVoidFuncByORD(),
1785 DeclOSFuncByORD(), DeclWinFuncByORD(), AssignFuncPByORD(),
1786 DeclWinFuncByORD_CACHE(), DeclWinFuncByORD_CACHE_survive(),
1787 DeclWinFuncByORD_CACHE_resetError_survive(),
1788 DeclWinFunc_CACHE(), DeclWinFunc_CACHE_resetError(),
1789 DeclWinFunc_CACHE_survive(), DeclWinFunc_CACHE_resetError_survive()
1790 See the header files and the C code in the supplied OS/2-related
1792 modules for the details on usage of these functions.
1793 Some of these functions also combine dynaloading semantic with the
1795 error-propagation semantic discussed above.
1796
1798 Because of idiosyncrasies of OS/2 one cannot have all the eggs in the
1799 same basket (though EMX environment tries hard to overcome this
1800 limitations, so the situation may somehow improve). There are 4
1801 executables for Perl provided by the distribution:
1802 perl.exe
1804 The main workhorse. This is a chimera executable: it is compiled as an
1805 "a.out"-style executable, but is linked with "omf"-style dynamic
1806 library perl.dll, and with dynamic CRT DLL. This executable is a VIO
1807 application.
1808 It can load perl dynamic extensions, and it can fork().
1810 Note. Keep in mind that fork() is needed to open a pipe to yourself.
1812 perl_.exe
1814 This is a statically linked "a.out"-style executable. It cannot load
1815 dynamic Perl extensions. The executable supplied in binary
1816 distributions has a lot of extensions prebuilt, thus the above
1817 restriction is important only if you use custom-built extensions. This
1818 executable is a VIO application.
1819 This is the only executable with does not require OS/2. The friends
1821 locked into "M$" world would appreciate the fact that this executable
1822 runs under DOS, Win0.3*, Win0.95 and WinNT with an appropriate
1823 extender. See "Other OSes".
1824 perl__.exe
1826 This is the same executable as perl___.exe, but it is a PM application.
1827 Note. Usually (unless explicitly redirected during the startup) STDIN,
1829 STDERR, and STDOUT of a PM application are redirected to nul. However,
1830 it is possible to see them if you start "perl__.exe" from a PM program
1831 which emulates a console window, like Shell mode of Emacs or EPM. Thus
1832 it is possible to use Perl debugger (see perldebug) to debug your PM
1833 application (but beware of the message loop lockups - this will not
1834 work if you have a message queue to serve, unless you hook the serving
1835 into the getc() function of the debugger).
1836 Another way to see the output of a PM program is to run it as
1838 pm_prog args 2>&1 | cat -
1840 with a shell different from cmd.exe, so that it does not create a link
1842 between a VIO session and the session of "pm_porg". (Such a link
1843 closes the VIO window.) E.g., this works with sh.exe - or with Perl!
1844 open P, 'pm_prog args 2>&1 |' or die;
1846 print while <P>;
1847 The flavor perl__.exe is required if you want to start your program
1849 without a VIO window present, but not "detach"ed (run "help detach" for
1850 more info). Very useful for extensions which use PM, like "Perl/Tk" or
1851 "OpenGL".
1852 Note also that the differences between PM and VIO executables are only
1854 in the default behaviour. One can start any executable in any kind of
1855 session by using the arguments "/fs", "/pm" or "/win" switches of the
1856 command "start" (of CMD.EXE or a similar shell). Alternatively, one
1857 can use the numeric first argument of the "system" Perl function (see
1858 OS2::Process).
1859 perl___.exe
1861 This is an "omf"-style executable which is dynamically linked to
1862 perl.dll and CRT DLL. I know no advantages of this executable over
1863 "perl.exe", but it cannot fork() at all. Well, one advantage is that
1864 the build process is not so convoluted as with "perl.exe".
1865 It is a VIO application.
1867 Why strange names?
1869 Since Perl processes the "#!"-line (cf. "DESCRIPTION" in perlrun,
1870 "Command Switches" in perlrun, "No Perl script found in input" in
1871 perldiag), it should know when a program is a Perl. There is some
1872 naming convention which allows Perl to distinguish correct lines from
1873 wrong ones. The above names are almost the only names allowed by this
1874 convention which do not contain digits (which have absolutely different
1875 semantics).
1876 Why dynamic linking?
1878 Well, having several executables dynamically linked to the same huge
1879 library has its advantages, but this would not substantiate the
1880 additional work to make it compile. The reason is the complicated-to-
1881 developers but very quick and convenient-to-users "hard" dynamic
1882 linking used by OS/2.
1883 There are two distinctive features of the dyna-linking model of OS/2:
1885 first, all the references to external functions are resolved at the
1886 compile time; second, there is no runtime fixup of the DLLs after they
1887 are loaded into memory. The first feature is an enormous advantage
1888 over other models: it avoids conflicts when several DLLs used by an
1889 application export entries with the same name. In such cases "other"
1890 models of dyna-linking just choose between these two entry points using
1891 some random criterion - with predictable disasters as results. But it
1892 is the second feature which requires the build of perl.dll.
1893 The address tables of DLLs are patched only once, when they are loaded.
1895 The addresses of the entry points into DLLs are guaranteed to be the
1896 same for all the programs which use the same DLL. This removes the
1897 runtime fixup - once DLL is loaded, its code is read-only.
1898 While this allows some (significant?) performance advantages, this
1900 makes life much harder for developers, since the above scheme makes it
1901 impossible for a DLL to be "linked" to a symbol in the .EXE file.
1902 Indeed, this would need a DLL to have different relocations tables for
1903 the (different) executables which use this DLL.
1904 However, a dynamically loaded Perl extension is forced to use some
1906 symbols from the perl executable, e.g., to know how to find the
1907 arguments to the functions: the arguments live on the perl internal
1908 evaluation stack. The solution is to put the main code of the
1909 interpreter into a DLL, and make the .EXE file which just loads this
1910 DLL into memory and supplies command-arguments. The extension DLL
1911 cannot link to symbols in .EXE, but it has no problem linking to
1912 symbols in the .DLL.
1913 This greatly increases the load time for the application (as well as
1915 complexity of the compilation). Since interpreter is in a DLL, the C
1916 RTL is basically forced to reside in a DLL as well (otherwise
1917 extensions would not be able to use CRT). There are some advantages if
1918 you use different flavors of perl, such as running perl.exe and
1919 perl__.exe simultaneously: they share the memory of perl.dll.
1920 NOTE. There is one additional effect which makes DLLs more wasteful:
1922 DLLs are loaded in the shared memory region, which is a scarse resource
1923 given the 512M barrier of the "standard" OS/2 virtual memory. The code
1924 of .EXE files is also shared by all the processes which use the
1925 particular .EXE, but they are "shared in the private address space of
1926 the process"; this is possible because the address at which different
1927 sections of the .EXE file are loaded is decided at compile-time, thus
1928 all the processes have these sections loaded at same addresses, and no
1929 fixup of internal links inside the .EXE is needed.
1930 Since DLLs may be loaded at run time, to have the same mechanism for
1932 DLLs one needs to have the address range of any of the loaded DLLs in
1933 the system to be available in all the processes which did not load a
1934 particular DLL yet. This is why the DLLs are mapped to the shared
1935 memory region.
1936 Why chimera build?
1938 Current EMX environment does not allow DLLs compiled using Unixish
1939 "a.out" format to export symbols for data (or at least some types of
1940 data). This forces "omf"-style compile of perl.dll.
1941 Current EMX environment does not allow .EXE files compiled in "omf"
1943 format to fork(). fork() is needed for exactly three Perl operations:
1944 • explicit fork() in the script,
1946 • "open FH, "|-""
1948 • "open FH, "-|"", in other words, opening pipes to itself.
1950 While these operations are not questions of life and death, they are
1952 needed for a lot of useful scripts. This forces "a.out"-style compile
1953 of perl.exe.
1954
1956 Here we list environment variables with are either OS/2- and DOS- and
1957 Win*-specific, or are more important under OS/2 than under other OSes.
1958 "PERLLIB_PREFIX"
1960 Specific for EMX port. Should have the form
1961 path1;path2
1963 or
1965 path1 path2
1967 If the beginning of some prebuilt path matches path1, it is substituted
1969 with path2.
1970 Should be used if the perl library is moved from the default location
1972 in preference to "PERL(5)LIB", since this would not leave wrong entries
1973 in @INC. For example, if the compiled version of perl looks for @INC
1974 in f:/perllib/lib, and you want to install the library in h:/opt/gnu,
1975 do
1976 set PERLLIB_PREFIX=f:/perllib/lib;h:/opt/gnu
1978 This will cause Perl with the prebuilt @INC of
1980 f:/perllib/lib/5.00553/os2
1982 f:/perllib/lib/5.00553
1983 f:/perllib/lib/site_perl/5.00553/os2
1984 f:/perllib/lib/site_perl/5.00553
1985 .
1986 to use the following @INC:
1988 h:/opt/gnu/5.00553/os2
1990 h:/opt/gnu/5.00553
1991 h:/opt/gnu/site_perl/5.00553/os2
1992 h:/opt/gnu/site_perl/5.00553
1993 .
1994 "PERL_BADLANG"
1996 If 0, perl ignores setlocale() failing. May be useful with some strange
1997 locales.
1998 "PERL_BADFREE"
2000 If 0, perl would not warn of in case of unwarranted free(). With older
2001 perls this might be useful in conjunction with the module DB_File,
2002 which was buggy when dynamically linked and OMF-built.
2003 Should not be set with newer Perls, since this may hide some real
2005 problems.
2006 "PERL_SH_DIR"
2008 Specific for EMX port. Gives the directory part of the location for
2009 sh.exe.
2010 "USE_PERL_FLOCK"
2012 Specific for EMX port. Since flock(3) is present in EMX, but is not
2013 functional, it is emulated by perl. To disable the emulations, set
2014 environment variable "USE_PERL_FLOCK=0".
2015 "TMP" or "TEMP"
2017 Specific for EMX port. Used as storage place for temporary files.
2018
2020 Here we list major changes which could make you by surprise.
2021 Text-mode filehandles
2023 Starting from version 5.8, Perl uses a builtin translation layer for
2024 text-mode files. This replaces the efficient well-tested EMX layer by
2025 some code which should be best characterized as a "quick hack".
2026 In addition to possible bugs and an inability to follow changes to the
2028 translation policy with off/on switches of TERMIO translation, this
2029 introduces a serious incompatible change: before sysread() on text-mode
2030 filehandles would go through the translation layer, now it would not.
2031 Priorities
2033 "setpriority" and "getpriority" are not compatible with earlier ports
2034 by Andreas Kaiser. See "setpriority, getpriority".
2035 DLL name mangling: pre 5.6.2
2037 With the release 5.003_01 the dynamically loadable libraries should be
2038 rebuilt when a different version of Perl is compiled. In particular,
2039 DLLs (including perl.dll) are now created with the names which contain
2040 a checksum, thus allowing workaround for OS/2 scheme of caching DLLs.
2041 It may be possible to code a simple workaround which would
2043 • find the old DLLs looking through the old @INC;
2045 • mangle the names according to the scheme of new perl and copy the
2047 DLLs to these names;
2048 • edit the internal "LX" tables of DLL to reflect the change of the
2050 name (probably not needed for Perl extension DLLs, since the
2051 internally coded names are not used for "specific" DLLs, they used
2052 only for "global" DLLs).
2053 • edit the internal "IMPORT" tables and change the name of the "old"
2055 perl????.dll to the "new" perl????.dll.
2056 DLL name mangling: 5.6.2 and beyond
2058 In fact mangling of extension DLLs was done due to misunderstanding of
2059 the OS/2 dynaloading model. OS/2 (effectively) maintains two different
2060 tables of loaded DLL:
2061 Global DLLs
2063 those loaded by the base name from "LIBPATH"; including those
2064 associated at link time;
2065 specific DLLs
2067 loaded by the full name.
2068 When resolving a request for a global DLL, the table of already-loaded
2070 specific DLLs is (effectively) ignored; moreover, specific DLLs are
2071 always loaded from the prescribed path.
2072 There is/was a minor twist which makes this scheme fragile: what to do
2074 with DLLs loaded from
2075 "BEGINLIBPATH" and "ENDLIBPATH"
2077 (which depend on the process)
2078 . from "LIBPATH"
2080 which effectively depends on the process (although "LIBPATH" is the
2081 same for all the processes).
2082 Unless "LIBPATHSTRICT" is set to "T" (and the kernel is after
2084 2000/09/01), such DLLs are considered to be global. When loading a
2085 global DLL it is first looked in the table of already-loaded global
2086 DLLs. Because of this the fact that one executable loaded a DLL from
2087 "BEGINLIBPATH" and "ENDLIBPATH", or . from "LIBPATH" may affect which
2088 DLL is loaded when another executable requests a DLL with the same
2089 name. This is the reason for version-specific mangling of the DLL name
2090 for perl DLL.
2091 Since the Perl extension DLLs are always loaded with the full path,
2093 there is no need to mangle their names in a version-specific ways:
2094 their directory already reflects the corresponding version of perl, and
2095 @INC takes into account binary compatibility with older version.
2096 Starting from 5.6.2 the name mangling scheme is fixed to be the same as
2097 for Perl 5.005_53 (same as in a popular binary release). Thus new
2098 Perls will be able to resolve the names of old extension DLLs if @INC
2099 allows finding their directories.
2100 However, this still does not guarantee that these DLL may be loaded.
2102 The reason is the mangling of the name of the Perl DLL. And since the
2103 extension DLLs link with the Perl DLL, extension DLLs for older
2104 versions would load an older Perl DLL, and would most probably segfault
2105 (since the data in this DLL is not properly initialized).
2106 There is a partial workaround (which can be made complete with newer
2108 OS/2 kernels): create a forwarder DLL with the same name as the DLL of
2109 the older version of Perl, which forwards the entry points to the newer
2110 Perl's DLL. Make this DLL accessible on (say) the "BEGINLIBPATH" of
2111 the new Perl executable. When the new executable accesses old Perl's
2112 extension DLLs, they would request the old Perl's DLL by name, get the
2113 forwarder instead, so effectively will link with the currently running
2114 (new) Perl DLL.
2115 This may break in two ways:
2117 • Old perl executable is started when a new executable is running has
2119 loaded an extension compiled for the old executable (ouph!). In
2120 this case the old executable will get a forwarder DLL instead of
2121 the old perl DLL, so would link with the new perl DLL. While not
2122 directly fatal, it will behave the same as new executable. This
2123 beats the whole purpose of explicitly starting an old executable.
2124 • A new executable loads an extension compiled for the old executable
2126 when an old perl executable is running. In this case the extension
2127 will not pick up the forwarder - with fatal results.
2128 With support for "LIBPATHSTRICT" this may be circumvented - unless one
2130 of DLLs is started from . from "LIBPATH" (I do not know whether
2131 "LIBPATHSTRICT" affects this case).
2132 REMARK. Unless newer kernels allow . in "BEGINLIBPATH" (older do not),
2134 this mess cannot be completely cleaned. (It turns out that as of the
2135 beginning of 2002, . is not allowed, but .\. is - and it has the same
2136 effect.)
2137 REMARK. "LIBPATHSTRICT", "BEGINLIBPATH" and "ENDLIBPATH" are not
2139 environment variables, although cmd.exe emulates them on "SET ..."
2140 lines. From Perl they may be accessed by Cwd::extLibpath and
2141 Cwd::extLibpath_set.
2142 DLL forwarder generation
2144 Assume that the old DLL is named perlE0AC.dll (as is one for 5.005_53),
2145 and the new version is 5.6.1. Create a file perl5shim.def-leader with
2146 LIBRARY 'perlE0AC' INITINSTANCE TERMINSTANCE
2148 DESCRIPTION '@#perl5-porters@perl.org:5.006001#@ Perl module for 5.00553 -> Perl 5.6.1 forwarder'
2149 CODE LOADONCALL
2150 DATA LOADONCALL NONSHARED MULTIPLE
2151 EXPORTS
2152 modifying the versions/names as needed. Run
2154 perl -wnle "next if 0../EXPORTS/; print qq( \"$1\")
2156 if /\"(\w+)\"/" perl5.def >lst
2157 in the Perl build directory (to make the DLL smaller replace perl5.def
2159 with the definition file for the older version of Perl if present).
2160 cat perl5shim.def-leader lst >perl5shim.def
2162 gcc -Zomf -Zdll -o perlE0AC.dll perl5shim.def -s -llibperl
2163 (ignore multiple "warning L4085").
2165 Threading
2167 As of release 5.003_01 perl is linked to multithreaded C RTL DLL. If
2168 perl itself is not compiled multithread-enabled, so will not be perl's
2169 malloc(). However, extensions may use multiple thread on their own
2170 risk.
2171 This was needed to compile "Perl/Tk" for XFree86-OS/2 out-of-the-box,
2173 and link with DLLs for other useful libraries, which typically are
2174 compiled with "-Zmt -Zcrtdll".
2175 Calls to external programs
2177 Due to a popular demand the perl external program calling has been
2178 changed wrt Andreas Kaiser's port. If perl needs to call an external
2179 program via shell, the f:/bin/sh.exe will be called, or whatever is the
2180 override, see ""PERL_SH_DIR"".
2181 Thus means that you need to get some copy of a sh.exe as well (I use
2183 one from pdksh). The path F:/bin above is set up automatically during
2184 the build to a correct value on the builder machine, but is overridable
2185 at runtime,
2186 Reasons: a consensus on "perl5-porters" was that perl should use one
2188 non-overridable shell per platform. The obvious choices for OS/2 are
2189 cmd.exe and sh.exe. Having perl build itself would be impossible with
2190 cmd.exe as a shell, thus I picked up "sh.exe". This assures almost 100%
2191 compatibility with the scripts coming from *nix. As an added benefit
2192 this works as well under DOS if you use DOS-enabled port of pdksh (see
2193 "Prerequisites").
2194 Disadvantages: currently sh.exe of pdksh calls external programs via
2196 fork()/exec(), and there is no functioning exec() on OS/2. exec() is
2197 emulated by EMX by an asynchronous call while the caller waits for
2198 child completion (to pretend that the "pid" did not change). This means
2199 that 1 extra copy of sh.exe is made active via fork()/exec(), which may
2200 lead to some resources taken from the system (even if we do not count
2201 extra work needed for fork()ing).
2202 Note that this a lesser issue now when we do not spawn sh.exe unless
2204 needed (metachars found).
2205 One can always start cmd.exe explicitly via
2207 system 'cmd', '/c', 'mycmd', 'arg1', 'arg2', ...
2209 If you need to use cmd.exe, and do not want to hand-edit thousands of
2211 your scripts, the long-term solution proposed on p5-p is to have a
2212 directive
2213 use OS2::Cmd;
2215 which will override system(), exec(), ``, and "open(,'...|')". With
2217 current perl you may override only system(), readpipe() - the explicit
2218 version of ``, and maybe exec(). The code will substitute the one-
2219 argument call to system() by "CORE::system('cmd.exe', '/c', shift)".
2220 If you have some working code for "OS2::Cmd", please send it to me, I
2222 will include it into distribution. I have no need for such a module, so
2223 cannot test it.
2224 For the details of the current situation with calling external
2226 programs, see "Starting OS/2 (and DOS) programs under Perl". Set us
2227 mention a couple of features:
2228 • External scripts may be called by their basename. Perl will try
2230 the same extensions as when processing -S command-line switch.
2231 • External scripts starting with "#!" or "extproc " will be executed
2233 directly, without calling the shell, by calling the program
2234 specified on the rest of the first line.
2235 Memory allocation
2237 Perl uses its own malloc() under OS/2 - interpreters are usually
2238 malloc-bound for speed, but perl is not, since its malloc is lightning-
2239 fast. Perl-memory-usage-tuned benchmarks show that Perl's malloc is 5
2240 times quicker than EMX one. I do not have convincing data about memory
2241 footprint, but a (pretty random) benchmark showed that Perl's one is 5%
2242 better.
2243 Combination of perl's malloc() and rigid DLL name resolution creates a
2245 special problem with library functions which expect their return value
2246 to be free()d by system's free(). To facilitate extensions which need
2247 to call such functions, system memory-allocation functions are still
2248 available with the prefix "emx_" added. (Currently only DLL perl has
2249 this, it should propagate to perl_.exe shortly.)
2250 Threads
2252 One can build perl with thread support enabled by providing "-D
2253 usethreads" option to Configure. Currently OS/2 support of threads is
2254 very preliminary.
2255 Most notable problems:
2257 "COND_WAIT"
2259 may have a race condition (but probably does not due to edge-
2260 triggered nature of OS/2 Event semaphores). (Needs a
2261 reimplementation (in terms of chaining waiting threads, with the
2262 linked list stored in per-thread structure?)?)
2263 os2.c
2265 has a couple of static variables used in OS/2-specific functions.
2266 (Need to be moved to per-thread structure, or serialized?)
2267 Note that these problems should not discourage experimenting, since
2269 they have a low probability of affecting small programs.
2270
2272 This description is not updated often (since 5.6.1?), see ./os2/Changes
2273 for more info.
2274
2276 Ilya Zakharevich, cpan@ilyaz.org
2277
2279 perl(1).
2280perl v5.38.2 2023-11-30 PERLOS2(1)