1*e0680481Safresh1# vim: syntax=pod 2*e0680481Safresh1 3ba47ec9dSmillertIf you read this file _as_is_, just ignore the funny characters you 4ba47ec9dSmillertsee. It is written in the POD format (see perlpod manpage) which is 5ba47ec9dSmillertspecially designed to be readable as is. 6ba47ec9dSmillert 7ba47ec9dSmillert=head1 NAME 8ba47ec9dSmillert 9ba47ec9dSmillertperlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT. 10ba47ec9dSmillert 11ba47ec9dSmillert=head1 SYNOPSIS 12ba47ec9dSmillert 13ba47ec9dSmillertOne can read this document in the following formats: 14ba47ec9dSmillert 15ba47ec9dSmillert man perlos2 16ba47ec9dSmillert view perl perlos2 17ba47ec9dSmillert explorer perlos2.html 18ba47ec9dSmillert info perlos2 19ba47ec9dSmillert 20ba47ec9dSmillertto list some (not all may be available simultaneously), or it may 21ba47ec9dSmillertbe read I<as is>: either as F<README.os2>, or F<pod/perlos2.pod>. 22ba47ec9dSmillert 23ba47ec9dSmillertTo read the F<.INF> version of documentation (B<very> recommended) 24ba47ec9dSmillertoutside of OS/2, one needs an IBM's reader (may be available on IBM 25ba47ec9dSmillertftp sites (?) (URL anyone?)) or shipped with PC DOS 7.0 and IBM's 26ba47ec9dSmillertVisual Age C++ 3.5. 27ba47ec9dSmillert 28ba47ec9dSmillertA copy of a Win* viewer is contained in the "Just add OS/2 Warp" package 29ba47ec9dSmillert 30ba47ec9dSmillert ftp://ftp.software.ibm.com/ps/products/os2/tools/jaow/jaow.zip 31ba47ec9dSmillert 32ba47ec9dSmillertin F<?:\JUST_ADD\view.exe>. This gives one an access to EMX's 33ba47ec9dSmillertF<.INF> docs as well (text form is available in F</emx/doc> in 3479cd0b9aSmillertEMX's distribution). There is also a different viewer named xview. 35ba47ec9dSmillert 3679cd0b9aSmillertNote that if you have F<lynx.exe> or F<netscape.exe> installed, you can follow WWW links 37ba47ec9dSmillertfrom this document in F<.INF> format. If you have EMX docs installed 38ba47ec9dSmillertcorrectly, you can follow library links (you need to have C<view emxbook> 39ba47ec9dSmillertworking by setting C<EMXBOOK> environment variable as it is described 40ba47ec9dSmillertin EMX docs). 41ba47ec9dSmillert 42ba47ec9dSmillert=cut 43ba47ec9dSmillert 4479cd0b9aSmillertContents (This may be a little bit obsolete) 45ba47ec9dSmillert 46ba47ec9dSmillert perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT. 47ba47ec9dSmillert 48ba47ec9dSmillert NAME 49ba47ec9dSmillert SYNOPSIS 50ba47ec9dSmillert DESCRIPTION 51ba47ec9dSmillert - Target 52ba47ec9dSmillert - Other OSes 53ba47ec9dSmillert - Prerequisites 54ba47ec9dSmillert - Starting Perl programs under OS/2 (and DOS and...) 55ba47ec9dSmillert - Starting OS/2 (and DOS) programs under Perl 56ba47ec9dSmillert Frequently asked questions 5779cd0b9aSmillert - "It does not work" 58ba47ec9dSmillert - I cannot run external programs 5979cd0b9aSmillert - I cannot embed perl into my program, or use perl.dll from my 60ba47ec9dSmillert - `` and pipe-open do not work under DOS. 61ba47ec9dSmillert - Cannot start find.exe "pattern" file 62ba47ec9dSmillert INSTALLATION 63ba47ec9dSmillert - Automatic binary installation 64ba47ec9dSmillert - Manual binary installation 65ba47ec9dSmillert - Warning 66ba47ec9dSmillert Accessing documentation 67ba47ec9dSmillert - OS/2 .INF file 68ba47ec9dSmillert - Plain text 69ba47ec9dSmillert - Manpages 70ba47ec9dSmillert - HTML 71ba47ec9dSmillert - GNU info files 7279cd0b9aSmillert - PDF files 73ba47ec9dSmillert - LaTeX docs 74ba47ec9dSmillert BUILD 7579cd0b9aSmillert - The short story 76ba47ec9dSmillert - Prerequisites 77ba47ec9dSmillert - Getting perl source 78ba47ec9dSmillert - Application of the patches 79ba47ec9dSmillert - Hand-editing 80ba47ec9dSmillert - Making 81ba47ec9dSmillert - Testing 82ba47ec9dSmillert - Installing the built perl 83ba47ec9dSmillert - a.out-style build 84ba47ec9dSmillert Build FAQ 85ba47ec9dSmillert - Some / became \ in pdksh. 86ba47ec9dSmillert - 'errno' - unresolved external 8779cd0b9aSmillert - Problems with tr or sed 88ba47ec9dSmillert - Some problem (forget which ;-) 89ba47ec9dSmillert - Library ... not found 90ba47ec9dSmillert - Segfault in make 9179cd0b9aSmillert - op/sprintf test failure 9279cd0b9aSmillert Specific (mis)features of OS/2 port 93ba47ec9dSmillert - setpriority, getpriority 94ba47ec9dSmillert - system() 95ba47ec9dSmillert - extproc on the first line 96ba47ec9dSmillert - Additional modules: 97ba47ec9dSmillert - Prebuilt methods: 9879cd0b9aSmillert - Prebuilt variables: 99ba47ec9dSmillert - Misfeatures 100ba47ec9dSmillert - Modifications 10179cd0b9aSmillert - Identifying DLLs 10279cd0b9aSmillert - Centralized management of resources 103ba47ec9dSmillert Perl flavors 104ba47ec9dSmillert - perl.exe 105ba47ec9dSmillert - perl_.exe 106ba47ec9dSmillert - perl__.exe 107ba47ec9dSmillert - perl___.exe 108ba47ec9dSmillert - Why strange names? 109ba47ec9dSmillert - Why dynamic linking? 110ba47ec9dSmillert - Why chimera build? 111ba47ec9dSmillert ENVIRONMENT 112ba47ec9dSmillert - PERLLIB_PREFIX 113ba47ec9dSmillert - PERL_BADLANG 114ba47ec9dSmillert - PERL_BADFREE 115ba47ec9dSmillert - PERL_SH_DIR 11679cd0b9aSmillert - USE_PERL_FLOCK 117ba47ec9dSmillert - TMP or TEMP 118ba47ec9dSmillert Evolution 11979cd0b9aSmillert - Text-mode filehandles 120ba47ec9dSmillert - Priorities 12179cd0b9aSmillert - DLL name mangling: pre 5.6.2 12279cd0b9aSmillert - DLL name mangling: 5.6.2 and beyond 12379cd0b9aSmillert - DLL forwarder generation 124ba47ec9dSmillert - Threading 125ba47ec9dSmillert - Calls to external programs 126ba47ec9dSmillert - Memory allocation 1276345ca90Smillert - Threads 12879cd0b9aSmillert BUGS 129ba47ec9dSmillert AUTHOR 130ba47ec9dSmillert SEE ALSO 131ba47ec9dSmillert 132ba47ec9dSmillert=head1 DESCRIPTION 133ba47ec9dSmillert 134ba47ec9dSmillert=head2 Target 135ba47ec9dSmillert 13679cd0b9aSmillertThe target is to make OS/2 one of the best supported platform for 137ba47ec9dSmillertusing/building/developing Perl and I<Perl applications>, as well as 138ba47ec9dSmillertmake Perl the best language to use under OS/2. The secondary target is 139ba47ec9dSmillertto try to make this work under DOS and Win* as well (but not B<too> hard). 140ba47ec9dSmillert 141ba47ec9dSmillertThe current state is quite close to this target. Known limitations: 142ba47ec9dSmillert 143ba47ec9dSmillert=over 5 144ba47ec9dSmillert 145ba47ec9dSmillert=item * 146ba47ec9dSmillert 14779cd0b9aSmillertSome *nix programs use fork() a lot; with the mostly useful flavors of 14879cd0b9aSmillertperl for OS/2 (there are several built simultaneously) this is 14979cd0b9aSmillertsupported; but some flavors do not support this (e.g., when Perl is 15079cd0b9aSmillertcalled from inside REXX). Using fork() after 15179cd0b9aSmillertI<use>ing dynamically loading extensions would not work with I<very> old 15279cd0b9aSmillertversions of EMX. 153ba47ec9dSmillert 154ba47ec9dSmillert=item * 155ba47ec9dSmillert 15648950c12SsthenYou need a separate perl executable F<perl__.exe> (see L</perl__.exe>) 157c5dcfd37Smillertif you want to use PM code in your application (as Perl/Tk or OpenGL 158c5dcfd37SmillertPerl modules do) without having a text-mode window present. 159c5dcfd37Smillert 160c5dcfd37SmillertWhile using the standard F<perl.exe> from a text-mode window is possible 161c5dcfd37Smillerttoo, I have seen cases when this causes degradation of the system stability. 162c5dcfd37SmillertUsing F<perl__.exe> avoids such a degradation. 163ba47ec9dSmillert 164ba47ec9dSmillert=item * 165ba47ec9dSmillert 166ba47ec9dSmillertThere is no simple way to access WPS objects. The only way I know 16748950c12Ssthenis via C<OS2::REXX> and C<SOM> extensions (see L<OS2::REXX>, L<SOM>). 16879cd0b9aSmillertHowever, we do not have access to 169ba47ec9dSmillertconvenience methods of Object-REXX. (Is it possible at all? I know 170c5dcfd37Smillertof no Object-REXX API.) The C<SOM> extension (currently in alpha-text) 17179cd0b9aSmillertmay eventually remove this shortcoming; however, due to the fact that 17279cd0b9aSmillertDII is not supported by the C<SOM> module, using C<SOM> is not as 17379cd0b9aSmillertconvenient as one would like it. 174ba47ec9dSmillert 175ba47ec9dSmillert=back 176ba47ec9dSmillert 177ba47ec9dSmillertPlease keep this list up-to-date by informing me about other items. 178ba47ec9dSmillert 179ba47ec9dSmillert=head2 Other OSes 180ba47ec9dSmillert 181ba47ec9dSmillertSince OS/2 port of perl uses a remarkable EMX environment, it can 182c5dcfd37Smillertrun (and build extensions, and - possibly - be built itself) under any 183ba47ec9dSmillertenvironment which can run EMX. The current list is DOS, 184ba47ec9dSmillertDOS-inside-OS/2, Win0.3*, Win0.95 and WinNT. Out of many perl flavors, 1859f11ffb7Safresh1only one works, see L</"F<perl_.exe>">. 186ba47ec9dSmillert 187ba47ec9dSmillertNote that not all features of Perl are available under these 188ba47ec9dSmillertenvironments. This depends on the features the I<extender> - most 189ba47ec9dSmillertprobably RSX - decided to implement. 190ba47ec9dSmillert 19148950c12SsthenCf. L</Prerequisites>. 192ba47ec9dSmillert 193ba47ec9dSmillert=head2 Prerequisites 194ba47ec9dSmillert 195ba47ec9dSmillert=over 6 196ba47ec9dSmillert 197ba47ec9dSmillert=item EMX 198ba47ec9dSmillert 199ba47ec9dSmillertEMX runtime is required (may be substituted by RSX). Note that 200ba47ec9dSmillertit is possible to make F<perl_.exe> to run under DOS without any 201eac174f2Safresh1external support by binding F<emx.exe>/F<rsx.exe> to it, see L<emxbind(1)>. 202eac174f2Safresh1Note that under DOS for best results one should use RSX runtime, which 203ba47ec9dSmillerthas much more functions working (like C<fork>, C<popen> and so on). In 204ba47ec9dSmillertfact RSX is required if there is no VCPI present. Note the 20579cd0b9aSmillertRSX requires DPMI. Many implementations of DPMI are known to be very 20679cd0b9aSmillertbuggy, beware! 207ba47ec9dSmillert 208c5dcfd37SmillertOnly the latest runtime is supported, currently C<0.9d fix 03>. Perl may run 209ba47ec9dSmillertunder earlier versions of EMX, but this is not tested. 210ba47ec9dSmillert 211ba47ec9dSmillertOne can get different parts of EMX from, say 212ba47ec9dSmillert 2130dc2eaceSmillert ftp://crydee.sai.msu.ru/pub/comp/os/os2/leo/gnu/emx+gcc/ 2140dc2eaceSmillert http://hobbes.nmsu.edu/h-browse.php?dir=/pub/os2/dev/emx/v0.9d/ 215ba47ec9dSmillert 216ba47ec9dSmillertThe runtime component should have the name F<emxrt.zip>. 217ba47ec9dSmillert 21879cd0b9aSmillertB<NOTE>. When using F<emx.exe>/F<rsx.exe>, it is enough to have them on your path. One 219ba47ec9dSmillertdoes not need to specify them explicitly (though this 220ba47ec9dSmillert 221ba47ec9dSmillert emx perl_.exe -de 0 222ba47ec9dSmillert 223ba47ec9dSmillertwill work as well.) 224ba47ec9dSmillert 225ba47ec9dSmillert=item RSX 226ba47ec9dSmillert 227ba47ec9dSmillertTo run Perl on DPMI platforms one needs RSX runtime. This is 228ba47ec9dSmillertneeded under DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT (see 2299f11ffb7Safresh1L</"Other OSes">). RSX would not work with VCPI 230ba47ec9dSmillertonly, as EMX would, it requires DMPI. 231ba47ec9dSmillert 232ba47ec9dSmillertHaving RSX and the latest F<sh.exe> one gets a fully functional 233ba47ec9dSmillertB<*nix>-ish environment under DOS, say, C<fork>, C<``> and 234ba47ec9dSmillertpipe-C<open> work. In fact, MakeMaker works (for static build), so one 235ba47ec9dSmillertcan have Perl development environment under DOS. 236ba47ec9dSmillert 237ba47ec9dSmillertOne can get RSX from, say 238ba47ec9dSmillert 2390dc2eaceSmillert http://cd.textfiles.com/hobbesos29804/disk1/EMX09C/ 2400dc2eaceSmillert ftp://crydee.sai.msu.ru/pub/comp/os/os2/leo/gnu/emx+gcc/contrib/ 241ba47ec9dSmillert 242ba47ec9dSmillertContact the author on C<rainer@mathematik.uni-bielefeld.de>. 243ba47ec9dSmillert 244c5dcfd37SmillertThe latest F<sh.exe> with DOS hooks is available in 245ba47ec9dSmillert 24679cd0b9aSmillert http://www.ilyaz.org/software/os2/ 247c5dcfd37Smillert 248c5dcfd37Smillertas F<sh_dos.zip> or under similar names starting with C<sh>, C<pdksh> etc. 249ba47ec9dSmillert 250ba47ec9dSmillert=item HPFS 251ba47ec9dSmillert 25279cd0b9aSmillertPerl does not care about file systems, but the perl library contains 25379cd0b9aSmillertmany files with long names, so to install it intact one needs a file 25479cd0b9aSmillertsystem which supports long file names. 255ba47ec9dSmillert 256ba47ec9dSmillertNote that if you do not plan to build the perl itself, it may be 257ba47ec9dSmillertpossible to fool EMX to truncate file names. This is not supported, 258ba47ec9dSmillertread EMX docs to see how to do it. 259ba47ec9dSmillert 260ba47ec9dSmillert=item pdksh 261ba47ec9dSmillert 262ba47ec9dSmillertTo start external programs with complicated command lines (like with 263ba47ec9dSmillertpipes in between, and/or quoting of arguments), Perl uses an external 264c5dcfd37Smillertshell. With EMX port such shell should be named F<sh.exe>, and located 265ba47ec9dSmillerteither in the wired-in-during-compile locations (usually F<F:/bin>), 2669f11ffb7Safresh1or in configurable location (see L</"C<PERL_SH_DIR>">). 267ba47ec9dSmillert 268c5dcfd37SmillertFor best results use EMX pdksh. The standard binary (5.2.14 or later) runs 26948950c12Ssthenunder DOS (with L</RSX>) as well, see 270ba47ec9dSmillert 27179cd0b9aSmillert http://www.ilyaz.org/software/os2/ 272ba47ec9dSmillert 273ba47ec9dSmillert=back 274ba47ec9dSmillert 275ba47ec9dSmillert=head2 Starting Perl programs under OS/2 (and DOS and...) 276ba47ec9dSmillert 277ba47ec9dSmillertStart your Perl program F<foo.pl> with arguments C<arg1 arg2 arg3> the 278ba47ec9dSmillertsame way as on any other platform, by 279ba47ec9dSmillert 280ba47ec9dSmillert perl foo.pl arg1 arg2 arg3 281ba47ec9dSmillert 282ba47ec9dSmillertIf you want to specify perl options C<-my_opts> to the perl itself (as 28379cd0b9aSmillertopposed to your program), use 284ba47ec9dSmillert 285ba47ec9dSmillert perl -my_opts foo.pl arg1 arg2 arg3 286ba47ec9dSmillert 287ba47ec9dSmillertAlternately, if you use OS/2-ish shell, like CMD or 4os2, put 288ba47ec9dSmillertthe following at the start of your perl script: 289ba47ec9dSmillert 290ba47ec9dSmillert extproc perl -S -my_opts 291ba47ec9dSmillert 292ba47ec9dSmillertrename your program to F<foo.cmd>, and start it by typing 293ba47ec9dSmillert 294ba47ec9dSmillert foo arg1 arg2 arg3 295ba47ec9dSmillert 296ba47ec9dSmillertNote that because of stupid OS/2 limitations the full path of the perl 297ba47ec9dSmillertscript is not available when you use C<extproc>, thus you are forced to 298c5dcfd37Smillertuse C<-S> perl switch, and your script should be on the C<PATH>. As a plus 299ba47ec9dSmillertside, if you know a full path to your script, you may still start it 300ba47ec9dSmillertwith 301ba47ec9dSmillert 302ba47ec9dSmillert perl ../../blah/foo.cmd arg1 arg2 arg3 303ba47ec9dSmillert 304ba47ec9dSmillert(note that the argument C<-my_opts> is taken care of by the C<extproc> line 305eac174f2Safresh1in your script, see C<L</extproc>> on the first line). 306ba47ec9dSmillert 307ba47ec9dSmillertTo understand what the above I<magic> does, read perl docs about C<-S> 308ba47ec9dSmillertswitch - see L<perlrun>, and cmdref about C<extproc>: 309ba47ec9dSmillert 310ba47ec9dSmillert view perl perlrun 311ba47ec9dSmillert man perlrun 312ba47ec9dSmillert view cmdref extproc 313ba47ec9dSmillert help extproc 314ba47ec9dSmillert 315ba47ec9dSmillertor whatever method you prefer. 316ba47ec9dSmillert 317ba47ec9dSmillertThere are also endless possibilities to use I<executable extensions> of 318ba47ec9dSmillert4os2, I<associations> of WPS and so on... However, if you use 319ba47ec9dSmillert*nixish shell (like F<sh.exe> supplied in the binary distribution), 32048950c12Ssthenyou need to follow the syntax specified in L<perlrun/"Command Switches">. 321ba47ec9dSmillert 32279cd0b9aSmillertNote that B<-S> switch supports scripts with additional extensions 323ba47ec9dSmillertF<.cmd>, F<.btm>, F<.bat>, F<.pl> as well. 324ba47ec9dSmillert 325ba47ec9dSmillert=head2 Starting OS/2 (and DOS) programs under Perl 326ba47ec9dSmillert 327ba47ec9dSmillertThis is what system() (see L<perlfunc/system>), C<``> (see 328ba47ec9dSmillertL<perlop/"I/O Operators">), and I<open pipe> (see L<perlfunc/open>) 329ba47ec9dSmillertare for. (Avoid exec() (see L<perlfunc/exec>) unless you know what you 330ba47ec9dSmillertdo). 331ba47ec9dSmillert 332ba47ec9dSmillertNote however that to use some of these operators you need to have a 3339f11ffb7Safresh1sh-syntax shell installed (see L</"Pdksh">, 3349f11ffb7Safresh1L</"Frequently asked questions">), and perl should be able to find it 3359f11ffb7Safresh1(see L</"C<PERL_SH_DIR>">). 336ba47ec9dSmillert 3376345ca90SmillertThe cases when the shell is used are: 3386345ca90Smillert 3396345ca90Smillert=over 3406345ca90Smillert 3416345ca90Smillert=item 1 3426345ca90Smillert 3436345ca90SmillertOne-argument system() (see L<perlfunc/system>), exec() (see L<perlfunc/exec>) 3446345ca90Smillertwith redirection or shell meta-characters; 3456345ca90Smillert 3466345ca90Smillert=item 2 3476345ca90Smillert 3486345ca90SmillertPipe-open (see L<perlfunc/open>) with the command which contains redirection 3496345ca90Smillertor shell meta-characters; 3506345ca90Smillert 3516345ca90Smillert=item 3 3526345ca90Smillert 3536345ca90SmillertBackticks C<``> (see L<perlop/"I/O Operators">) with the command which contains 3546345ca90Smillertredirection or shell meta-characters; 3556345ca90Smillert 3566345ca90Smillert=item 4 3576345ca90Smillert 3586345ca90SmillertIf the executable called by system()/exec()/pipe-open()/C<``> is a script 3596345ca90Smillertwith the "magic" C<#!> line or C<extproc> line which specifies shell; 3606345ca90Smillert 3616345ca90Smillert=item 5 3626345ca90Smillert 3636345ca90SmillertIf the executable called by system()/exec()/pipe-open()/C<``> is a script 3646345ca90Smillertwithout "magic" line, and C<$ENV{EXECSHELL}> is set to shell; 3656345ca90Smillert 3666345ca90Smillert=item 6 3676345ca90Smillert 3686345ca90SmillertIf the executable called by system()/exec()/pipe-open()/C<``> is not 36979cd0b9aSmillertfound (is not this remark obsolete?); 3706345ca90Smillert 3716345ca90Smillert=item 7 3726345ca90Smillert 37379cd0b9aSmillertFor globbing (see L<perlfunc/glob>, L<perlop/"I/O Operators">) 37479cd0b9aSmillert(obsolete? Perl uses builtin globbing nowadays...). 3756345ca90Smillert 3766345ca90Smillert=back 3776345ca90Smillert 3786345ca90SmillertFor the sake of speed for a common case, in the above algorithms 3796345ca90Smillertbackslashes in the command name are not considered as shell metacharacters. 3806345ca90Smillert 3816345ca90SmillertPerl starts scripts which begin with cookies 3826345ca90SmillertC<extproc> or C<#!> directly, without an intervention of shell. Perl uses the 3836345ca90Smillertsame algorithm to find the executable as F<pdksh>: if the path 38479cd0b9aSmillerton C<#!> line does not work, and contains C</>, then the directory 38579cd0b9aSmillertpart of the executable is ignored, and the executable 3866345ca90Smillertis searched in F<.> and on C<PATH>. To find arguments for these scripts 3876345ca90SmillertPerl uses a different algorithm than F<pdksh>: up to 3 arguments are 3886345ca90Smillertrecognized, and trailing whitespace is stripped. 3896345ca90Smillert 3906345ca90SmillertIf a script 3916345ca90Smillertdoes not contain such a cooky, then to avoid calling F<sh.exe>, Perl uses 3926345ca90Smillertthe same algorithm as F<pdksh>: if C<$ENV{EXECSHELL}> is set, the 3936345ca90Smillertscript is given as the first argument to this command, if not set, then 3946345ca90SmillertC<$ENV{COMSPEC} /c> is used (or a hardwired guess if C<$ENV{COMSPEC}> is 3956345ca90Smillertnot set). 3966345ca90Smillert 39779cd0b9aSmillertWhen starting scripts directly, Perl uses exactly the same algorithm as for 3986345ca90Smillertthe search of script given by B<-S> command-line option: it will look in 3996345ca90Smillertthe current directory, then on components of C<$ENV{PATH}> using the 4006345ca90Smillertfollowing order of appended extensions: no extension, F<.cmd>, F<.btm>, 4016345ca90SmillertF<.bat>, F<.pl>. 4026345ca90Smillert 4036345ca90SmillertNote that Perl will start to look for scripts only if OS/2 cannot start the 4046345ca90Smillertspecified application, thus C<system 'blah'> will not look for a script if 40579cd0b9aSmillertthere is an executable file F<blah.exe> I<anywhere> on C<PATH>. In 40679cd0b9aSmillertother words, C<PATH> is essentially searched twice: once by the OS for 40779cd0b9aSmillertan executable, then by Perl for scripts. 4086345ca90Smillert 409e5157e49Safresh1Note also that executable files on OS/2 can have an arbitrary extension, but 410e5157e49Safresh1F<.exe> will be automatically appended if no dot is present in the name. The 411e5157e49Safresh1workaround is as simple as that: since F<blah.> and F<blah> denote the same 412e5157e49Safresh1file (at list on FAT and HPFS file systems), to start an executable residing in 413e5157e49Safresh1file F<n:/bin/blah> (no extension) give an argument C<n:/bin/blah.> (dot 414e5157e49Safresh1appended) to system(). 4156345ca90Smillert 41679cd0b9aSmillertPerl will start PM programs from VIO (=text-mode) Perl process in a 41779cd0b9aSmillertseparate PM session; 418c5dcfd37Smillertthe opposite is not true: when you start a non-PM program from a PM 41979cd0b9aSmillertPerl process, Perl would not run it in a separate session. If a separate 420c5dcfd37Smillertsession is desired, either ensure 421c5dcfd37Smillertthat shell will be used, as in C<system 'cmd /c myprog'>, or start it using 4226345ca90Smillertoptional arguments to system() documented in C<OS2::Process> module. This 423c5dcfd37Smillertis considered to be a feature. 424ba47ec9dSmillert 425ba47ec9dSmillert=head1 Frequently asked questions 426ba47ec9dSmillert 427c5dcfd37Smillert=head2 "It does not work" 428c5dcfd37Smillert 429c5dcfd37SmillertPerl binary distributions come with a F<testperl.cmd> script which tries 430c5dcfd37Smillertto detect common problems with misconfigured installations. There is a 431c5dcfd37Smillertpretty large chance it will discover which step of the installation you 432c5dcfd37Smillertmanaged to goof. C<;-)> 433c5dcfd37Smillert 434ba47ec9dSmillert=head2 I cannot run external programs 435ba47ec9dSmillert 436ba47ec9dSmillert=over 4 437ba47ec9dSmillert 438c5dcfd37Smillert=item * 439ba47ec9dSmillert 440ba47ec9dSmillertDid you run your programs with C<-w> switch? See 44156d68f1eSafresh1L</Starting OSE<sol>2 (and DOS) programs under Perl>. 442ba47ec9dSmillert 443c5dcfd37Smillert=item * 444ba47ec9dSmillert 445ba47ec9dSmillertDo you try to run I<internal> shell commands, like C<`copy a b`> 446ba47ec9dSmillert(internal for F<cmd.exe>), or C<`glob a*b`> (internal for ksh)? You 447ba47ec9dSmillertneed to specify your shell explicitly, like C<`cmd /c copy a b`>, 448ba47ec9dSmillertsince Perl cannot deduce which commands are internal to your shell. 449ba47ec9dSmillert 450ba47ec9dSmillert=back 451ba47ec9dSmillert 452ba47ec9dSmillert=head2 I cannot embed perl into my program, or use F<perl.dll> from my 453ba47ec9dSmillertprogram. 454ba47ec9dSmillert 455ba47ec9dSmillert=over 4 456ba47ec9dSmillert 457ba47ec9dSmillert=item Is your program EMX-compiled with C<-Zmt -Zcrtdll>? 458ba47ec9dSmillert 45979cd0b9aSmillertWell, nowadays Perl DLL should be usable from a differently compiled 46079cd0b9aSmillertprogram too... If you can run Perl code from REXX scripts (see 46179cd0b9aSmillertL<OS2::REXX>), then there are some other aspect of interaction which 46279cd0b9aSmillertare overlooked by the current hackish code to support 46379cd0b9aSmillertdifferently-compiled principal programs. 46479cd0b9aSmillert 46579cd0b9aSmillertIf everything else fails, you need to build a stand-alone DLL for 46679cd0b9aSmillertperl. Contact me, I did it once. Sockets would not work, as a lot of 46779cd0b9aSmillertother stuff. 468ba47ec9dSmillert 469ba47ec9dSmillert=item Did you use L<ExtUtils::Embed>? 470ba47ec9dSmillert 47179cd0b9aSmillertSome time ago I had reports it does not work. Nowadays it is checked 47279cd0b9aSmillertin the Perl test suite, so grep F<./t> subdirectory of the build tree 47379cd0b9aSmillert(as well as F<*.t> files in the F<./lib> subdirectory) to find how it 47479cd0b9aSmillertshould be done "correctly". 475ba47ec9dSmillert 476ba47ec9dSmillert=back 477ba47ec9dSmillert 478ba47ec9dSmillert=head2 C<``> and pipe-C<open> do not work under DOS. 479ba47ec9dSmillert 4809f11ffb7Safresh1This may a variant of just L</"I cannot run external programs">, or a 48148950c12Ssthendeeper problem. Basically: you I<need> RSX (see L</Prerequisites>) 482ba47ec9dSmillertfor these commands to work, and you may need a port of F<sh.exe> which 483ba47ec9dSmillertunderstands command arguments. One of such ports is listed in 48448950c12SsthenL</Prerequisites> under RSX. Do not forget to set variable 4859f11ffb7Safresh1L</"C<PERL_SH_DIR>"> as well. 486ba47ec9dSmillert 487ba47ec9dSmillertDPMI is required for RSX. 488ba47ec9dSmillert 489ba47ec9dSmillert=head2 Cannot start C<find.exe "pattern" file> 490ba47ec9dSmillert 49179cd0b9aSmillertThe whole idea of the "standard C API to start applications" is that 49279cd0b9aSmillertthe forms C<foo> and C<"foo"> of program arguments are completely 49348950c12Sstheninterchangeable. F<find> breaks this paradigm; 49479cd0b9aSmillert 49579cd0b9aSmillert find "pattern" file 49679cd0b9aSmillert find pattern file 49779cd0b9aSmillert 49879cd0b9aSmillertare not equivalent; F<find> cannot be started directly using the above 49979cd0b9aSmillertAPI. One needs a way to surround the doublequotes in some other 50079cd0b9aSmillertquoting construction, necessarily having an extra non-Unixish shell in 50179cd0b9aSmillertbetween. 50279cd0b9aSmillert 503ba47ec9dSmillertUse one of 504ba47ec9dSmillert 505ba47ec9dSmillert system 'cmd', '/c', 'find "pattern" file'; 506ba47ec9dSmillert `cmd /c 'find "pattern" file'` 507ba47ec9dSmillert 508ba47ec9dSmillertThis would start F<find.exe> via F<cmd.exe> via C<sh.exe> via 509ba47ec9dSmillertC<perl.exe>, but this is a price to pay if you want to use 51079cd0b9aSmillertnon-conforming program. 511ba47ec9dSmillert 512ba47ec9dSmillert=head1 INSTALLATION 513ba47ec9dSmillert 514ba47ec9dSmillert=head2 Automatic binary installation 515ba47ec9dSmillert 516c5dcfd37SmillertThe most convenient way of installing a binary distribution of perl is via perl installer 517ba47ec9dSmillertF<install.exe>. Just follow the instructions, and 99% of the 518ba47ec9dSmillertinstallation blues would go away. 519ba47ec9dSmillert 520ba47ec9dSmillertNote however, that you need to have F<unzip.exe> on your path, and 521ba47ec9dSmillertEMX environment I<running>. The latter means that if you just 522ba47ec9dSmillertinstalled EMX, and made all the needed changes to F<Config.sys>, 523ba47ec9dSmillertyou may need to reboot in between. Check EMX runtime by running 524ba47ec9dSmillert 525ba47ec9dSmillert emxrev 526ba47ec9dSmillert 52779cd0b9aSmillertBinary installer also creates a folder on your desktop with some useful 52879cd0b9aSmillertobjects. If you need to change some aspects of the work of the binary 52979cd0b9aSmillertinstaller, feel free to edit the file F<Perl.pkg>. This may be useful 53079cd0b9aSmillerte.g., if you need to run the installer many times and do not want to 53179cd0b9aSmillertmake many interactive changes in the GUI. 532ba47ec9dSmillert 533ba47ec9dSmillertB<Things not taken care of by automatic binary installation:> 534ba47ec9dSmillert 535ba47ec9dSmillert=over 15 536ba47ec9dSmillert 537ba47ec9dSmillert=item C<PERL_BADLANG> 538ba47ec9dSmillert 539ba47ec9dSmillertmay be needed if you change your codepage I<after> perl installation, 5409f11ffb7Safresh1and the new value is not supported by EMX. See L</"C<PERL_BADLANG>">. 541ba47ec9dSmillert 542ba47ec9dSmillert=item C<PERL_BADFREE> 543ba47ec9dSmillert 5449f11ffb7Safresh1see L</"C<PERL_BADFREE>">. 545ba47ec9dSmillert 546ba47ec9dSmillert=item F<Config.pm> 547ba47ec9dSmillert 548ba47ec9dSmillertThis file resides somewhere deep in the location you installed your 549ba47ec9dSmillertperl library, find it out by 550ba47ec9dSmillert 551ba47ec9dSmillert perl -MConfig -le "print $INC{'Config.pm'}" 552ba47ec9dSmillert 553ba47ec9dSmillertWhile most important values in this file I<are> updated by the binary 554ba47ec9dSmillertinstaller, some of them may need to be hand-edited. I know no such 55579cd0b9aSmillertdata, please keep me informed if you find one. Moreover, manual 55679cd0b9aSmillertchanges to the installed version may need to be accompanied by an edit 55779cd0b9aSmillertof this file. 558ba47ec9dSmillert 559ba47ec9dSmillert=back 560ba47ec9dSmillert 561ba47ec9dSmillertB<NOTE>. Because of a typo the binary installer of 5.00305 562ba47ec9dSmillertwould install a variable C<PERL_SHPATH> into F<Config.sys>. Please 563eac174f2Safresh1remove this variable and put C<L</PERL_SH_DIR>> instead. 564ba47ec9dSmillert 565ba47ec9dSmillert=head2 Manual binary installation 566ba47ec9dSmillert 567ba47ec9dSmillertAs of version 5.00305, OS/2 perl binary distribution comes split 568ba47ec9dSmillertinto 11 components. Unfortunately, to enable configurable binary 569ba47ec9dSmillertinstallation, the file paths in the zip files are not absolute, but 570ba47ec9dSmillertrelative to some directory. 571ba47ec9dSmillert 572ba47ec9dSmillertNote that the extraction with the stored paths is still necessary 573ba47ec9dSmillert(default with unzip, specify C<-d> to pkunzip). However, you 574ba47ec9dSmillertneed to know where to extract the files. You need also to manually 575ba47ec9dSmillertchange entries in F<Config.sys> to reflect where did you put the 576ba47ec9dSmillertfiles. Note that if you have some primitive unzipper (like 57779cd0b9aSmillertC<pkunzip>), you may get a lot of warnings/errors during 578ba47ec9dSmillertunzipping. Upgrade to C<(w)unzip>. 579ba47ec9dSmillert 580ba47ec9dSmillertBelow is the sample of what to do to reproduce the configuration on my 58179cd0b9aSmillertmachine. In F<VIEW.EXE> you can press C<Ctrl-Insert> now, and 58279cd0b9aSmillertcut-and-paste from the resulting file - created in the directory you 58379cd0b9aSmillertstarted F<VIEW.EXE> from. 58479cd0b9aSmillert 58579cd0b9aSmillertFor each component, we mention environment variables related to each 58679cd0b9aSmillertinstallation directory. Either choose directories to match your 58779cd0b9aSmillertvalues of the variables, or create/append-to variables to take into 58879cd0b9aSmillertaccount the directories. 589ba47ec9dSmillert 590ba47ec9dSmillert=over 3 591ba47ec9dSmillert 592ba47ec9dSmillert=item Perl VIO and PM executables (dynamically linked) 593ba47ec9dSmillert 594ba47ec9dSmillert unzip perl_exc.zip *.exe *.ico -d f:/emx.add/bin 595ba47ec9dSmillert unzip perl_exc.zip *.dll -d f:/emx.add/dll 596ba47ec9dSmillert 597ba47ec9dSmillert(have the directories with C<*.exe> on PATH, and C<*.dll> on 598ba47ec9dSmillertLIBPATH); 599ba47ec9dSmillert 600ba47ec9dSmillert=item Perl_ VIO executable (statically linked) 601ba47ec9dSmillert 602ba47ec9dSmillert unzip perl_aou.zip -d f:/emx.add/bin 603ba47ec9dSmillert 604ba47ec9dSmillert(have the directory on PATH); 605ba47ec9dSmillert 606ba47ec9dSmillert=item Executables for Perl utilities 607ba47ec9dSmillert 608ba47ec9dSmillert unzip perl_utl.zip -d f:/emx.add/bin 609ba47ec9dSmillert 610ba47ec9dSmillert(have the directory on PATH); 611ba47ec9dSmillert 612ba47ec9dSmillert=item Main Perl library 613ba47ec9dSmillert 614ba47ec9dSmillert unzip perl_mlb.zip -d f:/perllib/lib 615ba47ec9dSmillert 616c5dcfd37SmillertIf this directory is exactly the same as the prefix which was compiled 617c5dcfd37Smillertinto F<perl.exe>, you do not need to change 618c5dcfd37Smillertanything. However, for perl to find the library if you use a different 619c5dcfd37Smillertpath, you need to 6209f11ffb7Safresh1C<set PERLLIB_PREFIX> in F<Config.sys>, see L</"C<PERLLIB_PREFIX>">. 621ba47ec9dSmillert 622ba47ec9dSmillert=item Additional Perl modules 623ba47ec9dSmillert 624*e0680481Safresh1 unzip perl_ste.zip -d f:/perllib/lib/site_perl/5.38.2/ 625ba47ec9dSmillert 626c5dcfd37SmillertSame remark as above applies. Additionally, if this directory is not 627c5dcfd37Smillertone of directories on @INC (and @INC is influenced by C<PERLLIB_PREFIX>), you 628c5dcfd37Smillertneed to put this 629ba47ec9dSmillertdirectory and subdirectory F<./os2> in C<PERLLIB> or C<PERL5LIB> 630ba47ec9dSmillertvariable. Do not use C<PERL5LIB> unless you have it set already. See 631ba47ec9dSmillertL<perl/"ENVIRONMENT">. 632ba47ec9dSmillert 63379cd0b9aSmillertB<[Check whether this extraction directory is still applicable with 63479cd0b9aSmillertthe new directory structure layout!]> 63579cd0b9aSmillert 636ba47ec9dSmillert=item Tools to compile Perl modules 637ba47ec9dSmillert 638ba47ec9dSmillert unzip perl_blb.zip -d f:/perllib/lib 639ba47ec9dSmillert 640c5dcfd37SmillertSame remark as for F<perl_ste.zip>. 641ba47ec9dSmillert 642ba47ec9dSmillert=item Manpages for Perl and utilities 643ba47ec9dSmillert 644ba47ec9dSmillert unzip perl_man.zip -d f:/perllib/man 645ba47ec9dSmillert 646ba47ec9dSmillertThis directory should better be on C<MANPATH>. You need to have a 64779cd0b9aSmillertworking F<man> to access these files. 648ba47ec9dSmillert 649ba47ec9dSmillert=item Manpages for Perl modules 650ba47ec9dSmillert 651ba47ec9dSmillert unzip perl_mam.zip -d f:/perllib/man 652ba47ec9dSmillert 653ba47ec9dSmillertThis directory should better be on C<MANPATH>. You need to have a 654ba47ec9dSmillertworking man to access these files. 655ba47ec9dSmillert 656ba47ec9dSmillert=item Source for Perl documentation 657ba47ec9dSmillert 658ba47ec9dSmillert unzip perl_pod.zip -d f:/perllib/lib 659ba47ec9dSmillert 660c5dcfd37SmillertThis is used by the C<perldoc> program (see L<perldoc>), and may be used to 661ba47ec9dSmillertgenerate HTML documentation usable by WWW browsers, and 662ba47ec9dSmillertdocumentation in zillions of other formats: C<info>, C<LaTeX>, 66379cd0b9aSmillertC<Acrobat>, C<FrameMaker> and so on. [Use programs such as 66479cd0b9aSmillertF<pod2latex> etc.] 665ba47ec9dSmillert 666ba47ec9dSmillert=item Perl manual in F<.INF> format 667ba47ec9dSmillert 668ba47ec9dSmillert unzip perl_inf.zip -d d:/os2/book 669ba47ec9dSmillert 670ba47ec9dSmillertThis directory should better be on C<BOOKSHELF>. 671ba47ec9dSmillert 672ba47ec9dSmillert=item Pdksh 673ba47ec9dSmillert 674ba47ec9dSmillert unzip perl_sh.zip -d f:/bin 675ba47ec9dSmillert 676ba47ec9dSmillertThis is used by perl to run external commands which explicitly 677ba47ec9dSmillertrequire shell, like the commands using I<redirection> and I<shell 678ba47ec9dSmillertmetacharacters>. It is also used instead of explicit F</bin/sh>. 679ba47ec9dSmillert 6809f11ffb7Safresh1Set C<PERL_SH_DIR> (see L</"C<PERL_SH_DIR>">) if you move F<sh.exe> from 681ba47ec9dSmillertthe above location. 682ba47ec9dSmillert 68379cd0b9aSmillertB<Note.> It may be possible to use some other sh-compatible shell (untested). 684ba47ec9dSmillert 685ba47ec9dSmillert=back 686ba47ec9dSmillert 687ba47ec9dSmillertAfter you installed the components you needed and updated the 688ba47ec9dSmillertF<Config.sys> correspondingly, you need to hand-edit 689ba47ec9dSmillertF<Config.pm>. This file resides somewhere deep in the location you 690ba47ec9dSmillertinstalled your perl library, find it out by 691ba47ec9dSmillert 692ba47ec9dSmillert perl -MConfig -le "print $INC{'Config.pm'}" 693ba47ec9dSmillert 694ba47ec9dSmillertYou need to correct all the entries which look like file paths (they 695ba47ec9dSmillertcurrently start with C<f:/>). 696ba47ec9dSmillert 697ba47ec9dSmillert=head2 B<Warning> 698ba47ec9dSmillert 699ba47ec9dSmillertThe automatic and manual perl installation leave precompiled paths 700b46d8ef2Safresh1inside perl executables. While these paths are overwritable (see 7019f11ffb7Safresh1L</"C<PERLLIB_PREFIX>">, L</"C<PERL_SH_DIR>">), some people may prefer 702ba47ec9dSmillertbinary editing of paths inside the executables/DLLs. 703ba47ec9dSmillert 704ba47ec9dSmillert=head1 Accessing documentation 705ba47ec9dSmillert 706ba47ec9dSmillertDepending on how you built/installed perl you may have (otherwise 707ba47ec9dSmillertidentical) Perl documentation in the following formats: 708ba47ec9dSmillert 709ba47ec9dSmillert=head2 OS/2 F<.INF> file 710ba47ec9dSmillert 711ba47ec9dSmillertMost probably the most convenient form. Under OS/2 view it as 712ba47ec9dSmillert 713ba47ec9dSmillert view perl 714ba47ec9dSmillert view perl perlfunc 715ba47ec9dSmillert view perl less 716ba47ec9dSmillert view perl ExtUtils::MakeMaker 717ba47ec9dSmillert 718ba47ec9dSmillert(currently the last two may hit a wrong location, but this may improve 7199f11ffb7Safresh1soon). Under Win* see L</"SYNOPSIS">. 720ba47ec9dSmillert 721ba47ec9dSmillertIf you want to build the docs yourself, and have I<OS/2 toolkit>, run 722ba47ec9dSmillert 723ba47ec9dSmillert pod2ipf > perl.ipf 724ba47ec9dSmillert 725ba47ec9dSmillertin F</perllib/lib/pod> directory, then 726ba47ec9dSmillert 727ba47ec9dSmillert ipfc /inf perl.ipf 728ba47ec9dSmillert 729ba47ec9dSmillert(Expect a lot of errors during the both steps.) Now move it on your 730ba47ec9dSmillertBOOKSHELF path. 731ba47ec9dSmillert 732ba47ec9dSmillert=head2 Plain text 733ba47ec9dSmillert 734ba47ec9dSmillertIf you have perl documentation in the source form, perl utilities 735ba47ec9dSmillertinstalled, and GNU groff installed, you may use 736ba47ec9dSmillert 737ba47ec9dSmillert perldoc perlfunc 738ba47ec9dSmillert perldoc less 739ba47ec9dSmillert perldoc ExtUtils::MakeMaker 740ba47ec9dSmillert 741ba47ec9dSmillertto access the perl documentation in the text form (note that you may get 742ba47ec9dSmillertbetter results using perl manpages). 743ba47ec9dSmillert 744ba47ec9dSmillertAlternately, try running pod2text on F<.pod> files. 745ba47ec9dSmillert 746ba47ec9dSmillert=head2 Manpages 747ba47ec9dSmillert 74879cd0b9aSmillertIf you have F<man> installed on your system, and you installed perl 749ba47ec9dSmillertmanpages, use something like this: 750ba47ec9dSmillert 751ba47ec9dSmillert man perlfunc 752ba47ec9dSmillert man 3 less 753ba47ec9dSmillert man ExtUtils.MakeMaker 754ba47ec9dSmillert 755ba47ec9dSmillertto access documentation for different components of Perl. Start with 756ba47ec9dSmillert 757ba47ec9dSmillert man perl 758ba47ec9dSmillert 759ba47ec9dSmillertNote that dot (F<.>) is used as a package separator for documentation 760ba47ec9dSmillertfor packages, and as usual, sometimes you need to give the section - C<3> 761ba47ec9dSmillertabove - to avoid shadowing by the I<less(1) manpage>. 762ba47ec9dSmillert 763ba47ec9dSmillertMake sure that the directory B<above> the directory with manpages is 764ba47ec9dSmillerton our C<MANPATH>, like this 765ba47ec9dSmillert 766ba47ec9dSmillert set MANPATH=c:/man;f:/perllib/man 767ba47ec9dSmillert 768c5dcfd37Smillertfor Perl manpages in C<f:/perllib/man/man1/> etc. 769c5dcfd37Smillert 770ba47ec9dSmillert=head2 HTML 771ba47ec9dSmillert 772ba47ec9dSmillertIf you have some WWW browser available, installed the Perl 773ba47ec9dSmillertdocumentation in the source form, and Perl utilities, you can build 774ba47ec9dSmillertHTML docs. Cd to directory with F<.pod> files, and do like this 775ba47ec9dSmillert 776ba47ec9dSmillert cd f:/perllib/lib/pod 777ba47ec9dSmillert pod2html 778ba47ec9dSmillert 779ba47ec9dSmillertAfter this you can direct your browser the file F<perl.html> in this 780ba47ec9dSmillertdirectory, and go ahead with reading docs, like this: 781ba47ec9dSmillert 782ba47ec9dSmillert explore file:///f:/perllib/lib/pod/perl.html 783ba47ec9dSmillert 784ba47ec9dSmillertAlternatively you may be able to get these docs prebuilt from CPAN. 785ba47ec9dSmillert 786ba47ec9dSmillert=head2 GNU C<info> files 787ba47ec9dSmillert 788ba47ec9dSmillertUsers of Emacs would appreciate it very much, especially with 78979cd0b9aSmillertC<CPerl> mode loaded. You need to get latest C<pod2texi> from C<CPAN>, 79079cd0b9aSmillertor, alternately, the prebuilt info pages. 791ba47ec9dSmillert 79279cd0b9aSmillert=head2 F<PDF> files 793ba47ec9dSmillert 79479cd0b9aSmillertfor C<Acrobat> are available on CPAN (may be for slightly older version of 795ba47ec9dSmillertperl). 796ba47ec9dSmillert 797ba47ec9dSmillert=head2 C<LaTeX> docs 798ba47ec9dSmillert 799ba47ec9dSmillertcan be constructed using C<pod2latex>. 800ba47ec9dSmillert 801ba47ec9dSmillert=head1 BUILD 802ba47ec9dSmillert 8030dc2eaceSmillertHere we discuss how to build Perl under OS/2. 804c5dcfd37Smillert 805c5dcfd37Smillert=head2 The short story 806c5dcfd37Smillert 807c5dcfd37SmillertAssume that you are a seasoned porter, so are sure that all the necessary 808c5dcfd37Smillerttools are already present on your system, and you know how to get the Perl 809c5dcfd37Smillertsource distribution. Untar it, change to the extract directory, and 810c5dcfd37Smillert 811c5dcfd37Smillert gnupatch -p0 < os2\diff.configure 812c5dcfd37Smillert sh Configure -des -D prefix=f:/perllib 813c5dcfd37Smillert make 814c5dcfd37Smillert make test 815c5dcfd37Smillert make install 816c5dcfd37Smillert make aout_test 817c5dcfd37Smillert make aout_install 818c5dcfd37Smillert 819c5dcfd37SmillertThis puts the executables in f:/perllib/bin. Manually move them to the 82079cd0b9aSmillertC<PATH>, manually move the built F<perl*.dll> to C<LIBPATH> (here for 82179cd0b9aSmillertPerl DLL F<*> is a not-very-meaningful hex checksum), and run 822c5dcfd37Smillert 823c5dcfd37Smillert make installcmd INSTALLCMDDIR=d:/ir/on/path 824c5dcfd37Smillert 82579cd0b9aSmillertAssuming that the C<man>-files were put on an appropriate location, 82679cd0b9aSmillertthis completes the installation of minimal Perl system. (The binary 82779cd0b9aSmillertdistribution contains also a lot of additional modules, and the 82879cd0b9aSmillertdocumentation in INF format.) 82979cd0b9aSmillert 830c5dcfd37SmillertWhat follows is a detailed guide through these steps. 831ba47ec9dSmillert 832ba47ec9dSmillert=head2 Prerequisites 833ba47ec9dSmillert 834ba47ec9dSmillertYou need to have the latest EMX development environment, the full 835ba47ec9dSmillertGNU tool suite (gawk renamed to awk, and GNU F<find.exe> 836ba47ec9dSmillertearlier on path than the OS/2 F<find.exe>, same with F<sort.exe>, to 837ba47ec9dSmillertcheck use 838ba47ec9dSmillert 839ba47ec9dSmillert find --version 840ba47ec9dSmillert sort --version 841ba47ec9dSmillert 842ba47ec9dSmillert). You need the latest version of F<pdksh> installed as F<sh.exe>. 843ba47ec9dSmillert 8446345ca90SmillertCheck that you have B<BSD> libraries and headers installed, and - 8456345ca90Smillertoptionally - Berkeley DB headers and libraries, and crypt. 8466345ca90Smillert 84779cd0b9aSmillertPossible locations to get the files: 848ba47ec9dSmillert 8490dc2eaceSmillert 8500dc2eaceSmillert ftp://ftp.uni-heidelberg.de/pub/os2/unix/ 8510dc2eaceSmillert http://hobbes.nmsu.edu/h-browse.php?dir=/pub/os2 8520dc2eaceSmillert http://cd.textfiles.com/hobbesos29804/disk1/DEV32/ 8530dc2eaceSmillert http://cd.textfiles.com/hobbesos29804/disk1/EMX09C/ 854ba47ec9dSmillert 855ba47ec9dSmillertIt is reported that the following archives contain enough utils to 856c5dcfd37Smillertbuild perl: F<gnufutil.zip>, F<gnusutil.zip>, F<gnututil.zip>, F<gnused.zip>, 85779cd0b9aSmillertF<gnupatch.zip>, F<gnuawk.zip>, F<gnumake.zip>, F<gnugrep.zip>, F<bsddev.zip> and 858c5dcfd37SmillertF<ksh527rt.zip> (or a later version). Note that all these utilities are 859c5dcfd37Smillertknown to be available from LEO: 860ba47ec9dSmillert 8610dc2eaceSmillert ftp://crydee.sai.msu.ru/pub/comp/os/os2/leo/gnu/ 862ba47ec9dSmillert 86379cd0b9aSmillertNote also that the F<db.lib> and F<db.a> from the EMX distribution 86479cd0b9aSmillertare not suitable for multi-threaded compile (even single-threaded 86579cd0b9aSmillertflavor of Perl uses multi-threaded C RTL, for 86679cd0b9aSmillertcompatibility with XFree86-OS/2). Get a corrected one from 86779cd0b9aSmillert 86879cd0b9aSmillert http://www.ilyaz.org/software/os2/db_mt.zip 86979cd0b9aSmillert 870c5dcfd37SmillertIf you have I<exactly the same version of Perl> installed already, 871c5dcfd37Smillertmake sure that no copies or perl are currently running. Later steps 872c5dcfd37Smillertof the build may fail since an older version of F<perl.dll> loaded into 87309e75b67Smillertmemory may be found. Running C<make test> becomes meaningless, since 87409e75b67Smillertthe test are checking a previous build of perl (this situation is detected 875b8851fccSafresh1and reported by F<os2/os2_base.t> test). Do not forget to unset 87609e75b67SmillertC<PERL_EMXLOAD_SEC> in environment. 877ba47ec9dSmillert 878ba47ec9dSmillertAlso make sure that you have F</tmp> directory on the current drive, 879ba47ec9dSmillertand F<.> directory in your C<LIBPATH>. One may try to correct the 880ba47ec9dSmillertlatter condition by 881ba47ec9dSmillert 88279cd0b9aSmillert set BEGINLIBPATH .\. 883ba47ec9dSmillert 88479cd0b9aSmillertif you use something like F<CMD.EXE> or latest versions of 88579cd0b9aSmillertF<4os2.exe>. (Setting BEGINLIBPATH to just C<.> is ignored by the 88679cd0b9aSmillertOS/2 kernel.) 887ba47ec9dSmillert 888ba47ec9dSmillertMake sure your gcc is good for C<-Zomf> linking: run C<omflibs> 889ba47ec9dSmillertscript in F</emx/lib> directory. 890ba47ec9dSmillert 891ba47ec9dSmillertCheck that you have link386 installed. It comes standard with OS/2, 892ba47ec9dSmillertbut may be not installed due to customization. If typing 893ba47ec9dSmillert 894ba47ec9dSmillert link386 895ba47ec9dSmillert 896ba47ec9dSmillertshows you do not have it, do I<Selective install>, and choose C<Link 897ba47ec9dSmillertobject modules> in I<Optional system utilities/More>. If you get into 898c5dcfd37Smillertlink386 prompts, press C<Ctrl-C> to exit. 899ba47ec9dSmillert 900ba47ec9dSmillert=head2 Getting perl source 901ba47ec9dSmillert 902ba47ec9dSmillertYou need to fetch the latest perl source (including developers 903ba47ec9dSmillertreleases). With some probability it is located in 904ba47ec9dSmillert 9050dc2eaceSmillert http://www.cpan.org/src/ 9060dc2eaceSmillert http://www.cpan.org/src/unsupported 907ba47ec9dSmillert 908ba47ec9dSmillertIf not, you may need to dig in the indices to find it in the directory 909ba47ec9dSmillertof the current maintainer. 910ba47ec9dSmillert 911ba47ec9dSmillertQuick cycle of developers release may break the OS/2 build time to 912ba47ec9dSmillerttime, looking into 913ba47ec9dSmillert 914f64b279aSmillert http://www.cpan.org/ports/os2/ 915ba47ec9dSmillert 916ba47ec9dSmillertmay indicate the latest release which was publicly released by the 917ba47ec9dSmillertmaintainer. Note that the release may include some additional patches 918ba47ec9dSmillertto apply to the current source of perl. 919ba47ec9dSmillert 920ba47ec9dSmillertExtract it like this 921ba47ec9dSmillert 922ba47ec9dSmillert tar vzxf perl5.00409.tar.gz 923ba47ec9dSmillert 924ba47ec9dSmillertYou may see a message about errors while extracting F<Configure>. This is 925ba47ec9dSmillertbecause there is a conflict with a similarly-named file F<configure>. 926ba47ec9dSmillert 927ba47ec9dSmillertChange to the directory of extraction. 928ba47ec9dSmillert 929ba47ec9dSmillert=head2 Application of the patches 930ba47ec9dSmillert 931e2e5c5d3SmillertYou need to apply the patches in F<./os2/diff.*> like this: 932ba47ec9dSmillert 933ba47ec9dSmillert gnupatch -p0 < os2\diff.configure 934ba47ec9dSmillert 935ba47ec9dSmillertYou may also need to apply the patches supplied with the binary 93679cd0b9aSmillertdistribution of perl. It also makes sense to look on the 93779cd0b9aSmillertperl5-porters mailing list for the latest OS/2-related patches (see 93879cd0b9aSmillertL<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/>). Such 93979cd0b9aSmillertpatches usually contain strings C</os2/> and C<patch>, so it makes 94079cd0b9aSmillertsense looking for these strings. 941ba47ec9dSmillert 942ba47ec9dSmillert=head2 Hand-editing 943ba47ec9dSmillert 944ba47ec9dSmillertYou may look into the file F<./hints/os2.sh> and correct anything 945ba47ec9dSmillertwrong you find there. I do not expect it is needed anywhere. 946ba47ec9dSmillert 947ba47ec9dSmillert=head2 Making 948ba47ec9dSmillert 949ba47ec9dSmillert sh Configure -des -D prefix=f:/perllib 950ba47ec9dSmillert 951ba47ec9dSmillertC<prefix> means: where to install the resulting perl library. Giving 952ba47ec9dSmillertcorrect prefix you may avoid the need to specify C<PERLLIB_PREFIX>, 9539f11ffb7Safresh1see L</"C<PERLLIB_PREFIX>">. 954ba47ec9dSmillert 955ba47ec9dSmillertI<Ignore the message about missing C<ln>, and about C<-c> option to 956c5dcfd37Smillerttr>. The latter is most probably already fixed, if you see it and can trace 957c5dcfd37Smillertwhere the latter spurious warning comes from, please inform me. 958ba47ec9dSmillert 959ba47ec9dSmillertNow 960ba47ec9dSmillert 961ba47ec9dSmillert make 962ba47ec9dSmillert 963ba47ec9dSmillertAt some moment the built may die, reporting a I<version mismatch> or 964c5dcfd37SmillertI<unable to run F<perl>>. This means that you do not have F<.> in 965c5dcfd37Smillertyour LIBPATH, so F<perl.exe> cannot find the needed F<perl67B2.dll> (treat 966c5dcfd37Smillertthese hex digits as line noise). After this is fixed the build 967c5dcfd37Smillertshould finish without a lot of fuss. 968ba47ec9dSmillert 969ba47ec9dSmillert=head2 Testing 970ba47ec9dSmillert 971ba47ec9dSmillertNow run 972ba47ec9dSmillert 973ba47ec9dSmillert make test 974ba47ec9dSmillert 97579cd0b9aSmillertAll tests should succeed (with some of them skipped). If you have the 97679cd0b9aSmillertsame version of Perl installed, it is crucial that you have C<.> early 97779cd0b9aSmillertin your LIBPATH (or in BEGINLIBPATH), otherwise your tests will most 97879cd0b9aSmillertprobably test the wrong version of Perl. 979ba47ec9dSmillert 9806345ca90SmillertSome tests may generate extra messages similar to 981ba47ec9dSmillert 9826345ca90Smillert=over 4 983ba47ec9dSmillert 9846345ca90Smillert=item A lot of C<bad free> 985ba47ec9dSmillert 986c5dcfd37Smillertin database tests related to Berkeley DB. I<This should be fixed already.> 9879f11ffb7Safresh1If it persists, you may disable this warnings, see L</"C<PERL_BADFREE>">. 9886345ca90Smillert 9896345ca90Smillert=item Process terminated by SIGTERM/SIGINT 9906345ca90Smillert 9916345ca90SmillertThis is a standard message issued by OS/2 applications. *nix 992c5dcfd37Smillertapplications die in silence. It is considered to be a feature. One can 9936345ca90Smillerteasily disable this by appropriate sighandlers. 9946345ca90Smillert 9956345ca90SmillertHowever the test engine bleeds these message to screen in unexpected 9966345ca90Smillertmoments. Two messages of this kind I<should> be present during 9976345ca90Smillerttesting. 9986345ca90Smillert 9996345ca90Smillert=back 10006345ca90Smillert 10016345ca90SmillertTo get finer test reports, call 1002ba47ec9dSmillert 10036345ca90Smillert perl t/harness 10046345ca90Smillert 10056345ca90SmillertThe report with F<io/pipe.t> failing may look like this: 10066345ca90Smillert 10076345ca90Smillert Failed Test Status Wstat Total Fail Failed List of failed 10086345ca90Smillert ------------------------------------------------------------ 10096345ca90Smillert io/pipe.t 12 1 8.33% 9 10106345ca90Smillert 7 tests skipped, plus 56 subtests skipped. 1011b8851fccSafresh1 Failed 1/195 test scripts, 99.49% okay. 1/6542 subtests failed, 1012b8851fccSafresh1 99.98% okay. 10136345ca90Smillert 10146345ca90SmillertThe reasons for most important skipped tests are: 1015ba47ec9dSmillert 1016ba47ec9dSmillert=over 8 1017ba47ec9dSmillert 10186345ca90Smillert=item F<op/fs.t> 1019ba47ec9dSmillert 1020e2e5c5d3Smillert=over 4 1021e2e5c5d3Smillert 1022e5157e49Safresh1=item Z<>18 1023ba47ec9dSmillert 10246345ca90SmillertChecks C<atime> and C<mtime> of C<stat()> - unfortunately, HPFS 10256345ca90Smillertprovides only 2sec time granularity (for compatibility with FAT?). 1026ba47ec9dSmillert 1027e5157e49Safresh1=item Z<>25 1028ba47ec9dSmillert 1029ba47ec9dSmillertChecks C<truncate()> on a filehandle just opened for write - I do not 1030ba47ec9dSmillertknow why this should or should not work. 1031ba47ec9dSmillert 1032ba47ec9dSmillert=back 1033ba47ec9dSmillert 1034ba47ec9dSmillert=item F<op/stat.t> 1035ba47ec9dSmillert 1036ba47ec9dSmillertChecks C<stat()>. Tests: 1037ba47ec9dSmillert 1038ba47ec9dSmillert=over 4 1039ba47ec9dSmillert 1040ba47ec9dSmillert=item 4 1041ba47ec9dSmillert 10426345ca90SmillertChecks C<atime> and C<mtime> of C<stat()> - unfortunately, HPFS 10436345ca90Smillertprovides only 2sec time granularity (for compatibility with FAT?). 1044ba47ec9dSmillert 1045ba47ec9dSmillert=back 1046ba47ec9dSmillert 1047ba47ec9dSmillert=back 1048ba47ec9dSmillert 1049ba47ec9dSmillert=head2 Installing the built perl 1050ba47ec9dSmillert 105179cd0b9aSmillertIf you haven't yet moved C<perl*.dll> onto LIBPATH, do it now. 10526345ca90Smillert 1053ba47ec9dSmillertRun 1054ba47ec9dSmillert 1055ba47ec9dSmillert make install 1056ba47ec9dSmillert 1057ba47ec9dSmillertIt would put the generated files into needed locations. Manually put 1058ba47ec9dSmillertF<perl.exe>, F<perl__.exe> and F<perl___.exe> to a location on your 1059ba47ec9dSmillertPATH, F<perl.dll> to a location on your LIBPATH. 1060ba47ec9dSmillert 1061ba47ec9dSmillertRun 1062ba47ec9dSmillert 1063c5dcfd37Smillert make installcmd INSTALLCMDDIR=d:/ir/on/path 1064ba47ec9dSmillert 1065ba47ec9dSmillertto convert perl utilities to F<.cmd> files and put them on 1066ba47ec9dSmillertPATH. You need to put F<.EXE>-utilities on path manually. They are 1067ba47ec9dSmillertinstalled in C<$prefix/bin>, here C<$prefix> is what you gave to 106848950c12SsthenF<Configure>, see L</Making>. 1069ba47ec9dSmillert 107079cd0b9aSmillertIf you use C<man>, either move the installed F<*/man/> directories to 107179cd0b9aSmillertyour C<MANPATH>, or modify C<MANPATH> to match the location. (One 107279cd0b9aSmillertcould have avoided this by providing a correct C<manpath> option to 107379cd0b9aSmillertF<./Configure>, or editing F<./config.sh> between configuring and 107479cd0b9aSmillertmaking steps.) 107579cd0b9aSmillert 1076ba47ec9dSmillert=head2 C<a.out>-style build 1077ba47ec9dSmillert 10789f11ffb7Safresh1Proceed as above, but make F<perl_.exe> (see L</"F<perl_.exe>">) by 1079ba47ec9dSmillert 1080ba47ec9dSmillert make perl_ 1081ba47ec9dSmillert 1082ba47ec9dSmillerttest and install by 1083ba47ec9dSmillert 1084ba47ec9dSmillert make aout_test 1085ba47ec9dSmillert make aout_install 1086ba47ec9dSmillert 1087ba47ec9dSmillertManually put F<perl_.exe> to a location on your PATH. 1088ba47ec9dSmillert 1089ba47ec9dSmillertB<Note.> The build process for C<perl_> I<does not know> about all the 1090ba47ec9dSmillertdependencies, so you should make sure that anything is up-to-date, 1091ba47ec9dSmillertsay, by doing 1092ba47ec9dSmillert 1093c5dcfd37Smillert make perl_dll 1094ba47ec9dSmillert 1095ba47ec9dSmillertfirst. 1096ba47ec9dSmillert 109709e75b67Smillert=head1 Building a binary distribution 109809e75b67Smillert 109909e75b67Smillert[This section provides a short overview only...] 110009e75b67Smillert 110109e75b67SmillertBuilding should proceed differently depending on whether the version of perl 110209e75b67Smillertyou install is already present and used on your system, or is a new version 110309e75b67Smillertnot yet used. The description below assumes that the version is new, so 110409e75b67Smillertinstalling its DLLs and F<.pm> files will not disrupt the operation of your 110509e75b67Smillertsystem even if some intermediate steps are not yet fully working. 110609e75b67Smillert 110709e75b67SmillertThe other cases require a little bit more convoluted procedures. Below I 110809e75b67Smillertsuppose that the current version of Perl is C<5.8.2>, so the executables are 110909e75b67Smillertnamed accordingly. 111009e75b67Smillert 111109e75b67Smillert=over 111209e75b67Smillert 111309e75b67Smillert=item 1. 111409e75b67Smillert 111509e75b67SmillertFully build and test the Perl distribution. Make sure that no tests are 111609e75b67Smillertfailing with C<test> and C<aout_test> targets; fix the bugs in Perl and 111709e75b67Smillertthe Perl test suite detected by these tests. Make sure that C<all_test> 111848950c12Ssthenmake target runs as clean as possible. Check that F<os2/perlrexx.cmd> 111909e75b67Smillertruns fine. 112009e75b67Smillert 112109e75b67Smillert=item 2. 112209e75b67Smillert 112309e75b67SmillertFully install Perl, including C<installcmd> target. Copy the generated DLLs 112409e75b67Smillertto C<LIBPATH>; copy the numbered Perl executables (as in F<perl5.8.2.exe>) 112509e75b67Smillertto C<PATH>; copy C<perl_.exe> to C<PATH> as C<perl_5.8.2.exe>. Think whether 112609e75b67Smillertyou need backward-compatibility DLLs. In most cases you do not need to install 112709e75b67Smillertthem yet; but sometime this may simplify the following steps. 112809e75b67Smillert 112909e75b67Smillert=item 3. 113009e75b67Smillert 113109e75b67SmillertMake sure that C<CPAN.pm> can download files from CPAN. If not, you may need 113209e75b67Smillertto manually install C<Net::FTP>. 113309e75b67Smillert 113409e75b67Smillert=item 4. 113509e75b67Smillert 113609e75b67SmillertInstall the bundle C<Bundle::OS2_default> 113709e75b67Smillert 113809e75b67Smillert perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_1 113909e75b67Smillert 114009e75b67SmillertThis may take a couple of hours on 1GHz processor (when run the first time). 114109e75b67SmillertAnd this should not be necessarily a smooth procedure. Some modules may not 114209e75b67Smillertspecify required dependencies, so one may need to repeat this procedure several 114309e75b67Smillerttimes until the results stabilize. 114409e75b67Smillert 114509e75b67Smillert perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_2 114609e75b67Smillert perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_3 114709e75b67Smillert 114809e75b67SmillertEven after they stabilize, some tests may fail. 114909e75b67Smillert 115009e75b67SmillertFix as many discovered bugs as possible. Document all the bugs which are not 115109e75b67Smillertfixed, and all the failures with unknown reasons. Inspect the produced logs 115209e75b67SmillertF<00cpan_i_1> to find suspiciously skipped tests, and other fishy events. 115309e75b67Smillert 115409e75b67SmillertKeep in mind that I<installation> of some modules may fail too: for example, 115509e75b67Smillertthe DLLs to update may be already loaded by F<CPAN.pm>. Inspect the C<install> 115609e75b67Smillertlogs (in the example above F<00cpan_i_1> etc) for errors, and install things 115709e75b67Smillertmanually, as in 115809e75b67Smillert 115909e75b67Smillert cd $CPANHOME/.cpan/build/Digest-MD5-2.31 116009e75b67Smillert make install 116109e75b67Smillert 116209e75b67SmillertSome distributions may fail some tests, but you may want to install them 116309e75b67Smillertanyway (as above, or via C<force install> command of C<CPAN.pm> shell-mode). 116409e75b67Smillert 116509e75b67SmillertSince this procedure may take quite a long time to complete, it makes sense 116609e75b67Smillertto "freeze" your CPAN configuration by disabling periodic updates of the 116709e75b67Smillertlocal copy of CPAN index: set C<index_expire> to some big value (I use 365), 116809e75b67Smillertthen save the settings 116909e75b67Smillert 117009e75b67Smillert CPAN> o conf index_expire 365 117109e75b67Smillert CPAN> o conf commit 117209e75b67Smillert 117309e75b67SmillertReset back to the default value C<1> when you are finished. 117409e75b67Smillert 117509e75b67Smillert=item 5. 117609e75b67Smillert 117709e75b67SmillertWhen satisfied with the results, rerun the C<installcmd> target. Now you 117809e75b67Smillertcan copy C<perl5.8.2.exe> to C<perl.exe>, and install the other OMF-build 117909e75b67Smillertexecutables: C<perl__.exe> etc. They are ready to be used. 118009e75b67Smillert 118109e75b67Smillert=item 6. 118209e75b67Smillert 118309e75b67SmillertChange to the C<./pod> directory of the build tree, download the Perl logo 118409e75b67SmillertF<CamelGrayBig.BMP>, and run 118509e75b67Smillert 118609e75b67Smillert ( perl2ipf > perl.ipf ) |& tee 00ipf 118709e75b67Smillert ipfc /INF perl.ipf |& tee 00inf 118809e75b67Smillert 118909e75b67SmillertThis produces the Perl docs online book C<perl.INF>. Install in on 119009e75b67SmillertC<BOOKSHELF> path. 119109e75b67Smillert 119209e75b67Smillert=item 7. 119309e75b67Smillert 119409e75b67SmillertNow is the time to build statically linked executable F<perl_.exe> which 119509e75b67Smillertincludes newly-installed via C<Bundle::OS2_default> modules. Doing testing 119609e75b67Smillertvia C<CPAN.pm> is going to be painfully slow, since it statically links 119709e75b67Smillerta new executable per XS extension. 119809e75b67Smillert 119909e75b67SmillertHere is a possible workaround: create a toplevel F<Makefile.PL> in 12009f11ffb7Safresh1F<$CPANHOME/.cpan/build/> with contents being (compare with L</Making 120109e75b67Smillertexecutables with a custom collection of statically loaded extensions>) 120209e75b67Smillert 120309e75b67Smillert use ExtUtils::MakeMaker; 120409e75b67Smillert WriteMakefile NAME => 'dummy'; 120509e75b67Smillert 120609e75b67Smillertexecute this as 120709e75b67Smillert 120809e75b67Smillert perl_5.8.2.exe Makefile.PL <nul |& tee 00aout_c1 120909e75b67Smillert make -k all test <nul |& 00aout_t1 121009e75b67Smillert 121109e75b67SmillertAgain, this procedure should not be absolutely smooth. Some C<Makefile.PL>'s 121209e75b67Smillertin subdirectories may be buggy, and would not run as "child" scripts. The 121309e75b67Smillertinterdependency of modules can strike you; however, since non-XS modules 121409e75b67Smillertare already installed, the prerequisites of most modules have a very good 121509e75b67Smillertchance to be present. 121609e75b67Smillert 121709e75b67SmillertIf you discover some glitches, move directories of problematic modules to a 121809e75b67Smillertdifferent location; if these modules are non-XS modules, you may just ignore 121909e75b67Smillertthem - they are already installed; the remaining, XS, modules you need to 122009e75b67Smillertinstall manually one by one. 122109e75b67Smillert 122209e75b67SmillertAfter each such removal you need to rerun the C<Makefile.PL>/C<make> process; 122309e75b67Smillertusually this procedure converges soon. (But be sure to convert all the 122409e75b67Smillertnecessary external C libraries from F<.lib> format to F<.a> format: run one of 122509e75b67Smillert 122609e75b67Smillert emxaout foo.lib 122709e75b67Smillert emximp -o foo.a foo.lib 122809e75b67Smillert 122909e75b67Smillertwhichever is appropriate.) Also, make sure that the DLLs for external 123056d68f1eSafresh1libraries are usable with executables compiled without C<-Zmtd> options. 123109e75b67Smillert 123209e75b67SmillertWhen you are sure that only a few subdirectories 123309e75b67Smillertlead to failures, you may want to add C<-j4> option to C<make> to speed up 123409e75b67Smillertskipping subdirectories with already finished build. 123509e75b67Smillert 123609e75b67SmillertWhen you are satisfied with the results of tests, install the build C libraries 123709e75b67Smillertfor extensions: 123809e75b67Smillert 123909e75b67Smillert make install |& tee 00aout_i 124009e75b67Smillert 124109e75b67SmillertNow you can rename the file F<./perl.exe> generated during the last phase 124209e75b67Smillertto F<perl_5.8.2.exe>; place it on C<PATH>; if there is an inter-dependency 124309e75b67Smillertbetween some XS modules, you may need to repeat the C<test>/C<install> loop 124409e75b67Smillertwith this new executable and some excluded modules - until the procedure 124509e75b67Smillertconverges. 124609e75b67Smillert 124709e75b67SmillertNow you have all the necessary F<.a> libraries for these Perl modules in the 124809e75b67Smillertplaces where Perl builder can find it. Use the perl builder: change to an 124909e75b67Smillertempty directory, create a "dummy" F<Makefile.PL> again, and run 125009e75b67Smillert 125109e75b67Smillert perl_5.8.2.exe Makefile.PL |& tee 00c 125209e75b67Smillert make perl |& tee 00p 125309e75b67Smillert 125409e75b67SmillertThis should create an executable F<./perl.exe> with all the statically loaded 125509e75b67Smillertextensions built in. Compare the generated F<perlmain.c> files to make sure 125609e75b67Smillertthat during the iterations the number of loaded extensions only increases. 125709e75b67SmillertRename F<./perl.exe> to F<perl_5.8.2.exe> on C<PATH>. 125809e75b67Smillert 125909e75b67SmillertWhen it converges, you got a functional variant of F<perl_5.8.2.exe>; copy it 126009e75b67Smillertto C<perl_.exe>. You are done with generation of the local Perl installation. 126109e75b67Smillert 126209e75b67Smillert=item 8. 126309e75b67Smillert 126409e75b67SmillertMake sure that the installed modules are actually installed in the location 126509e75b67Smillertof the new Perl, and are not inherited from entries of @INC given for 126609e75b67Smillertinheritance from the older versions of Perl: set C<PERLLIB_582_PREFIX> to 126709e75b67Smillertredirect the new version of Perl to a new location, and copy the installed 126809e75b67Smillertfiles to this new location. Redo the tests to make sure that the versions of 126909e75b67Smillertmodules inherited from older versions of Perl are not needed. 127009e75b67Smillert 127148950c12SsthenActually, the log output of L<pod2ipf(1)> during the step 6 gives a very detailed 127209e75b67Smillertinfo about which modules are loaded from which place; so you may use it as 127309e75b67Smillertan additional verification tool. 127409e75b67Smillert 127509e75b67SmillertCheck that some temporary files did not make into the perl install tree. 127609e75b67SmillertRun something like this 127709e75b67Smillert 127809e75b67Smillert pfind . -f "!(/\.(pm|pl|ix|al|h|a|lib|txt|pod|imp|bs|dll|ld|bs|inc|xbm|yml|cgi|uu|e2x|skip|packlist|eg|cfg|html|pub|enc|all|ini|po|pot)$/i or /^\w+$/") | less 127909e75b67Smillert 128009e75b67Smillertin the install tree (both top one and F<sitelib> one). 128109e75b67Smillert 128209e75b67SmillertCompress all the DLLs with F<lxlite>. The tiny F<.exe> can be compressed with 128309e75b67SmillertC</c:max> (the bug only appears when there is a fixup in the last 6 bytes of a 128409e75b67Smillertpage (?); since the tiny executables are much smaller than a page, the bug 128509e75b67Smillertwill not hit). Do not compress C<perl_.exe> - it would not work under DOS. 128609e75b67Smillert 128709e75b67Smillert=item 9. 128809e75b67Smillert 128909e75b67SmillertNow you can generate the binary distribution. This is done by running the 129009e75b67Smillerttest of the CPAN distribution C<OS2::SoftInstaller>. Tune up the file 129109e75b67SmillertF<test.pl> to suit the layout of current version of Perl first. Do not 129209e75b67Smillertforget to pack the necessary external DLLs accordingly. Include the 129309e75b67Smillertdescription of the bugs and test suite failures you could not fix. Include 129409e75b67Smillertthe small-stack versions of Perl executables from Perl build directory. 129509e75b67Smillert 129609e75b67SmillertInclude F<perl5.def> so that people can relink the perl DLL preserving 129709e75b67Smillertthe binary compatibility, or can create compatibility DLLs. Include the diff 129809e75b67Smillertfiles (C<diff -pu old new>) of fixes you did so that people can rebuild your 129909e75b67Smillertversion. Include F<perl5.map> so that one can use remote debugging. 130009e75b67Smillert 130109e75b67Smillert=item 10. 130209e75b67Smillert 130309e75b67SmillertShare what you did with the other people. Relax. Enjoy fruits of your work. 130409e75b67Smillert 130509e75b67Smillert=item 11. 130609e75b67Smillert 130709e75b67SmillertBrace yourself for thanks, bug reports, hate mail and spam coming as result 130809e75b67Smillertof the previous step. No good deed should remain unpunished! 130909e75b67Smillert 131009e75b67Smillert=back 131109e75b67Smillert 131209e75b67Smillert=head1 Building custom F<.EXE> files 131309e75b67Smillert 131409e75b67SmillertThe Perl executables can be easily rebuilt at any moment. Moreover, one can 131509e75b67Smillertuse the I<embedding> interface (see L<perlembed>) to make very customized 131609e75b67Smillertexecutables. 131709e75b67Smillert 131809e75b67Smillert=head2 Making executables with a custom collection of statically loaded extensions 131909e75b67Smillert 132009e75b67SmillertIt is a little bit easier to do so while I<decreasing> the list of statically 132109e75b67Smillertloaded extensions. We discuss this case only here. 132209e75b67Smillert 132309e75b67Smillert=over 132409e75b67Smillert 132509e75b67Smillert=item 1. 132609e75b67Smillert 132709e75b67SmillertChange to an empty directory, and create a placeholder <Makefile.PL>: 132809e75b67Smillert 132909e75b67Smillert use ExtUtils::MakeMaker; 133009e75b67Smillert WriteMakefile NAME => 'dummy'; 133109e75b67Smillert 133209e75b67Smillert=item 2. 133309e75b67Smillert 133409e75b67SmillertRun it with the flavor of Perl (F<perl.exe> or F<perl_.exe>) you want to 133509e75b67Smillertrebuild. 133609e75b67Smillert 133709e75b67Smillert perl_ Makefile.PL 133809e75b67Smillert 133909e75b67Smillert=item 3. 134009e75b67Smillert 134109e75b67SmillertAsk it to create new Perl executable: 134209e75b67Smillert 134309e75b67Smillert make perl 134409e75b67Smillert 134509e75b67Smillert(you may need to manually add C<PERLTYPE=-DPERL_CORE> to this commandline on 134609e75b67Smillertsome versions of Perl; the symptom is that the command-line globbing does not 134709e75b67Smillertwork from OS/2 shells with the newly-compiled executable; check with 134809e75b67Smillert 134909e75b67Smillert .\perl.exe -wle "print for @ARGV" * 135009e75b67Smillert 135109e75b67Smillert). 135209e75b67Smillert 135309e75b67Smillert=item 4. 135409e75b67Smillert 135509e75b67SmillertThe previous step created F<perlmain.c> which contains a list of newXS() calls 135609e75b67Smillertnear the end. Removing unnecessary calls, and rerunning 135709e75b67Smillert 135809e75b67Smillert make perl 135909e75b67Smillert 136009e75b67Smillertwill produce a customized executable. 136109e75b67Smillert 136209e75b67Smillert=back 136309e75b67Smillert 136409e75b67Smillert=head2 Making executables with a custom search-paths 136509e75b67Smillert 136609e75b67SmillertThe default perl executable is flexible enough to support most usages. 136709e75b67SmillertHowever, one may want something yet more flexible; for example, one may want 136809e75b67Smillertto find Perl DLL relatively to the location of the EXE file; or one may want 136909e75b67Smillertto ignore the environment when setting the Perl-library search patch, etc. 137009e75b67Smillert 137109e75b67SmillertIf you fill comfortable with I<embedding> interface (see L<perlembed>), such 1372eac174f2Safresh1things are easy to do repeating the steps outlined in L</Making 137309e75b67Smillertexecutables with a custom collection of statically loaded extensions>, and 137409e75b67Smillertdoing more comprehensive edits to main() of F<perlmain.c>. The people with 137509e75b67Smillertlittle desire to understand Perl can just rename main(), and do necessary 137609e75b67Smillertmodification in a custom main() which calls the renamed function in appropriate 137709e75b67Smillerttime. 137809e75b67Smillert 137909e75b67SmillertHowever, there is a third way: perl DLL exports the main() function and several 138009e75b67Smillertcallbacks to customize the search path. Below is a complete example of a 138109e75b67Smillert"Perl loader" which 138209e75b67Smillert 138309e75b67Smillert=over 138409e75b67Smillert 138509e75b67Smillert=item 1. 138609e75b67Smillert 138709e75b67SmillertLooks for Perl DLL in the directory C<$exedir/../dll>; 138809e75b67Smillert 138909e75b67Smillert=item 2. 139009e75b67Smillert 139109e75b67SmillertPrepends the above directory to C<BEGINLIBPATH>; 139209e75b67Smillert 139309e75b67Smillert=item 3. 139409e75b67Smillert 139509e75b67SmillertFails if the Perl DLL found via C<BEGINLIBPATH> is different from what was 139609e75b67Smillertloaded on step 1; e.g., another process could have loaded it from C<LIBPATH> 139709e75b67Smillertor from a different value of C<BEGINLIBPATH>. In these cases one needs to 139809e75b67Smillertmodify the setting of the system so that this other process either does not 139909e75b67Smillertrun, or loads the DLL from C<BEGINLIBPATH> with C<LIBPATHSTRICT=T> (available 140009e75b67Smillertwith kernels after September 2000). 140109e75b67Smillert 140209e75b67Smillert=item 4. 140309e75b67Smillert 140409e75b67SmillertLoads Perl library from C<$exedir/../dll/lib/>. 140509e75b67Smillert 140609e75b67Smillert=item 5. 140709e75b67Smillert 140809e75b67SmillertUses Bourne shell from C<$exedir/../dll/sh/ksh.exe>. 140909e75b67Smillert 141009e75b67Smillert=back 141109e75b67Smillert 141209e75b67SmillertFor best results compile the C file below with the same options as the Perl 141309e75b67SmillertDLL. However, a lot of functionality will work even if the executable is not 141409e75b67Smillertan EMX applications, e.g., if compiled with 141509e75b67Smillert 1416e5157e49Safresh1 gcc -Wall -DDOSISH -DOS2=1 -O2 -s -Zomf -Zsys perl-starter.c \ 1417e5157e49Safresh1 -DPERL_DLL_BASENAME=\"perl312F\" -Zstack 8192 -Zlinker /PM:VIO 141809e75b67Smillert 141909e75b67SmillertHere is the sample C file: 142009e75b67Smillert 142109e75b67Smillert #define INCL_DOS 142209e75b67Smillert #define INCL_NOPM 1423b8851fccSafresh1 /* These are needed for compile if os2.h includes os2tk.h, not 1424b8851fccSafresh1 * os2emx.h */ 142509e75b67Smillert #define INCL_DOSPROCESS 142609e75b67Smillert #include <os2.h> 142709e75b67Smillert 142809e75b67Smillert #include "EXTERN.h" 142909e75b67Smillert #define PERL_IN_MINIPERLMAIN_C 143009e75b67Smillert #include "perl.h" 143109e75b67Smillert 143209e75b67Smillert static char *me; 143309e75b67Smillert HMODULE handle; 143409e75b67Smillert 143509e75b67Smillert static void 143609e75b67Smillert die_with(char *msg1, char *msg2, char *msg3, char *msg4) 143709e75b67Smillert { 143809e75b67Smillert ULONG c; 143909e75b67Smillert char *s = " error: "; 144009e75b67Smillert 144109e75b67Smillert DosWrite(2, me, strlen(me), &c); 144209e75b67Smillert DosWrite(2, s, strlen(s), &c); 144309e75b67Smillert DosWrite(2, msg1, strlen(msg1), &c); 144409e75b67Smillert DosWrite(2, msg2, strlen(msg2), &c); 144509e75b67Smillert DosWrite(2, msg3, strlen(msg3), &c); 144609e75b67Smillert DosWrite(2, msg4, strlen(msg4), &c); 144709e75b67Smillert DosWrite(2, "\r\n", 2, &c); 144809e75b67Smillert exit(255); 144909e75b67Smillert } 145009e75b67Smillert 1451b8851fccSafresh1 typedef ULONG (*fill_extLibpath_t)(int type, 1452b8851fccSafresh1 char *pre, 1453b8851fccSafresh1 char *post, 1454b8851fccSafresh1 int replace, 1455b8851fccSafresh1 char *msg); 145609e75b67Smillert typedef int (*main_t)(int type, char *argv[], char *env[]); 145709e75b67Smillert typedef int (*handler_t)(void* data, int which); 145809e75b67Smillert 145909e75b67Smillert #ifndef PERL_DLL_BASENAME 146009e75b67Smillert # define PERL_DLL_BASENAME "perl" 146109e75b67Smillert #endif 146209e75b67Smillert 146309e75b67Smillert static HMODULE 146409e75b67Smillert load_perl_dll(char *basename) 146509e75b67Smillert { 146609e75b67Smillert char buf[300], fail[260]; 146709e75b67Smillert STRLEN l, dirl; 146809e75b67Smillert fill_extLibpath_t f; 146909e75b67Smillert ULONG rc_fullname; 147009e75b67Smillert HMODULE handle, handle1; 147109e75b67Smillert 147209e75b67Smillert if (_execname(buf, sizeof(buf) - 13) != 0) 147309e75b67Smillert die_with("Can't find full path: ", strerror(errno), "", ""); 147448950c12Ssthen /* XXXX Fill 'me' with new value */ 147509e75b67Smillert l = strlen(buf); 147609e75b67Smillert while (l && buf[l-1] != '/' && buf[l-1] != '\\') 147709e75b67Smillert l--; 147809e75b67Smillert dirl = l - 1; 147909e75b67Smillert strcpy(buf + l, basename); 148009e75b67Smillert l += strlen(basename); 148109e75b67Smillert strcpy(buf + l, ".dll"); 1482b8851fccSafresh1 if ( (rc_fullname = DosLoadModule(fail, sizeof fail, buf, &handle)) 1483b8851fccSafresh1 != 0 148409e75b67Smillert && DosLoadModule(fail, sizeof fail, basename, &handle) != 0 ) 148509e75b67Smillert die_with("Can't load DLL ", buf, "", ""); 148609e75b67Smillert if (rc_fullname) 148709e75b67Smillert return handle; /* was loaded with short name; all is fine */ 148809e75b67Smillert if (DosQueryProcAddr(handle, 0, "fill_extLibpath", (PFN*)&f)) 1489b8851fccSafresh1 die_with(buf, 1490b8851fccSafresh1 ": DLL exports no symbol ", 1491b8851fccSafresh1 "fill_extLibpath", 1492b8851fccSafresh1 ""); 149309e75b67Smillert buf[dirl] = 0; 149409e75b67Smillert if (f(0 /*BEGINLIBPATH*/, buf /* prepend */, NULL /* append */, 149509e75b67Smillert 0 /* keep old value */, me)) 149609e75b67Smillert die_with(me, ": prepending BEGINLIBPATH", "", ""); 149709e75b67Smillert if (DosLoadModule(fail, sizeof fail, basename, &handle1) != 0) 1498b8851fccSafresh1 die_with(me, 1499b8851fccSafresh1 ": finding perl DLL again via BEGINLIBPATH", 1500b8851fccSafresh1 "", 1501b8851fccSafresh1 ""); 150209e75b67Smillert buf[dirl] = '\\'; 150309e75b67Smillert if (handle1 != handle) { 150409e75b67Smillert if (DosQueryModuleName(handle1, sizeof(fail), fail)) 150509e75b67Smillert strcpy(fail, "???"); 1506b8851fccSafresh1 die_with(buf, 1507b8851fccSafresh1 ":\n\tperl DLL via BEGINLIBPATH is different: \n\t", 150809e75b67Smillert fail, 1509b8851fccSafresh1 "\n\tYou may need to manipulate global BEGINLIBPATH" 1510b8851fccSafresh1 " and LIBPATHSTRICT" 1511b8851fccSafresh1 "\n\tso that the other copy is loaded via" 1512b8851fccSafresh1 BEGINLIBPATH."); 151309e75b67Smillert } 151409e75b67Smillert return handle; 151509e75b67Smillert } 151609e75b67Smillert 151709e75b67Smillert int 151809e75b67Smillert main(int argc, char **argv, char **env) 151909e75b67Smillert { 152009e75b67Smillert main_t f; 152109e75b67Smillert handler_t h; 152209e75b67Smillert 152309e75b67Smillert me = argv[0]; 152409e75b67Smillert /**/ 152509e75b67Smillert handle = load_perl_dll(PERL_DLL_BASENAME); 152609e75b67Smillert 1527b8851fccSafresh1 if (DosQueryProcAddr(handle, 1528b8851fccSafresh1 0, 1529b8851fccSafresh1 "Perl_OS2_handler_install", 1530b8851fccSafresh1 (PFN*)&h)) 1531b8851fccSafresh1 die_with(PERL_DLL_BASENAME, 1532b8851fccSafresh1 ": DLL exports no symbol ", 1533b8851fccSafresh1 "Perl_OS2_handler_install", 1534b8851fccSafresh1 ""); 153509e75b67Smillert if ( !h((void *)"~installprefix", Perlos2_handler_perllib_from) 153609e75b67Smillert || !h((void *)"~dll", Perlos2_handler_perllib_to) 153709e75b67Smillert || !h((void *)"~dll/sh/ksh.exe", Perlos2_handler_perl_sh) ) 1538b8851fccSafresh1 die_with(PERL_DLL_BASENAME, 1539b8851fccSafresh1 ": Can't install @INC manglers", 1540b8851fccSafresh1 "", 1541b8851fccSafresh1 ""); 154209e75b67Smillert if (DosQueryProcAddr(handle, 0, "dll_perlmain", (PFN*)&f)) 1543b8851fccSafresh1 die_with(PERL_DLL_BASENAME, 1544b8851fccSafresh1 ": DLL exports no symbol ", 1545b8851fccSafresh1 "dll_perlmain", 1546b8851fccSafresh1 ""); 154709e75b67Smillert return f(argc, argv, env); 154809e75b67Smillert } 154909e75b67Smillert 1550ba47ec9dSmillert=head1 Build FAQ 1551ba47ec9dSmillert 1552ba47ec9dSmillert=head2 Some C</> became C<\> in pdksh. 1553ba47ec9dSmillert 155448950c12SsthenYou have a very old pdksh. See L</Prerequisites>. 1555ba47ec9dSmillert 1556ba47ec9dSmillert=head2 C<'errno'> - unresolved external 1557ba47ec9dSmillert 155848950c12SsthenYou do not have MT-safe F<db.lib>. See L</Prerequisites>. 1559ba47ec9dSmillert 15606345ca90Smillert=head2 Problems with tr or sed 1561ba47ec9dSmillert 15626345ca90Smillertreported with very old version of tr and sed. 1563ba47ec9dSmillert 1564ba47ec9dSmillert=head2 Some problem (forget which ;-) 1565ba47ec9dSmillert 1566ba47ec9dSmillertYou have an older version of F<perl.dll> on your LIBPATH, which 1567ba47ec9dSmillertbroke the build of extensions. 1568ba47ec9dSmillert 1569ba47ec9dSmillert=head2 Library ... not found 1570ba47ec9dSmillert 157148950c12SsthenYou did not run C<omflibs>. See L</Prerequisites>. 1572ba47ec9dSmillert 1573ba47ec9dSmillert=head2 Segfault in make 1574ba47ec9dSmillert 157548950c12SsthenYou use an old version of GNU make. See L</Prerequisites>. 1576ba47ec9dSmillert 1577c5dcfd37Smillert=head2 op/sprintf test failure 1578c5dcfd37Smillert 1579c5dcfd37SmillertThis can result from a bug in emx sprintf which was fixed in 0.9d fix 03. 1580c5dcfd37Smillert 1581ba47ec9dSmillert=head1 Specific (mis)features of OS/2 port 1582ba47ec9dSmillert 1583ba47ec9dSmillert=head2 C<setpriority>, C<getpriority> 1584ba47ec9dSmillert 1585ba47ec9dSmillertNote that these functions are compatible with *nix, not with the older 1586ba47ec9dSmillertports of '94 - 95. The priorities are absolute, go from 32 to -95, 1587ba47ec9dSmillertlower is quicker. 0 is the default priority. 1588ba47ec9dSmillert 158979cd0b9aSmillertB<WARNING>. Calling C<getpriority> on a non-existing process could lock 159079cd0b9aSmillertthe system before Warp3 fixpak22. Starting with Warp3, Perl will use 159179cd0b9aSmillerta workaround: it aborts getpriority() if the process is not present. 159279cd0b9aSmillertThis is not possible on older versions C<2.*>, and has a race 159379cd0b9aSmillertcondition anyway. 1594c5dcfd37Smillert 1595ba47ec9dSmillert=head2 C<system()> 1596ba47ec9dSmillert 1597ba47ec9dSmillertMulti-argument form of C<system()> allows an additional numeric 1598ba47ec9dSmillertargument. The meaning of this argument is described in 1599ba47ec9dSmillertL<OS2::Process>. 1600ba47ec9dSmillert 1601c5dcfd37SmillertWhen finding a program to run, Perl first asks the OS to look for executables 160279cd0b9aSmillerton C<PATH> (OS/2 adds extension F<.exe> if no extension is present). 160379cd0b9aSmillertIf not found, it looks for a script with possible extensions 1604c5dcfd37Smillertadded in this order: no extension, F<.cmd>, F<.btm>, 1605c5dcfd37SmillertF<.bat>, F<.pl>. If found, Perl checks the start of the file for magic 1606c5dcfd37Smillertstrings C<"#!"> and C<"extproc ">. If found, Perl uses the rest of the 1607c5dcfd37Smillertfirst line as the beginning of the command line to run this script. The 1608c5dcfd37Smillertonly mangling done to the first line is extraction of arguments (currently 1609c5dcfd37Smillertup to 3), and ignoring of the path-part of the "interpreter" name if it can't 1610c5dcfd37Smillertbe found using the full path. 1611c5dcfd37Smillert 1612c5dcfd37SmillertE.g., C<system 'foo', 'bar', 'baz'> may lead Perl to finding 1613c5dcfd37SmillertF<C:/emx/bin/foo.cmd> with the first line being 1614c5dcfd37Smillert 1615c5dcfd37Smillert extproc /bin/bash -x -c 1616c5dcfd37Smillert 161779cd0b9aSmillertIf F</bin/bash.exe> is not found, then Perl looks for an executable F<bash.exe> on 1618c5dcfd37SmillertC<PATH>. If found in F<C:/emx.add/bin/bash.exe>, then the above system() is 1619c5dcfd37Smillerttranslated to 1620c5dcfd37Smillert 1621c5dcfd37Smillert system qw(C:/emx.add/bin/bash.exe -x -c C:/emx/bin/foo.cmd bar baz) 1622c5dcfd37Smillert 1623c5dcfd37SmillertOne additional translation is performed: instead of F</bin/sh> Perl uses 16249f11ffb7Safresh1the hardwired-or-customized shell (see L</"C<PERL_SH_DIR>">). 1625c5dcfd37Smillert 1626c5dcfd37SmillertThe above search for "interpreter" is recursive: if F<bash> executable is not 1627c5dcfd37Smillertfound, but F<bash.btm> is found, Perl will investigate its first line etc. 1628c5dcfd37SmillertThe only hardwired limit on the recursion depth is implicit: there is a limit 1629c5dcfd37Smillert4 on the number of additional arguments inserted before the actual arguments 1630c5dcfd37Smillertgiven to system(). In particular, if no additional arguments are specified 1631c5dcfd37Smillerton the "magic" first lines, then the limit on the depth is 4. 1632c5dcfd37Smillert 163379cd0b9aSmillertIf Perl finds that the found executable is of PM type when the 163479cd0b9aSmillertcurrent session is not, it will start the new process in a separate session of 1635c5dcfd37Smillertnecessary type. Call via C<OS2::Process> to disable this magic. 1636c5dcfd37Smillert 163779cd0b9aSmillertB<WARNING>. Due to the described logic, you need to explicitly 163879cd0b9aSmillertspecify F<.com> extension if needed. Moreover, if the executable 163979cd0b9aSmillertF<perl5.6.1> is requested, Perl will not look for F<perl5.6.1.exe>. 164079cd0b9aSmillert[This may change in the future.] 164179cd0b9aSmillert 1642ba47ec9dSmillert=head2 C<extproc> on the first line 1643ba47ec9dSmillert 1644c5dcfd37SmillertIf the first chars of a Perl script are C<"extproc ">, this line is treated 1645ba47ec9dSmillertas C<#!>-line, thus all the switches on this line are processed (twice 1646c5dcfd37Smillertif script was started via cmd.exe). See L<perlrun/DESCRIPTION>. 1647ba47ec9dSmillert 1648ba47ec9dSmillert=head2 Additional modules: 1649ba47ec9dSmillert 1650c5dcfd37SmillertL<OS2::Process>, L<OS2::DLL>, L<OS2::REXX>, L<OS2::PrfDB>, L<OS2::ExtAttr>. These 16516345ca90Smillertmodules provide access to additional numeric argument for C<system> 1652c5dcfd37Smillertand to the information about the running process, 1653c5dcfd37Smillertto DLLs having functions with REXX signature and to the REXX runtime, to 1654ba47ec9dSmillertOS/2 databases in the F<.INI> format, and to Extended Attributes. 1655ba47ec9dSmillert 1656ba47ec9dSmillertTwo additional extensions by Andreas Kaiser, C<OS2::UPM>, and 1657c5dcfd37SmillertC<OS2::FTP>, are included into C<ILYAZ> directory, mirrored on CPAN. 165879cd0b9aSmillertOther OS/2-related extensions are available too. 1659ba47ec9dSmillert 1660ba47ec9dSmillert=head2 Prebuilt methods: 1661ba47ec9dSmillert 1662ba47ec9dSmillert=over 4 1663ba47ec9dSmillert 1664ba47ec9dSmillert=item C<File::Copy::syscopy> 1665ba47ec9dSmillert 1666ba47ec9dSmillertused by C<File::Copy::copy>, see L<File::Copy>. 1667ba47ec9dSmillert 1668ba47ec9dSmillert=item C<DynaLoader::mod2fname> 1669ba47ec9dSmillert 1670ba47ec9dSmillertused by C<DynaLoader> for DLL name mangling. 1671ba47ec9dSmillert 1672ba47ec9dSmillert=item C<Cwd::current_drive()> 1673ba47ec9dSmillert 1674ba47ec9dSmillertSelf explanatory. 1675ba47ec9dSmillert 1676ba47ec9dSmillert=item C<Cwd::sys_chdir(name)> 1677ba47ec9dSmillert 1678ba47ec9dSmillertleaves drive as it is. 1679ba47ec9dSmillert 1680ba47ec9dSmillert=item C<Cwd::change_drive(name)> 1681ba47ec9dSmillert 168248950c12Ssthenchanges the "current" drive. 1683ba47ec9dSmillert 1684ba47ec9dSmillert=item C<Cwd::sys_is_absolute(name)> 1685ba47ec9dSmillert 1686ba47ec9dSmillertmeans has drive letter and is_rooted. 1687ba47ec9dSmillert 1688ba47ec9dSmillert=item C<Cwd::sys_is_rooted(name)> 1689ba47ec9dSmillert 1690ba47ec9dSmillertmeans has leading C<[/\\]> (maybe after a drive-letter:). 1691ba47ec9dSmillert 1692ba47ec9dSmillert=item C<Cwd::sys_is_relative(name)> 1693ba47ec9dSmillert 1694ba47ec9dSmillertmeans changes with current dir. 1695ba47ec9dSmillert 1696ba47ec9dSmillert=item C<Cwd::sys_cwd(name)> 1697ba47ec9dSmillert 1698ba47ec9dSmillertInterface to cwd from EMX. Used by C<Cwd::cwd>. 1699ba47ec9dSmillert 1700ba47ec9dSmillert=item C<Cwd::sys_abspath(name, dir)> 1701ba47ec9dSmillert 1702ba47ec9dSmillertReally really odious function to implement. Returns absolute name of 1703ba47ec9dSmillertfile which would have C<name> if CWD were C<dir>. C<Dir> defaults to the 1704ba47ec9dSmillertcurrent dir. 1705ba47ec9dSmillert 1706e2e5c5d3Smillert=item C<Cwd::extLibpath([type])> 1707ba47ec9dSmillert 1708ba47ec9dSmillertGet current value of extended library search path. If C<type> is 170979cd0b9aSmillertpresent and positive, works with C<END_LIBPATH>, if negative, works 171079cd0b9aSmillertwith C<LIBPATHSTRICT>, otherwise with C<BEGIN_LIBPATH>. 1711ba47ec9dSmillert 1712ba47ec9dSmillert=item C<Cwd::extLibpath_set( path [, type ] )> 1713ba47ec9dSmillert 1714ba47ec9dSmillertSet current value of extended library search path. If C<type> is 171579cd0b9aSmillertpresent and positive, works with <END_LIBPATH>, if negative, works 171679cd0b9aSmillertwith C<LIBPATHSTRICT>, otherwise with C<BEGIN_LIBPATH>. 1717ba47ec9dSmillert 1718c5dcfd37Smillert=item C<OS2::Error(do_harderror,do_exception)> 1719c5dcfd37Smillert 1720c5dcfd37SmillertReturns C<undef> if it was not called yet, otherwise bit 1 is 1721c5dcfd37Smillertset if on the previous call do_harderror was enabled, bit 172279cd0b9aSmillert2 is set if on previous call do_exception was enabled. 1723c5dcfd37Smillert 1724c5dcfd37SmillertThis function enables/disables error popups associated with 1725c5dcfd37Smillerthardware errors (Disk not ready etc.) and software exceptions. 1726c5dcfd37Smillert 1727c5dcfd37SmillertI know of no way to find out the state of popups I<before> the first call 1728c5dcfd37Smillertto this function. 1729c5dcfd37Smillert 1730c5dcfd37Smillert=item C<OS2::Errors2Drive(drive)> 1731c5dcfd37Smillert 1732c5dcfd37SmillertReturns C<undef> if it was not called yet, otherwise return false if errors 1733c5dcfd37Smillertwere not requested to be written to a hard drive, or the drive letter if 1734c5dcfd37Smillertthis was requested. 1735c5dcfd37Smillert 1736c5dcfd37SmillertThis function may redirect error popups associated with hardware errors 1737c5dcfd37Smillert(Disk not ready etc.) and software exceptions to the file POPUPLOG.OS2 at 1738c5dcfd37Smillertthe root directory of the specified drive. Overrides OS2::Error() specified 1739c5dcfd37Smillertby individual programs. Given argument undef will disable redirection. 1740c5dcfd37Smillert 1741c5dcfd37SmillertHas global effect, persists after the application exits. 1742c5dcfd37Smillert 1743c5dcfd37SmillertI know of no way to find out the state of redirection of popups to the disk 1744c5dcfd37SmillertI<before> the first call to this function. 1745c5dcfd37Smillert 1746c5dcfd37Smillert=item OS2::SysInfo() 1747c5dcfd37Smillert 1748c5dcfd37SmillertReturns a hash with system information. The keys of the hash are 1749c5dcfd37Smillert 1750c5dcfd37Smillert MAX_PATH_LENGTH, MAX_TEXT_SESSIONS, MAX_PM_SESSIONS, 1751c5dcfd37Smillert MAX_VDM_SESSIONS, BOOT_DRIVE, DYN_PRI_VARIATION, 1752c5dcfd37Smillert MAX_WAIT, MIN_SLICE, MAX_SLICE, PAGE_SIZE, 1753c5dcfd37Smillert VERSION_MAJOR, VERSION_MINOR, VERSION_REVISION, 1754c5dcfd37Smillert MS_COUNT, TIME_LOW, TIME_HIGH, TOTPHYSMEM, TOTRESMEM, 1755c5dcfd37Smillert TOTAVAILMEM, MAXPRMEM, MAXSHMEM, TIMER_INTERVAL, 1756c5dcfd37Smillert MAX_COMP_LENGTH, FOREGROUND_FS_SESSION, 1757c5dcfd37Smillert FOREGROUND_PROCESS 1758c5dcfd37Smillert 1759c5dcfd37Smillert=item OS2::BootDrive() 1760c5dcfd37Smillert 1761c5dcfd37SmillertReturns a letter without colon. 1762c5dcfd37Smillert 1763c5dcfd37Smillert=item C<OS2::MorphPM(serve)>, C<OS2::UnMorphPM(serve)> 1764c5dcfd37Smillert 1765c5dcfd37SmillertTransforms the current application into a PM application and back. 1766c5dcfd37SmillertThe argument true means that a real message loop is going to be served. 1767c5dcfd37SmillertOS2::MorphPM() returns the PM message queue handle as an integer. 1768c5dcfd37Smillert 17699f11ffb7Safresh1See L</"Centralized management of resources"> for additional details. 1770c5dcfd37Smillert 1771c5dcfd37Smillert=item C<OS2::Serve_Messages(force)> 1772c5dcfd37Smillert 1773c5dcfd37SmillertFake on-demand retrieval of outstanding PM messages. If C<force> is false, 1774c5dcfd37Smillertwill not dispatch messages if a real message loop is known to 1775c5dcfd37Smillertbe present. Returns number of messages retrieved. 1776c5dcfd37Smillert 1777c5dcfd37SmillertDies with "QUITing..." if WM_QUIT message is obtained. 1778c5dcfd37Smillert 1779c5dcfd37Smillert=item C<OS2::Process_Messages(force [, cnt])> 1780c5dcfd37Smillert 1781c5dcfd37SmillertRetrieval of PM messages until window creation/destruction. 1782c5dcfd37SmillertIf C<force> is false, will not dispatch messages if a real message loop 1783c5dcfd37Smillertis known to be present. 1784c5dcfd37Smillert 1785c5dcfd37SmillertReturns change in number of windows. If C<cnt> is given, 1786c5dcfd37Smillertit is incremented by the number of messages retrieved. 1787c5dcfd37Smillert 1788c5dcfd37SmillertDies with "QUITing..." if WM_QUIT message is obtained. 1789c5dcfd37Smillert 1790c5dcfd37Smillert=item C<OS2::_control87(new,mask)> 1791c5dcfd37Smillert 1792c5dcfd37Smillertthe same as L<_control87(3)> of EMX. Takes integers as arguments, returns 1793c5dcfd37Smillertthe previous coprocessor control word as an integer. Only bits in C<new> which 1794c5dcfd37Smillertare present in C<mask> are changed in the control word. 1795c5dcfd37Smillert 1796c5dcfd37Smillert=item OS2::get_control87() 1797c5dcfd37Smillert 1798c5dcfd37Smillertgets the coprocessor control word as an integer. 1799c5dcfd37Smillert 1800c5dcfd37Smillert=item C<OS2::set_control87_em(new=MCW_EM,mask=MCW_EM)> 1801c5dcfd37Smillert 1802c5dcfd37SmillertThe variant of OS2::_control87() with default values good for 1803c5dcfd37Smillerthandling exception mask: if no C<mask>, uses exception mask part of C<new> 1804c5dcfd37Smillertonly. If no C<new>, disables all the floating point exceptions. 1805c5dcfd37Smillert 18069f11ffb7Safresh1See L</"Misfeatures"> for details. 1807c5dcfd37Smillert 180879cd0b9aSmillert=item C<OS2::DLLname([how [, \&xsub]])> 180979cd0b9aSmillert 181079cd0b9aSmillertGives the information about the Perl DLL or the DLL containing the C 181179cd0b9aSmillertfunction bound to by C<&xsub>. The meaning of C<how> is: default (2): 181279cd0b9aSmillertfull name; 0: handle; 1: module name. 181379cd0b9aSmillert 1814ba47ec9dSmillert=back 1815ba47ec9dSmillert 1816ba47ec9dSmillert(Note that some of these may be moved to different libraries - 1817ba47ec9dSmillerteventually). 1818ba47ec9dSmillert 1819ba47ec9dSmillert 1820c5dcfd37Smillert=head2 Prebuilt variables: 1821c5dcfd37Smillert 1822c5dcfd37Smillert=over 4 1823c5dcfd37Smillert 1824c5dcfd37Smillert=item $OS2::emx_rev 1825c5dcfd37Smillert 182679cd0b9aSmillertnumeric value is the same as _emx_rev of EMX, a string value the same 182779cd0b9aSmillertas _emx_vprt (similar to C<0.9c>). 1828c5dcfd37Smillert 1829c5dcfd37Smillert=item $OS2::emx_env 1830c5dcfd37Smillert 1831c5dcfd37Smillertsame as _emx_env of EMX, a number similar to 0x8001. 1832c5dcfd37Smillert 1833c5dcfd37Smillert=item $OS2::os_ver 1834c5dcfd37Smillert 1835c5dcfd37Smillerta number C<OS_MAJOR + 0.001 * OS_MINOR>. 1836c5dcfd37Smillert 183779cd0b9aSmillert=item $OS2::is_aout 183879cd0b9aSmillert 183979cd0b9aSmillerttrue if the Perl library was compiled in AOUT format. 184079cd0b9aSmillert 184179cd0b9aSmillert=item $OS2::can_fork 184279cd0b9aSmillert 184379cd0b9aSmillerttrue if the current executable is an AOUT EMX executable, so Perl can 184479cd0b9aSmillertfork. Do not use this, use the portable check for 184579cd0b9aSmillert$Config::Config{dfork}. 184679cd0b9aSmillert 184779cd0b9aSmillert=item $OS2::nsyserror 184879cd0b9aSmillert 184979cd0b9aSmillertThis variable (default is 1) controls whether to enforce the contents 185079cd0b9aSmillertof $^E to start with C<SYS0003>-like id. If set to 0, then the string 185179cd0b9aSmillertvalue of $^E is what is available from the OS/2 message file. (Some 185279cd0b9aSmillertmessages in this file have an C<SYS0003>-like id prepended, some not.) 185379cd0b9aSmillert 1854c5dcfd37Smillert=back 1855c5dcfd37Smillert 1856ba47ec9dSmillert=head2 Misfeatures 1857ba47ec9dSmillert 1858ba47ec9dSmillert=over 4 1859ba47ec9dSmillert 1860c5dcfd37Smillert=item * 1861ba47ec9dSmillert 1862ba47ec9dSmillertSince L<flock(3)> is present in EMX, but is not functional, it is 1863ba47ec9dSmillertemulated by perl. To disable the emulations, set environment variable 1864ba47ec9dSmillertC<USE_PERL_FLOCK=0>. 1865ba47ec9dSmillert 1866c5dcfd37Smillert=item * 1867ba47ec9dSmillert 1868ba47ec9dSmillertHere is the list of things which may be "broken" on 1869ba47ec9dSmillertEMX (from EMX docs): 1870ba47ec9dSmillert 1871c5dcfd37Smillert=over 4 1872ba47ec9dSmillert 1873ba47ec9dSmillert=item * 1874ba47ec9dSmillert 1875ba47ec9dSmillertThe functions L<recvmsg(3)>, L<sendmsg(3)>, and L<socketpair(3)> are not 1876ba47ec9dSmillertimplemented. 1877ba47ec9dSmillert 1878ba47ec9dSmillert=item * 1879ba47ec9dSmillert 1880ba47ec9dSmillertL<sock_init(3)> is not required and not implemented. 1881ba47ec9dSmillert 1882ba47ec9dSmillert=item * 1883ba47ec9dSmillert 1884ba47ec9dSmillertL<flock(3)> is not yet implemented (dummy function). (Perl has a workaround.) 1885ba47ec9dSmillert 1886ba47ec9dSmillert=item * 1887ba47ec9dSmillert 1888ba47ec9dSmillertL<kill(3)>: Special treatment of PID=0, PID=1 and PID=-1 is not implemented. 1889ba47ec9dSmillert 1890ba47ec9dSmillert=item * 1891ba47ec9dSmillert 1892ba47ec9dSmillertL<waitpid(3)>: 1893ba47ec9dSmillert 1894ba47ec9dSmillert WUNTRACED 1895ba47ec9dSmillert Not implemented. 1896ba47ec9dSmillert waitpid() is not implemented for negative values of PID. 1897ba47ec9dSmillert 1898ba47ec9dSmillert=back 1899ba47ec9dSmillert 1900ba47ec9dSmillertNote that C<kill -9> does not work with the current version of EMX. 1901ba47ec9dSmillert 1902c5dcfd37Smillert=item * 1903ba47ec9dSmillert 19049f11ffb7Safresh1See L</"Text-mode filehandles">. 1905ba47ec9dSmillert 1906c5dcfd37Smillert=item * 1907c5dcfd37Smillert 1908c5dcfd37SmillertUnix-domain sockets on OS/2 live in a pseudo-file-system C</sockets/...>. 1909c5dcfd37SmillertTo avoid a failure to create a socket with a name of a different form, 1910c5dcfd37SmillertC<"/socket/"> is prepended to the socket name (unless it starts with this 1911c5dcfd37Smillertalready). 1912c5dcfd37Smillert 1913c5dcfd37SmillertThis may lead to problems later in case the socket is accessed via the 1914c5dcfd37Smillert"usual" file-system calls using the "initial" name. 1915c5dcfd37Smillert 1916c5dcfd37Smillert=item * 1917c5dcfd37Smillert 1918c5dcfd37SmillertApparently, IBM used a compiler (for some period of time around '95?) which 1919c5dcfd37Smillertchanges FP mask right and left. This is not I<that> bad for IBM's 1920c5dcfd37Smillertprograms, but the same compiler was used for DLLs which are used with 1921c5dcfd37Smillertgeneral-purpose applications. When these DLLs are used, the state of 1922c5dcfd37Smillertfloating-point flags in the application is not predictable. 1923c5dcfd37Smillert 1924c5dcfd37SmillertWhat is much worse, some DLLs change the floating point flags when in 1925c5dcfd37Smillert_DLLInitTerm() (e.g., F<TCP32IP>). This means that even if you do not I<call> 1926c5dcfd37Smillertany function in the DLL, just the act of loading this DLL will reset your 1927c5dcfd37Smillertflags. What is worse, the same compiler was used to compile some HOOK DLLs. 1928c5dcfd37SmillertGiven that HOOK dlls are executed in the context of I<all> the applications 192948950c12Ssthenin the system, this means a complete unpredictability of floating point 1930c5dcfd37Smillertflags on systems using such HOOK DLLs. E.g., F<GAMESRVR.DLL> of B<DIVE> 1931c5dcfd37Smillertorigin changes the floating point flags on each write to the TTY of a VIO 1932c5dcfd37Smillert(windowed text-mode) applications. 1933c5dcfd37Smillert 1934c5dcfd37SmillertSome other (not completely debugged) situations when FP flags change include 1935c5dcfd37Smillertsome video drivers (?), and some operations related to creation of the windows. 1936c5dcfd37SmillertPeople who code B<OpenGL> may have more experience on this. 1937c5dcfd37Smillert 1938c5dcfd37SmillertPerl is generally used in the situation when all the floating-point 1939c5dcfd37Smillertexceptions are ignored, as is the default under EMX. If they are not ignored, 1940c5dcfd37Smillertsome benign Perl programs would get a C<SIGFPE> and would die a horrible death. 1941c5dcfd37Smillert 1942c5dcfd37SmillertTo circumvent this, Perl uses two hacks. They help against I<one> type of 1943c5dcfd37Smillertdamage only: FP flags changed when loading a DLL. 1944c5dcfd37Smillert 194579cd0b9aSmillertOne of the hacks is to disable floating point exceptions on Perl startup (as 1946c5dcfd37Smillertis the default with EMX). This helps only with compile-time-linked DLLs 1947c5dcfd37Smillertchanging the flags before main() had a chance to be called. 1948c5dcfd37Smillert 1949c5dcfd37SmillertThe other hack is to restore FP flags after a call to dlopen(). This helps 1950c5dcfd37Smillertagainst similar damage done by DLLs _DLLInitTerm() at runtime. Currently 1951c5dcfd37Smillertno way to switch these hacks off is provided. 1952c5dcfd37Smillert 1953ba47ec9dSmillert=back 1954ba47ec9dSmillert 1955ba47ec9dSmillert=head2 Modifications 1956ba47ec9dSmillert 1957ba47ec9dSmillertPerl modifies some standard C library calls in the following ways: 1958ba47ec9dSmillert 1959ba47ec9dSmillert=over 9 1960ba47ec9dSmillert 1961ba47ec9dSmillert=item C<popen> 1962ba47ec9dSmillert 19639f11ffb7Safresh1C<my_popen> uses F<sh.exe> if shell is required, cf. L</"C<PERL_SH_DIR>">. 1964ba47ec9dSmillert 1965ba47ec9dSmillert=item C<tmpnam> 1966ba47ec9dSmillert 1967ba47ec9dSmillertis created using C<TMP> or C<TEMP> environment variable, via 1968ba47ec9dSmillertC<tempnam>. 1969ba47ec9dSmillert 1970ba47ec9dSmillert=item C<tmpfile> 1971ba47ec9dSmillert 1972ba47ec9dSmillertIf the current directory is not writable, file is created using modified 1973ba47ec9dSmillertC<tmpnam>, so there may be a race condition. 1974ba47ec9dSmillert 1975ba47ec9dSmillert=item C<ctermid> 1976ba47ec9dSmillert 1977ba47ec9dSmillerta dummy implementation. 1978ba47ec9dSmillert 1979ba47ec9dSmillert=item C<stat> 1980ba47ec9dSmillert 1981ba47ec9dSmillertC<os2_stat> special-cases F</dev/tty> and F</dev/con>. 1982ba47ec9dSmillert 1983c5dcfd37Smillert=item C<mkdir>, C<rmdir> 1984c5dcfd37Smillert 1985c5dcfd37Smillertthese EMX functions do not work if the path contains a trailing C</>. 1986c5dcfd37SmillertPerl contains a workaround for this. 1987c5dcfd37Smillert 1988ba47ec9dSmillert=item C<flock> 1989ba47ec9dSmillert 1990ba47ec9dSmillertSince L<flock(3)> is present in EMX, but is not functional, it is 1991ba47ec9dSmillertemulated by perl. To disable the emulations, set environment variable 1992ba47ec9dSmillertC<USE_PERL_FLOCK=0>. 1993ba47ec9dSmillert 1994ba47ec9dSmillert=back 1995ba47ec9dSmillert 1996c5dcfd37Smillert=head2 Identifying DLLs 1997c5dcfd37Smillert 1998c5dcfd37SmillertAll the DLLs built with the current versions of Perl have ID strings 1999c5dcfd37Smillertidentifying the name of the extension, its version, and the version 2000c5dcfd37Smillertof Perl required for this DLL. Run C<bldlevel DLL-name> to find this 2001c5dcfd37Smillertinfo. 2002c5dcfd37Smillert 2003c5dcfd37Smillert=head2 Centralized management of resources 2004c5dcfd37Smillert 2005c5dcfd37SmillertSince to call certain OS/2 API one needs to have a correctly initialized 2006c5dcfd37SmillertC<Win> subsystem, OS/2-specific extensions may require getting C<HAB>s and 2007c5dcfd37SmillertC<HMQ>s. If an extension would do it on its own, another extension could 2008c5dcfd37Smillertfail to initialize. 2009c5dcfd37Smillert 2010c5dcfd37SmillertPerl provides a centralized management of these resources: 2011c5dcfd37Smillert 2012c5dcfd37Smillert=over 2013c5dcfd37Smillert 2014c5dcfd37Smillert=item C<HAB> 2015c5dcfd37Smillert 2016c5dcfd37SmillertTo get the HAB, the extension should call C<hab = perl_hab_GET()> in C. After 2017c5dcfd37Smillertthis call is performed, C<hab> may be accessed as C<Perl_hab>. There is 2018c5dcfd37Smillertno need to release the HAB after it is used. 2019c5dcfd37Smillert 2020c5dcfd37SmillertIf by some reasons F<perl.h> cannot be included, use 2021c5dcfd37Smillert 2022c5dcfd37Smillert extern int Perl_hab_GET(void); 2023c5dcfd37Smillert 2024c5dcfd37Smillertinstead. 2025c5dcfd37Smillert 2026c5dcfd37Smillert=item C<HMQ> 2027c5dcfd37Smillert 2028c5dcfd37SmillertThere are two cases: 2029c5dcfd37Smillert 2030c5dcfd37Smillert=over 2031c5dcfd37Smillert 2032c5dcfd37Smillert=item * 2033c5dcfd37Smillert 2034c5dcfd37Smillertthe extension needs an C<HMQ> only because some API will not work otherwise. 2035c5dcfd37SmillertUse C<serve = 0> below. 2036c5dcfd37Smillert 2037c5dcfd37Smillert=item * 2038c5dcfd37Smillert 2039c5dcfd37Smillertthe extension needs an C<HMQ> since it wants to engage in a PM event loop. 2040c5dcfd37SmillertUse C<serve = 1> below. 2041c5dcfd37Smillert 2042c5dcfd37Smillert=back 2043c5dcfd37Smillert 2044c5dcfd37SmillertTo get an C<HMQ>, the extension should call C<hmq = perl_hmq_GET(serve)> in C. 2045c5dcfd37SmillertAfter this call is performed, C<hmq> may be accessed as C<Perl_hmq>. 2046c5dcfd37Smillert 2047c5dcfd37SmillertTo signal to Perl that HMQ is not needed any more, call 2048c5dcfd37SmillertC<perl_hmq_UNSET(serve)>. Perl process will automatically morph/unmorph itself 2049c5dcfd37Smillertinto/from a PM process if HMQ is needed/not-needed. Perl will automatically 2050c5dcfd37Smillertenable/disable C<WM_QUIT> message during shutdown if the message queue is 2051c5dcfd37Smillertserved/not-served. 2052c5dcfd37Smillert 2053c5dcfd37SmillertB<NOTE>. If during a shutdown there is a message queue which did not disable 2054c5dcfd37SmillertWM_QUIT, and which did not process the received WM_QUIT message, the 2055c5dcfd37Smillertshutdown will be automatically cancelled. Do not call C<perl_hmq_GET(1)> 2056c5dcfd37Smillertunless you are going to process messages on an orderly basis. 2057c5dcfd37Smillert 205848950c12Ssthen=item Treating errors reported by OS/2 API 205979cd0b9aSmillert 206079cd0b9aSmillertThere are two principal conventions (it is useful to call them C<Dos*> 206179cd0b9aSmillertand C<Win*> - though this part of the function signature is not always 206279cd0b9aSmillertdetermined by the name of the API) of reporting the error conditions 206379cd0b9aSmillertof OS/2 API. Most of C<Dos*> APIs report the error code as the result 206479cd0b9aSmillertof the call (so 0 means success, and there are many types of errors). 206579cd0b9aSmillertMost of C<Win*> API report success/fail via the result being 206679cd0b9aSmillertC<TRUE>/C<FALSE>; to find the reason for the failure one should call 206779cd0b9aSmillertWinGetLastError() API. 206879cd0b9aSmillert 206979cd0b9aSmillertSome C<Win*> entry points also overload a "meaningful" return value 207079cd0b9aSmillertwith the error indicator; having a 0 return value indicates an error. 207179cd0b9aSmillertYet some other C<Win*> entry points overload things even more, and 0 207279cd0b9aSmillertreturn value may mean a successful call returning a valid value 0, as 207379cd0b9aSmillertwell as an error condition; in the case of a 0 return value one should 207479cd0b9aSmillertcall WinGetLastError() API to distinguish a successful call from a 207579cd0b9aSmillertfailing one. 207679cd0b9aSmillert 207779cd0b9aSmillertBy convention, all the calls to OS/2 API should indicate their 207879cd0b9aSmillertfailures by resetting $^E. All the Perl-accessible functions which 207979cd0b9aSmillertcall OS/2 API may be broken into two classes: some die()s when an API 208079cd0b9aSmillerterror is encountered, the other report the error via a false return 208179cd0b9aSmillertvalue (of course, this does not concern Perl-accessible functions 208279cd0b9aSmillertwhich I<expect> a failure of the OS/2 API call, having some workarounds 208379cd0b9aSmillertcoded). 208479cd0b9aSmillert 208579cd0b9aSmillertObviously, in the situation of the last type of the signature of an OS/2 208679cd0b9aSmillertAPI, it is must more convenient for the users if the failure is 208779cd0b9aSmillertindicated by die()ing: one does not need to check $^E to know that 208879cd0b9aSmillertsomething went wrong. If, however, this solution is not desirable by 208979cd0b9aSmillertsome reason, the code in question should reset $^E to 0 before making 209079cd0b9aSmillertthis OS/2 API call, so that the caller of this Perl-accessible 209179cd0b9aSmillertfunction has a chance to distinguish a success-but-0-return value from 209279cd0b9aSmillerta failure. (One may return undef as an alternative way of reporting 209379cd0b9aSmillertan error.) 209479cd0b9aSmillert 209579cd0b9aSmillertThe macros to simplify this type of error propagation are 209679cd0b9aSmillert 209779cd0b9aSmillert=over 209879cd0b9aSmillert 209979cd0b9aSmillert=item C<CheckOSError(expr)> 210079cd0b9aSmillert 210179cd0b9aSmillertReturns true on error, sets $^E. Expects expr() be a call of 210279cd0b9aSmillertC<Dos*>-style API. 210379cd0b9aSmillert 210479cd0b9aSmillert=item C<CheckWinError(expr)> 210579cd0b9aSmillert 210679cd0b9aSmillertReturns true on error, sets $^E. Expects expr() be a call of 210779cd0b9aSmillertC<Win*>-style API. 210879cd0b9aSmillert 210979cd0b9aSmillert=item C<SaveWinError(expr)> 211079cd0b9aSmillert 211179cd0b9aSmillertReturns C<expr>, sets $^E from WinGetLastError() if C<expr> is false. 211279cd0b9aSmillert 211379cd0b9aSmillert=item C<SaveCroakWinError(expr,die,name1,name2)> 211479cd0b9aSmillert 211579cd0b9aSmillertReturns C<expr>, sets $^E from WinGetLastError() if C<expr> is false, 211679cd0b9aSmillertand die()s if C<die> and $^E are true. The message to die is the 211779cd0b9aSmillertconcatenated strings C<name1> and C<name2>, separated by C<": "> from 211879cd0b9aSmillertthe contents of $^E. 211979cd0b9aSmillert 212079cd0b9aSmillert=item C<WinError_2_Perl_rc> 212179cd0b9aSmillert 212279cd0b9aSmillertSets C<Perl_rc> to the return value of WinGetLastError(). 212379cd0b9aSmillert 212479cd0b9aSmillert=item C<FillWinError> 212579cd0b9aSmillert 212679cd0b9aSmillertSets C<Perl_rc> to the return value of WinGetLastError(), and sets $^E 212779cd0b9aSmillertto the corresponding value. 212879cd0b9aSmillert 212979cd0b9aSmillert=item C<FillOSError(rc)> 213079cd0b9aSmillert 213179cd0b9aSmillertSets C<Perl_rc> to C<rc>, and sets $^E to the corresponding value. 213279cd0b9aSmillert 213379cd0b9aSmillert=back 213479cd0b9aSmillert 213548950c12Ssthen=item Loading DLLs and ordinals in DLLs 213679cd0b9aSmillert 213779cd0b9aSmillertSome DLLs are only present in some versions of OS/2, or in some 213879cd0b9aSmillertconfigurations of OS/2. Some exported entry points are present only 213979cd0b9aSmillertin DLLs shipped with some versions of OS/2. If these DLLs and entry 214079cd0b9aSmillertpoints were linked directly for a Perl executable/DLL or from a Perl 214179cd0b9aSmillertextensions, this binary would work only with the specified 214279cd0b9aSmillertversions/setups. Even if these entry points were not needed, the 214379cd0b9aSmillertI<load> of the executable (or DLL) would fail. 214479cd0b9aSmillert 214579cd0b9aSmillertFor example, many newer useful APIs are not present in OS/2 v2; many 214679cd0b9aSmillertPM-related APIs require DLLs not available on floppy-boot setup. 214779cd0b9aSmillert 214879cd0b9aSmillertTo make these calls fail I<only when the calls are executed>, one 214979cd0b9aSmillertshould call these API via a dynamic linking API. There is a subsystem 215079cd0b9aSmillertin Perl to simplify such type of calls. A large number of entry 215179cd0b9aSmillertpoints available for such linking is provided (see C<entries_ordinals> 215279cd0b9aSmillert- and also C<PMWIN_entries> - in F<os2ish.h>). These ordinals can be 215379cd0b9aSmillertaccessed via the APIs: 215479cd0b9aSmillert 215579cd0b9aSmillert CallORD(), DeclFuncByORD(), DeclVoidFuncByORD(), 215679cd0b9aSmillert DeclOSFuncByORD(), DeclWinFuncByORD(), AssignFuncPByORD(), 215779cd0b9aSmillert DeclWinFuncByORD_CACHE(), DeclWinFuncByORD_CACHE_survive(), 215879cd0b9aSmillert DeclWinFuncByORD_CACHE_resetError_survive(), 215979cd0b9aSmillert DeclWinFunc_CACHE(), DeclWinFunc_CACHE_resetError(), 216079cd0b9aSmillert DeclWinFunc_CACHE_survive(), DeclWinFunc_CACHE_resetError_survive() 216179cd0b9aSmillert 216279cd0b9aSmillertSee the header files and the C code in the supplied OS/2-related 216379cd0b9aSmillertmodules for the details on usage of these functions. 216479cd0b9aSmillert 216579cd0b9aSmillertSome of these functions also combine dynaloading semantic with the 216679cd0b9aSmillerterror-propagation semantic discussed above. 216779cd0b9aSmillert 2168c5dcfd37Smillert=back 2169c5dcfd37Smillert 2170ba47ec9dSmillert=head1 Perl flavors 2171ba47ec9dSmillert 2172ba47ec9dSmillertBecause of idiosyncrasies of OS/2 one cannot have all the eggs in the 2173ba47ec9dSmillertsame basket (though EMX environment tries hard to overcome this 2174ba47ec9dSmillertlimitations, so the situation may somehow improve). There are 4 2175ba47ec9dSmillertexecutables for Perl provided by the distribution: 2176ba47ec9dSmillert 2177ba47ec9dSmillert=head2 F<perl.exe> 2178ba47ec9dSmillert 2179ba47ec9dSmillertThe main workhorse. This is a chimera executable: it is compiled as an 2180ba47ec9dSmillertC<a.out>-style executable, but is linked with C<omf>-style dynamic 2181ba47ec9dSmillertlibrary F<perl.dll>, and with dynamic CRT DLL. This executable is a 2182ba47ec9dSmillertVIO application. 2183ba47ec9dSmillert 2184c5dcfd37SmillertIt can load perl dynamic extensions, and it can fork(). 2185ba47ec9dSmillert 2186ba47ec9dSmillertB<Note.> Keep in mind that fork() is needed to open a pipe to yourself. 2187ba47ec9dSmillert 2188ba47ec9dSmillert=head2 F<perl_.exe> 2189ba47ec9dSmillert 2190c5dcfd37SmillertThis is a statically linked C<a.out>-style executable. It cannot 2191c5dcfd37Smillertload dynamic Perl extensions. The executable supplied in binary 2192c5dcfd37Smillertdistributions has a lot of extensions prebuilt, thus the above restriction is 2193c5dcfd37Smillertimportant only if you use custom-built extensions. This executable is a VIO 2194ba47ec9dSmillertapplication. 2195ba47ec9dSmillert 2196c5dcfd37SmillertI<This is the only executable with does not require OS/2.> The 2197ba47ec9dSmillertfriends locked into C<M$> world would appreciate the fact that this 2198ba47ec9dSmillertexecutable runs under DOS, Win0.3*, Win0.95 and WinNT with an 21999f11ffb7Safresh1appropriate extender. See L</"Other OSes">. 2200ba47ec9dSmillert 2201ba47ec9dSmillert=head2 F<perl__.exe> 2202ba47ec9dSmillert 2203ba47ec9dSmillertThis is the same executable as F<perl___.exe>, but it is a PM 2204ba47ec9dSmillertapplication. 2205ba47ec9dSmillert 2206c5dcfd37SmillertB<Note.> Usually (unless explicitly redirected during the startup) 2207c5dcfd37SmillertSTDIN, STDERR, and STDOUT of a PM 2208c5dcfd37Smillertapplication are redirected to F<nul>. However, it is possible to I<see> 2209ba47ec9dSmillertthem if you start C<perl__.exe> from a PM program which emulates a 2210ba47ec9dSmillertconsole window, like I<Shell mode> of Emacs or EPM. Thus it I<is 2211ba47ec9dSmillertpossible> to use Perl debugger (see L<perldebug>) to debug your PM 2212c5dcfd37Smillertapplication (but beware of the message loop lockups - this will not 2213c5dcfd37Smillertwork if you have a message queue to serve, unless you hook the serving 2214c5dcfd37Smillertinto the getc() function of the debugger). 2215ba47ec9dSmillert 2216c5dcfd37SmillertAnother way to see the output of a PM program is to run it as 2217c5dcfd37Smillert 2218c5dcfd37Smillert pm_prog args 2>&1 | cat - 2219c5dcfd37Smillert 2220c5dcfd37Smillertwith a shell I<different> from F<cmd.exe>, so that it does not create 2221c5dcfd37Smillerta link between a VIO session and the session of C<pm_porg>. (Such a link 2222c5dcfd37Smillertcloses the VIO window.) E.g., this works with F<sh.exe> - or with Perl! 2223c5dcfd37Smillert 2224c5dcfd37Smillert open P, 'pm_prog args 2>&1 |' or die; 2225c5dcfd37Smillert print while <P>; 2226c5dcfd37Smillert 2227c5dcfd37SmillertThe flavor F<perl__.exe> is required if you want to start your program without 2228c5dcfd37Smillerta VIO window present, but not C<detach>ed (run C<help detach> for more info). 2229c5dcfd37SmillertVery useful for extensions which use PM, like C<Perl/Tk> or C<OpenGL>. 2230ba47ec9dSmillert 223179cd0b9aSmillertNote also that the differences between PM and VIO executables are only 223279cd0b9aSmillertin the I<default> behaviour. One can start I<any> executable in 223379cd0b9aSmillertI<any> kind of session by using the arguments C</fs>, C</pm> or 223479cd0b9aSmillertC</win> switches of the command C<start> (of F<CMD.EXE> or a similar 223579cd0b9aSmillertshell). Alternatively, one can use the numeric first argument of the 2236ad15181aSmillertC<system> Perl function (see L<OS2::Process>). 223779cd0b9aSmillert 2238ba47ec9dSmillert=head2 F<perl___.exe> 2239ba47ec9dSmillert 2240ba47ec9dSmillertThis is an C<omf>-style executable which is dynamically linked to 2241ba47ec9dSmillertF<perl.dll> and CRT DLL. I know no advantages of this executable 2242ba47ec9dSmillertover C<perl.exe>, but it cannot fork() at all. Well, one advantage is 2243ba47ec9dSmillertthat the build process is not so convoluted as with C<perl.exe>. 2244ba47ec9dSmillert 2245ba47ec9dSmillertIt is a VIO application. 2246ba47ec9dSmillert 2247ba47ec9dSmillert=head2 Why strange names? 2248ba47ec9dSmillert 2249ba47ec9dSmillertSince Perl processes the C<#!>-line (cf. 225048950c12SsthenL<perlrun/DESCRIPTION>, L<perlrun/Command Switches>, 2251ba47ec9dSmillertL<perldiag/"No Perl script found in input">), it should know when a 2252ba47ec9dSmillertprogram I<is a Perl>. There is some naming convention which allows 2253ba47ec9dSmillertPerl to distinguish correct lines from wrong ones. The above names are 2254ba47ec9dSmillertalmost the only names allowed by this convention which do not contain 2255ba47ec9dSmillertdigits (which have absolutely different semantics). 2256ba47ec9dSmillert 2257ba47ec9dSmillert=head2 Why dynamic linking? 2258ba47ec9dSmillert 2259ba47ec9dSmillertWell, having several executables dynamically linked to the same huge 2260ba47ec9dSmillertlibrary has its advantages, but this would not substantiate the 2261c5dcfd37Smillertadditional work to make it compile. The reason is the complicated-to-developers 2262c5dcfd37Smillertbut very quick and convenient-to-users "hard" dynamic linking used by OS/2. 2263c5dcfd37Smillert 2264c5dcfd37SmillertThere are two distinctive features of the dyna-linking model of OS/2: 226579cd0b9aSmillertfirst, all the references to external functions are resolved at the compile time; 226679cd0b9aSmillertsecond, there is no runtime fixup of the DLLs after they are loaded into memory. 2267c5dcfd37SmillertThe first feature is an enormous advantage over other models: it avoids 2268c5dcfd37Smillertconflicts when several DLLs used by an application export entries with 2269c5dcfd37Smillertthe same name. In such cases "other" models of dyna-linking just choose 2270c5dcfd37Smillertbetween these two entry points using some random criterion - with predictable 2271c5dcfd37Smillertdisasters as results. But it is the second feature which requires the build 2272c5dcfd37Smillertof F<perl.dll>. 2273ba47ec9dSmillert 2274ba47ec9dSmillertThe address tables of DLLs are patched only once, when they are 2275c5dcfd37Smillertloaded. The addresses of the entry points into DLLs are guaranteed to be 2276c5dcfd37Smillertthe same for all the programs which use the same DLL. This removes the 2277c5dcfd37Smillertruntime fixup - once DLL is loaded, its code is read-only. 2278ba47ec9dSmillert 2279c5dcfd37SmillertWhile this allows some (significant?) performance advantages, this makes life 2280c5dcfd37Smillertmuch harder for developers, since the above scheme makes it impossible 2281c5dcfd37Smillertfor a DLL to be "linked" to a symbol in the F<.EXE> file. Indeed, this 2282ba47ec9dSmillertwould need a DLL to have different relocations tables for the 2283c5dcfd37Smillert(different) executables which use this DLL. 2284ba47ec9dSmillert 2285c5dcfd37SmillertHowever, a dynamically loaded Perl extension is forced to use some symbols 2286c5dcfd37Smillertfrom the perl 2287c5dcfd37Smillertexecutable, e.g., to know how to find the arguments to the functions: 2288c5dcfd37Smillertthe arguments live on the perl 2289c5dcfd37Smillertinternal evaluation stack. The solution is to put the main code of 2290c5dcfd37Smillertthe interpreter into a DLL, and make the F<.EXE> file which just loads 2291c5dcfd37Smillertthis DLL into memory and supplies command-arguments. The extension DLL 2292c5dcfd37Smillertcannot link to symbols in F<.EXE>, but it has no problem linking 2293c5dcfd37Smillertto symbols in the F<.DLL>. 2294ba47ec9dSmillert 2295ba47ec9dSmillertThis I<greatly> increases the load time for the application (as well as 2296c5dcfd37Smillertcomplexity of the compilation). Since interpreter is in a DLL, 2297c5dcfd37Smillertthe C RTL is basically forced to reside in a DLL as well (otherwise 2298c5dcfd37Smillertextensions would not be able to use CRT). There are some advantages if 2299c5dcfd37Smillertyou use different flavors of perl, such as running F<perl.exe> and 2300c5dcfd37SmillertF<perl__.exe> simultaneously: they share the memory of F<perl.dll>. 2301c5dcfd37Smillert 2302c5dcfd37SmillertB<NOTE>. There is one additional effect which makes DLLs more wasteful: 2303c5dcfd37SmillertDLLs are loaded in the shared memory region, which is a scarse resource 2304c5dcfd37Smillertgiven the 512M barrier of the "standard" OS/2 virtual memory. The code of 2305c5dcfd37SmillertF<.EXE> files is also shared by all the processes which use the particular 2306c5dcfd37SmillertF<.EXE>, but they are "shared in the private address space of the process"; 2307c5dcfd37Smillertthis is possible because the address at which different sections 2308c5dcfd37Smillertof the F<.EXE> file are loaded is decided at compile-time, thus all the 2309c5dcfd37Smillertprocesses have these sections loaded at same addresses, and no fixup 2310c5dcfd37Smillertof internal links inside the F<.EXE> is needed. 2311c5dcfd37Smillert 231279cd0b9aSmillertSince DLLs may be loaded at run time, to have the same mechanism for DLLs 2313c5dcfd37Smillertone needs to have the address range of I<any of the loaded> DLLs in the 2314c5dcfd37Smillertsystem to be available I<in all the processes> which did not load a particular 2315c5dcfd37SmillertDLL yet. This is why the DLLs are mapped to the shared memory region. 2316ba47ec9dSmillert 2317ba47ec9dSmillert=head2 Why chimera build? 2318ba47ec9dSmillert 2319ba47ec9dSmillertCurrent EMX environment does not allow DLLs compiled using Unixish 2320c5dcfd37SmillertC<a.out> format to export symbols for data (or at least some types of 2321c5dcfd37Smillertdata). This forces C<omf>-style compile of F<perl.dll>. 2322ba47ec9dSmillert 2323ba47ec9dSmillertCurrent EMX environment does not allow F<.EXE> files compiled in 2324ba47ec9dSmillertC<omf> format to fork(). fork() is needed for exactly three Perl 2325ba47ec9dSmillertoperations: 2326ba47ec9dSmillert 2327ba47ec9dSmillert=over 4 2328ba47ec9dSmillert 2329c5dcfd37Smillert=item * 2330ba47ec9dSmillert 2331c5dcfd37Smillertexplicit fork() in the script, 2332ba47ec9dSmillert 2333c5dcfd37Smillert=item * 2334ba47ec9dSmillert 2335c5dcfd37SmillertC<open FH, "|-"> 2336ba47ec9dSmillert 2337c5dcfd37Smillert=item * 2338c5dcfd37Smillert 2339c5dcfd37SmillertC<open FH, "-|">, in other words, opening pipes to itself. 2340ba47ec9dSmillert 2341ba47ec9dSmillert=back 2342ba47ec9dSmillert 2343c5dcfd37SmillertWhile these operations are not questions of life and death, they are 2344c5dcfd37Smillertneeded for a lot of 2345c5dcfd37Smillertuseful scripts. This forces C<a.out>-style compile of 2346ba47ec9dSmillertF<perl.exe>. 2347ba47ec9dSmillert 2348ba47ec9dSmillert 2349ba47ec9dSmillert=head1 ENVIRONMENT 2350ba47ec9dSmillert 2351ba47ec9dSmillertHere we list environment variables with are either OS/2- and DOS- and 2352ba47ec9dSmillertWin*-specific, or are more important under OS/2 than under other OSes. 2353ba47ec9dSmillert 2354ba47ec9dSmillert=head2 C<PERLLIB_PREFIX> 2355ba47ec9dSmillert 2356ba47ec9dSmillertSpecific for EMX port. Should have the form 2357ba47ec9dSmillert 2358ba47ec9dSmillert path1;path2 2359ba47ec9dSmillert 2360ba47ec9dSmillertor 2361ba47ec9dSmillert 2362ba47ec9dSmillert path1 path2 2363ba47ec9dSmillert 2364ba47ec9dSmillertIf the beginning of some prebuilt path matches F<path1>, it is 2365ba47ec9dSmillertsubstituted with F<path2>. 2366ba47ec9dSmillert 2367ba47ec9dSmillertShould be used if the perl library is moved from the default 2368ba47ec9dSmillertlocation in preference to C<PERL(5)LIB>, since this would not leave wrong 2369c5dcfd37Smillertentries in @INC. For example, if the compiled version of perl looks for @INC 2370ba47ec9dSmillertin F<f:/perllib/lib>, and you want to install the library in 2371ba47ec9dSmillertF<h:/opt/gnu>, do 2372ba47ec9dSmillert 2373ba47ec9dSmillert set PERLLIB_PREFIX=f:/perllib/lib;h:/opt/gnu 2374ba47ec9dSmillert 2375c5dcfd37SmillertThis will cause Perl with the prebuilt @INC of 2376c5dcfd37Smillert 2377c5dcfd37Smillert f:/perllib/lib/5.00553/os2 2378c5dcfd37Smillert f:/perllib/lib/5.00553 2379c5dcfd37Smillert f:/perllib/lib/site_perl/5.00553/os2 2380c5dcfd37Smillert f:/perllib/lib/site_perl/5.00553 2381c5dcfd37Smillert . 2382c5dcfd37Smillert 2383c5dcfd37Smillertto use the following @INC: 2384c5dcfd37Smillert 2385c5dcfd37Smillert h:/opt/gnu/5.00553/os2 2386c5dcfd37Smillert h:/opt/gnu/5.00553 2387c5dcfd37Smillert h:/opt/gnu/site_perl/5.00553/os2 2388c5dcfd37Smillert h:/opt/gnu/site_perl/5.00553 2389c5dcfd37Smillert . 2390c5dcfd37Smillert 2391ba47ec9dSmillert=head2 C<PERL_BADLANG> 2392ba47ec9dSmillert 2393c5dcfd37SmillertIf 0, perl ignores setlocale() failing. May be useful with some 2394ba47ec9dSmillertstrange I<locale>s. 2395ba47ec9dSmillert 2396ba47ec9dSmillert=head2 C<PERL_BADFREE> 2397ba47ec9dSmillert 2398c5dcfd37SmillertIf 0, perl would not warn of in case of unwarranted free(). With older 2399c5dcfd37Smillertperls this might be 2400c5dcfd37Smillertuseful in conjunction with the module DB_File, which was buggy when 2401c5dcfd37Smillertdynamically linked and OMF-built. 2402c5dcfd37Smillert 2403c5dcfd37SmillertShould not be set with newer Perls, since this may hide some I<real> problems. 2404ba47ec9dSmillert 2405ba47ec9dSmillert=head2 C<PERL_SH_DIR> 2406ba47ec9dSmillert 2407ba47ec9dSmillertSpecific for EMX port. Gives the directory part of the location for 2408ba47ec9dSmillertF<sh.exe>. 2409ba47ec9dSmillert 2410ba47ec9dSmillert=head2 C<USE_PERL_FLOCK> 2411ba47ec9dSmillert 2412ba47ec9dSmillertSpecific for EMX port. Since L<flock(3)> is present in EMX, but is not 2413ba47ec9dSmillertfunctional, it is emulated by perl. To disable the emulations, set 2414ba47ec9dSmillertenvironment variable C<USE_PERL_FLOCK=0>. 2415ba47ec9dSmillert 2416ba47ec9dSmillert=head2 C<TMP> or C<TEMP> 2417ba47ec9dSmillert 2418c5dcfd37SmillertSpecific for EMX port. Used as storage place for temporary files. 2419ba47ec9dSmillert 2420ba47ec9dSmillert=head1 Evolution 2421ba47ec9dSmillert 2422ba47ec9dSmillertHere we list major changes which could make you by surprise. 2423ba47ec9dSmillert 242479cd0b9aSmillert=head2 Text-mode filehandles 242579cd0b9aSmillert 242679cd0b9aSmillertStarting from version 5.8, Perl uses a builtin translation layer for 242779cd0b9aSmillerttext-mode files. This replaces the efficient well-tested EMX layer by 242879cd0b9aSmillertsome code which should be best characterized as a "quick hack". 242979cd0b9aSmillert 243079cd0b9aSmillertIn addition to possible bugs and an inability to follow changes to the 243179cd0b9aSmillerttranslation policy with off/on switches of TERMIO translation, this 243279cd0b9aSmillertintroduces a serious incompatible change: before sysread() on 243379cd0b9aSmillerttext-mode filehandles would go through the translation layer, now it 243479cd0b9aSmillertwould not. 243579cd0b9aSmillert 2436ba47ec9dSmillert=head2 Priorities 2437ba47ec9dSmillert 2438ba47ec9dSmillertC<setpriority> and C<getpriority> are not compatible with earlier 2439eac174f2Safresh1ports by Andreas Kaiser. See L</setpriority, getpriority>. 2440ba47ec9dSmillert 244179cd0b9aSmillert=head2 DLL name mangling: pre 5.6.2 2442ba47ec9dSmillert 2443ba47ec9dSmillertWith the release 5.003_01 the dynamically loadable libraries 2444c5dcfd37Smillertshould be rebuilt when a different version of Perl is compiled. In particular, 2445c5dcfd37SmillertDLLs (including F<perl.dll>) are now created with the names 2446ba47ec9dSmillertwhich contain a checksum, thus allowing workaround for OS/2 scheme of 2447ba47ec9dSmillertcaching DLLs. 2448ba47ec9dSmillert 2449c5dcfd37SmillertIt may be possible to code a simple workaround which would 2450c5dcfd37Smillert 2451c5dcfd37Smillert=over 2452c5dcfd37Smillert 2453c5dcfd37Smillert=item * 2454c5dcfd37Smillert 2455c5dcfd37Smillertfind the old DLLs looking through the old @INC; 2456c5dcfd37Smillert 2457c5dcfd37Smillert=item * 2458c5dcfd37Smillert 2459c5dcfd37Smillertmangle the names according to the scheme of new perl and copy the DLLs to 2460c5dcfd37Smillertthese names; 2461c5dcfd37Smillert 2462c5dcfd37Smillert=item * 2463c5dcfd37Smillert 2464c5dcfd37Smillertedit the internal C<LX> tables of DLL to reflect the change of the name 2465c5dcfd37Smillert(probably not needed for Perl extension DLLs, since the internally coded names 2466c5dcfd37Smillertare not used for "specific" DLLs, they used only for "global" DLLs). 2467c5dcfd37Smillert 2468c5dcfd37Smillert=item * 2469c5dcfd37Smillert 2470c5dcfd37Smillertedit the internal C<IMPORT> tables and change the name of the "old" 2471c5dcfd37SmillertF<perl????.dll> to the "new" F<perl????.dll>. 2472c5dcfd37Smillert 2473c5dcfd37Smillert=back 2474c5dcfd37Smillert 247579cd0b9aSmillert=head2 DLL name mangling: 5.6.2 and beyond 247679cd0b9aSmillert 247779cd0b9aSmillertIn fact mangling of I<extension> DLLs was done due to misunderstanding 247879cd0b9aSmillertof the OS/2 dynaloading model. OS/2 (effectively) maintains two 247979cd0b9aSmillertdifferent tables of loaded DLL: 248079cd0b9aSmillert 248179cd0b9aSmillert=over 248279cd0b9aSmillert 248379cd0b9aSmillert=item Global DLLs 248479cd0b9aSmillert 248579cd0b9aSmillertthose loaded by the base name from C<LIBPATH>; including those 248679cd0b9aSmillertassociated at link time; 248779cd0b9aSmillert 248879cd0b9aSmillert=item specific DLLs 248979cd0b9aSmillert 249079cd0b9aSmillertloaded by the full name. 249179cd0b9aSmillert 249279cd0b9aSmillert=back 249379cd0b9aSmillert 249479cd0b9aSmillertWhen resolving a request for a global DLL, the table of already-loaded 249579cd0b9aSmillertspecific DLLs is (effectively) ignored; moreover, specific DLLs are 249679cd0b9aSmillertI<always> loaded from the prescribed path. 249779cd0b9aSmillert 249879cd0b9aSmillertThere is/was a minor twist which makes this scheme fragile: what to do 249979cd0b9aSmillertwith DLLs loaded from 250079cd0b9aSmillert 250179cd0b9aSmillert=over 250279cd0b9aSmillert 250379cd0b9aSmillert=item C<BEGINLIBPATH> and C<ENDLIBPATH> 250479cd0b9aSmillert 250579cd0b9aSmillert(which depend on the process) 250679cd0b9aSmillert 250779cd0b9aSmillert=item F<.> from C<LIBPATH> 250879cd0b9aSmillert 250979cd0b9aSmillertwhich I<effectively> depends on the process (although C<LIBPATH> is the 251079cd0b9aSmillertsame for all the processes). 251179cd0b9aSmillert 251279cd0b9aSmillert=back 251379cd0b9aSmillert 251479cd0b9aSmillertUnless C<LIBPATHSTRICT> is set to C<T> (and the kernel is after 251579cd0b9aSmillert2000/09/01), such DLLs are considered to be global. When loading a 251679cd0b9aSmillertglobal DLL it is first looked in the table of already-loaded global 251779cd0b9aSmillertDLLs. Because of this the fact that one executable loaded a DLL from 251879cd0b9aSmillertC<BEGINLIBPATH> and C<ENDLIBPATH>, or F<.> from C<LIBPATH> may affect 251979cd0b9aSmillertI<which> DLL is loaded when I<another> executable requests a DLL with 252079cd0b9aSmillertthe same name. I<This> is the reason for version-specific mangling of 252179cd0b9aSmillertthe DLL name for perl DLL. 252279cd0b9aSmillert 252379cd0b9aSmillertSince the Perl extension DLLs are always loaded with the full path, 252479cd0b9aSmillertthere is no need to mangle their names in a version-specific ways: 252579cd0b9aSmillerttheir directory already reflects the corresponding version of perl, 252679cd0b9aSmillertand @INC takes into account binary compatibility with older version. 252779cd0b9aSmillertStarting from C<5.6.2> the name mangling scheme is fixed to be the 252879cd0b9aSmillertsame as for Perl 5.005_53 (same as in a popular binary release). Thus 252979cd0b9aSmillertnew Perls will be able to I<resolve the names> of old extension DLLs 253079cd0b9aSmillertif @INC allows finding their directories. 253179cd0b9aSmillert 253279cd0b9aSmillertHowever, this still does not guarantee that these DLL may be loaded. 253379cd0b9aSmillertThe reason is the mangling of the name of the I<Perl DLL>. And since 253479cd0b9aSmillertthe extension DLLs link with the Perl DLL, extension DLLs for older 253579cd0b9aSmillertversions would load an older Perl DLL, and would most probably 253679cd0b9aSmillertsegfault (since the data in this DLL is not properly initialized). 253779cd0b9aSmillert 253879cd0b9aSmillertThere is a partial workaround (which can be made complete with newer 253979cd0b9aSmillertOS/2 kernels): create a forwarder DLL with the same name as the DLL of 254079cd0b9aSmillertthe older version of Perl, which forwards the entry points to the 254179cd0b9aSmillertnewer Perl's DLL. Make this DLL accessible on (say) the C<BEGINLIBPATH> of 254279cd0b9aSmillertthe new Perl executable. When the new executable accesses old Perl's 254379cd0b9aSmillertextension DLLs, they would request the old Perl's DLL by name, get the 254479cd0b9aSmillertforwarder instead, so effectively will link with the currently running 254579cd0b9aSmillert(new) Perl DLL. 254679cd0b9aSmillert 254779cd0b9aSmillertThis may break in two ways: 254879cd0b9aSmillert 254979cd0b9aSmillert=over 255079cd0b9aSmillert 255179cd0b9aSmillert=item * 255279cd0b9aSmillert 255379cd0b9aSmillertOld perl executable is started when a new executable is running has 255479cd0b9aSmillertloaded an extension compiled for the old executable (ouph!). In this 255579cd0b9aSmillertcase the old executable will get a forwarder DLL instead of the old 255679cd0b9aSmillertperl DLL, so would link with the new perl DLL. While not directly 255779cd0b9aSmillertfatal, it will behave the same as new executable. This beats the whole 255879cd0b9aSmillertpurpose of explicitly starting an old executable. 255979cd0b9aSmillert 256079cd0b9aSmillert=item * 256179cd0b9aSmillert 256279cd0b9aSmillertA new executable loads an extension compiled for the old executable 256379cd0b9aSmillertwhen an old perl executable is running. In this case the extension 256479cd0b9aSmillertwill not pick up the forwarder - with fatal results. 256579cd0b9aSmillert 256679cd0b9aSmillert=back 256779cd0b9aSmillert 256879cd0b9aSmillertWith support for C<LIBPATHSTRICT> this may be circumvented - unless 256979cd0b9aSmillertone of DLLs is started from F<.> from C<LIBPATH> (I do not know 257079cd0b9aSmillertwhether C<LIBPATHSTRICT> affects this case). 257179cd0b9aSmillert 257279cd0b9aSmillertB<REMARK>. Unless newer kernels allow F<.> in C<BEGINLIBPATH> (older 257379cd0b9aSmillertdo not), this mess cannot be completely cleaned. (It turns out that 257479cd0b9aSmillertas of the beginning of 2002, F<.> is not allowed, but F<.\.> is - and 257579cd0b9aSmillertit has the same effect.) 257679cd0b9aSmillert 257779cd0b9aSmillert 257879cd0b9aSmillertB<REMARK>. C<LIBPATHSTRICT>, C<BEGINLIBPATH> and C<ENDLIBPATH> are 257979cd0b9aSmillertnot environment variables, although F<cmd.exe> emulates them on C<SET 258048950c12Ssthen...> lines. From Perl they may be accessed by 258148950c12SsthenL<Cwd::extLibpath|/Cwd::extLibpath([type])> and 258248950c12SsthenL<Cwd::extLibpath_set|/Cwd::extLibpath_set( path [, type ] )>. 258379cd0b9aSmillert 258479cd0b9aSmillert=head2 DLL forwarder generation 258579cd0b9aSmillert 258679cd0b9aSmillertAssume that the old DLL is named F<perlE0AC.dll> (as is one for 258779cd0b9aSmillert5.005_53), and the new version is 5.6.1. Create a file 258879cd0b9aSmillertF<perl5shim.def-leader> with 258979cd0b9aSmillert 259079cd0b9aSmillert LIBRARY 'perlE0AC' INITINSTANCE TERMINSTANCE 259179cd0b9aSmillert DESCRIPTION '@#perl5-porters@perl.org:5.006001#@ Perl module for 5.00553 -> Perl 5.6.1 forwarder' 259279cd0b9aSmillert CODE LOADONCALL 259379cd0b9aSmillert DATA LOADONCALL NONSHARED MULTIPLE 259479cd0b9aSmillert EXPORTS 259579cd0b9aSmillert 259679cd0b9aSmillertmodifying the versions/names as needed. Run 259779cd0b9aSmillert 2598b8851fccSafresh1 perl -wnle "next if 0../EXPORTS/; print qq( \"$1\") 2599b8851fccSafresh1 if /\"(\w+)\"/" perl5.def >lst 260079cd0b9aSmillert 260179cd0b9aSmillertin the Perl build directory (to make the DLL smaller replace perl5.def 260279cd0b9aSmillertwith the definition file for the older version of Perl if present). 260379cd0b9aSmillert 260479cd0b9aSmillert cat perl5shim.def-leader lst >perl5shim.def 260579cd0b9aSmillert gcc -Zomf -Zdll -o perlE0AC.dll perl5shim.def -s -llibperl 260679cd0b9aSmillert 260779cd0b9aSmillert(ignore multiple C<warning L4085>). 260879cd0b9aSmillert 2609ba47ec9dSmillert=head2 Threading 2610ba47ec9dSmillert 2611c5dcfd37SmillertAs of release 5.003_01 perl is linked to multithreaded C RTL 2612c5dcfd37SmillertDLL. If perl itself is not compiled multithread-enabled, so will not be perl's 2613ba47ec9dSmillertmalloc(). However, extensions may use multiple thread on their own 2614ba47ec9dSmillertrisk. 2615ba47ec9dSmillert 2616c5dcfd37SmillertThis was needed to compile C<Perl/Tk> for XFree86-OS/2 out-of-the-box, and 2617c5dcfd37Smillertlink with DLLs for other useful libraries, which typically are compiled 2618c5dcfd37Smillertwith C<-Zmt -Zcrtdll>. 2619ba47ec9dSmillert 2620ba47ec9dSmillert=head2 Calls to external programs 2621ba47ec9dSmillert 2622ba47ec9dSmillertDue to a popular demand the perl external program calling has been 2623ba47ec9dSmillertchanged wrt Andreas Kaiser's port. I<If> perl needs to call an 2624ba47ec9dSmillertexternal program I<via shell>, the F<f:/bin/sh.exe> will be called, or 26259f11ffb7Safresh1whatever is the override, see L</"C<PERL_SH_DIR>">. 2626ba47ec9dSmillert 2627ba47ec9dSmillertThus means that you need to get some copy of a F<sh.exe> as well (I 2628c5dcfd37Smillertuse one from pdksh). The path F<F:/bin> above is set up automatically during 2629ba47ec9dSmillertthe build to a correct value on the builder machine, but is 2630ba47ec9dSmillertoverridable at runtime, 2631ba47ec9dSmillert 2632ba47ec9dSmillertB<Reasons:> a consensus on C<perl5-porters> was that perl should use 2633ba47ec9dSmillertone non-overridable shell per platform. The obvious choices for OS/2 2634ba47ec9dSmillertare F<cmd.exe> and F<sh.exe>. Having perl build itself would be impossible 2635c5dcfd37Smillertwith F<cmd.exe> as a shell, thus I picked up C<sh.exe>. This assures almost 2636ba47ec9dSmillert100% compatibility with the scripts coming from *nix. As an added benefit 2637ba47ec9dSmillertthis works as well under DOS if you use DOS-enabled port of pdksh 263848950c12Ssthen(see L</Prerequisites>). 2639ba47ec9dSmillert 2640ba47ec9dSmillertB<Disadvantages:> currently F<sh.exe> of pdksh calls external programs 2641ba47ec9dSmillertvia fork()/exec(), and there is I<no> functioning exec() on 2642c5dcfd37SmillertOS/2. exec() is emulated by EMX by an asynchronous call while the caller 2643ba47ec9dSmillertwaits for child completion (to pretend that the C<pid> did not change). This 2644ba47ec9dSmillertmeans that 1 I<extra> copy of F<sh.exe> is made active via fork()/exec(), 2645ba47ec9dSmillertwhich may lead to some resources taken from the system (even if we do 2646ba47ec9dSmillertnot count extra work needed for fork()ing). 2647ba47ec9dSmillert 2648ba47ec9dSmillertNote that this a lesser issue now when we do not spawn F<sh.exe> 2649ba47ec9dSmillertunless needed (metachars found). 2650ba47ec9dSmillert 2651ba47ec9dSmillertOne can always start F<cmd.exe> explicitly via 2652ba47ec9dSmillert 2653ba47ec9dSmillert system 'cmd', '/c', 'mycmd', 'arg1', 'arg2', ... 2654ba47ec9dSmillert 2655ba47ec9dSmillertIf you need to use F<cmd.exe>, and do not want to hand-edit thousands of your 2656ba47ec9dSmillertscripts, the long-term solution proposed on p5-p is to have a directive 2657ba47ec9dSmillert 2658ba47ec9dSmillert use OS2::Cmd; 2659ba47ec9dSmillert 2660ba47ec9dSmillertwhich will override system(), exec(), C<``>, and 2661ba47ec9dSmillertC<open(,'...|')>. With current perl you may override only system(), 2662ba47ec9dSmillertreadpipe() - the explicit version of C<``>, and maybe exec(). The code 2663ba47ec9dSmillertwill substitute the one-argument call to system() by 2664ba47ec9dSmillertC<CORE::system('cmd.exe', '/c', shift)>. 2665ba47ec9dSmillert 2666ba47ec9dSmillertIf you have some working code for C<OS2::Cmd>, please send it to me, 2667ba47ec9dSmillertI will include it into distribution. I have no need for such a module, so 2668ba47ec9dSmillertcannot test it. 2669ba47ec9dSmillert 26706345ca90SmillertFor the details of the current situation with calling external programs, 267156d68f1eSafresh1see L</Starting OSE<sol>2 (and DOS) programs under Perl>. Set us 267256d68f1eSafresh1mention a couple of features: 26736345ca90Smillert 2674c5dcfd37Smillert=over 4 26756345ca90Smillert 2676c5dcfd37Smillert=item * 26776345ca90Smillert 2678c5dcfd37SmillertExternal scripts may be called by their basename. Perl will try the same 2679c5dcfd37Smillertextensions as when processing B<-S> command-line switch. 2680c5dcfd37Smillert 2681c5dcfd37Smillert=item * 2682c5dcfd37Smillert 2683c5dcfd37SmillertExternal scripts starting with C<#!> or C<extproc > will be executed directly, 2684c5dcfd37Smillertwithout calling the shell, by calling the program specified on the rest of 2685c5dcfd37Smillertthe first line. 26866345ca90Smillert 26876345ca90Smillert=back 26886345ca90Smillert 2689ba47ec9dSmillert=head2 Memory allocation 2690ba47ec9dSmillert 2691ba47ec9dSmillertPerl uses its own malloc() under OS/2 - interpreters are usually malloc-bound 2692ba47ec9dSmillertfor speed, but perl is not, since its malloc is lightning-fast. 2693c5dcfd37SmillertPerl-memory-usage-tuned benchmarks show that Perl's malloc is 5 times quicker 2694c5dcfd37Smillertthan EMX one. I do not have convincing data about memory footprint, but 2695c5dcfd37Smillerta (pretty random) benchmark showed that Perl's one is 5% better. 2696ba47ec9dSmillert 2697ba47ec9dSmillertCombination of perl's malloc() and rigid DLL name resolution creates 2698ba47ec9dSmillerta special problem with library functions which expect their return value to 2699ba47ec9dSmillertbe free()d by system's free(). To facilitate extensions which need to call 2700ba47ec9dSmillertsuch functions, system memory-allocation functions are still available with 2701ba47ec9dSmillertthe prefix C<emx_> added. (Currently only DLL perl has this, it should 2702ba47ec9dSmillertpropagate to F<perl_.exe> shortly.) 2703ba47ec9dSmillert 27046345ca90Smillert=head2 Threads 27056345ca90Smillert 27066345ca90SmillertOne can build perl with thread support enabled by providing C<-D usethreads> 27076345ca90Smillertoption to F<Configure>. Currently OS/2 support of threads is very 27086345ca90Smillertpreliminary. 27096345ca90Smillert 27106345ca90SmillertMost notable problems: 27116345ca90Smillert 2712c5dcfd37Smillert=over 4 27136345ca90Smillert 27146345ca90Smillert=item C<COND_WAIT> 27156345ca90Smillert 271679cd0b9aSmillertmay have a race condition (but probably does not due to edge-triggered 271779cd0b9aSmillertnature of OS/2 Event semaphores). (Needs a reimplementation (in terms of chaining 271879cd0b9aSmillertwaiting threads, with the linked list stored in per-thread structure?)?) 27196345ca90Smillert 27206345ca90Smillert=item F<os2.c> 27216345ca90Smillert 27226345ca90Smillerthas a couple of static variables used in OS/2-specific functions. (Need to be 27236345ca90Smillertmoved to per-thread structure, or serialized?) 27246345ca90Smillert 27256345ca90Smillert=back 27266345ca90Smillert 27276345ca90SmillertNote that these problems should not discourage experimenting, since they 27286345ca90Smillerthave a low probability of affecting small programs. 27296345ca90Smillert 273079cd0b9aSmillert=head1 BUGS 273179cd0b9aSmillert 273209e75b67SmillertThis description is not updated often (since 5.6.1?), see F<./os2/Changes> 273348950c12Ssthenfor more info. 273479cd0b9aSmillert 2735ba47ec9dSmillert=cut 2736ba47ec9dSmillert 2737ba47ec9dSmillertOS/2 extensions 2738ba47ec9dSmillert~~~~~~~~~~~~~~~ 2739ba47ec9dSmillertI include 3 extensions by Andreas Kaiser, OS2::REXX, OS2::UPM, and OS2::FTP, 2740ba47ec9dSmillertinto my ftp directory, mirrored on CPAN. I made 2741ba47ec9dSmillertsome minor changes needed to compile them by standard tools. I cannot 2742ba47ec9dSmillerttest UPM and FTP, so I will appreciate your feedback. Other extensions 2743ba47ec9dSmillertthere are OS2::ExtAttr, OS2::PrfDB for tied access to EAs and .INI 2744ba47ec9dSmillertfiles - and maybe some other extensions at the time you read it. 2745ba47ec9dSmillert 2746ba47ec9dSmillertNote that OS2 perl defines 2 pseudo-extension functions 2747ba47ec9dSmillertOS2::Copy::copy and DynaLoader::mod2fname (many more now, see 27489f11ffb7Safresh1L</Prebuilt methods>). 2749ba47ec9dSmillert 2750ba47ec9dSmillertThe -R switch of older perl is deprecated. If you need to call a REXX code 2751ba47ec9dSmillertwhich needs access to variables, include the call into a REXX compartment 2752ba47ec9dSmillertcreated by 2753ba47ec9dSmillert REXX_call {...block...}; 2754ba47ec9dSmillert 2755ba47ec9dSmillertTwo new functions are supported by REXX code, 2756ba47ec9dSmillert REXX_eval 'string'; 2757ba47ec9dSmillert REXX_eval_with 'string', REXX_function_name => \&perl_sub_reference; 2758ba47ec9dSmillert 2759ba47ec9dSmillertIf you have some other extensions you want to share, send the code to 2760ba47ec9dSmillertme. At least two are available: tied access to EA's, and tied access 2761ba47ec9dSmillertto system databases. 2762ba47ec9dSmillert 2763ba47ec9dSmillert=head1 AUTHOR 2764ba47ec9dSmillert 276579cd0b9aSmillertIlya Zakharevich, cpan@ilyaz.org 2766ba47ec9dSmillert 2767ba47ec9dSmillert=head1 SEE ALSO 2768ba47ec9dSmillert 2769ba47ec9dSmillertperl(1). 2770ba47ec9dSmillert 2771ba47ec9dSmillert=cut 2772ba47ec9dSmillert 2773