diff options
Diffstat (limited to 'upstream/mageia-cauldron/man1/perlos2.1')
| -rw-r--r-- | upstream/mageia-cauldron/man1/perlos2.1 | 2600 |
1 files changed, 2600 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1/perlos2.1 b/upstream/mageia-cauldron/man1/perlos2.1 new file mode 100644 index 00000000..ab2a20bc --- /dev/null +++ b/upstream/mageia-cauldron/man1/perlos2.1 @@ -0,0 +1,2600 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "PERLOS2 1" +.TH PERLOS2 1 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +perlos2 \- Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT. +.SH SYNOPSIS +.IX Header "SYNOPSIS" +One can read this document in the following formats: +.PP +.Vb 4 +\& man perlos2 +\& view perl perlos2 +\& explorer perlos2.html +\& info perlos2 +.Ve +.PP +to list some (not all may be available simultaneously), or it may +be read \fIas is\fR: either as \fIREADME.os2\fR, or \fIpod/perlos2.pod\fR. +.PP +To read the \fI.INF\fR version of documentation (\fBvery\fR recommended) +outside of OS/2, one needs an IBM's reader (may be available on IBM +ftp sites (?) (URL anyone?)) or shipped with PC DOS 7.0 and IBM's +Visual Age C++ 3.5. +.PP +A copy of a Win* viewer is contained in the "Just add OS/2 Warp" package +.PP +.Vb 1 +\& ftp://ftp.software.ibm.com/ps/products/os2/tools/jaow/jaow.zip +.Ve +.PP +in \fI?:\eJUST_ADD\eview.exe\fR. This gives one an access to EMX's +\&\fI.INF\fR docs as well (text form is available in \fI/emx/doc\fR in +EMX's distribution). There is also a different viewer named xview. +.PP +Note that if you have \fIlynx.exe\fR or \fInetscape.exe\fR installed, you can follow WWW links +from this document in \fI.INF\fR format. If you have EMX docs installed +correctly, you can follow library links (you need to have \f(CW\*(C`view emxbook\*(C'\fR +working by setting \f(CW\*(C`EMXBOOK\*(C'\fR environment variable as it is described +in EMX docs). +.SH DESCRIPTION +.IX Header "DESCRIPTION" +.SS Target +.IX Subsection "Target" +The target is to make OS/2 one of the best supported platform for +using/building/developing Perl and \fIPerl applications\fR, as well as +make Perl the best language to use under OS/2. The secondary target is +to try to make this work under DOS and Win* as well (but not \fBtoo\fR hard). +.PP +The current state is quite close to this target. Known limitations: +.IP \(bu 5 +Some *nix programs use \fBfork()\fR a lot; with the mostly useful flavors of +perl for OS/2 (there are several built simultaneously) this is +supported; but some flavors do not support this (e.g., when Perl is +called from inside REXX). Using \fBfork()\fR after +\&\fIuse\fRing dynamically loading extensions would not work with \fIvery\fR old +versions of EMX. +.IP \(bu 5 +You need a separate perl executable \fIperl_\|_.exe\fR (see "perl_\|_.exe") +if you want to use PM code in your application (as Perl/Tk or OpenGL +Perl modules do) without having a text-mode window present. +.Sp +While using the standard \fIperl.exe\fR from a text-mode window is possible +too, I have seen cases when this causes degradation of the system stability. +Using \fIperl_\|_.exe\fR avoids such a degradation. +.IP \(bu 5 +There is no simple way to access WPS objects. The only way I know +is via \f(CW\*(C`OS2::REXX\*(C'\fR and \f(CW\*(C`SOM\*(C'\fR extensions (see OS2::REXX, SOM). +However, we do not have access to +convenience methods of Object-REXX. (Is it possible at all? I know +of no Object-REXX API.) The \f(CW\*(C`SOM\*(C'\fR extension (currently in alpha-text) +may eventually remove this shortcoming; however, due to the fact that +DII is not supported by the \f(CW\*(C`SOM\*(C'\fR module, using \f(CW\*(C`SOM\*(C'\fR is not as +convenient as one would like it. +.PP +Please keep this list up-to-date by informing me about other items. +.SS "Other OSes" +.IX Subsection "Other OSes" +Since OS/2 port of perl uses a remarkable EMX environment, it can +run (and build extensions, and \- possibly \- be built itself) under any +environment which can run EMX. The current list is DOS, +DOS\-inside\-OS/2, Win0.3*, Win0.95 and WinNT. Out of many perl flavors, +only one works, see "\fIperl_.exe\fR". +.PP +Note that not all features of Perl are available under these +environments. This depends on the features the \fIextender\fR \- most +probably RSX \- decided to implement. +.PP +Cf. "Prerequisites". +.SS Prerequisites +.IX Subsection "Prerequisites" +.IP EMX 6 +.IX Item "EMX" +EMX runtime is required (may be substituted by RSX). Note that +it is possible to make \fIperl_.exe\fR to run under DOS without any +external support by binding \fIemx.exe\fR/\fIrsx.exe\fR to it, see \fBemxbind\fR\|(1). +Note that under DOS for best results one should use RSX runtime, which +has much more functions working (like \f(CW\*(C`fork\*(C'\fR, \f(CW\*(C`popen\*(C'\fR and so on). In +fact RSX is required if there is no VCPI present. Note the +RSX requires DPMI. Many implementations of DPMI are known to be very +buggy, beware! +.Sp +Only the latest runtime is supported, currently \f(CW\*(C`0.9d fix 03\*(C'\fR. Perl may run +under earlier versions of EMX, but this is not tested. +.Sp +One can get different parts of EMX from, say +.Sp +.Vb 2 +\& ftp://crydee.sai.msu.ru/pub/comp/os/os2/leo/gnu/emx+gcc/ +\& http://hobbes.nmsu.edu/h\-browse.php?dir=/pub/os2/dev/emx/v0.9d/ +.Ve +.Sp +The runtime component should have the name \fIemxrt.zip\fR. +.Sp +\&\fBNOTE\fR. When using \fIemx.exe\fR/\fIrsx.exe\fR, it is enough to have them on your path. One +does not need to specify them explicitly (though this +.Sp +.Vb 1 +\& emx perl_.exe \-de 0 +.Ve +.Sp +will work as well.) +.IP RSX 6 +.IX Item "RSX" +To run Perl on DPMI platforms one needs RSX runtime. This is +needed under DOS\-inside\-OS/2, Win0.3*, Win0.95 and WinNT (see +"Other OSes"). RSX would not work with VCPI +only, as EMX would, it requires DMPI. +.Sp +Having RSX and the latest \fIsh.exe\fR one gets a fully functional +\&\fB*nix\fR\-ish environment under DOS, say, \f(CW\*(C`fork\*(C'\fR, \f(CW\`\`\fR and +pipe\-\f(CW\*(C`open\*(C'\fR work. In fact, MakeMaker works (for static build), so one +can have Perl development environment under DOS. +.Sp +One can get RSX from, say +.Sp +.Vb 2 +\& http://cd.textfiles.com/hobbesos29804/disk1/EMX09C/ +\& ftp://crydee.sai.msu.ru/pub/comp/os/os2/leo/gnu/emx+gcc/contrib/ +.Ve +.Sp +Contact the author on \f(CW\*(C`rainer@mathematik.uni\-bielefeld.de\*(C'\fR. +.Sp +The latest \fIsh.exe\fR with DOS hooks is available in +.Sp +.Vb 1 +\& http://www.ilyaz.org/software/os2/ +.Ve +.Sp +as \fIsh_dos.zip\fR or under similar names starting with \f(CW\*(C`sh\*(C'\fR, \f(CW\*(C`pdksh\*(C'\fR etc. +.IP HPFS 6 +.IX Item "HPFS" +Perl does not care about file systems, but the perl library contains +many files with long names, so to install it intact one needs a file +system which supports long file names. +.Sp +Note that if you do not plan to build the perl itself, it may be +possible to fool EMX to truncate file names. This is not supported, +read EMX docs to see how to do it. +.IP pdksh 6 +.IX Item "pdksh" +To start external programs with complicated command lines (like with +pipes in between, and/or quoting of arguments), Perl uses an external +shell. With EMX port such shell should be named \fIsh.exe\fR, and located +either in the wired-in-during-compile locations (usually \fIF:/bin\fR), +or in configurable location (see "\f(CW\*(C`PERL_SH_DIR\*(C'\fR"). +.Sp +For best results use EMX pdksh. The standard binary (5.2.14 or later) runs +under DOS (with "RSX") as well, see +.Sp +.Vb 1 +\& http://www.ilyaz.org/software/os2/ +.Ve +.SS "Starting Perl programs under OS/2 (and DOS and...)" +.IX Subsection "Starting Perl programs under OS/2 (and DOS and...)" +Start your Perl program \fIfoo.pl\fR with arguments \f(CW\*(C`arg1 arg2 arg3\*(C'\fR the +same way as on any other platform, by +.PP +.Vb 1 +\& perl foo.pl arg1 arg2 arg3 +.Ve +.PP +If you want to specify perl options \f(CW\*(C`\-my_opts\*(C'\fR to the perl itself (as +opposed to your program), use +.PP +.Vb 1 +\& perl \-my_opts foo.pl arg1 arg2 arg3 +.Ve +.PP +Alternately, if you use OS/2\-ish shell, like CMD or 4os2, put +the following at the start of your perl script: +.PP +.Vb 1 +\& extproc perl \-S \-my_opts +.Ve +.PP +rename your program to \fIfoo.cmd\fR, and start it by typing +.PP +.Vb 1 +\& foo arg1 arg2 arg3 +.Ve +.PP +Note that because of stupid OS/2 limitations the full path of the perl +script is not available when you use \f(CW\*(C`extproc\*(C'\fR, thus you are forced to +use \f(CW\*(C`\-S\*(C'\fR perl switch, and your script should be on the \f(CW\*(C`PATH\*(C'\fR. As a plus +side, if you know a full path to your script, you may still start it +with +.PP +.Vb 1 +\& perl ../../blah/foo.cmd arg1 arg2 arg3 +.Ve +.PP +(note that the argument \f(CW\*(C`\-my_opts\*(C'\fR is taken care of by the \f(CW\*(C`extproc\*(C'\fR line +in your script, see \f(CW"extproc"\fR on the first line). +.PP +To understand what the above \fImagic\fR does, read perl docs about \f(CW\*(C`\-S\*(C'\fR +switch \- see perlrun, and cmdref about \f(CW\*(C`extproc\*(C'\fR: +.PP +.Vb 4 +\& view perl perlrun +\& man perlrun +\& view cmdref extproc +\& help extproc +.Ve +.PP +or whatever method you prefer. +.PP +There are also endless possibilities to use \fIexecutable extensions\fR of +4os2, \fIassociations\fR of WPS and so on... However, if you use +*nixish shell (like \fIsh.exe\fR supplied in the binary distribution), +you need to follow the syntax specified in "Command Switches" in perlrun. +.PP +Note that \fB\-S\fR switch supports scripts with additional extensions +\&\fI.cmd\fR, \fI.btm\fR, \fI.bat\fR, \fI.pl\fR as well. +.SS "Starting OS/2 (and DOS) programs under Perl" +.IX Subsection "Starting OS/2 (and DOS) programs under Perl" +This is what \fBsystem()\fR (see "system" in perlfunc), \f(CW\`\`\fR (see +"I/O Operators" in perlop), and \fIopen pipe\fR (see "open" in perlfunc) +are for. (Avoid \fBexec()\fR (see "exec" in perlfunc) unless you know what you +do). +.PP +Note however that to use some of these operators you need to have a +sh-syntax shell installed (see "Pdksh", +"Frequently asked questions"), and perl should be able to find it +(see "\f(CW\*(C`PERL_SH_DIR\*(C'\fR"). +.PP +The cases when the shell is used are: +.IP 1. 4 +One-argument \fBsystem()\fR (see "system" in perlfunc), \fBexec()\fR (see "exec" in perlfunc) +with redirection or shell meta-characters; +.IP 2. 4 +Pipe-open (see "open" in perlfunc) with the command which contains redirection +or shell meta-characters; +.IP 3. 4 +Backticks \f(CW\`\`\fR (see "I/O Operators" in perlop) with the command which contains +redirection or shell meta-characters; +.IP 4. 4 +If the executable called by \fBsystem()\fR/\fBexec()\fR/pipe\-\fBopen()\fR/\f(CW\`\`\fR is a script +with the "magic" \f(CW\*(C`#!\*(C'\fR line or \f(CW\*(C`extproc\*(C'\fR line which specifies shell; +.IP 5. 4 +If the executable called by \fBsystem()\fR/\fBexec()\fR/pipe\-\fBopen()\fR/\f(CW\`\`\fR is a script +without "magic" line, and \f(CW$ENV{EXECSHELL}\fR is set to shell; +.IP 6. 4 +If the executable called by \fBsystem()\fR/\fBexec()\fR/pipe\-\fBopen()\fR/\f(CW\`\`\fR is not +found (is not this remark obsolete?); +.IP 7. 4 +For globbing (see "glob" in perlfunc, "I/O Operators" in perlop) +(obsolete? Perl uses builtin globbing nowadays...). +.PP +For the sake of speed for a common case, in the above algorithms +backslashes in the command name are not considered as shell metacharacters. +.PP +Perl starts scripts which begin with cookies +\&\f(CW\*(C`extproc\*(C'\fR or \f(CW\*(C`#!\*(C'\fR directly, without an intervention of shell. Perl uses the +same algorithm to find the executable as \fIpdksh\fR: if the path +on \f(CW\*(C`#!\*(C'\fR line does not work, and contains \f(CW\*(C`/\*(C'\fR, then the directory +part of the executable is ignored, and the executable +is searched in \fI.\fR and on \f(CW\*(C`PATH\*(C'\fR. To find arguments for these scripts +Perl uses a different algorithm than \fIpdksh\fR: up to 3 arguments are +recognized, and trailing whitespace is stripped. +.PP +If a script +does not contain such a cooky, then to avoid calling \fIsh.exe\fR, Perl uses +the same algorithm as \fIpdksh\fR: if \f(CW$ENV{EXECSHELL}\fR is set, the +script is given as the first argument to this command, if not set, then +\&\f(CW\*(C`$ENV{COMSPEC} /c\*(C'\fR is used (or a hardwired guess if \f(CW$ENV{COMSPEC}\fR is +not set). +.PP +When starting scripts directly, Perl uses exactly the same algorithm as for +the search of script given by \fB\-S\fR command-line option: it will look in +the current directory, then on components of \f(CW$ENV{PATH}\fR using the +following order of appended extensions: no extension, \fI.cmd\fR, \fI.btm\fR, +\&\fI.bat\fR, \fI.pl\fR. +.PP +Note that Perl will start to look for scripts only if OS/2 cannot start the +specified application, thus \f(CW\*(C`system \*(Aqblah\*(Aq\*(C'\fR will not look for a script if +there is an executable file \fIblah.exe\fR \fIanywhere\fR on \f(CW\*(C`PATH\*(C'\fR. In +other words, \f(CW\*(C`PATH\*(C'\fR is essentially searched twice: once by the OS for +an executable, then by Perl for scripts. +.PP +Note also that executable files on OS/2 can have an arbitrary extension, but +\&\fI.exe\fR will be automatically appended if no dot is present in the name. The +workaround is as simple as that: since \fIblah.\fR and \fIblah\fR denote the same +file (at list on FAT and HPFS file systems), to start an executable residing in +file \fIn:/bin/blah\fR (no extension) give an argument \f(CW\*(C`n:/bin/blah.\*(C'\fR (dot +appended) to \fBsystem()\fR. +.PP +Perl will start PM programs from VIO (=text\-mode) Perl process in a +separate PM session; +the opposite is not true: when you start a non-PM program from a PM +Perl process, Perl would not run it in a separate session. If a separate +session is desired, either ensure +that shell will be used, as in \f(CW\*(C`system \*(Aqcmd /c myprog\*(Aq\*(C'\fR, or start it using +optional arguments to \fBsystem()\fR documented in \f(CW\*(C`OS2::Process\*(C'\fR module. This +is considered to be a feature. +.SH "Frequently asked questions" +.IX Header "Frequently asked questions" +.SS """It does not work""" +.IX Subsection """It does not work""" +Perl binary distributions come with a \fItestperl.cmd\fR script which tries +to detect common problems with misconfigured installations. There is a +pretty large chance it will discover which step of the installation you +managed to goof. \f(CW\*(C`;\-)\*(C'\fR +.SS "I cannot run external programs" +.IX Subsection "I cannot run external programs" +.IP \(bu 4 +Did you run your programs with \f(CW\*(C`\-w\*(C'\fR switch? See +"Starting OS/2 (and DOS) programs under Perl". +.IP \(bu 4 +Do you try to run \fIinternal\fR shell commands, like \f(CW\`copy a b\`\fR +(internal for \fIcmd.exe\fR), or \f(CW\`glob a*b\`\fR (internal for ksh)? You +need to specify your shell explicitly, like \f(CW\`cmd /c copy a b\`\fR, +since Perl cannot deduce which commands are internal to your shell. +.SS "I cannot embed perl into my program, or use \fIperl.dll\fP from my program." +.IX Subsection "I cannot embed perl into my program, or use perl.dll from my program." +.ie n .IP "Is your program EMX-compiled with ""\-Zmt \-Zcrtdll""?" 4 +.el .IP "Is your program EMX-compiled with \f(CW\-Zmt \-Zcrtdll\fR?" 4 +.IX Item "Is your program EMX-compiled with -Zmt -Zcrtdll?" +Well, nowadays Perl DLL should be usable from a differently compiled +program too... If you can run Perl code from REXX scripts (see +OS2::REXX), then there are some other aspect of interaction which +are overlooked by the current hackish code to support +differently-compiled principal programs. +.Sp +If everything else fails, you need to build a stand-alone DLL for +perl. Contact me, I did it once. Sockets would not work, as a lot of +other stuff. +.IP "Did you use ExtUtils::Embed?" 4 +.IX Item "Did you use ExtUtils::Embed?" +Some time ago I had reports it does not work. Nowadays it is checked +in the Perl test suite, so grep \fI./t\fR subdirectory of the build tree +(as well as \fI*.t\fR files in the \fI./lib\fR subdirectory) to find how it +should be done "correctly". +.ie n .SS "\`\` and pipe\-""open"" do not work under DOS." +.el .SS "\f(CW\`\`\fP and pipe\-\f(CWopen\fP do not work under DOS." +.IX Subsection " and pipe-open do not work under DOS." +This may a variant of just "I cannot run external programs", or a +deeper problem. Basically: you \fIneed\fR RSX (see "Prerequisites") +for these commands to work, and you may need a port of \fIsh.exe\fR which +understands command arguments. One of such ports is listed in +"Prerequisites" under RSX. Do not forget to set variable +"\f(CW\*(C`PERL_SH_DIR\*(C'\fR" as well. +.PP +DPMI is required for RSX. +.ie n .SS "Cannot start ""find.exe ""pattern"" file""" +.el .SS "Cannot start \f(CWfind.exe ""pattern"" file\fP" +.IX Subsection "Cannot start find.exe ""pattern"" file" +The whole idea of the "standard C API to start applications" is that +the forms \f(CW\*(C`foo\*(C'\fR and \f(CW"foo"\fR of program arguments are completely +interchangeable. \fIfind\fR breaks this paradigm; +.PP +.Vb 2 +\& find "pattern" file +\& find pattern file +.Ve +.PP +are not equivalent; \fIfind\fR cannot be started directly using the above +API. One needs a way to surround the doublequotes in some other +quoting construction, necessarily having an extra non-Unixish shell in +between. +.PP +Use one of +.PP +.Vb 2 +\& system \*(Aqcmd\*(Aq, \*(Aq/c\*(Aq, \*(Aqfind "pattern" file\*(Aq; +\& \`cmd /c \*(Aqfind "pattern" file\*(Aq\` +.Ve +.PP +This would start \fIfind.exe\fR via \fIcmd.exe\fR via \f(CW\*(C`sh.exe\*(C'\fR via +\&\f(CW\*(C`perl.exe\*(C'\fR, but this is a price to pay if you want to use +non-conforming program. +.SH INSTALLATION +.IX Header "INSTALLATION" +.SS "Automatic binary installation" +.IX Subsection "Automatic binary installation" +The most convenient way of installing a binary distribution of perl is via perl installer +\&\fIinstall.exe\fR. Just follow the instructions, and 99% of the +installation blues would go away. +.PP +Note however, that you need to have \fIunzip.exe\fR on your path, and +EMX environment \fIrunning\fR. The latter means that if you just +installed EMX, and made all the needed changes to \fIConfig.sys\fR, +you may need to reboot in between. Check EMX runtime by running +.PP +.Vb 1 +\& emxrev +.Ve +.PP +Binary installer also creates a folder on your desktop with some useful +objects. If you need to change some aspects of the work of the binary +installer, feel free to edit the file \fIPerl.pkg\fR. This may be useful +e.g., if you need to run the installer many times and do not want to +make many interactive changes in the GUI. +.PP +\&\fBThings not taken care of by automatic binary installation:\fR +.ie n .IP """PERL_BADLANG""" 15 +.el .IP \f(CWPERL_BADLANG\fR 15 +.IX Item "PERL_BADLANG" +may be needed if you change your codepage \fIafter\fR perl installation, +and the new value is not supported by EMX. See "\f(CW\*(C`PERL_BADLANG\*(C'\fR". +.ie n .IP """PERL_BADFREE""" 15 +.el .IP \f(CWPERL_BADFREE\fR 15 +.IX Item "PERL_BADFREE" +see "\f(CW\*(C`PERL_BADFREE\*(C'\fR". +.IP \fIConfig.pm\fR 15 +.IX Item "Config.pm" +This file resides somewhere deep in the location you installed your +perl library, find it out by +.Sp +.Vb 1 +\& perl \-MConfig \-le "print $INC{\*(AqConfig.pm\*(Aq}" +.Ve +.Sp +While most important values in this file \fIare\fR updated by the binary +installer, some of them may need to be hand-edited. I know no such +data, please keep me informed if you find one. Moreover, manual +changes to the installed version may need to be accompanied by an edit +of this file. +.PP +\&\fBNOTE\fR. Because of a typo the binary installer of 5.00305 +would install a variable \f(CW\*(C`PERL_SHPATH\*(C'\fR into \fIConfig.sys\fR. Please +remove this variable and put \f(CW"PERL_SH_DIR"\fR instead. +.SS "Manual binary installation" +.IX Subsection "Manual binary installation" +As of version 5.00305, OS/2 perl binary distribution comes split +into 11 components. Unfortunately, to enable configurable binary +installation, the file paths in the zip files are not absolute, but +relative to some directory. +.PP +Note that the extraction with the stored paths is still necessary +(default with unzip, specify \f(CW\*(C`\-d\*(C'\fR to pkunzip). However, you +need to know where to extract the files. You need also to manually +change entries in \fIConfig.sys\fR to reflect where did you put the +files. Note that if you have some primitive unzipper (like +\&\f(CW\*(C`pkunzip\*(C'\fR), you may get a lot of warnings/errors during +unzipping. Upgrade to \f(CW\*(C`(w)unzip\*(C'\fR. +.PP +Below is the sample of what to do to reproduce the configuration on my +machine. In \fIVIEW.EXE\fR you can press \f(CW\*(C`Ctrl\-Insert\*(C'\fR now, and +cut-and-paste from the resulting file \- created in the directory you +started \fIVIEW.EXE\fR from. +.PP +For each component, we mention environment variables related to each +installation directory. Either choose directories to match your +values of the variables, or create/append\-to variables to take into +account the directories. +.IP "Perl VIO and PM executables (dynamically linked)" 3 +.IX Item "Perl VIO and PM executables (dynamically linked)" +.Vb 2 +\& unzip perl_exc.zip *.exe *.ico \-d f:/emx.add/bin +\& unzip perl_exc.zip *.dll \-d f:/emx.add/dll +.Ve +.Sp +(have the directories with \f(CW\*(C`*.exe\*(C'\fR on PATH, and \f(CW\*(C`*.dll\*(C'\fR on +LIBPATH); +.IP "Perl_ VIO executable (statically linked)" 3 +.IX Item "Perl_ VIO executable (statically linked)" +.Vb 1 +\& unzip perl_aou.zip \-d f:/emx.add/bin +.Ve +.Sp +(have the directory on PATH); +.IP "Executables for Perl utilities" 3 +.IX Item "Executables for Perl utilities" +.Vb 1 +\& unzip perl_utl.zip \-d f:/emx.add/bin +.Ve +.Sp +(have the directory on PATH); +.IP "Main Perl library" 3 +.IX Item "Main Perl library" +.Vb 1 +\& unzip perl_mlb.zip \-d f:/perllib/lib +.Ve +.Sp +If this directory is exactly the same as the prefix which was compiled +into \fIperl.exe\fR, you do not need to change +anything. However, for perl to find the library if you use a different +path, you need to +\&\f(CW\*(C`set PERLLIB_PREFIX\*(C'\fR in \fIConfig.sys\fR, see "\f(CW\*(C`PERLLIB_PREFIX\*(C'\fR". +.IP "Additional Perl modules" 3 +.IX Item "Additional Perl modules" +.Vb 1 +\& unzip perl_ste.zip \-d f:/perllib/lib/site_perl/5.38.2/ +.Ve +.Sp +Same remark as above applies. Additionally, if this directory is not +one of directories on \f(CW@INC\fR (and \f(CW@INC\fR is influenced by \f(CW\*(C`PERLLIB_PREFIX\*(C'\fR), you +need to put this +directory and subdirectory \fI./os2\fR in \f(CW\*(C`PERLLIB\*(C'\fR or \f(CW\*(C`PERL5LIB\*(C'\fR +variable. Do not use \f(CW\*(C`PERL5LIB\*(C'\fR unless you have it set already. See +"ENVIRONMENT" in perl. +.Sp +\&\fB[Check whether this extraction directory is still applicable with +the new directory structure layout!]\fR +.IP "Tools to compile Perl modules" 3 +.IX Item "Tools to compile Perl modules" +.Vb 1 +\& unzip perl_blb.zip \-d f:/perllib/lib +.Ve +.Sp +Same remark as for \fIperl_ste.zip\fR. +.IP "Manpages for Perl and utilities" 3 +.IX Item "Manpages for Perl and utilities" +.Vb 1 +\& unzip perl_man.zip \-d f:/perllib/man +.Ve +.Sp +This directory should better be on \f(CW\*(C`MANPATH\*(C'\fR. You need to have a +working \fIman\fR to access these files. +.IP "Manpages for Perl modules" 3 +.IX Item "Manpages for Perl modules" +.Vb 1 +\& unzip perl_mam.zip \-d f:/perllib/man +.Ve +.Sp +This directory should better be on \f(CW\*(C`MANPATH\*(C'\fR. You need to have a +working man to access these files. +.IP "Source for Perl documentation" 3 +.IX Item "Source for Perl documentation" +.Vb 1 +\& unzip perl_pod.zip \-d f:/perllib/lib +.Ve +.Sp +This is used by the \f(CW\*(C`perldoc\*(C'\fR program (see perldoc), and may be used to +generate HTML documentation usable by WWW browsers, and +documentation in zillions of other formats: \f(CW\*(C`info\*(C'\fR, \f(CW\*(C`LaTeX\*(C'\fR, +\&\f(CW\*(C`Acrobat\*(C'\fR, \f(CW\*(C`FrameMaker\*(C'\fR and so on. [Use programs such as +\&\fIpod2latex\fR etc.] +.IP "Perl manual in \fI.INF\fR format" 3 +.IX Item "Perl manual in .INF format" +.Vb 1 +\& unzip perl_inf.zip \-d d:/os2/book +.Ve +.Sp +This directory should better be on \f(CW\*(C`BOOKSHELF\*(C'\fR. +.IP Pdksh 3 +.IX Item "Pdksh" +.Vb 1 +\& unzip perl_sh.zip \-d f:/bin +.Ve +.Sp +This is used by perl to run external commands which explicitly +require shell, like the commands using \fIredirection\fR and \fIshell +metacharacters\fR. It is also used instead of explicit \fI/bin/sh\fR. +.Sp +Set \f(CW\*(C`PERL_SH_DIR\*(C'\fR (see "\f(CW\*(C`PERL_SH_DIR\*(C'\fR") if you move \fIsh.exe\fR from +the above location. +.Sp +\&\fBNote.\fR It may be possible to use some other sh-compatible shell (untested). +.PP +After you installed the components you needed and updated the +\&\fIConfig.sys\fR correspondingly, you need to hand-edit +\&\fIConfig.pm\fR. This file resides somewhere deep in the location you +installed your perl library, find it out by +.PP +.Vb 1 +\& perl \-MConfig \-le "print $INC{\*(AqConfig.pm\*(Aq}" +.Ve +.PP +You need to correct all the entries which look like file paths (they +currently start with \f(CW\*(C`f:/\*(C'\fR). +.SS \fBWarning\fP +.IX Subsection "Warning" +The automatic and manual perl installation leave precompiled paths +inside perl executables. While these paths are overwritable (see +"\f(CW\*(C`PERLLIB_PREFIX\*(C'\fR", "\f(CW\*(C`PERL_SH_DIR\*(C'\fR"), some people may prefer +binary editing of paths inside the executables/DLLs. +.SH "Accessing documentation" +.IX Header "Accessing documentation" +Depending on how you built/installed perl you may have (otherwise +identical) Perl documentation in the following formats: +.SS "OS/2 \fI.INF\fP file" +.IX Subsection "OS/2 .INF file" +Most probably the most convenient form. Under OS/2 view it as +.PP +.Vb 4 +\& view perl +\& view perl perlfunc +\& view perl less +\& view perl ExtUtils::MakeMaker +.Ve +.PP +(currently the last two may hit a wrong location, but this may improve +soon). Under Win* see "SYNOPSIS". +.PP +If you want to build the docs yourself, and have \fIOS/2 toolkit\fR, run +.PP +.Vb 1 +\& pod2ipf > perl.ipf +.Ve +.PP +in \fI/perllib/lib/pod\fR directory, then +.PP +.Vb 1 +\& ipfc /inf perl.ipf +.Ve +.PP +(Expect a lot of errors during the both steps.) Now move it on your +BOOKSHELF path. +.SS "Plain text" +.IX Subsection "Plain text" +If you have perl documentation in the source form, perl utilities +installed, and GNU groff installed, you may use +.PP +.Vb 3 +\& perldoc perlfunc +\& perldoc less +\& perldoc ExtUtils::MakeMaker +.Ve +.PP +to access the perl documentation in the text form (note that you may get +better results using perl manpages). +.PP +Alternately, try running pod2text on \fI.pod\fR files. +.SS Manpages +.IX Subsection "Manpages" +If you have \fIman\fR installed on your system, and you installed perl +manpages, use something like this: +.PP +.Vb 3 +\& man perlfunc +\& man 3 less +\& man ExtUtils.MakeMaker +.Ve +.PP +to access documentation for different components of Perl. Start with +.PP +.Vb 1 +\& man perl +.Ve +.PP +Note that dot (\fI.\fR) is used as a package separator for documentation +for packages, and as usual, sometimes you need to give the section \- \f(CW3\fR +above \- to avoid shadowing by the \fR\f(BIless\fR\fI\|(1) manpage\fR. +.PP +Make sure that the directory \fBabove\fR the directory with manpages is +on our \f(CW\*(C`MANPATH\*(C'\fR, like this +.PP +.Vb 1 +\& set MANPATH=c:/man;f:/perllib/man +.Ve +.PP +for Perl manpages in \f(CW\*(C`f:/perllib/man/man1/\*(C'\fR etc. +.SS HTML +.IX Subsection "HTML" +If you have some WWW browser available, installed the Perl +documentation in the source form, and Perl utilities, you can build +HTML docs. Cd to directory with \fI.pod\fR files, and do like this +.PP +.Vb 2 +\& cd f:/perllib/lib/pod +\& pod2html +.Ve +.PP +After this you can direct your browser the file \fIperl.html\fR in this +directory, and go ahead with reading docs, like this: +.PP +.Vb 1 +\& explore file:///f:/perllib/lib/pod/perl.html +.Ve +.PP +Alternatively you may be able to get these docs prebuilt from CPAN. +.ie n .SS "GNU ""info"" files" +.el .SS "GNU \f(CWinfo\fP files" +.IX Subsection "GNU info files" +Users of Emacs would appreciate it very much, especially with +\&\f(CW\*(C`CPerl\*(C'\fR mode loaded. You need to get latest \f(CW\*(C`pod2texi\*(C'\fR from \f(CW\*(C`CPAN\*(C'\fR, +or, alternately, the prebuilt info pages. +.SS "\fIPDF\fP files" +.IX Subsection "PDF files" +for \f(CW\*(C`Acrobat\*(C'\fR are available on CPAN (may be for slightly older version of +perl). +.ie n .SS """LaTeX"" docs" +.el .SS "\f(CWLaTeX\fP docs" +.IX Subsection "LaTeX docs" +can be constructed using \f(CW\*(C`pod2latex\*(C'\fR. +.SH BUILD +.IX Header "BUILD" +Here we discuss how to build Perl under OS/2. +.SS "The short story" +.IX Subsection "The short story" +Assume that you are a seasoned porter, so are sure that all the necessary +tools are already present on your system, and you know how to get the Perl +source distribution. Untar it, change to the extract directory, and +.PP +.Vb 7 +\& gnupatch \-p0 < os2\ediff.configure +\& sh Configure \-des \-D prefix=f:/perllib +\& make +\& make test +\& make install +\& make aout_test +\& make aout_install +.Ve +.PP +This puts the executables in f:/perllib/bin. Manually move them to the +\&\f(CW\*(C`PATH\*(C'\fR, manually move the built \fIperl*.dll\fR to \f(CW\*(C`LIBPATH\*(C'\fR (here for +Perl DLL \fI*\fR is a not-very-meaningful hex checksum), and run +.PP +.Vb 1 +\& make installcmd INSTALLCMDDIR=d:/ir/on/path +.Ve +.PP +Assuming that the \f(CW\*(C`man\*(C'\fR\-files were put on an appropriate location, +this completes the installation of minimal Perl system. (The binary +distribution contains also a lot of additional modules, and the +documentation in INF format.) +.PP +What follows is a detailed guide through these steps. +.SS Prerequisites +.IX Subsection "Prerequisites" +You need to have the latest EMX development environment, the full +GNU tool suite (gawk renamed to awk, and GNU \fIfind.exe\fR +earlier on path than the OS/2 \fIfind.exe\fR, same with \fIsort.exe\fR, to +check use +.PP +.Vb 2 +\& find \-\-version +\& sort \-\-version +.Ve +.PP +). You need the latest version of \fIpdksh\fR installed as \fIsh.exe\fR. +.PP +Check that you have \fBBSD\fR libraries and headers installed, and \- +optionally \- Berkeley DB headers and libraries, and crypt. +.PP +Possible locations to get the files: +.PP +.Vb 4 +\& ftp://ftp.uni\-heidelberg.de/pub/os2/unix/ +\& http://hobbes.nmsu.edu/h\-browse.php?dir=/pub/os2 +\& http://cd.textfiles.com/hobbesos29804/disk1/DEV32/ +\& http://cd.textfiles.com/hobbesos29804/disk1/EMX09C/ +.Ve +.PP +It is reported that the following archives contain enough utils to +build perl: \fIgnufutil.zip\fR, \fIgnusutil.zip\fR, \fIgnututil.zip\fR, \fIgnused.zip\fR, +\&\fIgnupatch.zip\fR, \fIgnuawk.zip\fR, \fIgnumake.zip\fR, \fIgnugrep.zip\fR, \fIbsddev.zip\fR and +\&\fIksh527rt.zip\fR (or a later version). Note that all these utilities are +known to be available from LEO: +.PP +.Vb 1 +\& ftp://crydee.sai.msu.ru/pub/comp/os/os2/leo/gnu/ +.Ve +.PP +Note also that the \fIdb.lib\fR and \fIdb.a\fR from the EMX distribution +are not suitable for multi-threaded compile (even single-threaded +flavor of Perl uses multi-threaded C RTL, for +compatibility with XFree86\-OS/2). Get a corrected one from +.PP +.Vb 1 +\& http://www.ilyaz.org/software/os2/db_mt.zip +.Ve +.PP +If you have \fIexactly the same version of Perl\fR installed already, +make sure that no copies or perl are currently running. Later steps +of the build may fail since an older version of \fIperl.dll\fR loaded into +memory may be found. Running \f(CW\*(C`make test\*(C'\fR becomes meaningless, since +the test are checking a previous build of perl (this situation is detected +and reported by \fIos2/os2_base.t\fR test). Do not forget to unset +\&\f(CW\*(C`PERL_EMXLOAD_SEC\*(C'\fR in environment. +.PP +Also make sure that you have \fI/tmp\fR directory on the current drive, +and \fI.\fR directory in your \f(CW\*(C`LIBPATH\*(C'\fR. One may try to correct the +latter condition by +.PP +.Vb 1 +\& set BEGINLIBPATH .\e. +.Ve +.PP +if you use something like \fICMD.EXE\fR or latest versions of +\&\fI4os2.exe\fR. (Setting BEGINLIBPATH to just \f(CW\*(C`.\*(C'\fR is ignored by the +OS/2 kernel.) +.PP +Make sure your gcc is good for \f(CW\*(C`\-Zomf\*(C'\fR linking: run \f(CW\*(C`omflibs\*(C'\fR +script in \fI/emx/lib\fR directory. +.PP +Check that you have link386 installed. It comes standard with OS/2, +but may be not installed due to customization. If typing +.PP +.Vb 1 +\& link386 +.Ve +.PP +shows you do not have it, do \fISelective install\fR, and choose \f(CW\*(C`Link +object modules\*(C'\fR in \fIOptional system utilities/More\fR. If you get into +link386 prompts, press \f(CW\*(C`Ctrl\-C\*(C'\fR to exit. +.SS "Getting perl source" +.IX Subsection "Getting perl source" +You need to fetch the latest perl source (including developers +releases). With some probability it is located in +.PP +.Vb 2 +\& http://www.cpan.org/src/ +\& http://www.cpan.org/src/unsupported +.Ve +.PP +If not, you may need to dig in the indices to find it in the directory +of the current maintainer. +.PP +Quick cycle of developers release may break the OS/2 build time to +time, looking into +.PP +.Vb 1 +\& http://www.cpan.org/ports/os2/ +.Ve +.PP +may indicate the latest release which was publicly released by the +maintainer. Note that the release may include some additional patches +to apply to the current source of perl. +.PP +Extract it like this +.PP +.Vb 1 +\& tar vzxf perl5.00409.tar.gz +.Ve +.PP +You may see a message about errors while extracting \fIConfigure\fR. This is +because there is a conflict with a similarly-named file \fIconfigure\fR. +.PP +Change to the directory of extraction. +.SS "Application of the patches" +.IX Subsection "Application of the patches" +You need to apply the patches in \fI./os2/diff.*\fR like this: +.PP +.Vb 1 +\& gnupatch \-p0 < os2\ediff.configure +.Ve +.PP +You may also need to apply the patches supplied with the binary +distribution of perl. It also makes sense to look on the +perl5\-porters mailing list for the latest OS/2\-related patches (see +<http://www.xray.mpe.mpg.de/mailing\-lists/perl5\-porters/>). Such +patches usually contain strings \f(CW\*(C`/os2/\*(C'\fR and \f(CW\*(C`patch\*(C'\fR, so it makes +sense looking for these strings. +.SS Hand-editing +.IX Subsection "Hand-editing" +You may look into the file \fI./hints/os2.sh\fR and correct anything +wrong you find there. I do not expect it is needed anywhere. +.SS Making +.IX Subsection "Making" +.Vb 1 +\& sh Configure \-des \-D prefix=f:/perllib +.Ve +.PP +\&\f(CW\*(C`prefix\*(C'\fR means: where to install the resulting perl library. Giving +correct prefix you may avoid the need to specify \f(CW\*(C`PERLLIB_PREFIX\*(C'\fR, +see "\f(CW\*(C`PERLLIB_PREFIX\*(C'\fR". +.PP +\&\fIIgnore the message about missing \fR\f(CI\*(C`ln\*(C'\fR\fI, and about \fR\f(CI\*(C`\-c\*(C'\fR\fI option to +tr\fR. The latter is most probably already fixed, if you see it and can trace +where the latter spurious warning comes from, please inform me. +.PP +Now +.PP +.Vb 1 +\& make +.Ve +.PP +At some moment the built may die, reporting a \fIversion mismatch\fR or +\&\fIunable to run perl\fR. This means that you do not have \fI.\fR in +your LIBPATH, so \fIperl.exe\fR cannot find the needed \fIperl67B2.dll\fR (treat +these hex digits as line noise). After this is fixed the build +should finish without a lot of fuss. +.SS Testing +.IX Subsection "Testing" +Now run +.PP +.Vb 1 +\& make test +.Ve +.PP +All tests should succeed (with some of them skipped). If you have the +same version of Perl installed, it is crucial that you have \f(CW\*(C`.\*(C'\fR early +in your LIBPATH (or in BEGINLIBPATH), otherwise your tests will most +probably test the wrong version of Perl. +.PP +Some tests may generate extra messages similar to +.ie n .IP "A lot of ""bad free""" 4 +.el .IP "A lot of \f(CWbad free\fR" 4 +.IX Item "A lot of bad free" +in database tests related to Berkeley DB. \fIThis should be fixed already.\fR +If it persists, you may disable this warnings, see "\f(CW\*(C`PERL_BADFREE\*(C'\fR". +.IP "Process terminated by SIGTERM/SIGINT" 4 +.IX Item "Process terminated by SIGTERM/SIGINT" +This is a standard message issued by OS/2 applications. *nix +applications die in silence. It is considered to be a feature. One can +easily disable this by appropriate sighandlers. +.Sp +However the test engine bleeds these message to screen in unexpected +moments. Two messages of this kind \fIshould\fR be present during +testing. +.PP +To get finer test reports, call +.PP +.Vb 1 +\& perl t/harness +.Ve +.PP +The report with \fIio/pipe.t\fR failing may look like this: +.PP +.Vb 6 +\& Failed Test Status Wstat Total Fail Failed List of failed +\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\& io/pipe.t 12 1 8.33% 9 +\& 7 tests skipped, plus 56 subtests skipped. +\& Failed 1/195 test scripts, 99.49% okay. 1/6542 subtests failed, +\& 99.98% okay. +.Ve +.PP +The reasons for most important skipped tests are: +.IP \fIop/fs.t\fR 8 +.IX Item "op/fs.t" +.RS 8 +.PD 0 +.IP 18 4 +.IX Item "18" +.PD +Checks \f(CW\*(C`atime\*(C'\fR and \f(CW\*(C`mtime\*(C'\fR of \f(CWstat()\fR \- unfortunately, HPFS +provides only 2sec time granularity (for compatibility with FAT?). +.IP 25 4 +.IX Item "25" +Checks \f(CWtruncate()\fR on a filehandle just opened for write \- I do not +know why this should or should not work. +.RE +.RS 8 +.RE +.IP \fIop/stat.t\fR 8 +.IX Item "op/stat.t" +Checks \f(CWstat()\fR. Tests: +.RS 8 +.IP 4 4 +.IX Item "4" +Checks \f(CW\*(C`atime\*(C'\fR and \f(CW\*(C`mtime\*(C'\fR of \f(CWstat()\fR \- unfortunately, HPFS +provides only 2sec time granularity (for compatibility with FAT?). +.RE +.RS 8 +.RE +.SS "Installing the built perl" +.IX Subsection "Installing the built perl" +If you haven't yet moved \f(CW\*(C`perl*.dll\*(C'\fR onto LIBPATH, do it now. +.PP +Run +.PP +.Vb 1 +\& make install +.Ve +.PP +It would put the generated files into needed locations. Manually put +\&\fIperl.exe\fR, \fIperl_\|_.exe\fR and \fIperl_\|_\|_.exe\fR to a location on your +PATH, \fIperl.dll\fR to a location on your LIBPATH. +.PP +Run +.PP +.Vb 1 +\& make installcmd INSTALLCMDDIR=d:/ir/on/path +.Ve +.PP +to convert perl utilities to \fI.cmd\fR files and put them on +PATH. You need to put \fI.EXE\fR\-utilities on path manually. They are +installed in \f(CW\*(C`$prefix/bin\*(C'\fR, here \f(CW$prefix\fR is what you gave to +\&\fIConfigure\fR, see "Making". +.PP +If you use \f(CW\*(C`man\*(C'\fR, either move the installed \fI*/man/\fR directories to +your \f(CW\*(C`MANPATH\*(C'\fR, or modify \f(CW\*(C`MANPATH\*(C'\fR to match the location. (One +could have avoided this by providing a correct \f(CW\*(C`manpath\*(C'\fR option to +\&\fI./Configure\fR, or editing \fI./config.sh\fR between configuring and +making steps.) +.ie n .SS """a.out""\-style build" +.el .SS "\f(CWa.out\fP\-style build" +.IX Subsection "a.out-style build" +Proceed as above, but make \fIperl_.exe\fR (see "\fIperl_.exe\fR") by +.PP +.Vb 1 +\& make perl_ +.Ve +.PP +test and install by +.PP +.Vb 2 +\& make aout_test +\& make aout_install +.Ve +.PP +Manually put \fIperl_.exe\fR to a location on your PATH. +.PP +\&\fBNote.\fR The build process for \f(CW\*(C`perl_\*(C'\fR \fIdoes not know\fR about all the +dependencies, so you should make sure that anything is up-to-date, +say, by doing +.PP +.Vb 1 +\& make perl_dll +.Ve +.PP +first. +.SH "Building a binary distribution" +.IX Header "Building a binary distribution" +[This section provides a short overview only...] +.PP +Building should proceed differently depending on whether the version of perl +you install is already present and used on your system, or is a new version +not yet used. The description below assumes that the version is new, so +installing its DLLs and \fI.pm\fR files will not disrupt the operation of your +system even if some intermediate steps are not yet fully working. +.PP +The other cases require a little bit more convoluted procedures. Below I +suppose that the current version of Perl is \f(CW5.8.2\fR, so the executables are +named accordingly. +.IP 1. 4 +Fully build and test the Perl distribution. Make sure that no tests are +failing with \f(CW\*(C`test\*(C'\fR and \f(CW\*(C`aout_test\*(C'\fR targets; fix the bugs in Perl and +the Perl test suite detected by these tests. Make sure that \f(CW\*(C`all_test\*(C'\fR +make target runs as clean as possible. Check that \fIos2/perlrexx.cmd\fR +runs fine. +.IP 2. 4 +Fully install Perl, including \f(CW\*(C`installcmd\*(C'\fR target. Copy the generated DLLs +to \f(CW\*(C`LIBPATH\*(C'\fR; copy the numbered Perl executables (as in \fIperl5.8.2.exe\fR) +to \f(CW\*(C`PATH\*(C'\fR; copy \f(CW\*(C`perl_.exe\*(C'\fR to \f(CW\*(C`PATH\*(C'\fR as \f(CW\*(C`perl_5.8.2.exe\*(C'\fR. Think whether +you need backward-compatibility DLLs. In most cases you do not need to install +them yet; but sometime this may simplify the following steps. +.IP 3. 4 +Make sure that \f(CW\*(C`CPAN.pm\*(C'\fR can download files from CPAN. If not, you may need +to manually install \f(CW\*(C`Net::FTP\*(C'\fR. +.IP 4. 4 +Install the bundle \f(CW\*(C`Bundle::OS2_default\*(C'\fR +.Sp +.Vb 1 +\& perl5.8.2 \-MCPAN \-e "install Bundle::OS2_default" < nul |& tee 00cpan_i_1 +.Ve +.Sp +This may take a couple of hours on 1GHz processor (when run the first time). +And this should not be necessarily a smooth procedure. Some modules may not +specify required dependencies, so one may need to repeat this procedure several +times until the results stabilize. +.Sp +.Vb 2 +\& perl5.8.2 \-MCPAN \-e "install Bundle::OS2_default" < nul |& tee 00cpan_i_2 +\& perl5.8.2 \-MCPAN \-e "install Bundle::OS2_default" < nul |& tee 00cpan_i_3 +.Ve +.Sp +Even after they stabilize, some tests may fail. +.Sp +Fix as many discovered bugs as possible. Document all the bugs which are not +fixed, and all the failures with unknown reasons. Inspect the produced logs +\&\fI00cpan_i_1\fR to find suspiciously skipped tests, and other fishy events. +.Sp +Keep in mind that \fIinstallation\fR of some modules may fail too: for example, +the DLLs to update may be already loaded by \fICPAN.pm\fR. Inspect the \f(CW\*(C`install\*(C'\fR +logs (in the example above \fI00cpan_i_1\fR etc) for errors, and install things +manually, as in +.Sp +.Vb 2 +\& cd $CPANHOME/.cpan/build/Digest\-MD5\-2.31 +\& make install +.Ve +.Sp +Some distributions may fail some tests, but you may want to install them +anyway (as above, or via \f(CW\*(C`force install\*(C'\fR command of \f(CW\*(C`CPAN.pm\*(C'\fR shell-mode). +.Sp +Since this procedure may take quite a long time to complete, it makes sense +to "freeze" your CPAN configuration by disabling periodic updates of the +local copy of CPAN index: set \f(CW\*(C`index_expire\*(C'\fR to some big value (I use 365), +then save the settings +.Sp +.Vb 2 +\& CPAN> o conf index_expire 365 +\& CPAN> o conf commit +.Ve +.Sp +Reset back to the default value \f(CW1\fR when you are finished. +.IP 5. 4 +When satisfied with the results, rerun the \f(CW\*(C`installcmd\*(C'\fR target. Now you +can copy \f(CW\*(C`perl5.8.2.exe\*(C'\fR to \f(CW\*(C`perl.exe\*(C'\fR, and install the other OMF-build +executables: \f(CW\*(C`perl_\|_.exe\*(C'\fR etc. They are ready to be used. +.IP 6. 4 +Change to the \f(CW\*(C`./pod\*(C'\fR directory of the build tree, download the Perl logo +\&\fICamelGrayBig.BMP\fR, and run +.Sp +.Vb 2 +\& ( perl2ipf > perl.ipf ) |& tee 00ipf +\& ipfc /INF perl.ipf |& tee 00inf +.Ve +.Sp +This produces the Perl docs online book \f(CW\*(C`perl.INF\*(C'\fR. Install in on +\&\f(CW\*(C`BOOKSHELF\*(C'\fR path. +.IP 7. 4 +Now is the time to build statically linked executable \fIperl_.exe\fR which +includes newly-installed via \f(CW\*(C`Bundle::OS2_default\*(C'\fR modules. Doing testing +via \f(CW\*(C`CPAN.pm\*(C'\fR is going to be painfully slow, since it statically links +a new executable per XS extension. +.Sp +Here is a possible workaround: create a toplevel \fIMakefile.PL\fR in +\&\fR\f(CI$CPANHOME\fR\fI/.cpan/build/\fR with contents being (compare with "Making +executables with a custom collection of statically loaded extensions") +.Sp +.Vb 2 +\& use ExtUtils::MakeMaker; +\& WriteMakefile NAME => \*(Aqdummy\*(Aq; +.Ve +.Sp +execute this as +.Sp +.Vb 2 +\& perl_5.8.2.exe Makefile.PL <nul |& tee 00aout_c1 +\& make \-k all test <nul |& 00aout_t1 +.Ve +.Sp +Again, this procedure should not be absolutely smooth. Some \f(CW\*(C`Makefile.PL\*(C'\fR's +in subdirectories may be buggy, and would not run as "child" scripts. The +interdependency of modules can strike you; however, since non-XS modules +are already installed, the prerequisites of most modules have a very good +chance to be present. +.Sp +If you discover some glitches, move directories of problematic modules to a +different location; if these modules are non-XS modules, you may just ignore +them \- they are already installed; the remaining, XS, modules you need to +install manually one by one. +.Sp +After each such removal you need to rerun the \f(CW\*(C`Makefile.PL\*(C'\fR/\f(CW\*(C`make\*(C'\fR process; +usually this procedure converges soon. (But be sure to convert all the +necessary external C libraries from \fI.lib\fR format to \fI.a\fR format: run one of +.Sp +.Vb 2 +\& emxaout foo.lib +\& emximp \-o foo.a foo.lib +.Ve +.Sp +whichever is appropriate.) Also, make sure that the DLLs for external +libraries are usable with executables compiled without \f(CW\*(C`\-Zmtd\*(C'\fR options. +.Sp +When you are sure that only a few subdirectories +lead to failures, you may want to add \f(CW\*(C`\-j4\*(C'\fR option to \f(CW\*(C`make\*(C'\fR to speed up +skipping subdirectories with already finished build. +.Sp +When you are satisfied with the results of tests, install the build C libraries +for extensions: +.Sp +.Vb 1 +\& make install |& tee 00aout_i +.Ve +.Sp +Now you can rename the file \fI./perl.exe\fR generated during the last phase +to \fIperl_5.8.2.exe\fR; place it on \f(CW\*(C`PATH\*(C'\fR; if there is an inter-dependency +between some XS modules, you may need to repeat the \f(CW\*(C`test\*(C'\fR/\f(CW\*(C`install\*(C'\fR loop +with this new executable and some excluded modules \- until the procedure +converges. +.Sp +Now you have all the necessary \fI.a\fR libraries for these Perl modules in the +places where Perl builder can find it. Use the perl builder: change to an +empty directory, create a "dummy" \fIMakefile.PL\fR again, and run +.Sp +.Vb 2 +\& perl_5.8.2.exe Makefile.PL |& tee 00c +\& make perl |& tee 00p +.Ve +.Sp +This should create an executable \fI./perl.exe\fR with all the statically loaded +extensions built in. Compare the generated \fIperlmain.c\fR files to make sure +that during the iterations the number of loaded extensions only increases. +Rename \fI./perl.exe\fR to \fIperl_5.8.2.exe\fR on \f(CW\*(C`PATH\*(C'\fR. +.Sp +When it converges, you got a functional variant of \fIperl_5.8.2.exe\fR; copy it +to \f(CW\*(C`perl_.exe\*(C'\fR. You are done with generation of the local Perl installation. +.IP 8. 4 +Make sure that the installed modules are actually installed in the location +of the new Perl, and are not inherited from entries of \f(CW@INC\fR given for +inheritance from the older versions of Perl: set \f(CW\*(C`PERLLIB_582_PREFIX\*(C'\fR to +redirect the new version of Perl to a new location, and copy the installed +files to this new location. Redo the tests to make sure that the versions of +modules inherited from older versions of Perl are not needed. +.Sp +Actually, the log output of \fBpod2ipf\fR\|(1) during the step 6 gives a very detailed +info about which modules are loaded from which place; so you may use it as +an additional verification tool. +.Sp +Check that some temporary files did not make into the perl install tree. +Run something like this +.Sp +.Vb 1 +\& pfind . \-f "!(/\e.(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 /^\ew+$/") | less +.Ve +.Sp +in the install tree (both top one and \fIsitelib\fR one). +.Sp +Compress all the DLLs with \fIlxlite\fR. The tiny \fI.exe\fR can be compressed with +\&\f(CW\*(C`/c:max\*(C'\fR (the bug only appears when there is a fixup in the last 6 bytes of a +page (?); since the tiny executables are much smaller than a page, the bug +will not hit). Do not compress \f(CW\*(C`perl_.exe\*(C'\fR \- it would not work under DOS. +.IP 9. 4 +Now you can generate the binary distribution. This is done by running the +test of the CPAN distribution \f(CW\*(C`OS2::SoftInstaller\*(C'\fR. Tune up the file +\&\fItest.pl\fR to suit the layout of current version of Perl first. Do not +forget to pack the necessary external DLLs accordingly. Include the +description of the bugs and test suite failures you could not fix. Include +the small-stack versions of Perl executables from Perl build directory. +.Sp +Include \fIperl5.def\fR so that people can relink the perl DLL preserving +the binary compatibility, or can create compatibility DLLs. Include the diff +files (\f(CW\*(C`diff \-pu old new\*(C'\fR) of fixes you did so that people can rebuild your +version. Include \fIperl5.map\fR so that one can use remote debugging. +.IP 10. 4 +Share what you did with the other people. Relax. Enjoy fruits of your work. +.IP 11. 4 +Brace yourself for thanks, bug reports, hate mail and spam coming as result +of the previous step. No good deed should remain unpunished! +.SH "Building custom \fI.EXE\fP files" +.IX Header "Building custom .EXE files" +The Perl executables can be easily rebuilt at any moment. Moreover, one can +use the \fIembedding\fR interface (see perlembed) to make very customized +executables. +.SS "Making executables with a custom collection of statically loaded extensions" +.IX Subsection "Making executables with a custom collection of statically loaded extensions" +It is a little bit easier to do so while \fIdecreasing\fR the list of statically +loaded extensions. We discuss this case only here. +.IP 1. 4 +Change to an empty directory, and create a placeholder <Makefile.PL>: +.Sp +.Vb 2 +\& use ExtUtils::MakeMaker; +\& WriteMakefile NAME => \*(Aqdummy\*(Aq; +.Ve +.IP 2. 4 +Run it with the flavor of Perl (\fIperl.exe\fR or \fIperl_.exe\fR) you want to +rebuild. +.Sp +.Vb 1 +\& perl_ Makefile.PL +.Ve +.IP 3. 4 +Ask it to create new Perl executable: +.Sp +.Vb 1 +\& make perl +.Ve +.Sp +(you may need to manually add \f(CW\*(C`PERLTYPE=\-DPERL_CORE\*(C'\fR to this commandline on +some versions of Perl; the symptom is that the command-line globbing does not +work from OS/2 shells with the newly-compiled executable; check with +.Sp +.Vb 1 +\& .\eperl.exe \-wle "print for @ARGV" * +.Ve +.Sp +). +.IP 4. 4 +The previous step created \fIperlmain.c\fR which contains a list of \fBnewXS()\fR calls +near the end. Removing unnecessary calls, and rerunning +.Sp +.Vb 1 +\& make perl +.Ve +.Sp +will produce a customized executable. +.SS "Making executables with a custom search-paths" +.IX Subsection "Making executables with a custom search-paths" +The default perl executable is flexible enough to support most usages. +However, one may want something yet more flexible; for example, one may want +to find Perl DLL relatively to the location of the EXE file; or one may want +to ignore the environment when setting the Perl-library search patch, etc. +.PP +If you fill comfortable with \fIembedding\fR interface (see perlembed), such +things are easy to do repeating the steps outlined in "Making +executables with a custom collection of statically loaded extensions", and +doing more comprehensive edits to \fBmain()\fR of \fIperlmain.c\fR. The people with +little desire to understand Perl can just rename \fBmain()\fR, and do necessary +modification in a custom \fBmain()\fR which calls the renamed function in appropriate +time. +.PP +However, there is a third way: perl DLL exports the \fBmain()\fR function and several +callbacks to customize the search path. Below is a complete example of a +"Perl loader" which +.IP 1. 4 +Looks for Perl DLL in the directory \f(CW\*(C`$exedir/../dll\*(C'\fR; +.IP 2. 4 +Prepends the above directory to \f(CW\*(C`BEGINLIBPATH\*(C'\fR; +.IP 3. 4 +Fails if the Perl DLL found via \f(CW\*(C`BEGINLIBPATH\*(C'\fR is different from what was +loaded on step 1; e.g., another process could have loaded it from \f(CW\*(C`LIBPATH\*(C'\fR +or from a different value of \f(CW\*(C`BEGINLIBPATH\*(C'\fR. In these cases one needs to +modify the setting of the system so that this other process either does not +run, or loads the DLL from \f(CW\*(C`BEGINLIBPATH\*(C'\fR with \f(CW\*(C`LIBPATHSTRICT=T\*(C'\fR (available +with kernels after September 2000). +.IP 4. 4 +Loads Perl library from \f(CW\*(C`$exedir/../dll/lib/\*(C'\fR. +.IP 5. 4 +Uses Bourne shell from \f(CW\*(C`$exedir/../dll/sh/ksh.exe\*(C'\fR. +.PP +For best results compile the C file below with the same options as the Perl +DLL. However, a lot of functionality will work even if the executable is not +an EMX applications, e.g., if compiled with +.PP +.Vb 2 +\& gcc \-Wall \-DDOSISH \-DOS2=1 \-O2 \-s \-Zomf \-Zsys perl\-starter.c \e +\& \-DPERL_DLL_BASENAME=\e"perl312F\e" \-Zstack 8192 \-Zlinker /PM:VIO +.Ve +.PP +Here is the sample C file: +.PP +.Vb 6 +\& #define INCL_DOS +\& #define INCL_NOPM +\& /* These are needed for compile if os2.h includes os2tk.h, not +\& * os2emx.h */ +\& #define INCL_DOSPROCESS +\& #include <os2.h> +\& +\& #include "EXTERN.h" +\& #define PERL_IN_MINIPERLMAIN_C +\& #include "perl.h" +\& +\& static char *me; +\& HMODULE handle; +\& +\& static void +\& die_with(char *msg1, char *msg2, char *msg3, char *msg4) +\& { +\& ULONG c; +\& char *s = " error: "; +\& +\& DosWrite(2, me, strlen(me), &c); +\& DosWrite(2, s, strlen(s), &c); +\& DosWrite(2, msg1, strlen(msg1), &c); +\& DosWrite(2, msg2, strlen(msg2), &c); +\& DosWrite(2, msg3, strlen(msg3), &c); +\& DosWrite(2, msg4, strlen(msg4), &c); +\& DosWrite(2, "\er\en", 2, &c); +\& exit(255); +\& } +\& +\& typedef ULONG (*fill_extLibpath_t)(int type, +\& char *pre, +\& char *post, +\& int replace, +\& char *msg); +\& typedef int (*main_t)(int type, char *argv[], char *env[]); +\& typedef int (*handler_t)(void* data, int which); +\& +\& #ifndef PERL_DLL_BASENAME +\& # define PERL_DLL_BASENAME "perl" +\& #endif +\& +\& static HMODULE +\& load_perl_dll(char *basename) +\& { +\& char buf[300], fail[260]; +\& STRLEN l, dirl; +\& fill_extLibpath_t f; +\& ULONG rc_fullname; +\& HMODULE handle, handle1; +\& +\& if (_execname(buf, sizeof(buf) \- 13) != 0) +\& die_with("Can\*(Aqt find full path: ", strerror(errno), "", ""); +\& /* XXXX Fill \*(Aqme\*(Aq with new value */ +\& l = strlen(buf); +\& while (l && buf[l\-1] != \*(Aq/\*(Aq && buf[l\-1] != \*(Aq\e\e\*(Aq) +\& l\-\-; +\& dirl = l \- 1; +\& strcpy(buf + l, basename); +\& l += strlen(basename); +\& strcpy(buf + l, ".dll"); +\& if ( (rc_fullname = DosLoadModule(fail, sizeof fail, buf, &handle)) +\& != 0 +\& && DosLoadModule(fail, sizeof fail, basename, &handle) != 0 ) +\& die_with("Can\*(Aqt load DLL ", buf, "", ""); +\& if (rc_fullname) +\& return handle; /* was loaded with short name; all is fine */ +\& if (DosQueryProcAddr(handle, 0, "fill_extLibpath", (PFN*)&f)) +\& die_with(buf, +\& ": DLL exports no symbol ", +\& "fill_extLibpath", +\& ""); +\& buf[dirl] = 0; +\& if (f(0 /*BEGINLIBPATH*/, buf /* prepend */, NULL /* append */, +\& 0 /* keep old value */, me)) +\& die_with(me, ": prepending BEGINLIBPATH", "", ""); +\& if (DosLoadModule(fail, sizeof fail, basename, &handle1) != 0) +\& die_with(me, +\& ": finding perl DLL again via BEGINLIBPATH", +\& "", +\& ""); +\& buf[dirl] = \*(Aq\e\e\*(Aq; +\& if (handle1 != handle) { +\& if (DosQueryModuleName(handle1, sizeof(fail), fail)) +\& strcpy(fail, "???"); +\& die_with(buf, +\& ":\en\etperl DLL via BEGINLIBPATH is different: \en\et", +\& fail, +\& "\en\etYou may need to manipulate global BEGINLIBPATH" +\& " and LIBPATHSTRICT" +\& "\en\etso that the other copy is loaded via" +\& BEGINLIBPATH."); +\& } +\& return handle; +\& } +\& +\& int +\& main(int argc, char **argv, char **env) +\& { +\& main_t f; +\& handler_t h; +\& +\& me = argv[0]; +\& /**/ +\& handle = load_perl_dll(PERL_DLL_BASENAME); +\& +\& if (DosQueryProcAddr(handle, +\& 0, +\& "Perl_OS2_handler_install", +\& (PFN*)&h)) +\& die_with(PERL_DLL_BASENAME, +\& ": DLL exports no symbol ", +\& "Perl_OS2_handler_install", +\& ""); +\& if ( !h((void *)"~installprefix", Perlos2_handler_perllib_from) +\& || !h((void *)"~dll", Perlos2_handler_perllib_to) +\& || !h((void *)"~dll/sh/ksh.exe", Perlos2_handler_perl_sh) ) +\& die_with(PERL_DLL_BASENAME, +\& ": Can\*(Aqt install @INC manglers", +\& "", +\& ""); +\& if (DosQueryProcAddr(handle, 0, "dll_perlmain", (PFN*)&f)) +\& die_with(PERL_DLL_BASENAME, +\& ": DLL exports no symbol ", +\& "dll_perlmain", +\& ""); +\& return f(argc, argv, env); +\& } +.Ve +.SH "Build FAQ" +.IX Header "Build FAQ" +.ie n .SS "Some ""/"" became ""\e"" in pdksh." +.el .SS "Some \f(CW/\fP became \f(CW\e\fP in pdksh." +.IX Subsection "Some / became in pdksh." +You have a very old pdksh. See "Prerequisites". +.ie n .SS "\*(Aqerrno\*(Aq \- unresolved external" +.el .SS "\f(CW\*(Aqerrno\*(Aq\fP \- unresolved external" +.IX Subsection "errno - unresolved external" +You do not have MT-safe \fIdb.lib\fR. See "Prerequisites". +.SS "Problems with tr or sed" +.IX Subsection "Problems with tr or sed" +reported with very old version of tr and sed. +.SS "Some problem (forget which ;\-)" +.IX Subsection "Some problem (forget which ;-)" +You have an older version of \fIperl.dll\fR on your LIBPATH, which +broke the build of extensions. +.SS "Library ... not found" +.IX Subsection "Library ... not found" +You did not run \f(CW\*(C`omflibs\*(C'\fR. See "Prerequisites". +.SS "Segfault in make" +.IX Subsection "Segfault in make" +You use an old version of GNU make. See "Prerequisites". +.SS "op/sprintf test failure" +.IX Subsection "op/sprintf test failure" +This can result from a bug in emx sprintf which was fixed in 0.9d fix 03. +.SH "Specific (mis)features of OS/2 port" +.IX Header "Specific (mis)features of OS/2 port" +.ie n .SS """setpriority"", ""getpriority""" +.el .SS "\f(CWsetpriority\fP, \f(CWgetpriority\fP" +.IX Subsection "setpriority, getpriority" +Note that these functions are compatible with *nix, not with the older +ports of '94 \- 95. The priorities are absolute, go from 32 to \-95, +lower is quicker. 0 is the default priority. +.PP +\&\fBWARNING\fR. Calling \f(CW\*(C`getpriority\*(C'\fR on a non-existing process could lock +the system before Warp3 fixpak22. Starting with Warp3, Perl will use +a workaround: it aborts \fBgetpriority()\fR if the process is not present. +This is not possible on older versions \f(CW\*(C`2.*\*(C'\fR, and has a race +condition anyway. +.ie n .SS system() +.el .SS \f(CWsystem()\fP +.IX Subsection "system()" +Multi-argument form of \f(CWsystem()\fR allows an additional numeric +argument. The meaning of this argument is described in +OS2::Process. +.PP +When finding a program to run, Perl first asks the OS to look for executables +on \f(CW\*(C`PATH\*(C'\fR (OS/2 adds extension \fI.exe\fR if no extension is present). +If not found, it looks for a script with possible extensions +added in this order: no extension, \fI.cmd\fR, \fI.btm\fR, +\&\fI.bat\fR, \fI.pl\fR. If found, Perl checks the start of the file for magic +strings \f(CW"#!"\fR and \f(CW"extproc "\fR. If found, Perl uses the rest of the +first line as the beginning of the command line to run this script. The +only mangling done to the first line is extraction of arguments (currently +up to 3), and ignoring of the path-part of the "interpreter" name if it can't +be found using the full path. +.PP +E.g., \f(CW\*(C`system \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq\*(C'\fR may lead Perl to finding +\&\fIC:/emx/bin/foo.cmd\fR with the first line being +.PP +.Vb 1 +\& extproc /bin/bash \-x \-c +.Ve +.PP +If \fI/bin/bash.exe\fR is not found, then Perl looks for an executable \fIbash.exe\fR on +\&\f(CW\*(C`PATH\*(C'\fR. If found in \fIC:/emx.add/bin/bash.exe\fR, then the above \fBsystem()\fR is +translated to +.PP +.Vb 1 +\& system qw(C:/emx.add/bin/bash.exe \-x \-c C:/emx/bin/foo.cmd bar baz) +.Ve +.PP +One additional translation is performed: instead of \fI/bin/sh\fR Perl uses +the hardwired-or-customized shell (see "\f(CW\*(C`PERL_SH_DIR\*(C'\fR"). +.PP +The above search for "interpreter" is recursive: if \fIbash\fR executable is not +found, but \fIbash.btm\fR is found, Perl will investigate its first line etc. +The only hardwired limit on the recursion depth is implicit: there is a limit +4 on the number of additional arguments inserted before the actual arguments +given to \fBsystem()\fR. In particular, if no additional arguments are specified +on the "magic" first lines, then the limit on the depth is 4. +.PP +If Perl finds that the found executable is of PM type when the +current session is not, it will start the new process in a separate session of +necessary type. Call via \f(CW\*(C`OS2::Process\*(C'\fR to disable this magic. +.PP +\&\fBWARNING\fR. Due to the described logic, you need to explicitly +specify \fI.com\fR extension if needed. Moreover, if the executable +\&\fIperl5.6.1\fR is requested, Perl will not look for \fIperl5.6.1.exe\fR. +[This may change in the future.] +.ie n .SS """extproc"" on the first line" +.el .SS "\f(CWextproc\fP on the first line" +.IX Subsection "extproc on the first line" +If the first chars of a Perl script are \f(CW"extproc "\fR, this line is treated +as \f(CW\*(C`#!\*(C'\fR\-line, thus all the switches on this line are processed (twice +if script was started via cmd.exe). See "DESCRIPTION" in perlrun. +.SS "Additional modules:" +.IX Subsection "Additional modules:" +OS2::Process, OS2::DLL, OS2::REXX, OS2::PrfDB, OS2::ExtAttr. These +modules provide access to additional numeric argument for \f(CW\*(C`system\*(C'\fR +and to the information about the running process, +to DLLs having functions with REXX signature and to the REXX runtime, to +OS/2 databases in the \fI.INI\fR format, and to Extended Attributes. +.PP +Two additional extensions by Andreas Kaiser, \f(CW\*(C`OS2::UPM\*(C'\fR, and +\&\f(CW\*(C`OS2::FTP\*(C'\fR, are included into \f(CW\*(C`ILYAZ\*(C'\fR directory, mirrored on CPAN. +Other OS/2\-related extensions are available too. +.SS "Prebuilt methods:" +.IX Subsection "Prebuilt methods:" +.ie n .IP """File::Copy::syscopy""" 4 +.el .IP \f(CWFile::Copy::syscopy\fR 4 +.IX Item "File::Copy::syscopy" +used by \f(CW\*(C`File::Copy::copy\*(C'\fR, see File::Copy. +.ie n .IP """DynaLoader::mod2fname""" 4 +.el .IP \f(CWDynaLoader::mod2fname\fR 4 +.IX Item "DynaLoader::mod2fname" +used by \f(CW\*(C`DynaLoader\*(C'\fR for DLL name mangling. +.ie n .IP Cwd::current_drive() 4 +.el .IP \f(CWCwd::current_drive()\fR 4 +.IX Item "Cwd::current_drive()" +Self explanatory. +.ie n .IP Cwd::sys_chdir(name) 4 +.el .IP \f(CWCwd::sys_chdir(name)\fR 4 +.IX Item "Cwd::sys_chdir(name)" +leaves drive as it is. +.ie n .IP Cwd::change_drive(name) 4 +.el .IP \f(CWCwd::change_drive(name)\fR 4 +.IX Item "Cwd::change_drive(name)" +changes the "current" drive. +.ie n .IP Cwd::sys_is_absolute(name) 4 +.el .IP \f(CWCwd::sys_is_absolute(name)\fR 4 +.IX Item "Cwd::sys_is_absolute(name)" +means has drive letter and is_rooted. +.ie n .IP Cwd::sys_is_rooted(name) 4 +.el .IP \f(CWCwd::sys_is_rooted(name)\fR 4 +.IX Item "Cwd::sys_is_rooted(name)" +means has leading \f(CW\*(C`[/\e\e]\*(C'\fR (maybe after a drive-letter:). +.ie n .IP Cwd::sys_is_relative(name) 4 +.el .IP \f(CWCwd::sys_is_relative(name)\fR 4 +.IX Item "Cwd::sys_is_relative(name)" +means changes with current dir. +.ie n .IP Cwd::sys_cwd(name) 4 +.el .IP \f(CWCwd::sys_cwd(name)\fR 4 +.IX Item "Cwd::sys_cwd(name)" +Interface to cwd from EMX. Used by \f(CW\*(C`Cwd::cwd\*(C'\fR. +.ie n .IP """Cwd::sys_abspath(name, dir)""" 4 +.el .IP "\f(CWCwd::sys_abspath(name, dir)\fR" 4 +.IX Item "Cwd::sys_abspath(name, dir)" +Really really odious function to implement. Returns absolute name of +file which would have \f(CW\*(C`name\*(C'\fR if CWD were \f(CW\*(C`dir\*(C'\fR. \f(CW\*(C`Dir\*(C'\fR defaults to the +current dir. +.ie n .IP Cwd::extLibpath([type]) 4 +.el .IP \f(CWCwd::extLibpath([type])\fR 4 +.IX Item "Cwd::extLibpath([type])" +Get current value of extended library search path. If \f(CW\*(C`type\*(C'\fR is +present and positive, works with \f(CW\*(C`END_LIBPATH\*(C'\fR, if negative, works +with \f(CW\*(C`LIBPATHSTRICT\*(C'\fR, otherwise with \f(CW\*(C`BEGIN_LIBPATH\*(C'\fR. +.ie n .IP """Cwd::extLibpath_set( path [, type ] )""" 4 +.el .IP "\f(CWCwd::extLibpath_set( path [, type ] )\fR" 4 +.IX Item "Cwd::extLibpath_set( path [, type ] )" +Set current value of extended library search path. If \f(CW\*(C`type\*(C'\fR is +present and positive, works with <END_LIBPATH>, if negative, works +with \f(CW\*(C`LIBPATHSTRICT\*(C'\fR, otherwise with \f(CW\*(C`BEGIN_LIBPATH\*(C'\fR. +.ie n .IP """OS2::Error(do_harderror,do_exception)""" 4 +.el .IP \f(CWOS2::Error(do_harderror,do_exception)\fR 4 +.IX Item "OS2::Error(do_harderror,do_exception)" +Returns \f(CW\*(C`undef\*(C'\fR if it was not called yet, otherwise bit 1 is +set if on the previous call do_harderror was enabled, bit +2 is set if on previous call do_exception was enabled. +.Sp +This function enables/disables error popups associated with +hardware errors (Disk not ready etc.) and software exceptions. +.Sp +I know of no way to find out the state of popups \fIbefore\fR the first call +to this function. +.ie n .IP OS2::Errors2Drive(drive) 4 +.el .IP \f(CWOS2::Errors2Drive(drive)\fR 4 +.IX Item "OS2::Errors2Drive(drive)" +Returns \f(CW\*(C`undef\*(C'\fR if it was not called yet, otherwise return false if errors +were not requested to be written to a hard drive, or the drive letter if +this was requested. +.Sp +This function may redirect error popups associated with hardware errors +(Disk not ready etc.) and software exceptions to the file POPUPLOG.OS2 at +the root directory of the specified drive. Overrides \fBOS2::Error()\fR specified +by individual programs. Given argument undef will disable redirection. +.Sp +Has global effect, persists after the application exits. +.Sp +I know of no way to find out the state of redirection of popups to the disk +\&\fIbefore\fR the first call to this function. +.IP \fBOS2::SysInfo()\fR 4 +.IX Item "OS2::SysInfo()" +Returns a hash with system information. The keys of the hash are +.Sp +.Vb 8 +\& MAX_PATH_LENGTH, MAX_TEXT_SESSIONS, MAX_PM_SESSIONS, +\& MAX_VDM_SESSIONS, BOOT_DRIVE, DYN_PRI_VARIATION, +\& MAX_WAIT, MIN_SLICE, MAX_SLICE, PAGE_SIZE, +\& VERSION_MAJOR, VERSION_MINOR, VERSION_REVISION, +\& MS_COUNT, TIME_LOW, TIME_HIGH, TOTPHYSMEM, TOTRESMEM, +\& TOTAVAILMEM, MAXPRMEM, MAXSHMEM, TIMER_INTERVAL, +\& MAX_COMP_LENGTH, FOREGROUND_FS_SESSION, +\& FOREGROUND_PROCESS +.Ve +.IP \fBOS2::BootDrive()\fR 4 +.IX Item "OS2::BootDrive()" +Returns a letter without colon. +.ie n .IP "OS2::MorphPM(serve), OS2::UnMorphPM(serve)" 4 +.el .IP "\f(CWOS2::MorphPM(serve)\fR, \f(CWOS2::UnMorphPM(serve)\fR" 4 +.IX Item "OS2::MorphPM(serve), OS2::UnMorphPM(serve)" +Transforms the current application into a PM application and back. +The argument true means that a real message loop is going to be served. +\&\fBOS2::MorphPM()\fR returns the PM message queue handle as an integer. +.Sp +See "Centralized management of resources" for additional details. +.ie n .IP OS2::Serve_Messages(force) 4 +.el .IP \f(CWOS2::Serve_Messages(force)\fR 4 +.IX Item "OS2::Serve_Messages(force)" +Fake on-demand retrieval of outstanding PM messages. If \f(CW\*(C`force\*(C'\fR is false, +will not dispatch messages if a real message loop is known to +be present. Returns number of messages retrieved. +.Sp +Dies with "QUITing..." if WM_QUIT message is obtained. +.ie n .IP """OS2::Process_Messages(force [, cnt])""" 4 +.el .IP "\f(CWOS2::Process_Messages(force [, cnt])\fR" 4 +.IX Item "OS2::Process_Messages(force [, cnt])" +Retrieval of PM messages until window creation/destruction. +If \f(CW\*(C`force\*(C'\fR is false, will not dispatch messages if a real message loop +is known to be present. +.Sp +Returns change in number of windows. If \f(CW\*(C`cnt\*(C'\fR is given, +it is incremented by the number of messages retrieved. +.Sp +Dies with "QUITing..." if WM_QUIT message is obtained. +.ie n .IP """OS2::_control87(new,mask)""" 4 +.el .IP \f(CWOS2::_control87(new,mask)\fR 4 +.IX Item "OS2::_control87(new,mask)" +the same as \fB_control87\fR\|(3) of EMX. Takes integers as arguments, returns +the previous coprocessor control word as an integer. Only bits in \f(CW\*(C`new\*(C'\fR which +are present in \f(CW\*(C`mask\*(C'\fR are changed in the control word. +.IP \fBOS2::get_control87()\fR 4 +.IX Item "OS2::get_control87()" +gets the coprocessor control word as an integer. +.ie n .IP """OS2::set_control87_em(new=MCW_EM,mask=MCW_EM)""" 4 +.el .IP \f(CWOS2::set_control87_em(new=MCW_EM,mask=MCW_EM)\fR 4 +.IX Item "OS2::set_control87_em(new=MCW_EM,mask=MCW_EM)" +The variant of \fBOS2::_control87()\fR with default values good for +handling exception mask: if no \f(CW\*(C`mask\*(C'\fR, uses exception mask part of \f(CW\*(C`new\*(C'\fR +only. If no \f(CW\*(C`new\*(C'\fR, disables all the floating point exceptions. +.Sp +See "Misfeatures" for details. +.ie n .IP """OS2::DLLname([how [, \e&xsub]])""" 4 +.el .IP "\f(CWOS2::DLLname([how [, \e&xsub]])\fR" 4 +.IX Item "OS2::DLLname([how [, &xsub]])" +Gives the information about the Perl DLL or the DLL containing the C +function bound to by \f(CW&xsub\fR. The meaning of \f(CW\*(C`how\*(C'\fR is: default (2): +full name; 0: handle; 1: module name. +.PP +(Note that some of these may be moved to different libraries \- +eventually). +.SS "Prebuilt variables:" +.IX Subsection "Prebuilt variables:" +.ie n .IP $OS2::emx_rev 4 +.el .IP \f(CW$OS2::emx_rev\fR 4 +.IX Item "$OS2::emx_rev" +numeric value is the same as _emx_rev of EMX, a string value the same +as _emx_vprt (similar to \f(CW\*(C`0.9c\*(C'\fR). +.ie n .IP $OS2::emx_env 4 +.el .IP \f(CW$OS2::emx_env\fR 4 +.IX Item "$OS2::emx_env" +same as _emx_env of EMX, a number similar to 0x8001. +.ie n .IP $OS2::os_ver 4 +.el .IP \f(CW$OS2::os_ver\fR 4 +.IX Item "$OS2::os_ver" +a number \f(CW\*(C`OS_MAJOR + 0.001 * OS_MINOR\*(C'\fR. +.ie n .IP $OS2::is_aout 4 +.el .IP \f(CW$OS2::is_aout\fR 4 +.IX Item "$OS2::is_aout" +true if the Perl library was compiled in AOUT format. +.ie n .IP $OS2::can_fork 4 +.el .IP \f(CW$OS2::can_fork\fR 4 +.IX Item "$OS2::can_fork" +true if the current executable is an AOUT EMX executable, so Perl can +fork. Do not use this, use the portable check for +\&\f(CW$Config::Config\fR{dfork}. +.ie n .IP $OS2::nsyserror 4 +.el .IP \f(CW$OS2::nsyserror\fR 4 +.IX Item "$OS2::nsyserror" +This variable (default is 1) controls whether to enforce the contents +of $^E to start with \f(CW\*(C`SYS0003\*(C'\fR\-like id. If set to 0, then the string +value of $^E is what is available from the OS/2 message file. (Some +messages in this file have an \f(CW\*(C`SYS0003\*(C'\fR\-like id prepended, some not.) +.SS Misfeatures +.IX Subsection "Misfeatures" +.IP \(bu 4 +Since \fBflock\fR\|(3) is present in EMX, but is not functional, it is +emulated by perl. To disable the emulations, set environment variable +\&\f(CW\*(C`USE_PERL_FLOCK=0\*(C'\fR. +.IP \(bu 4 +Here is the list of things which may be "broken" on +EMX (from EMX docs): +.RS 4 +.IP \(bu 4 +The functions \fBrecvmsg\fR\|(3), \fBsendmsg\fR\|(3), and \fBsocketpair\fR\|(3) are not +implemented. +.IP \(bu 4 +\&\fBsock_init\fR\|(3) is not required and not implemented. +.IP \(bu 4 +\&\fBflock\fR\|(3) is not yet implemented (dummy function). (Perl has a workaround.) +.IP \(bu 4 +\&\fBkill\fR\|(3): Special treatment of PID=0, PID=1 and PID=\-1 is not implemented. +.IP \(bu 4 +\&\fBwaitpid\fR\|(3): +.Sp +.Vb 3 +\& WUNTRACED +\& Not implemented. +\& waitpid() is not implemented for negative values of PID. +.Ve +.RE +.RS 4 +.Sp +Note that \f(CW\*(C`kill \-9\*(C'\fR does not work with the current version of EMX. +.RE +.IP \(bu 4 +See "Text-mode filehandles". +.IP \(bu 4 +Unix-domain sockets on OS/2 live in a pseudo-file-system \f(CW\*(C`/sockets/...\*(C'\fR. +To avoid a failure to create a socket with a name of a different form, +\&\f(CW"/socket/"\fR is prepended to the socket name (unless it starts with this +already). +.Sp +This may lead to problems later in case the socket is accessed via the +"usual" file-system calls using the "initial" name. +.IP \(bu 4 +Apparently, IBM used a compiler (for some period of time around '95?) which +changes FP mask right and left. This is not \fIthat\fR bad for IBM's +programs, but the same compiler was used for DLLs which are used with +general-purpose applications. When these DLLs are used, the state of +floating-point flags in the application is not predictable. +.Sp +What is much worse, some DLLs change the floating point flags when in +\&\fB_DLLInitTerm()\fR (e.g., \fITCP32IP\fR). This means that even if you do not \fIcall\fR +any function in the DLL, just the act of loading this DLL will reset your +flags. What is worse, the same compiler was used to compile some HOOK DLLs. +Given that HOOK dlls are executed in the context of \fIall\fR the applications +in the system, this means a complete unpredictability of floating point +flags on systems using such HOOK DLLs. E.g., \fIGAMESRVR.DLL\fR of \fBDIVE\fR +origin changes the floating point flags on each write to the TTY of a VIO +(windowed text-mode) applications. +.Sp +Some other (not completely debugged) situations when FP flags change include +some video drivers (?), and some operations related to creation of the windows. +People who code \fBOpenGL\fR may have more experience on this. +.Sp +Perl is generally used in the situation when all the floating-point +exceptions are ignored, as is the default under EMX. If they are not ignored, +some benign Perl programs would get a \f(CW\*(C`SIGFPE\*(C'\fR and would die a horrible death. +.Sp +To circumvent this, Perl uses two hacks. They help against \fIone\fR type of +damage only: FP flags changed when loading a DLL. +.Sp +One of the hacks is to disable floating point exceptions on Perl startup (as +is the default with EMX). This helps only with compile-time-linked DLLs +changing the flags before \fBmain()\fR had a chance to be called. +.Sp +The other hack is to restore FP flags after a call to \fBdlopen()\fR. This helps +against similar damage done by DLLs \fB_DLLInitTerm()\fR at runtime. Currently +no way to switch these hacks off is provided. +.SS Modifications +.IX Subsection "Modifications" +Perl modifies some standard C library calls in the following ways: +.ie n .IP """popen""" 9 +.el .IP \f(CWpopen\fR 9 +.IX Item "popen" +\&\f(CW\*(C`my_popen\*(C'\fR uses \fIsh.exe\fR if shell is required, cf. "\f(CW\*(C`PERL_SH_DIR\*(C'\fR". +.ie n .IP """tmpnam""" 9 +.el .IP \f(CWtmpnam\fR 9 +.IX Item "tmpnam" +is created using \f(CW\*(C`TMP\*(C'\fR or \f(CW\*(C`TEMP\*(C'\fR environment variable, via +\&\f(CW\*(C`tempnam\*(C'\fR. +.ie n .IP """tmpfile""" 9 +.el .IP \f(CWtmpfile\fR 9 +.IX Item "tmpfile" +If the current directory is not writable, file is created using modified +\&\f(CW\*(C`tmpnam\*(C'\fR, so there may be a race condition. +.ie n .IP """ctermid""" 9 +.el .IP \f(CWctermid\fR 9 +.IX Item "ctermid" +a dummy implementation. +.ie n .IP """stat""" 9 +.el .IP \f(CWstat\fR 9 +.IX Item "stat" +\&\f(CW\*(C`os2_stat\*(C'\fR special-cases \fI/dev/tty\fR and \fI/dev/con\fR. +.ie n .IP """mkdir"", ""rmdir""" 9 +.el .IP "\f(CWmkdir\fR, \f(CWrmdir\fR" 9 +.IX Item "mkdir, rmdir" +these EMX functions do not work if the path contains a trailing \f(CW\*(C`/\*(C'\fR. +Perl contains a workaround for this. +.ie n .IP """flock""" 9 +.el .IP \f(CWflock\fR 9 +.IX Item "flock" +Since \fBflock\fR\|(3) is present in EMX, but is not functional, it is +emulated by perl. To disable the emulations, set environment variable +\&\f(CW\*(C`USE_PERL_FLOCK=0\*(C'\fR. +.SS "Identifying DLLs" +.IX Subsection "Identifying DLLs" +All the DLLs built with the current versions of Perl have ID strings +identifying the name of the extension, its version, and the version +of Perl required for this DLL. Run \f(CW\*(C`bldlevel DLL\-name\*(C'\fR to find this +info. +.SS "Centralized management of resources" +.IX Subsection "Centralized management of resources" +Since to call certain OS/2 API one needs to have a correctly initialized +\&\f(CW\*(C`Win\*(C'\fR subsystem, OS/2\-specific extensions may require getting \f(CW\*(C`HAB\*(C'\fRs and +\&\f(CW\*(C`HMQ\*(C'\fRs. If an extension would do it on its own, another extension could +fail to initialize. +.PP +Perl provides a centralized management of these resources: +.ie n .IP """HAB""" 4 +.el .IP \f(CWHAB\fR 4 +.IX Item "HAB" +To get the HAB, the extension should call \f(CW\*(C`hab = perl_hab_GET()\*(C'\fR in C. After +this call is performed, \f(CW\*(C`hab\*(C'\fR may be accessed as \f(CW\*(C`Perl_hab\*(C'\fR. There is +no need to release the HAB after it is used. +.Sp +If by some reasons \fIperl.h\fR cannot be included, use +.Sp +.Vb 1 +\& extern int Perl_hab_GET(void); +.Ve +.Sp +instead. +.ie n .IP """HMQ""" 4 +.el .IP \f(CWHMQ\fR 4 +.IX Item "HMQ" +There are two cases: +.RS 4 +.IP \(bu 4 +the extension needs an \f(CW\*(C`HMQ\*(C'\fR only because some API will not work otherwise. +Use \f(CW\*(C`serve = 0\*(C'\fR below. +.IP \(bu 4 +the extension needs an \f(CW\*(C`HMQ\*(C'\fR since it wants to engage in a PM event loop. +Use \f(CW\*(C`serve = 1\*(C'\fR below. +.RE +.RS 4 +.Sp +To get an \f(CW\*(C`HMQ\*(C'\fR, the extension should call \f(CW\*(C`hmq = perl_hmq_GET(serve)\*(C'\fR in C. +After this call is performed, \f(CW\*(C`hmq\*(C'\fR may be accessed as \f(CW\*(C`Perl_hmq\*(C'\fR. +.Sp +To signal to Perl that HMQ is not needed any more, call +\&\f(CWperl_hmq_UNSET(serve)\fR. Perl process will automatically morph/unmorph itself +into/from a PM process if HMQ is needed/not\-needed. Perl will automatically +enable/disable \f(CW\*(C`WM_QUIT\*(C'\fR message during shutdown if the message queue is +served/not\-served. +.Sp +\&\fBNOTE\fR. If during a shutdown there is a message queue which did not disable +WM_QUIT, and which did not process the received WM_QUIT message, the +shutdown will be automatically cancelled. Do not call \f(CWperl_hmq_GET(1)\fR +unless you are going to process messages on an orderly basis. +.RE +.IP "Treating errors reported by OS/2 API" 4 +.IX Item "Treating errors reported by OS/2 API" +There are two principal conventions (it is useful to call them \f(CW\*(C`Dos*\*(C'\fR +and \f(CW\*(C`Win*\*(C'\fR \- though this part of the function signature is not always +determined by the name of the API) of reporting the error conditions +of OS/2 API. Most of \f(CW\*(C`Dos*\*(C'\fR APIs report the error code as the result +of the call (so 0 means success, and there are many types of errors). +Most of \f(CW\*(C`Win*\*(C'\fR API report success/fail via the result being +\&\f(CW\*(C`TRUE\*(C'\fR/\f(CW\*(C`FALSE\*(C'\fR; to find the reason for the failure one should call +\&\fBWinGetLastError()\fR API. +.Sp +Some \f(CW\*(C`Win*\*(C'\fR entry points also overload a "meaningful" return value +with the error indicator; having a 0 return value indicates an error. +Yet some other \f(CW\*(C`Win*\*(C'\fR entry points overload things even more, and 0 +return value may mean a successful call returning a valid value 0, as +well as an error condition; in the case of a 0 return value one should +call \fBWinGetLastError()\fR API to distinguish a successful call from a +failing one. +.Sp +By convention, all the calls to OS/2 API should indicate their +failures by resetting $^E. All the Perl-accessible functions which +call OS/2 API may be broken into two classes: some \fBdie()\fRs when an API +error is encountered, the other report the error via a false return +value (of course, this does not concern Perl-accessible functions +which \fIexpect\fR a failure of the OS/2 API call, having some workarounds +coded). +.Sp +Obviously, in the situation of the last type of the signature of an OS/2 +API, it is must more convenient for the users if the failure is +indicated by \fBdie()\fRing: one does not need to check $^E to know that +something went wrong. If, however, this solution is not desirable by +some reason, the code in question should reset $^E to 0 before making +this OS/2 API call, so that the caller of this Perl-accessible +function has a chance to distinguish a success\-but\-0\-return value from +a failure. (One may return undef as an alternative way of reporting +an error.) +.Sp +The macros to simplify this type of error propagation are +.RS 4 +.ie n .IP CheckOSError(expr) 4 +.el .IP \f(CWCheckOSError(expr)\fR 4 +.IX Item "CheckOSError(expr)" +Returns true on error, sets $^E. Expects \fBexpr()\fR be a call of +\&\f(CW\*(C`Dos*\*(C'\fR\-style API. +.ie n .IP CheckWinError(expr) 4 +.el .IP \f(CWCheckWinError(expr)\fR 4 +.IX Item "CheckWinError(expr)" +Returns true on error, sets $^E. Expects \fBexpr()\fR be a call of +\&\f(CW\*(C`Win*\*(C'\fR\-style API. +.ie n .IP SaveWinError(expr) 4 +.el .IP \f(CWSaveWinError(expr)\fR 4 +.IX Item "SaveWinError(expr)" +Returns \f(CW\*(C`expr\*(C'\fR, sets $^E from \fBWinGetLastError()\fR if \f(CW\*(C`expr\*(C'\fR is false. +.ie n .IP """SaveCroakWinError(expr,die,name1,name2)""" 4 +.el .IP \f(CWSaveCroakWinError(expr,die,name1,name2)\fR 4 +.IX Item "SaveCroakWinError(expr,die,name1,name2)" +Returns \f(CW\*(C`expr\*(C'\fR, sets $^E from \fBWinGetLastError()\fR if \f(CW\*(C`expr\*(C'\fR is false, +and \fBdie()\fRs if \f(CW\*(C`die\*(C'\fR and $^E are true. The message to die is the +concatenated strings \f(CW\*(C`name1\*(C'\fR and \f(CW\*(C`name2\*(C'\fR, separated by \f(CW": "\fR from +the contents of $^E. +.ie n .IP """WinError_2_Perl_rc""" 4 +.el .IP \f(CWWinError_2_Perl_rc\fR 4 +.IX Item "WinError_2_Perl_rc" +Sets \f(CW\*(C`Perl_rc\*(C'\fR to the return value of \fBWinGetLastError()\fR. +.ie n .IP """FillWinError""" 4 +.el .IP \f(CWFillWinError\fR 4 +.IX Item "FillWinError" +Sets \f(CW\*(C`Perl_rc\*(C'\fR to the return value of \fBWinGetLastError()\fR, and sets $^E +to the corresponding value. +.ie n .IP FillOSError(rc) 4 +.el .IP \f(CWFillOSError(rc)\fR 4 +.IX Item "FillOSError(rc)" +Sets \f(CW\*(C`Perl_rc\*(C'\fR to \f(CW\*(C`rc\*(C'\fR, and sets $^E to the corresponding value. +.RE +.RS 4 +.RE +.IP "Loading DLLs and ordinals in DLLs" 4 +.IX Item "Loading DLLs and ordinals in DLLs" +Some DLLs are only present in some versions of OS/2, or in some +configurations of OS/2. Some exported entry points are present only +in DLLs shipped with some versions of OS/2. If these DLLs and entry +points were linked directly for a Perl executable/DLL or from a Perl +extensions, this binary would work only with the specified +versions/setups. Even if these entry points were not needed, the +\&\fIload\fR of the executable (or DLL) would fail. +.Sp +For example, many newer useful APIs are not present in OS/2 v2; many +PM-related APIs require DLLs not available on floppy-boot setup. +.Sp +To make these calls fail \fIonly when the calls are executed\fR, one +should call these API via a dynamic linking API. There is a subsystem +in Perl to simplify such type of calls. A large number of entry +points available for such linking is provided (see \f(CW\*(C`entries_ordinals\*(C'\fR +\&\- and also \f(CW\*(C`PMWIN_entries\*(C'\fR \- in \fIos2ish.h\fR). These ordinals can be +accessed via the APIs: +.Sp +.Vb 6 +\& CallORD(), DeclFuncByORD(), DeclVoidFuncByORD(), +\& DeclOSFuncByORD(), DeclWinFuncByORD(), AssignFuncPByORD(), +\& DeclWinFuncByORD_CACHE(), DeclWinFuncByORD_CACHE_survive(), +\& DeclWinFuncByORD_CACHE_resetError_survive(), +\& DeclWinFunc_CACHE(), DeclWinFunc_CACHE_resetError(), +\& DeclWinFunc_CACHE_survive(), DeclWinFunc_CACHE_resetError_survive() +.Ve +.Sp +See the header files and the C code in the supplied OS/2\-related +modules for the details on usage of these functions. +.Sp +Some of these functions also combine dynaloading semantic with the +error-propagation semantic discussed above. +.SH "Perl flavors" +.IX Header "Perl flavors" +Because of idiosyncrasies of OS/2 one cannot have all the eggs in the +same basket (though EMX environment tries hard to overcome this +limitations, so the situation may somehow improve). There are 4 +executables for Perl provided by the distribution: +.SS \fIperl.exe\fP +.IX Subsection "perl.exe" +The main workhorse. This is a chimera executable: it is compiled as an +\&\f(CW\*(C`a.out\*(C'\fR\-style executable, but is linked with \f(CW\*(C`omf\*(C'\fR\-style dynamic +library \fIperl.dll\fR, and with dynamic CRT DLL. This executable is a +VIO application. +.PP +It can load perl dynamic extensions, and it can \fBfork()\fR. +.PP +\&\fBNote.\fR Keep in mind that \fBfork()\fR is needed to open a pipe to yourself. +.SS \fIperl_.exe\fP +.IX Subsection "perl_.exe" +This is a statically linked \f(CW\*(C`a.out\*(C'\fR\-style executable. It cannot +load dynamic Perl extensions. The executable supplied in binary +distributions has a lot of extensions prebuilt, thus the above restriction is +important only if you use custom-built extensions. This executable is a VIO +application. +.PP +\&\fIThis is the only executable with does not require OS/2.\fR The +friends locked into \f(CW\*(C`M$\*(C'\fR world would appreciate the fact that this +executable runs under DOS, Win0.3*, Win0.95 and WinNT with an +appropriate extender. See "Other OSes". +.SS \fIperl_\|_.exe\fP +.IX Subsection "perl__.exe" +This is the same executable as \fIperl_\|_\|_.exe\fR, but it is a PM +application. +.PP +\&\fBNote.\fR Usually (unless explicitly redirected during the startup) +STDIN, STDERR, and STDOUT of a PM +application are redirected to \fInul\fR. However, it is possible to \fIsee\fR +them if you start \f(CW\*(C`perl_\|_.exe\*(C'\fR from a PM program which emulates a +console window, like \fIShell mode\fR of Emacs or EPM. Thus it \fIis +possible\fR to use Perl debugger (see perldebug) to debug your PM +application (but beware of the message loop lockups \- this will not +work if you have a message queue to serve, unless you hook the serving +into the \fBgetc()\fR function of the debugger). +.PP +Another way to see the output of a PM program is to run it as +.PP +.Vb 1 +\& pm_prog args 2>&1 | cat \- +.Ve +.PP +with a shell \fIdifferent\fR from \fIcmd.exe\fR, so that it does not create +a link between a VIO session and the session of \f(CW\*(C`pm_porg\*(C'\fR. (Such a link +closes the VIO window.) E.g., this works with \fIsh.exe\fR \- or with Perl! +.PP +.Vb 2 +\& open P, \*(Aqpm_prog args 2>&1 |\*(Aq or die; +\& print while <P>; +.Ve +.PP +The flavor \fIperl_\|_.exe\fR is required if you want to start your program without +a VIO window present, but not \f(CW\*(C`detach\*(C'\fRed (run \f(CW\*(C`help detach\*(C'\fR for more info). +Very useful for extensions which use PM, like \f(CW\*(C`Perl/Tk\*(C'\fR or \f(CW\*(C`OpenGL\*(C'\fR. +.PP +Note also that the differences between PM and VIO executables are only +in the \fIdefault\fR behaviour. One can start \fIany\fR executable in +\&\fIany\fR kind of session by using the arguments \f(CW\*(C`/fs\*(C'\fR, \f(CW\*(C`/pm\*(C'\fR or +\&\f(CW\*(C`/win\*(C'\fR switches of the command \f(CW\*(C`start\*(C'\fR (of \fICMD.EXE\fR or a similar +shell). Alternatively, one can use the numeric first argument of the +\&\f(CW\*(C`system\*(C'\fR Perl function (see OS2::Process). +.SS \fIperl_\|_\|_.exe\fP +.IX Subsection "perl___.exe" +This is an \f(CW\*(C`omf\*(C'\fR\-style executable which is dynamically linked to +\&\fIperl.dll\fR and CRT DLL. I know no advantages of this executable +over \f(CW\*(C`perl.exe\*(C'\fR, but it cannot \fBfork()\fR at all. Well, one advantage is +that the build process is not so convoluted as with \f(CW\*(C`perl.exe\*(C'\fR. +.PP +It is a VIO application. +.SS "Why strange names?" +.IX Subsection "Why strange names?" +Since Perl processes the \f(CW\*(C`#!\*(C'\fR\-line (cf. +"DESCRIPTION" in perlrun, "Command Switches" in perlrun, +"No Perl script found in input" in perldiag), it should know when a +program \fIis a Perl\fR. There is some naming convention which allows +Perl to distinguish correct lines from wrong ones. The above names are +almost the only names allowed by this convention which do not contain +digits (which have absolutely different semantics). +.SS "Why dynamic linking?" +.IX Subsection "Why dynamic linking?" +Well, having several executables dynamically linked to the same huge +library has its advantages, but this would not substantiate the +additional work to make it compile. The reason is the complicated-to-developers +but very quick and convenient-to-users "hard" dynamic linking used by OS/2. +.PP +There are two distinctive features of the dyna-linking model of OS/2: +first, all the references to external functions are resolved at the compile time; +second, there is no runtime fixup of the DLLs after they are loaded into memory. +The first feature is an enormous advantage over other models: it avoids +conflicts when several DLLs used by an application export entries with +the same name. In such cases "other" models of dyna-linking just choose +between these two entry points using some random criterion \- with predictable +disasters as results. But it is the second feature which requires the build +of \fIperl.dll\fR. +.PP +The address tables of DLLs are patched only once, when they are +loaded. The addresses of the entry points into DLLs are guaranteed to be +the same for all the programs which use the same DLL. This removes the +runtime fixup \- once DLL is loaded, its code is read-only. +.PP +While this allows some (significant?) performance advantages, this makes life +much harder for developers, since the above scheme makes it impossible +for a DLL to be "linked" to a symbol in the \fI.EXE\fR file. Indeed, this +would need a DLL to have different relocations tables for the +(different) executables which use this DLL. +.PP +However, a dynamically loaded Perl extension is forced to use some symbols +from the perl +executable, e.g., to know how to find the arguments to the functions: +the arguments live on the perl +internal evaluation stack. The solution is to put the main code of +the interpreter into a DLL, and make the \fI.EXE\fR file which just loads +this DLL into memory and supplies command-arguments. The extension DLL +cannot link to symbols in \fI.EXE\fR, but it has no problem linking +to symbols in the \fI.DLL\fR. +.PP +This \fIgreatly\fR increases the load time for the application (as well as +complexity of the compilation). Since interpreter is in a DLL, +the C RTL is basically forced to reside in a DLL as well (otherwise +extensions would not be able to use CRT). There are some advantages if +you use different flavors of perl, such as running \fIperl.exe\fR and +\&\fIperl_\|_.exe\fR simultaneously: they share the memory of \fIperl.dll\fR. +.PP +\&\fBNOTE\fR. There is one additional effect which makes DLLs more wasteful: +DLLs are loaded in the shared memory region, which is a scarse resource +given the 512M barrier of the "standard" OS/2 virtual memory. The code of +\&\fI.EXE\fR files is also shared by all the processes which use the particular +\&\fI.EXE\fR, but they are "shared in the private address space of the process"; +this is possible because the address at which different sections +of the \fI.EXE\fR file are loaded is decided at compile-time, thus all the +processes have these sections loaded at same addresses, and no fixup +of internal links inside the \fI.EXE\fR is needed. +.PP +Since DLLs may be loaded at run time, to have the same mechanism for DLLs +one needs to have the address range of \fIany of the loaded\fR DLLs in the +system to be available \fIin all the processes\fR which did not load a particular +DLL yet. This is why the DLLs are mapped to the shared memory region. +.SS "Why chimera build?" +.IX Subsection "Why chimera build?" +Current EMX environment does not allow DLLs compiled using Unixish +\&\f(CW\*(C`a.out\*(C'\fR format to export symbols for data (or at least some types of +data). This forces \f(CW\*(C`omf\*(C'\fR\-style compile of \fIperl.dll\fR. +.PP +Current EMX environment does not allow \fI.EXE\fR files compiled in +\&\f(CW\*(C`omf\*(C'\fR format to \fBfork()\fR. \fBfork()\fR is needed for exactly three Perl +operations: +.IP \(bu 4 +explicit \fBfork()\fR in the script, +.IP \(bu 4 +\&\f(CW\*(C`open FH, "|\-"\*(C'\fR +.IP \(bu 4 +\&\f(CW\*(C`open FH, "\-|"\*(C'\fR, in other words, opening pipes to itself. +.PP +While these operations are not questions of life and death, they are +needed for a lot of +useful scripts. This forces \f(CW\*(C`a.out\*(C'\fR\-style compile of +\&\fIperl.exe\fR. +.SH ENVIRONMENT +.IX Header "ENVIRONMENT" +Here we list environment variables with are either OS/2\- and DOS\- and +Win*\-specific, or are more important under OS/2 than under other OSes. +.ie n .SS """PERLLIB_PREFIX""" +.el .SS \f(CWPERLLIB_PREFIX\fP +.IX Subsection "PERLLIB_PREFIX" +Specific for EMX port. Should have the form +.PP +.Vb 1 +\& path1;path2 +.Ve +.PP +or +.PP +.Vb 1 +\& path1 path2 +.Ve +.PP +If the beginning of some prebuilt path matches \fIpath1\fR, it is +substituted with \fIpath2\fR. +.PP +Should be used if the perl library is moved from the default +location in preference to \f(CW\*(C`PERL(5)LIB\*(C'\fR, since this would not leave wrong +entries in \f(CW@INC\fR. For example, if the compiled version of perl looks for \f(CW@INC\fR +in \fIf:/perllib/lib\fR, and you want to install the library in +\&\fIh:/opt/gnu\fR, do +.PP +.Vb 1 +\& set PERLLIB_PREFIX=f:/perllib/lib;h:/opt/gnu +.Ve +.PP +This will cause Perl with the prebuilt \f(CW@INC\fR of +.PP +.Vb 5 +\& f:/perllib/lib/5.00553/os2 +\& f:/perllib/lib/5.00553 +\& f:/perllib/lib/site_perl/5.00553/os2 +\& f:/perllib/lib/site_perl/5.00553 +\& . +.Ve +.PP +to use the following \f(CW@INC:\fR +.PP +.Vb 5 +\& h:/opt/gnu/5.00553/os2 +\& h:/opt/gnu/5.00553 +\& h:/opt/gnu/site_perl/5.00553/os2 +\& h:/opt/gnu/site_perl/5.00553 +\& . +.Ve +.ie n .SS """PERL_BADLANG""" +.el .SS \f(CWPERL_BADLANG\fP +.IX Subsection "PERL_BADLANG" +If 0, perl ignores \fBsetlocale()\fR failing. May be useful with some +strange \fIlocale\fRs. +.ie n .SS """PERL_BADFREE""" +.el .SS \f(CWPERL_BADFREE\fP +.IX Subsection "PERL_BADFREE" +If 0, perl would not warn of in case of unwarranted \fBfree()\fR. With older +perls this might be +useful in conjunction with the module DB_File, which was buggy when +dynamically linked and OMF-built. +.PP +Should not be set with newer Perls, since this may hide some \fIreal\fR problems. +.ie n .SS """PERL_SH_DIR""" +.el .SS \f(CWPERL_SH_DIR\fP +.IX Subsection "PERL_SH_DIR" +Specific for EMX port. Gives the directory part of the location for +\&\fIsh.exe\fR. +.ie n .SS """USE_PERL_FLOCK""" +.el .SS \f(CWUSE_PERL_FLOCK\fP +.IX Subsection "USE_PERL_FLOCK" +Specific for EMX port. Since \fBflock\fR\|(3) is present in EMX, but is not +functional, it is emulated by perl. To disable the emulations, set +environment variable \f(CW\*(C`USE_PERL_FLOCK=0\*(C'\fR. +.ie n .SS """TMP"" or ""TEMP""" +.el .SS "\f(CWTMP\fP or \f(CWTEMP\fP" +.IX Subsection "TMP or TEMP" +Specific for EMX port. Used as storage place for temporary files. +.SH Evolution +.IX Header "Evolution" +Here we list major changes which could make you by surprise. +.SS "Text-mode filehandles" +.IX Subsection "Text-mode filehandles" +Starting from version 5.8, Perl uses a builtin translation layer for +text-mode files. This replaces the efficient well-tested EMX layer by +some code which should be best characterized as a "quick hack". +.PP +In addition to possible bugs and an inability to follow changes to the +translation policy with off/on switches of TERMIO translation, this +introduces a serious incompatible change: before \fBsysread()\fR on +text-mode filehandles would go through the translation layer, now it +would not. +.SS Priorities +.IX Subsection "Priorities" +\&\f(CW\*(C`setpriority\*(C'\fR and \f(CW\*(C`getpriority\*(C'\fR are not compatible with earlier +ports by Andreas Kaiser. See "setpriority, getpriority". +.SS "DLL name mangling: pre 5.6.2" +.IX Subsection "DLL name mangling: pre 5.6.2" +With the release 5.003_01 the dynamically loadable libraries +should be rebuilt when a different version of Perl is compiled. In particular, +DLLs (including \fIperl.dll\fR) are now created with the names +which contain a checksum, thus allowing workaround for OS/2 scheme of +caching DLLs. +.PP +It may be possible to code a simple workaround which would +.IP \(bu 4 +find the old DLLs looking through the old \f(CW@INC\fR; +.IP \(bu 4 +mangle the names according to the scheme of new perl and copy the DLLs to +these names; +.IP \(bu 4 +edit the internal \f(CW\*(C`LX\*(C'\fR tables of DLL to reflect the change of the name +(probably not needed for Perl extension DLLs, since the internally coded names +are not used for "specific" DLLs, they used only for "global" DLLs). +.IP \(bu 4 +edit the internal \f(CW\*(C`IMPORT\*(C'\fR tables and change the name of the "old" +\&\fIperl????.dll\fR to the "new" \fIperl????.dll\fR. +.SS "DLL name mangling: 5.6.2 and beyond" +.IX Subsection "DLL name mangling: 5.6.2 and beyond" +In fact mangling of \fIextension\fR DLLs was done due to misunderstanding +of the OS/2 dynaloading model. OS/2 (effectively) maintains two +different tables of loaded DLL: +.IP "Global DLLs" 4 +.IX Item "Global DLLs" +those loaded by the base name from \f(CW\*(C`LIBPATH\*(C'\fR; including those +associated at link time; +.IP "specific DLLs" 4 +.IX Item "specific DLLs" +loaded by the full name. +.PP +When resolving a request for a global DLL, the table of already-loaded +specific DLLs is (effectively) ignored; moreover, specific DLLs are +\&\fIalways\fR loaded from the prescribed path. +.PP +There is/was a minor twist which makes this scheme fragile: what to do +with DLLs loaded from +.ie n .IP """BEGINLIBPATH"" and ""ENDLIBPATH""" 4 +.el .IP "\f(CWBEGINLIBPATH\fR and \f(CWENDLIBPATH\fR" 4 +.IX Item "BEGINLIBPATH and ENDLIBPATH" +(which depend on the process) +.ie n .IP "\fI.\fR from ""LIBPATH""" 4 +.el .IP "\fI.\fR from \f(CWLIBPATH\fR" 4 +.IX Item ". from LIBPATH" +which \fIeffectively\fR depends on the process (although \f(CW\*(C`LIBPATH\*(C'\fR is the +same for all the processes). +.PP +Unless \f(CW\*(C`LIBPATHSTRICT\*(C'\fR is set to \f(CW\*(C`T\*(C'\fR (and the kernel is after +2000/09/01), such DLLs are considered to be global. When loading a +global DLL it is first looked in the table of already-loaded global +DLLs. Because of this the fact that one executable loaded a DLL from +\&\f(CW\*(C`BEGINLIBPATH\*(C'\fR and \f(CW\*(C`ENDLIBPATH\*(C'\fR, or \fI.\fR from \f(CW\*(C`LIBPATH\*(C'\fR may affect +\&\fIwhich\fR DLL is loaded when \fIanother\fR executable requests a DLL with +the same name. \fIThis\fR is the reason for version-specific mangling of +the DLL name for perl DLL. +.PP +Since the Perl extension DLLs are always loaded with the full path, +there is no need to mangle their names in a version-specific ways: +their directory already reflects the corresponding version of perl, +and \f(CW@INC\fR takes into account binary compatibility with older version. +Starting from \f(CW5.6.2\fR the name mangling scheme is fixed to be the +same as for Perl 5.005_53 (same as in a popular binary release). Thus +new Perls will be able to \fIresolve the names\fR of old extension DLLs +if \f(CW@INC\fR allows finding their directories. +.PP +However, this still does not guarantee that these DLL may be loaded. +The reason is the mangling of the name of the \fIPerl DLL\fR. And since +the extension DLLs link with the Perl DLL, extension DLLs for older +versions would load an older Perl DLL, and would most probably +segfault (since the data in this DLL is not properly initialized). +.PP +There is a partial workaround (which can be made complete with newer +OS/2 kernels): create a forwarder DLL with the same name as the DLL of +the older version of Perl, which forwards the entry points to the +newer Perl's DLL. Make this DLL accessible on (say) the \f(CW\*(C`BEGINLIBPATH\*(C'\fR of +the new Perl executable. When the new executable accesses old Perl's +extension DLLs, they would request the old Perl's DLL by name, get the +forwarder instead, so effectively will link with the currently running +(new) Perl DLL. +.PP +This may break in two ways: +.IP \(bu 4 +Old perl executable is started when a new executable is running has +loaded an extension compiled for the old executable (ouph!). In this +case the old executable will get a forwarder DLL instead of the old +perl DLL, so would link with the new perl DLL. While not directly +fatal, it will behave the same as new executable. This beats the whole +purpose of explicitly starting an old executable. +.IP \(bu 4 +A new executable loads an extension compiled for the old executable +when an old perl executable is running. In this case the extension +will not pick up the forwarder \- with fatal results. +.PP +With support for \f(CW\*(C`LIBPATHSTRICT\*(C'\fR this may be circumvented \- unless +one of DLLs is started from \fI.\fR from \f(CW\*(C`LIBPATH\*(C'\fR (I do not know +whether \f(CW\*(C`LIBPATHSTRICT\*(C'\fR affects this case). +.PP +\&\fBREMARK\fR. Unless newer kernels allow \fI.\fR in \f(CW\*(C`BEGINLIBPATH\*(C'\fR (older +do not), this mess cannot be completely cleaned. (It turns out that +as of the beginning of 2002, \fI.\fR is not allowed, but \fI.\e.\fR is \- and +it has the same effect.) +.PP +\&\fBREMARK\fR. \f(CW\*(C`LIBPATHSTRICT\*(C'\fR, \f(CW\*(C`BEGINLIBPATH\*(C'\fR and \f(CW\*(C`ENDLIBPATH\*(C'\fR are +not environment variables, although \fIcmd.exe\fR emulates them on \f(CW\*(C`SET +\&...\*(C'\fR lines. From Perl they may be accessed by +Cwd::extLibpath and +Cwd::extLibpath_set. +.SS "DLL forwarder generation" +.IX Subsection "DLL forwarder generation" +Assume that the old DLL is named \fIperlE0AC.dll\fR (as is one for +5.005_53), and the new version is 5.6.1. Create a file +\&\fIperl5shim.def\-leader\fR with +.PP +.Vb 5 +\& LIBRARY \*(AqperlE0AC\*(Aq INITINSTANCE TERMINSTANCE +\& DESCRIPTION \*(Aq@#perl5\-porters@perl.org:5.006001#@ Perl module for 5.00553 \-> Perl 5.6.1 forwarder\*(Aq +\& CODE LOADONCALL +\& DATA LOADONCALL NONSHARED MULTIPLE +\& EXPORTS +.Ve +.PP +modifying the versions/names as needed. Run +.PP +.Vb 2 +\& perl \-wnle "next if 0../EXPORTS/; print qq( \e"$1\e") +\& if /\e"(\ew+)\e"/" perl5.def >lst +.Ve +.PP +in the Perl build directory (to make the DLL smaller replace perl5.def +with the definition file for the older version of Perl if present). +.PP +.Vb 2 +\& cat perl5shim.def\-leader lst >perl5shim.def +\& gcc \-Zomf \-Zdll \-o perlE0AC.dll perl5shim.def \-s \-llibperl +.Ve +.PP +(ignore multiple \f(CW\*(C`warning L4085\*(C'\fR). +.SS Threading +.IX Subsection "Threading" +As of release 5.003_01 perl is linked to multithreaded C RTL +DLL. If perl itself is not compiled multithread-enabled, so will not be perl's +\&\fBmalloc()\fR. However, extensions may use multiple thread on their own +risk. +.PP +This was needed to compile \f(CW\*(C`Perl/Tk\*(C'\fR for XFree86\-OS/2 out-of-the-box, and +link with DLLs for other useful libraries, which typically are compiled +with \f(CW\*(C`\-Zmt \-Zcrtdll\*(C'\fR. +.SS "Calls to external programs" +.IX Subsection "Calls to external programs" +Due to a popular demand the perl external program calling has been +changed wrt Andreas Kaiser's port. \fIIf\fR perl needs to call an +external program \fIvia shell\fR, the \fIf:/bin/sh.exe\fR will be called, or +whatever is the override, see "\f(CW\*(C`PERL_SH_DIR\*(C'\fR". +.PP +Thus means that you need to get some copy of a \fIsh.exe\fR as well (I +use one from pdksh). The path \fIF:/bin\fR above is set up automatically during +the build to a correct value on the builder machine, but is +overridable at runtime, +.PP +\&\fBReasons:\fR a consensus on \f(CW\*(C`perl5\-porters\*(C'\fR was that perl should use +one non-overridable shell per platform. The obvious choices for OS/2 +are \fIcmd.exe\fR and \fIsh.exe\fR. Having perl build itself would be impossible +with \fIcmd.exe\fR as a shell, thus I picked up \f(CW\*(C`sh.exe\*(C'\fR. This assures almost +100% compatibility with the scripts coming from *nix. As an added benefit +this works as well under DOS if you use DOS-enabled port of pdksh +(see "Prerequisites"). +.PP +\&\fBDisadvantages:\fR currently \fIsh.exe\fR of pdksh calls external programs +via \fBfork()\fR/\fBexec()\fR, and there is \fIno\fR functioning \fBexec()\fR on +OS/2. \fBexec()\fR is emulated by EMX by an asynchronous call while the caller +waits for child completion (to pretend that the \f(CW\*(C`pid\*(C'\fR did not change). This +means that 1 \fIextra\fR copy of \fIsh.exe\fR is made active via \fBfork()\fR/\fBexec()\fR, +which may lead to some resources taken from the system (even if we do +not count extra work needed for \fBfork()\fRing). +.PP +Note that this a lesser issue now when we do not spawn \fIsh.exe\fR +unless needed (metachars found). +.PP +One can always start \fIcmd.exe\fR explicitly via +.PP +.Vb 1 +\& system \*(Aqcmd\*(Aq, \*(Aq/c\*(Aq, \*(Aqmycmd\*(Aq, \*(Aqarg1\*(Aq, \*(Aqarg2\*(Aq, ... +.Ve +.PP +If you need to use \fIcmd.exe\fR, and do not want to hand-edit thousands of your +scripts, the long-term solution proposed on p5\-p is to have a directive +.PP +.Vb 1 +\& use OS2::Cmd; +.Ve +.PP +which will override \fBsystem()\fR, \fBexec()\fR, \f(CW\`\`\fR, and +\&\f(CW\*(C`open(,\*(Aq...|\*(Aq)\*(C'\fR. With current perl you may override only \fBsystem()\fR, +\&\fBreadpipe()\fR \- the explicit version of \f(CW\`\`\fR, and maybe \fBexec()\fR. The code +will substitute the one-argument call to \fBsystem()\fR by +\&\f(CW\*(C`CORE::system(\*(Aqcmd.exe\*(Aq, \*(Aq/c\*(Aq, shift)\*(C'\fR. +.PP +If you have some working code for \f(CW\*(C`OS2::Cmd\*(C'\fR, please send it to me, +I will include it into distribution. I have no need for such a module, so +cannot test it. +.PP +For the details of the current situation with calling external programs, +see "Starting OS/2 (and DOS) programs under Perl". Set us +mention a couple of features: +.IP \(bu 4 +External scripts may be called by their basename. Perl will try the same +extensions as when processing \fB\-S\fR command-line switch. +.IP \(bu 4 +External scripts starting with \f(CW\*(C`#!\*(C'\fR or \f(CW\*(C`extproc \*(C'\fR will be executed directly, +without calling the shell, by calling the program specified on the rest of +the first line. +.SS "Memory allocation" +.IX Subsection "Memory allocation" +Perl uses its own \fBmalloc()\fR under OS/2 \- interpreters are usually malloc-bound +for speed, but perl is not, since its malloc is lightning-fast. +Perl-memory-usage-tuned benchmarks show that Perl's malloc is 5 times quicker +than EMX one. I do not have convincing data about memory footprint, but +a (pretty random) benchmark showed that Perl's one is 5% better. +.PP +Combination of perl's \fBmalloc()\fR and rigid DLL name resolution creates +a special problem with library functions which expect their return value to +be \fBfree()\fRd by system's \fBfree()\fR. To facilitate extensions which need to call +such functions, system memory-allocation functions are still available with +the prefix \f(CW\*(C`emx_\*(C'\fR added. (Currently only DLL perl has this, it should +propagate to \fIperl_.exe\fR shortly.) +.SS Threads +.IX Subsection "Threads" +One can build perl with thread support enabled by providing \f(CW\*(C`\-D usethreads\*(C'\fR +option to \fIConfigure\fR. Currently OS/2 support of threads is very +preliminary. +.PP +Most notable problems: +.ie n .IP """COND_WAIT""" 4 +.el .IP \f(CWCOND_WAIT\fR 4 +.IX Item "COND_WAIT" +may have a race condition (but probably does not due to edge-triggered +nature of OS/2 Event semaphores). (Needs a reimplementation (in terms of chaining +waiting threads, with the linked list stored in per-thread structure?)?) +.IP \fIos2.c\fR 4 +.IX Item "os2.c" +has a couple of static variables used in OS/2\-specific functions. (Need to be +moved to per-thread structure, or serialized?) +.PP +Note that these problems should not discourage experimenting, since they +have a low probability of affecting small programs. +.SH BUGS +.IX Header "BUGS" +This description is not updated often (since 5.6.1?), see \fI./os2/Changes\fR +for more info. +.SH AUTHOR +.IX Header "AUTHOR" +Ilya Zakharevich, cpan@ilyaz.org +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBperl\fR\|(1). |