1# vim: syntax=pod 2 3If you read this file _as_is_, just ignore the funny characters you 4see. It is written in the POD format (see perlpod manpage) which is 5specially designed to be readable as is. 6 7=head1 NAME 8 9perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT. 10 11=head1 SYNOPSIS 12 13One can read this document in the following formats: 14 15 man perlos2 16 view perl perlos2 17 explorer perlos2.html 18 info perlos2 19 20to list some (not all may be available simultaneously), or it may 21be read I<as is>: either as F<README.os2>, or F<pod/perlos2.pod>. 22 23To read the F<.INF> version of documentation (B<very> recommended) 24outside of OS/2, one needs an IBM's reader (may be available on IBM 25ftp sites (?) (URL anyone?)) or shipped with PC DOS 7.0 and IBM's 26Visual Age C++ 3.5. 27 28A copy of a Win* viewer is contained in the "Just add OS/2 Warp" package 29 30 ftp://ftp.software.ibm.com/ps/products/os2/tools/jaow/jaow.zip 31 32in F<?:\JUST_ADD\view.exe>. This gives one an access to EMX's 33F<.INF> docs as well (text form is available in F</emx/doc> in 34EMX's distribution). There is also a different viewer named xview. 35 36Note that if you have F<lynx.exe> or F<netscape.exe> installed, you can follow WWW links 37from this document in F<.INF> format. If you have EMX docs installed 38correctly, you can follow library links (you need to have C<view emxbook> 39working by setting C<EMXBOOK> environment variable as it is described 40in EMX docs). 41 42=cut 43 44Contents (This may be a little bit obsolete) 45 46 perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT. 47 48 NAME 49 SYNOPSIS 50 DESCRIPTION 51 - Target 52 - Other OSes 53 - Prerequisites 54 - Starting Perl programs under OS/2 (and DOS and...) 55 - Starting OS/2 (and DOS) programs under Perl 56 Frequently asked questions 57 - "It does not work" 58 - I cannot run external programs 59 - I cannot embed perl into my program, or use perl.dll from my 60 - `` and pipe-open do not work under DOS. 61 - Cannot start find.exe "pattern" file 62 INSTALLATION 63 - Automatic binary installation 64 - Manual binary installation 65 - Warning 66 Accessing documentation 67 - OS/2 .INF file 68 - Plain text 69 - Manpages 70 - HTML 71 - GNU info files 72 - PDF files 73 - LaTeX docs 74 BUILD 75 - The short story 76 - Prerequisites 77 - Getting perl source 78 - Application of the patches 79 - Hand-editing 80 - Making 81 - Testing 82 - Installing the built perl 83 - a.out-style build 84 Build FAQ 85 - Some / became \ in pdksh. 86 - 'errno' - unresolved external 87 - Problems with tr or sed 88 - Some problem (forget which ;-) 89 - Library ... not found 90 - Segfault in make 91 - op/sprintf test failure 92 Specific (mis)features of OS/2 port 93 - setpriority, getpriority 94 - system() 95 - extproc on the first line 96 - Additional modules: 97 - Prebuilt methods: 98 - Prebuilt variables: 99 - Misfeatures 100 - Modifications 101 - Identifying DLLs 102 - Centralized management of resources 103 Perl flavors 104 - perl.exe 105 - perl_.exe 106 - perl__.exe 107 - perl___.exe 108 - Why strange names? 109 - Why dynamic linking? 110 - Why chimera build? 111 ENVIRONMENT 112 - PERLLIB_PREFIX 113 - PERL_BADLANG 114 - PERL_BADFREE 115 - PERL_SH_DIR 116 - USE_PERL_FLOCK 117 - TMP or TEMP 118 Evolution 119 - Text-mode filehandles 120 - Priorities 121 - DLL name mangling: pre 5.6.2 122 - DLL name mangling: 5.6.2 and beyond 123 - DLL forwarder generation 124 - Threading 125 - Calls to external programs 126 - Memory allocation 127 - Threads 128 BUGS 129 AUTHOR 130 SEE ALSO 131 132=head1 DESCRIPTION 133 134=head2 Target 135 136The target is to make OS/2 one of the best supported platform for 137using/building/developing Perl and I<Perl applications>, as well as 138make Perl the best language to use under OS/2. The secondary target is 139to try to make this work under DOS and Win* as well (but not B<too> hard). 140 141The current state is quite close to this target. Known limitations: 142 143=over 5 144 145=item * 146 147Some *nix programs use fork() a lot; with the mostly useful flavors of 148perl for OS/2 (there are several built simultaneously) this is 149supported; but some flavors do not support this (e.g., when Perl is 150called from inside REXX). Using fork() after 151I<use>ing dynamically loading extensions would not work with I<very> old 152versions of EMX. 153 154=item * 155 156You need a separate perl executable F<perl__.exe> (see L</perl__.exe>) 157if you want to use PM code in your application (as Perl/Tk or OpenGL 158Perl modules do) without having a text-mode window present. 159 160While using the standard F<perl.exe> from a text-mode window is possible 161too, I have seen cases when this causes degradation of the system stability. 162Using F<perl__.exe> avoids such a degradation. 163 164=item * 165 166There is no simple way to access WPS objects. The only way I know 167is via C<OS2::REXX> and C<SOM> extensions (see L<OS2::REXX>, L<SOM>). 168However, we do not have access to 169convenience methods of Object-REXX. (Is it possible at all? I know 170of no Object-REXX API.) The C<SOM> extension (currently in alpha-text) 171may eventually remove this shortcoming; however, due to the fact that 172DII is not supported by the C<SOM> module, using C<SOM> is not as 173convenient as one would like it. 174 175=back 176 177Please keep this list up-to-date by informing me about other items. 178 179=head2 Other OSes 180 181Since OS/2 port of perl uses a remarkable EMX environment, it can 182run (and build extensions, and - possibly - be built itself) under any 183environment which can run EMX. The current list is DOS, 184DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT. Out of many perl flavors, 185only one works, see L</"F<perl_.exe>">. 186 187Note that not all features of Perl are available under these 188environments. This depends on the features the I<extender> - most 189probably RSX - decided to implement. 190 191Cf. L</Prerequisites>. 192 193=head2 Prerequisites 194 195=over 6 196 197=item EMX 198 199EMX runtime is required (may be substituted by RSX). Note that 200it is possible to make F<perl_.exe> to run under DOS without any 201external support by binding F<emx.exe>/F<rsx.exe> to it, see L<emxbind(1)>. 202Note that under DOS for best results one should use RSX runtime, which 203has much more functions working (like C<fork>, C<popen> and so on). In 204fact RSX is required if there is no VCPI present. Note the 205RSX requires DPMI. Many implementations of DPMI are known to be very 206buggy, beware! 207 208Only the latest runtime is supported, currently C<0.9d fix 03>. Perl may run 209under earlier versions of EMX, but this is not tested. 210 211One can get different parts of EMX from, say 212 213 ftp://crydee.sai.msu.ru/pub/comp/os/os2/leo/gnu/emx+gcc/ 214 http://hobbes.nmsu.edu/h-browse.php?dir=/pub/os2/dev/emx/v0.9d/ 215 216The runtime component should have the name F<emxrt.zip>. 217 218B<NOTE>. When using F<emx.exe>/F<rsx.exe>, it is enough to have them on your path. One 219does not need to specify them explicitly (though this 220 221 emx perl_.exe -de 0 222 223will work as well.) 224 225=item RSX 226 227To run Perl on DPMI platforms one needs RSX runtime. This is 228needed under DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT (see 229L</"Other OSes">). RSX would not work with VCPI 230only, as EMX would, it requires DMPI. 231 232Having RSX and the latest F<sh.exe> one gets a fully functional 233B<*nix>-ish environment under DOS, say, C<fork>, C<``> and 234pipe-C<open> work. In fact, MakeMaker works (for static build), so one 235can have Perl development environment under DOS. 236 237One can get RSX from, say 238 239 http://cd.textfiles.com/hobbesos29804/disk1/EMX09C/ 240 ftp://crydee.sai.msu.ru/pub/comp/os/os2/leo/gnu/emx+gcc/contrib/ 241 242Contact the author on C<rainer@mathematik.uni-bielefeld.de>. 243 244The latest F<sh.exe> with DOS hooks is available in 245 246 http://www.ilyaz.org/software/os2/ 247 248as F<sh_dos.zip> or under similar names starting with C<sh>, C<pdksh> etc. 249 250=item HPFS 251 252Perl does not care about file systems, but the perl library contains 253many files with long names, so to install it intact one needs a file 254system which supports long file names. 255 256Note that if you do not plan to build the perl itself, it may be 257possible to fool EMX to truncate file names. This is not supported, 258read EMX docs to see how to do it. 259 260=item pdksh 261 262To start external programs with complicated command lines (like with 263pipes in between, and/or quoting of arguments), Perl uses an external 264shell. With EMX port such shell should be named F<sh.exe>, and located 265either in the wired-in-during-compile locations (usually F<F:/bin>), 266or in configurable location (see L</"C<PERL_SH_DIR>">). 267 268For best results use EMX pdksh. The standard binary (5.2.14 or later) runs 269under DOS (with L</RSX>) as well, see 270 271 http://www.ilyaz.org/software/os2/ 272 273=back 274 275=head2 Starting Perl programs under OS/2 (and DOS and...) 276 277Start your Perl program F<foo.pl> with arguments C<arg1 arg2 arg3> the 278same way as on any other platform, by 279 280 perl foo.pl arg1 arg2 arg3 281 282If you want to specify perl options C<-my_opts> to the perl itself (as 283opposed to your program), use 284 285 perl -my_opts foo.pl arg1 arg2 arg3 286 287Alternately, if you use OS/2-ish shell, like CMD or 4os2, put 288the following at the start of your perl script: 289 290 extproc perl -S -my_opts 291 292rename your program to F<foo.cmd>, and start it by typing 293 294 foo arg1 arg2 arg3 295 296Note that because of stupid OS/2 limitations the full path of the perl 297script is not available when you use C<extproc>, thus you are forced to 298use C<-S> perl switch, and your script should be on the C<PATH>. As a plus 299side, if you know a full path to your script, you may still start it 300with 301 302 perl ../../blah/foo.cmd arg1 arg2 arg3 303 304(note that the argument C<-my_opts> is taken care of by the C<extproc> line 305in your script, see C<L</extproc>> on the first line). 306 307To understand what the above I<magic> does, read perl docs about C<-S> 308switch - see L<perlrun>, and cmdref about C<extproc>: 309 310 view perl perlrun 311 man perlrun 312 view cmdref extproc 313 help extproc 314 315or whatever method you prefer. 316 317There are also endless possibilities to use I<executable extensions> of 3184os2, I<associations> of WPS and so on... However, if you use 319*nixish shell (like F<sh.exe> supplied in the binary distribution), 320you need to follow the syntax specified in L<perlrun/"Command Switches">. 321 322Note that B<-S> switch supports scripts with additional extensions 323F<.cmd>, F<.btm>, F<.bat>, F<.pl> as well. 324 325=head2 Starting OS/2 (and DOS) programs under Perl 326 327This is what system() (see L<perlfunc/system>), C<``> (see 328L<perlop/"I/O Operators">), and I<open pipe> (see L<perlfunc/open>) 329are for. (Avoid exec() (see L<perlfunc/exec>) unless you know what you 330do). 331 332Note however that to use some of these operators you need to have a 333sh-syntax shell installed (see L</"Pdksh">, 334L</"Frequently asked questions">), and perl should be able to find it 335(see L</"C<PERL_SH_DIR>">). 336 337The cases when the shell is used are: 338 339=over 340 341=item 1 342 343One-argument system() (see L<perlfunc/system>), exec() (see L<perlfunc/exec>) 344with redirection or shell meta-characters; 345 346=item 2 347 348Pipe-open (see L<perlfunc/open>) with the command which contains redirection 349or shell meta-characters; 350 351=item 3 352 353Backticks C<``> (see L<perlop/"I/O Operators">) with the command which contains 354redirection or shell meta-characters; 355 356=item 4 357 358If the executable called by system()/exec()/pipe-open()/C<``> is a script 359with the "magic" C<#!> line or C<extproc> line which specifies shell; 360 361=item 5 362 363If the executable called by system()/exec()/pipe-open()/C<``> is a script 364without "magic" line, and C<$ENV{EXECSHELL}> is set to shell; 365 366=item 6 367 368If the executable called by system()/exec()/pipe-open()/C<``> is not 369found (is not this remark obsolete?); 370 371=item 7 372 373For globbing (see L<perlfunc/glob>, L<perlop/"I/O Operators">) 374(obsolete? Perl uses builtin globbing nowadays...). 375 376=back 377 378For the sake of speed for a common case, in the above algorithms 379backslashes in the command name are not considered as shell metacharacters. 380 381Perl starts scripts which begin with cookies 382C<extproc> or C<#!> directly, without an intervention of shell. Perl uses the 383same algorithm to find the executable as F<pdksh>: if the path 384on C<#!> line does not work, and contains C</>, then the directory 385part of the executable is ignored, and the executable 386is searched in F<.> and on C<PATH>. To find arguments for these scripts 387Perl uses a different algorithm than F<pdksh>: up to 3 arguments are 388recognized, and trailing whitespace is stripped. 389 390If a script 391does not contain such a cooky, then to avoid calling F<sh.exe>, Perl uses 392the same algorithm as F<pdksh>: if C<$ENV{EXECSHELL}> is set, the 393script is given as the first argument to this command, if not set, then 394C<$ENV{COMSPEC} /c> is used (or a hardwired guess if C<$ENV{COMSPEC}> is 395not set). 396 397When starting scripts directly, Perl uses exactly the same algorithm as for 398the search of script given by B<-S> command-line option: it will look in 399the current directory, then on components of C<$ENV{PATH}> using the 400following order of appended extensions: no extension, F<.cmd>, F<.btm>, 401F<.bat>, F<.pl>. 402 403Note that Perl will start to look for scripts only if OS/2 cannot start the 404specified application, thus C<system 'blah'> will not look for a script if 405there is an executable file F<blah.exe> I<anywhere> on C<PATH>. In 406other words, C<PATH> is essentially searched twice: once by the OS for 407an executable, then by Perl for scripts. 408 409Note also that executable files on OS/2 can have an arbitrary extension, but 410F<.exe> will be automatically appended if no dot is present in the name. The 411workaround is as simple as that: since F<blah.> and F<blah> denote the same 412file (at list on FAT and HPFS file systems), to start an executable residing in 413file F<n:/bin/blah> (no extension) give an argument C<n:/bin/blah.> (dot 414appended) to system(). 415 416Perl will start PM programs from VIO (=text-mode) Perl process in a 417separate PM session; 418the opposite is not true: when you start a non-PM program from a PM 419Perl process, Perl would not run it in a separate session. If a separate 420session is desired, either ensure 421that shell will be used, as in C<system 'cmd /c myprog'>, or start it using 422optional arguments to system() documented in C<OS2::Process> module. This 423is considered to be a feature. 424 425=head1 Frequently asked questions 426 427=head2 "It does not work" 428 429Perl binary distributions come with a F<testperl.cmd> script which tries 430to detect common problems with misconfigured installations. There is a 431pretty large chance it will discover which step of the installation you 432managed to goof. C<;-)> 433 434=head2 I cannot run external programs 435 436=over 4 437 438=item * 439 440Did you run your programs with C<-w> switch? See 441L</Starting OSE<sol>2 (and DOS) programs under Perl>. 442 443=item * 444 445Do you try to run I<internal> shell commands, like C<`copy a b`> 446(internal for F<cmd.exe>), or C<`glob a*b`> (internal for ksh)? You 447need to specify your shell explicitly, like C<`cmd /c copy a b`>, 448since Perl cannot deduce which commands are internal to your shell. 449 450=back 451 452=head2 I cannot embed perl into my program, or use F<perl.dll> from my 453program. 454 455=over 4 456 457=item Is your program EMX-compiled with C<-Zmt -Zcrtdll>? 458 459Well, nowadays Perl DLL should be usable from a differently compiled 460program too... If you can run Perl code from REXX scripts (see 461L<OS2::REXX>), then there are some other aspect of interaction which 462are overlooked by the current hackish code to support 463differently-compiled principal programs. 464 465If everything else fails, you need to build a stand-alone DLL for 466perl. Contact me, I did it once. Sockets would not work, as a lot of 467other stuff. 468 469=item Did you use L<ExtUtils::Embed>? 470 471Some time ago I had reports it does not work. Nowadays it is checked 472in the Perl test suite, so grep F<./t> subdirectory of the build tree 473(as well as F<*.t> files in the F<./lib> subdirectory) to find how it 474should be done "correctly". 475 476=back 477 478=head2 C<``> and pipe-C<open> do not work under DOS. 479 480This may a variant of just L</"I cannot run external programs">, or a 481deeper problem. Basically: you I<need> RSX (see L</Prerequisites>) 482for these commands to work, and you may need a port of F<sh.exe> which 483understands command arguments. One of such ports is listed in 484L</Prerequisites> under RSX. Do not forget to set variable 485L</"C<PERL_SH_DIR>"> as well. 486 487DPMI is required for RSX. 488 489=head2 Cannot start C<find.exe "pattern" file> 490 491The whole idea of the "standard C API to start applications" is that 492the forms C<foo> and C<"foo"> of program arguments are completely 493interchangeable. F<find> breaks this paradigm; 494 495 find "pattern" file 496 find pattern file 497 498are not equivalent; F<find> cannot be started directly using the above 499API. One needs a way to surround the doublequotes in some other 500quoting construction, necessarily having an extra non-Unixish shell in 501between. 502 503Use one of 504 505 system 'cmd', '/c', 'find "pattern" file'; 506 `cmd /c 'find "pattern" file'` 507 508This would start F<find.exe> via F<cmd.exe> via C<sh.exe> via 509C<perl.exe>, but this is a price to pay if you want to use 510non-conforming program. 511 512=head1 INSTALLATION 513 514=head2 Automatic binary installation 515 516The most convenient way of installing a binary distribution of perl is via perl installer 517F<install.exe>. Just follow the instructions, and 99% of the 518installation blues would go away. 519 520Note however, that you need to have F<unzip.exe> on your path, and 521EMX environment I<running>. The latter means that if you just 522installed EMX, and made all the needed changes to F<Config.sys>, 523you may need to reboot in between. Check EMX runtime by running 524 525 emxrev 526 527Binary installer also creates a folder on your desktop with some useful 528objects. If you need to change some aspects of the work of the binary 529installer, feel free to edit the file F<Perl.pkg>. This may be useful 530e.g., if you need to run the installer many times and do not want to 531make many interactive changes in the GUI. 532 533B<Things not taken care of by automatic binary installation:> 534 535=over 15 536 537=item C<PERL_BADLANG> 538 539may be needed if you change your codepage I<after> perl installation, 540and the new value is not supported by EMX. See L</"C<PERL_BADLANG>">. 541 542=item C<PERL_BADFREE> 543 544see L</"C<PERL_BADFREE>">. 545 546=item F<Config.pm> 547 548This file resides somewhere deep in the location you installed your 549perl library, find it out by 550 551 perl -MConfig -le "print $INC{'Config.pm'}" 552 553While most important values in this file I<are> updated by the binary 554installer, some of them may need to be hand-edited. I know no such 555data, please keep me informed if you find one. Moreover, manual 556changes to the installed version may need to be accompanied by an edit 557of this file. 558 559=back 560 561B<NOTE>. Because of a typo the binary installer of 5.00305 562would install a variable C<PERL_SHPATH> into F<Config.sys>. Please 563remove this variable and put C<L</PERL_SH_DIR>> instead. 564 565=head2 Manual binary installation 566 567As of version 5.00305, OS/2 perl binary distribution comes split 568into 11 components. Unfortunately, to enable configurable binary 569installation, the file paths in the zip files are not absolute, but 570relative to some directory. 571 572Note that the extraction with the stored paths is still necessary 573(default with unzip, specify C<-d> to pkunzip). However, you 574need to know where to extract the files. You need also to manually 575change entries in F<Config.sys> to reflect where did you put the 576files. Note that if you have some primitive unzipper (like 577C<pkunzip>), you may get a lot of warnings/errors during 578unzipping. Upgrade to C<(w)unzip>. 579 580Below is the sample of what to do to reproduce the configuration on my 581machine. In F<VIEW.EXE> you can press C<Ctrl-Insert> now, and 582cut-and-paste from the resulting file - created in the directory you 583started F<VIEW.EXE> from. 584 585For each component, we mention environment variables related to each 586installation directory. Either choose directories to match your 587values of the variables, or create/append-to variables to take into 588account the directories. 589 590=over 3 591 592=item Perl VIO and PM executables (dynamically linked) 593 594 unzip perl_exc.zip *.exe *.ico -d f:/emx.add/bin 595 unzip perl_exc.zip *.dll -d f:/emx.add/dll 596 597(have the directories with C<*.exe> on PATH, and C<*.dll> on 598LIBPATH); 599 600=item Perl_ VIO executable (statically linked) 601 602 unzip perl_aou.zip -d f:/emx.add/bin 603 604(have the directory on PATH); 605 606=item Executables for Perl utilities 607 608 unzip perl_utl.zip -d f:/emx.add/bin 609 610(have the directory on PATH); 611 612=item Main Perl library 613 614 unzip perl_mlb.zip -d f:/perllib/lib 615 616If this directory is exactly the same as the prefix which was compiled 617into F<perl.exe>, you do not need to change 618anything. However, for perl to find the library if you use a different 619path, you need to 620C<set PERLLIB_PREFIX> in F<Config.sys>, see L</"C<PERLLIB_PREFIX>">. 621 622=item Additional Perl modules 623 624 unzip perl_ste.zip -d f:/perllib/lib/site_perl/5.38.2/ 625 626Same remark as above applies. Additionally, if this directory is not 627one of directories on @INC (and @INC is influenced by C<PERLLIB_PREFIX>), you 628need to put this 629directory and subdirectory F<./os2> in C<PERLLIB> or C<PERL5LIB> 630variable. Do not use C<PERL5LIB> unless you have it set already. See 631L<perl/"ENVIRONMENT">. 632 633B<[Check whether this extraction directory is still applicable with 634the new directory structure layout!]> 635 636=item Tools to compile Perl modules 637 638 unzip perl_blb.zip -d f:/perllib/lib 639 640Same remark as for F<perl_ste.zip>. 641 642=item Manpages for Perl and utilities 643 644 unzip perl_man.zip -d f:/perllib/man 645 646This directory should better be on C<MANPATH>. You need to have a 647working F<man> to access these files. 648 649=item Manpages for Perl modules 650 651 unzip perl_mam.zip -d f:/perllib/man 652 653This directory should better be on C<MANPATH>. You need to have a 654working man to access these files. 655 656=item Source for Perl documentation 657 658 unzip perl_pod.zip -d f:/perllib/lib 659 660This is used by the C<perldoc> program (see L<perldoc>), and may be used to 661generate HTML documentation usable by WWW browsers, and 662documentation in zillions of other formats: C<info>, C<LaTeX>, 663C<Acrobat>, C<FrameMaker> and so on. [Use programs such as 664F<pod2latex> etc.] 665 666=item Perl manual in F<.INF> format 667 668 unzip perl_inf.zip -d d:/os2/book 669 670This directory should better be on C<BOOKSHELF>. 671 672=item Pdksh 673 674 unzip perl_sh.zip -d f:/bin 675 676This is used by perl to run external commands which explicitly 677require shell, like the commands using I<redirection> and I<shell 678metacharacters>. It is also used instead of explicit F</bin/sh>. 679 680Set C<PERL_SH_DIR> (see L</"C<PERL_SH_DIR>">) if you move F<sh.exe> from 681the above location. 682 683B<Note.> It may be possible to use some other sh-compatible shell (untested). 684 685=back 686 687After you installed the components you needed and updated the 688F<Config.sys> correspondingly, you need to hand-edit 689F<Config.pm>. This file resides somewhere deep in the location you 690installed your perl library, find it out by 691 692 perl -MConfig -le "print $INC{'Config.pm'}" 693 694You need to correct all the entries which look like file paths (they 695currently start with C<f:/>). 696 697=head2 B<Warning> 698 699The automatic and manual perl installation leave precompiled paths 700inside perl executables. While these paths are overwritable (see 701L</"C<PERLLIB_PREFIX>">, L</"C<PERL_SH_DIR>">), some people may prefer 702binary editing of paths inside the executables/DLLs. 703 704=head1 Accessing documentation 705 706Depending on how you built/installed perl you may have (otherwise 707identical) Perl documentation in the following formats: 708 709=head2 OS/2 F<.INF> file 710 711Most probably the most convenient form. Under OS/2 view it as 712 713 view perl 714 view perl perlfunc 715 view perl less 716 view perl ExtUtils::MakeMaker 717 718(currently the last two may hit a wrong location, but this may improve 719soon). Under Win* see L</"SYNOPSIS">. 720 721If you want to build the docs yourself, and have I<OS/2 toolkit>, run 722 723 pod2ipf > perl.ipf 724 725in F</perllib/lib/pod> directory, then 726 727 ipfc /inf perl.ipf 728 729(Expect a lot of errors during the both steps.) Now move it on your 730BOOKSHELF path. 731 732=head2 Plain text 733 734If you have perl documentation in the source form, perl utilities 735installed, and GNU groff installed, you may use 736 737 perldoc perlfunc 738 perldoc less 739 perldoc ExtUtils::MakeMaker 740 741to access the perl documentation in the text form (note that you may get 742better results using perl manpages). 743 744Alternately, try running pod2text on F<.pod> files. 745 746=head2 Manpages 747 748If you have F<man> installed on your system, and you installed perl 749manpages, use something like this: 750 751 man perlfunc 752 man 3 less 753 man ExtUtils.MakeMaker 754 755to access documentation for different components of Perl. Start with 756 757 man perl 758 759Note that dot (F<.>) is used as a package separator for documentation 760for packages, and as usual, sometimes you need to give the section - C<3> 761above - to avoid shadowing by the I<less(1) manpage>. 762 763Make sure that the directory B<above> the directory with manpages is 764on our C<MANPATH>, like this 765 766 set MANPATH=c:/man;f:/perllib/man 767 768for Perl manpages in C<f:/perllib/man/man1/> etc. 769 770=head2 HTML 771 772If you have some WWW browser available, installed the Perl 773documentation in the source form, and Perl utilities, you can build 774HTML docs. Cd to directory with F<.pod> files, and do like this 775 776 cd f:/perllib/lib/pod 777 pod2html 778 779After this you can direct your browser the file F<perl.html> in this 780directory, and go ahead with reading docs, like this: 781 782 explore file:///f:/perllib/lib/pod/perl.html 783 784Alternatively you may be able to get these docs prebuilt from CPAN. 785 786=head2 GNU C<info> files 787 788Users of Emacs would appreciate it very much, especially with 789C<CPerl> mode loaded. You need to get latest C<pod2texi> from C<CPAN>, 790or, alternately, the prebuilt info pages. 791 792=head2 F<PDF> files 793 794for C<Acrobat> are available on CPAN (may be for slightly older version of 795perl). 796 797=head2 C<LaTeX> docs 798 799can be constructed using C<pod2latex>. 800 801=head1 BUILD 802 803Here we discuss how to build Perl under OS/2. 804 805=head2 The short story 806 807Assume that you are a seasoned porter, so are sure that all the necessary 808tools are already present on your system, and you know how to get the Perl 809source distribution. Untar it, change to the extract directory, and 810 811 gnupatch -p0 < os2\diff.configure 812 sh Configure -des -D prefix=f:/perllib 813 make 814 make test 815 make install 816 make aout_test 817 make aout_install 818 819This puts the executables in f:/perllib/bin. Manually move them to the 820C<PATH>, manually move the built F<perl*.dll> to C<LIBPATH> (here for 821Perl DLL F<*> is a not-very-meaningful hex checksum), and run 822 823 make installcmd INSTALLCMDDIR=d:/ir/on/path 824 825Assuming that the C<man>-files were put on an appropriate location, 826this completes the installation of minimal Perl system. (The binary 827distribution contains also a lot of additional modules, and the 828documentation in INF format.) 829 830What follows is a detailed guide through these steps. 831 832=head2 Prerequisites 833 834You need to have the latest EMX development environment, the full 835GNU tool suite (gawk renamed to awk, and GNU F<find.exe> 836earlier on path than the OS/2 F<find.exe>, same with F<sort.exe>, to 837check use 838 839 find --version 840 sort --version 841 842). You need the latest version of F<pdksh> installed as F<sh.exe>. 843 844Check that you have B<BSD> libraries and headers installed, and - 845optionally - Berkeley DB headers and libraries, and crypt. 846 847Possible locations to get the files: 848 849 850 ftp://ftp.uni-heidelberg.de/pub/os2/unix/ 851 http://hobbes.nmsu.edu/h-browse.php?dir=/pub/os2 852 http://cd.textfiles.com/hobbesos29804/disk1/DEV32/ 853 http://cd.textfiles.com/hobbesos29804/disk1/EMX09C/ 854 855It is reported that the following archives contain enough utils to 856build perl: F<gnufutil.zip>, F<gnusutil.zip>, F<gnututil.zip>, F<gnused.zip>, 857F<gnupatch.zip>, F<gnuawk.zip>, F<gnumake.zip>, F<gnugrep.zip>, F<bsddev.zip> and 858F<ksh527rt.zip> (or a later version). Note that all these utilities are 859known to be available from LEO: 860 861 ftp://crydee.sai.msu.ru/pub/comp/os/os2/leo/gnu/ 862 863Note also that the F<db.lib> and F<db.a> from the EMX distribution 864are not suitable for multi-threaded compile (even single-threaded 865flavor of Perl uses multi-threaded C RTL, for 866compatibility with XFree86-OS/2). Get a corrected one from 867 868 http://www.ilyaz.org/software/os2/db_mt.zip 869 870If you have I<exactly the same version of Perl> installed already, 871make sure that no copies or perl are currently running. Later steps 872of the build may fail since an older version of F<perl.dll> loaded into 873memory may be found. Running C<make test> becomes meaningless, since 874the test are checking a previous build of perl (this situation is detected 875and reported by F<os2/os2_base.t> test). Do not forget to unset 876C<PERL_EMXLOAD_SEC> in environment. 877 878Also make sure that you have F</tmp> directory on the current drive, 879and F<.> directory in your C<LIBPATH>. One may try to correct the 880latter condition by 881 882 set BEGINLIBPATH .\. 883 884if you use something like F<CMD.EXE> or latest versions of 885F<4os2.exe>. (Setting BEGINLIBPATH to just C<.> is ignored by the 886OS/2 kernel.) 887 888Make sure your gcc is good for C<-Zomf> linking: run C<omflibs> 889script in F</emx/lib> directory. 890 891Check that you have link386 installed. It comes standard with OS/2, 892but may be not installed due to customization. If typing 893 894 link386 895 896shows you do not have it, do I<Selective install>, and choose C<Link 897object modules> in I<Optional system utilities/More>. If you get into 898link386 prompts, press C<Ctrl-C> to exit. 899 900=head2 Getting perl source 901 902You need to fetch the latest perl source (including developers 903releases). With some probability it is located in 904 905 http://www.cpan.org/src/ 906 http://www.cpan.org/src/unsupported 907 908If not, you may need to dig in the indices to find it in the directory 909of the current maintainer. 910 911Quick cycle of developers release may break the OS/2 build time to 912time, looking into 913 914 http://www.cpan.org/ports/os2/ 915 916may indicate the latest release which was publicly released by the 917maintainer. Note that the release may include some additional patches 918to apply to the current source of perl. 919 920Extract it like this 921 922 tar vzxf perl5.00409.tar.gz 923 924You may see a message about errors while extracting F<Configure>. This is 925because there is a conflict with a similarly-named file F<configure>. 926 927Change to the directory of extraction. 928 929=head2 Application of the patches 930 931You need to apply the patches in F<./os2/diff.*> like this: 932 933 gnupatch -p0 < os2\diff.configure 934 935You may also need to apply the patches supplied with the binary 936distribution of perl. It also makes sense to look on the 937perl5-porters mailing list for the latest OS/2-related patches (see 938L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/>). Such 939patches usually contain strings C</os2/> and C<patch>, so it makes 940sense looking for these strings. 941 942=head2 Hand-editing 943 944You may look into the file F<./hints/os2.sh> and correct anything 945wrong you find there. I do not expect it is needed anywhere. 946 947=head2 Making 948 949 sh Configure -des -D prefix=f:/perllib 950 951C<prefix> means: where to install the resulting perl library. Giving 952correct prefix you may avoid the need to specify C<PERLLIB_PREFIX>, 953see L</"C<PERLLIB_PREFIX>">. 954 955I<Ignore the message about missing C<ln>, and about C<-c> option to 956tr>. The latter is most probably already fixed, if you see it and can trace 957where the latter spurious warning comes from, please inform me. 958 959Now 960 961 make 962 963At some moment the built may die, reporting a I<version mismatch> or 964I<unable to run F<perl>>. This means that you do not have F<.> in 965your LIBPATH, so F<perl.exe> cannot find the needed F<perl67B2.dll> (treat 966these hex digits as line noise). After this is fixed the build 967should finish without a lot of fuss. 968 969=head2 Testing 970 971Now run 972 973 make test 974 975All tests should succeed (with some of them skipped). If you have the 976same version of Perl installed, it is crucial that you have C<.> early 977in your LIBPATH (or in BEGINLIBPATH), otherwise your tests will most 978probably test the wrong version of Perl. 979 980Some tests may generate extra messages similar to 981 982=over 4 983 984=item A lot of C<bad free> 985 986in database tests related to Berkeley DB. I<This should be fixed already.> 987If it persists, you may disable this warnings, see L</"C<PERL_BADFREE>">. 988 989=item Process terminated by SIGTERM/SIGINT 990 991This is a standard message issued by OS/2 applications. *nix 992applications die in silence. It is considered to be a feature. One can 993easily disable this by appropriate sighandlers. 994 995However the test engine bleeds these message to screen in unexpected 996moments. Two messages of this kind I<should> be present during 997testing. 998 999=back 1000 1001To get finer test reports, call 1002 1003 perl t/harness 1004 1005The report with F<io/pipe.t> failing may look like this: 1006 1007 Failed Test Status Wstat Total Fail Failed List of failed 1008 ------------------------------------------------------------ 1009 io/pipe.t 12 1 8.33% 9 1010 7 tests skipped, plus 56 subtests skipped. 1011 Failed 1/195 test scripts, 99.49% okay. 1/6542 subtests failed, 1012 99.98% okay. 1013 1014The reasons for most important skipped tests are: 1015 1016=over 8 1017 1018=item F<op/fs.t> 1019 1020=over 4 1021 1022=item Z<>18 1023 1024Checks C<atime> and C<mtime> of C<stat()> - unfortunately, HPFS 1025provides only 2sec time granularity (for compatibility with FAT?). 1026 1027=item Z<>25 1028 1029Checks C<truncate()> on a filehandle just opened for write - I do not 1030know why this should or should not work. 1031 1032=back 1033 1034=item F<op/stat.t> 1035 1036Checks C<stat()>. Tests: 1037 1038=over 4 1039 1040=item 4 1041 1042Checks C<atime> and C<mtime> of C<stat()> - unfortunately, HPFS 1043provides only 2sec time granularity (for compatibility with FAT?). 1044 1045=back 1046 1047=back 1048 1049=head2 Installing the built perl 1050 1051If you haven't yet moved C<perl*.dll> onto LIBPATH, do it now. 1052 1053Run 1054 1055 make install 1056 1057It would put the generated files into needed locations. Manually put 1058F<perl.exe>, F<perl__.exe> and F<perl___.exe> to a location on your 1059PATH, F<perl.dll> to a location on your LIBPATH. 1060 1061Run 1062 1063 make installcmd INSTALLCMDDIR=d:/ir/on/path 1064 1065to convert perl utilities to F<.cmd> files and put them on 1066PATH. You need to put F<.EXE>-utilities on path manually. They are 1067installed in C<$prefix/bin>, here C<$prefix> is what you gave to 1068F<Configure>, see L</Making>. 1069 1070If you use C<man>, either move the installed F<*/man/> directories to 1071your C<MANPATH>, or modify C<MANPATH> to match the location. (One 1072could have avoided this by providing a correct C<manpath> option to 1073F<./Configure>, or editing F<./config.sh> between configuring and 1074making steps.) 1075 1076=head2 C<a.out>-style build 1077 1078Proceed as above, but make F<perl_.exe> (see L</"F<perl_.exe>">) by 1079 1080 make perl_ 1081 1082test and install by 1083 1084 make aout_test 1085 make aout_install 1086 1087Manually put F<perl_.exe> to a location on your PATH. 1088 1089B<Note.> The build process for C<perl_> I<does not know> about all the 1090dependencies, so you should make sure that anything is up-to-date, 1091say, by doing 1092 1093 make perl_dll 1094 1095first. 1096 1097=head1 Building a binary distribution 1098 1099[This section provides a short overview only...] 1100 1101Building should proceed differently depending on whether the version of perl 1102you install is already present and used on your system, or is a new version 1103not yet used. The description below assumes that the version is new, so 1104installing its DLLs and F<.pm> files will not disrupt the operation of your 1105system even if some intermediate steps are not yet fully working. 1106 1107The other cases require a little bit more convoluted procedures. Below I 1108suppose that the current version of Perl is C<5.8.2>, so the executables are 1109named accordingly. 1110 1111=over 1112 1113=item 1. 1114 1115Fully build and test the Perl distribution. Make sure that no tests are 1116failing with C<test> and C<aout_test> targets; fix the bugs in Perl and 1117the Perl test suite detected by these tests. Make sure that C<all_test> 1118make target runs as clean as possible. Check that F<os2/perlrexx.cmd> 1119runs fine. 1120 1121=item 2. 1122 1123Fully install Perl, including C<installcmd> target. Copy the generated DLLs 1124to C<LIBPATH>; copy the numbered Perl executables (as in F<perl5.8.2.exe>) 1125to C<PATH>; copy C<perl_.exe> to C<PATH> as C<perl_5.8.2.exe>. Think whether 1126you need backward-compatibility DLLs. In most cases you do not need to install 1127them yet; but sometime this may simplify the following steps. 1128 1129=item 3. 1130 1131Make sure that C<CPAN.pm> can download files from CPAN. If not, you may need 1132to manually install C<Net::FTP>. 1133 1134=item 4. 1135 1136Install the bundle C<Bundle::OS2_default> 1137 1138 perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_1 1139 1140This may take a couple of hours on 1GHz processor (when run the first time). 1141And this should not be necessarily a smooth procedure. Some modules may not 1142specify required dependencies, so one may need to repeat this procedure several 1143times until the results stabilize. 1144 1145 perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_2 1146 perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_3 1147 1148Even after they stabilize, some tests may fail. 1149 1150Fix as many discovered bugs as possible. Document all the bugs which are not 1151fixed, and all the failures with unknown reasons. Inspect the produced logs 1152F<00cpan_i_1> to find suspiciously skipped tests, and other fishy events. 1153 1154Keep in mind that I<installation> of some modules may fail too: for example, 1155the DLLs to update may be already loaded by F<CPAN.pm>. Inspect the C<install> 1156logs (in the example above F<00cpan_i_1> etc) for errors, and install things 1157manually, as in 1158 1159 cd $CPANHOME/.cpan/build/Digest-MD5-2.31 1160 make install 1161 1162Some distributions may fail some tests, but you may want to install them 1163anyway (as above, or via C<force install> command of C<CPAN.pm> shell-mode). 1164 1165Since this procedure may take quite a long time to complete, it makes sense 1166to "freeze" your CPAN configuration by disabling periodic updates of the 1167local copy of CPAN index: set C<index_expire> to some big value (I use 365), 1168then save the settings 1169 1170 CPAN> o conf index_expire 365 1171 CPAN> o conf commit 1172 1173Reset back to the default value C<1> when you are finished. 1174 1175=item 5. 1176 1177When satisfied with the results, rerun the C<installcmd> target. Now you 1178can copy C<perl5.8.2.exe> to C<perl.exe>, and install the other OMF-build 1179executables: C<perl__.exe> etc. They are ready to be used. 1180 1181=item 6. 1182 1183Change to the C<./pod> directory of the build tree, download the Perl logo 1184F<CamelGrayBig.BMP>, and run 1185 1186 ( perl2ipf > perl.ipf ) |& tee 00ipf 1187 ipfc /INF perl.ipf |& tee 00inf 1188 1189This produces the Perl docs online book C<perl.INF>. Install in on 1190C<BOOKSHELF> path. 1191 1192=item 7. 1193 1194Now is the time to build statically linked executable F<perl_.exe> which 1195includes newly-installed via C<Bundle::OS2_default> modules. Doing testing 1196via C<CPAN.pm> is going to be painfully slow, since it statically links 1197a new executable per XS extension. 1198 1199Here is a possible workaround: create a toplevel F<Makefile.PL> in 1200F<$CPANHOME/.cpan/build/> with contents being (compare with L</Making 1201executables with a custom collection of statically loaded extensions>) 1202 1203 use ExtUtils::MakeMaker; 1204 WriteMakefile NAME => 'dummy'; 1205 1206execute this as 1207 1208 perl_5.8.2.exe Makefile.PL <nul |& tee 00aout_c1 1209 make -k all test <nul |& 00aout_t1 1210 1211Again, this procedure should not be absolutely smooth. Some C<Makefile.PL>'s 1212in subdirectories may be buggy, and would not run as "child" scripts. The 1213interdependency of modules can strike you; however, since non-XS modules 1214are already installed, the prerequisites of most modules have a very good 1215chance to be present. 1216 1217If you discover some glitches, move directories of problematic modules to a 1218different location; if these modules are non-XS modules, you may just ignore 1219them - they are already installed; the remaining, XS, modules you need to 1220install manually one by one. 1221 1222After each such removal you need to rerun the C<Makefile.PL>/C<make> process; 1223usually this procedure converges soon. (But be sure to convert all the 1224necessary external C libraries from F<.lib> format to F<.a> format: run one of 1225 1226 emxaout foo.lib 1227 emximp -o foo.a foo.lib 1228 1229whichever is appropriate.) Also, make sure that the DLLs for external 1230libraries are usable with executables compiled without C<-Zmtd> options. 1231 1232When you are sure that only a few subdirectories 1233lead to failures, you may want to add C<-j4> option to C<make> to speed up 1234skipping subdirectories with already finished build. 1235 1236When you are satisfied with the results of tests, install the build C libraries 1237for extensions: 1238 1239 make install |& tee 00aout_i 1240 1241Now you can rename the file F<./perl.exe> generated during the last phase 1242to F<perl_5.8.2.exe>; place it on C<PATH>; if there is an inter-dependency 1243between some XS modules, you may need to repeat the C<test>/C<install> loop 1244with this new executable and some excluded modules - until the procedure 1245converges. 1246 1247Now you have all the necessary F<.a> libraries for these Perl modules in the 1248places where Perl builder can find it. Use the perl builder: change to an 1249empty directory, create a "dummy" F<Makefile.PL> again, and run 1250 1251 perl_5.8.2.exe Makefile.PL |& tee 00c 1252 make perl |& tee 00p 1253 1254This should create an executable F<./perl.exe> with all the statically loaded 1255extensions built in. Compare the generated F<perlmain.c> files to make sure 1256that during the iterations the number of loaded extensions only increases. 1257Rename F<./perl.exe> to F<perl_5.8.2.exe> on C<PATH>. 1258 1259When it converges, you got a functional variant of F<perl_5.8.2.exe>; copy it 1260to C<perl_.exe>. You are done with generation of the local Perl installation. 1261 1262=item 8. 1263 1264Make sure that the installed modules are actually installed in the location 1265of the new Perl, and are not inherited from entries of @INC given for 1266inheritance from the older versions of Perl: set C<PERLLIB_582_PREFIX> to 1267redirect the new version of Perl to a new location, and copy the installed 1268files to this new location. Redo the tests to make sure that the versions of 1269modules inherited from older versions of Perl are not needed. 1270 1271Actually, the log output of L<pod2ipf(1)> during the step 6 gives a very detailed 1272info about which modules are loaded from which place; so you may use it as 1273an additional verification tool. 1274 1275Check that some temporary files did not make into the perl install tree. 1276Run something like this 1277 1278 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 1279 1280in the install tree (both top one and F<sitelib> one). 1281 1282Compress all the DLLs with F<lxlite>. The tiny F<.exe> can be compressed with 1283C</c:max> (the bug only appears when there is a fixup in the last 6 bytes of a 1284page (?); since the tiny executables are much smaller than a page, the bug 1285will not hit). Do not compress C<perl_.exe> - it would not work under DOS. 1286 1287=item 9. 1288 1289Now you can generate the binary distribution. This is done by running the 1290test of the CPAN distribution C<OS2::SoftInstaller>. Tune up the file 1291F<test.pl> to suit the layout of current version of Perl first. Do not 1292forget to pack the necessary external DLLs accordingly. Include the 1293description of the bugs and test suite failures you could not fix. Include 1294the small-stack versions of Perl executables from Perl build directory. 1295 1296Include F<perl5.def> so that people can relink the perl DLL preserving 1297the binary compatibility, or can create compatibility DLLs. Include the diff 1298files (C<diff -pu old new>) of fixes you did so that people can rebuild your 1299version. Include F<perl5.map> so that one can use remote debugging. 1300 1301=item 10. 1302 1303Share what you did with the other people. Relax. Enjoy fruits of your work. 1304 1305=item 11. 1306 1307Brace yourself for thanks, bug reports, hate mail and spam coming as result 1308of the previous step. No good deed should remain unpunished! 1309 1310=back 1311 1312=head1 Building custom F<.EXE> files 1313 1314The Perl executables can be easily rebuilt at any moment. Moreover, one can 1315use the I<embedding> interface (see L<perlembed>) to make very customized 1316executables. 1317 1318=head2 Making executables with a custom collection of statically loaded extensions 1319 1320It is a little bit easier to do so while I<decreasing> the list of statically 1321loaded extensions. We discuss this case only here. 1322 1323=over 1324 1325=item 1. 1326 1327Change to an empty directory, and create a placeholder <Makefile.PL>: 1328 1329 use ExtUtils::MakeMaker; 1330 WriteMakefile NAME => 'dummy'; 1331 1332=item 2. 1333 1334Run it with the flavor of Perl (F<perl.exe> or F<perl_.exe>) you want to 1335rebuild. 1336 1337 perl_ Makefile.PL 1338 1339=item 3. 1340 1341Ask it to create new Perl executable: 1342 1343 make perl 1344 1345(you may need to manually add C<PERLTYPE=-DPERL_CORE> to this commandline on 1346some versions of Perl; the symptom is that the command-line globbing does not 1347work from OS/2 shells with the newly-compiled executable; check with 1348 1349 .\perl.exe -wle "print for @ARGV" * 1350 1351). 1352 1353=item 4. 1354 1355The previous step created F<perlmain.c> which contains a list of newXS() calls 1356near the end. Removing unnecessary calls, and rerunning 1357 1358 make perl 1359 1360will produce a customized executable. 1361 1362=back 1363 1364=head2 Making executables with a custom search-paths 1365 1366The default perl executable is flexible enough to support most usages. 1367However, one may want something yet more flexible; for example, one may want 1368to find Perl DLL relatively to the location of the EXE file; or one may want 1369to ignore the environment when setting the Perl-library search patch, etc. 1370 1371If you fill comfortable with I<embedding> interface (see L<perlembed>), such 1372things are easy to do repeating the steps outlined in L</Making 1373executables with a custom collection of statically loaded extensions>, and 1374doing more comprehensive edits to main() of F<perlmain.c>. The people with 1375little desire to understand Perl can just rename main(), and do necessary 1376modification in a custom main() which calls the renamed function in appropriate 1377time. 1378 1379However, there is a third way: perl DLL exports the main() function and several 1380callbacks to customize the search path. Below is a complete example of a 1381"Perl loader" which 1382 1383=over 1384 1385=item 1. 1386 1387Looks for Perl DLL in the directory C<$exedir/../dll>; 1388 1389=item 2. 1390 1391Prepends the above directory to C<BEGINLIBPATH>; 1392 1393=item 3. 1394 1395Fails if the Perl DLL found via C<BEGINLIBPATH> is different from what was 1396loaded on step 1; e.g., another process could have loaded it from C<LIBPATH> 1397or from a different value of C<BEGINLIBPATH>. In these cases one needs to 1398modify the setting of the system so that this other process either does not 1399run, or loads the DLL from C<BEGINLIBPATH> with C<LIBPATHSTRICT=T> (available 1400with kernels after September 2000). 1401 1402=item 4. 1403 1404Loads Perl library from C<$exedir/../dll/lib/>. 1405 1406=item 5. 1407 1408Uses Bourne shell from C<$exedir/../dll/sh/ksh.exe>. 1409 1410=back 1411 1412For best results compile the C file below with the same options as the Perl 1413DLL. However, a lot of functionality will work even if the executable is not 1414an EMX applications, e.g., if compiled with 1415 1416 gcc -Wall -DDOSISH -DOS2=1 -O2 -s -Zomf -Zsys perl-starter.c \ 1417 -DPERL_DLL_BASENAME=\"perl312F\" -Zstack 8192 -Zlinker /PM:VIO 1418 1419Here is the sample C file: 1420 1421 #define INCL_DOS 1422 #define INCL_NOPM 1423 /* These are needed for compile if os2.h includes os2tk.h, not 1424 * os2emx.h */ 1425 #define INCL_DOSPROCESS 1426 #include <os2.h> 1427 1428 #include "EXTERN.h" 1429 #define PERL_IN_MINIPERLMAIN_C 1430 #include "perl.h" 1431 1432 static char *me; 1433 HMODULE handle; 1434 1435 static void 1436 die_with(char *msg1, char *msg2, char *msg3, char *msg4) 1437 { 1438 ULONG c; 1439 char *s = " error: "; 1440 1441 DosWrite(2, me, strlen(me), &c); 1442 DosWrite(2, s, strlen(s), &c); 1443 DosWrite(2, msg1, strlen(msg1), &c); 1444 DosWrite(2, msg2, strlen(msg2), &c); 1445 DosWrite(2, msg3, strlen(msg3), &c); 1446 DosWrite(2, msg4, strlen(msg4), &c); 1447 DosWrite(2, "\r\n", 2, &c); 1448 exit(255); 1449 } 1450 1451 typedef ULONG (*fill_extLibpath_t)(int type, 1452 char *pre, 1453 char *post, 1454 int replace, 1455 char *msg); 1456 typedef int (*main_t)(int type, char *argv[], char *env[]); 1457 typedef int (*handler_t)(void* data, int which); 1458 1459 #ifndef PERL_DLL_BASENAME 1460 # define PERL_DLL_BASENAME "perl" 1461 #endif 1462 1463 static HMODULE 1464 load_perl_dll(char *basename) 1465 { 1466 char buf[300], fail[260]; 1467 STRLEN l, dirl; 1468 fill_extLibpath_t f; 1469 ULONG rc_fullname; 1470 HMODULE handle, handle1; 1471 1472 if (_execname(buf, sizeof(buf) - 13) != 0) 1473 die_with("Can't find full path: ", strerror(errno), "", ""); 1474 /* XXXX Fill 'me' with new value */ 1475 l = strlen(buf); 1476 while (l && buf[l-1] != '/' && buf[l-1] != '\\') 1477 l--; 1478 dirl = l - 1; 1479 strcpy(buf + l, basename); 1480 l += strlen(basename); 1481 strcpy(buf + l, ".dll"); 1482 if ( (rc_fullname = DosLoadModule(fail, sizeof fail, buf, &handle)) 1483 != 0 1484 && DosLoadModule(fail, sizeof fail, basename, &handle) != 0 ) 1485 die_with("Can't load DLL ", buf, "", ""); 1486 if (rc_fullname) 1487 return handle; /* was loaded with short name; all is fine */ 1488 if (DosQueryProcAddr(handle, 0, "fill_extLibpath", (PFN*)&f)) 1489 die_with(buf, 1490 ": DLL exports no symbol ", 1491 "fill_extLibpath", 1492 ""); 1493 buf[dirl] = 0; 1494 if (f(0 /*BEGINLIBPATH*/, buf /* prepend */, NULL /* append */, 1495 0 /* keep old value */, me)) 1496 die_with(me, ": prepending BEGINLIBPATH", "", ""); 1497 if (DosLoadModule(fail, sizeof fail, basename, &handle1) != 0) 1498 die_with(me, 1499 ": finding perl DLL again via BEGINLIBPATH", 1500 "", 1501 ""); 1502 buf[dirl] = '\\'; 1503 if (handle1 != handle) { 1504 if (DosQueryModuleName(handle1, sizeof(fail), fail)) 1505 strcpy(fail, "???"); 1506 die_with(buf, 1507 ":\n\tperl DLL via BEGINLIBPATH is different: \n\t", 1508 fail, 1509 "\n\tYou may need to manipulate global BEGINLIBPATH" 1510 " and LIBPATHSTRICT" 1511 "\n\tso that the other copy is loaded via" 1512 BEGINLIBPATH."); 1513 } 1514 return handle; 1515 } 1516 1517 int 1518 main(int argc, char **argv, char **env) 1519 { 1520 main_t f; 1521 handler_t h; 1522 1523 me = argv[0]; 1524 /**/ 1525 handle = load_perl_dll(PERL_DLL_BASENAME); 1526 1527 if (DosQueryProcAddr(handle, 1528 0, 1529 "Perl_OS2_handler_install", 1530 (PFN*)&h)) 1531 die_with(PERL_DLL_BASENAME, 1532 ": DLL exports no symbol ", 1533 "Perl_OS2_handler_install", 1534 ""); 1535 if ( !h((void *)"~installprefix", Perlos2_handler_perllib_from) 1536 || !h((void *)"~dll", Perlos2_handler_perllib_to) 1537 || !h((void *)"~dll/sh/ksh.exe", Perlos2_handler_perl_sh) ) 1538 die_with(PERL_DLL_BASENAME, 1539 ": Can't install @INC manglers", 1540 "", 1541 ""); 1542 if (DosQueryProcAddr(handle, 0, "dll_perlmain", (PFN*)&f)) 1543 die_with(PERL_DLL_BASENAME, 1544 ": DLL exports no symbol ", 1545 "dll_perlmain", 1546 ""); 1547 return f(argc, argv, env); 1548 } 1549 1550=head1 Build FAQ 1551 1552=head2 Some C</> became C<\> in pdksh. 1553 1554You have a very old pdksh. See L</Prerequisites>. 1555 1556=head2 C<'errno'> - unresolved external 1557 1558You do not have MT-safe F<db.lib>. See L</Prerequisites>. 1559 1560=head2 Problems with tr or sed 1561 1562reported with very old version of tr and sed. 1563 1564=head2 Some problem (forget which ;-) 1565 1566You have an older version of F<perl.dll> on your LIBPATH, which 1567broke the build of extensions. 1568 1569=head2 Library ... not found 1570 1571You did not run C<omflibs>. See L</Prerequisites>. 1572 1573=head2 Segfault in make 1574 1575You use an old version of GNU make. See L</Prerequisites>. 1576 1577=head2 op/sprintf test failure 1578 1579This can result from a bug in emx sprintf which was fixed in 0.9d fix 03. 1580 1581=head1 Specific (mis)features of OS/2 port 1582 1583=head2 C<setpriority>, C<getpriority> 1584 1585Note that these functions are compatible with *nix, not with the older 1586ports of '94 - 95. The priorities are absolute, go from 32 to -95, 1587lower is quicker. 0 is the default priority. 1588 1589B<WARNING>. Calling C<getpriority> on a non-existing process could lock 1590the system before Warp3 fixpak22. Starting with Warp3, Perl will use 1591a workaround: it aborts getpriority() if the process is not present. 1592This is not possible on older versions C<2.*>, and has a race 1593condition anyway. 1594 1595=head2 C<system()> 1596 1597Multi-argument form of C<system()> allows an additional numeric 1598argument. The meaning of this argument is described in 1599L<OS2::Process>. 1600 1601When finding a program to run, Perl first asks the OS to look for executables 1602on C<PATH> (OS/2 adds extension F<.exe> if no extension is present). 1603If not found, it looks for a script with possible extensions 1604added in this order: no extension, F<.cmd>, F<.btm>, 1605F<.bat>, F<.pl>. If found, Perl checks the start of the file for magic 1606strings C<"#!"> and C<"extproc ">. If found, Perl uses the rest of the 1607first line as the beginning of the command line to run this script. The 1608only mangling done to the first line is extraction of arguments (currently 1609up to 3), and ignoring of the path-part of the "interpreter" name if it can't 1610be found using the full path. 1611 1612E.g., C<system 'foo', 'bar', 'baz'> may lead Perl to finding 1613F<C:/emx/bin/foo.cmd> with the first line being 1614 1615 extproc /bin/bash -x -c 1616 1617If F</bin/bash.exe> is not found, then Perl looks for an executable F<bash.exe> on 1618C<PATH>. If found in F<C:/emx.add/bin/bash.exe>, then the above system() is 1619translated to 1620 1621 system qw(C:/emx.add/bin/bash.exe -x -c C:/emx/bin/foo.cmd bar baz) 1622 1623One additional translation is performed: instead of F</bin/sh> Perl uses 1624the hardwired-or-customized shell (see L</"C<PERL_SH_DIR>">). 1625 1626The above search for "interpreter" is recursive: if F<bash> executable is not 1627found, but F<bash.btm> is found, Perl will investigate its first line etc. 1628The only hardwired limit on the recursion depth is implicit: there is a limit 16294 on the number of additional arguments inserted before the actual arguments 1630given to system(). In particular, if no additional arguments are specified 1631on the "magic" first lines, then the limit on the depth is 4. 1632 1633If Perl finds that the found executable is of PM type when the 1634current session is not, it will start the new process in a separate session of 1635necessary type. Call via C<OS2::Process> to disable this magic. 1636 1637B<WARNING>. Due to the described logic, you need to explicitly 1638specify F<.com> extension if needed. Moreover, if the executable 1639F<perl5.6.1> is requested, Perl will not look for F<perl5.6.1.exe>. 1640[This may change in the future.] 1641 1642=head2 C<extproc> on the first line 1643 1644If the first chars of a Perl script are C<"extproc ">, this line is treated 1645as C<#!>-line, thus all the switches on this line are processed (twice 1646if script was started via cmd.exe). See L<perlrun/DESCRIPTION>. 1647 1648=head2 Additional modules: 1649 1650L<OS2::Process>, L<OS2::DLL>, L<OS2::REXX>, L<OS2::PrfDB>, L<OS2::ExtAttr>. These 1651modules provide access to additional numeric argument for C<system> 1652and to the information about the running process, 1653to DLLs having functions with REXX signature and to the REXX runtime, to 1654OS/2 databases in the F<.INI> format, and to Extended Attributes. 1655 1656Two additional extensions by Andreas Kaiser, C<OS2::UPM>, and 1657C<OS2::FTP>, are included into C<ILYAZ> directory, mirrored on CPAN. 1658Other OS/2-related extensions are available too. 1659 1660=head2 Prebuilt methods: 1661 1662=over 4 1663 1664=item C<File::Copy::syscopy> 1665 1666used by C<File::Copy::copy>, see L<File::Copy>. 1667 1668=item C<DynaLoader::mod2fname> 1669 1670used by C<DynaLoader> for DLL name mangling. 1671 1672=item C<Cwd::current_drive()> 1673 1674Self explanatory. 1675 1676=item C<Cwd::sys_chdir(name)> 1677 1678leaves drive as it is. 1679 1680=item C<Cwd::change_drive(name)> 1681 1682changes the "current" drive. 1683 1684=item C<Cwd::sys_is_absolute(name)> 1685 1686means has drive letter and is_rooted. 1687 1688=item C<Cwd::sys_is_rooted(name)> 1689 1690means has leading C<[/\\]> (maybe after a drive-letter:). 1691 1692=item C<Cwd::sys_is_relative(name)> 1693 1694means changes with current dir. 1695 1696=item C<Cwd::sys_cwd(name)> 1697 1698Interface to cwd from EMX. Used by C<Cwd::cwd>. 1699 1700=item C<Cwd::sys_abspath(name, dir)> 1701 1702Really really odious function to implement. Returns absolute name of 1703file which would have C<name> if CWD were C<dir>. C<Dir> defaults to the 1704current dir. 1705 1706=item C<Cwd::extLibpath([type])> 1707 1708Get current value of extended library search path. If C<type> is 1709present and positive, works with C<END_LIBPATH>, if negative, works 1710with C<LIBPATHSTRICT>, otherwise with C<BEGIN_LIBPATH>. 1711 1712=item C<Cwd::extLibpath_set( path [, type ] )> 1713 1714Set current value of extended library search path. If C<type> is 1715present and positive, works with <END_LIBPATH>, if negative, works 1716with C<LIBPATHSTRICT>, otherwise with C<BEGIN_LIBPATH>. 1717 1718=item C<OS2::Error(do_harderror,do_exception)> 1719 1720Returns C<undef> if it was not called yet, otherwise bit 1 is 1721set if on the previous call do_harderror was enabled, bit 17222 is set if on previous call do_exception was enabled. 1723 1724This function enables/disables error popups associated with 1725hardware errors (Disk not ready etc.) and software exceptions. 1726 1727I know of no way to find out the state of popups I<before> the first call 1728to this function. 1729 1730=item C<OS2::Errors2Drive(drive)> 1731 1732Returns C<undef> if it was not called yet, otherwise return false if errors 1733were not requested to be written to a hard drive, or the drive letter if 1734this was requested. 1735 1736This function may redirect error popups associated with hardware errors 1737(Disk not ready etc.) and software exceptions to the file POPUPLOG.OS2 at 1738the root directory of the specified drive. Overrides OS2::Error() specified 1739by individual programs. Given argument undef will disable redirection. 1740 1741Has global effect, persists after the application exits. 1742 1743I know of no way to find out the state of redirection of popups to the disk 1744I<before> the first call to this function. 1745 1746=item OS2::SysInfo() 1747 1748Returns a hash with system information. The keys of the hash are 1749 1750 MAX_PATH_LENGTH, MAX_TEXT_SESSIONS, MAX_PM_SESSIONS, 1751 MAX_VDM_SESSIONS, BOOT_DRIVE, DYN_PRI_VARIATION, 1752 MAX_WAIT, MIN_SLICE, MAX_SLICE, PAGE_SIZE, 1753 VERSION_MAJOR, VERSION_MINOR, VERSION_REVISION, 1754 MS_COUNT, TIME_LOW, TIME_HIGH, TOTPHYSMEM, TOTRESMEM, 1755 TOTAVAILMEM, MAXPRMEM, MAXSHMEM, TIMER_INTERVAL, 1756 MAX_COMP_LENGTH, FOREGROUND_FS_SESSION, 1757 FOREGROUND_PROCESS 1758 1759=item OS2::BootDrive() 1760 1761Returns a letter without colon. 1762 1763=item C<OS2::MorphPM(serve)>, C<OS2::UnMorphPM(serve)> 1764 1765Transforms the current application into a PM application and back. 1766The argument true means that a real message loop is going to be served. 1767OS2::MorphPM() returns the PM message queue handle as an integer. 1768 1769See L</"Centralized management of resources"> for additional details. 1770 1771=item C<OS2::Serve_Messages(force)> 1772 1773Fake on-demand retrieval of outstanding PM messages. If C<force> is false, 1774will not dispatch messages if a real message loop is known to 1775be present. Returns number of messages retrieved. 1776 1777Dies with "QUITing..." if WM_QUIT message is obtained. 1778 1779=item C<OS2::Process_Messages(force [, cnt])> 1780 1781Retrieval of PM messages until window creation/destruction. 1782If C<force> is false, will not dispatch messages if a real message loop 1783is known to be present. 1784 1785Returns change in number of windows. If C<cnt> is given, 1786it is incremented by the number of messages retrieved. 1787 1788Dies with "QUITing..." if WM_QUIT message is obtained. 1789 1790=item C<OS2::_control87(new,mask)> 1791 1792the same as L<_control87(3)> of EMX. Takes integers as arguments, returns 1793the previous coprocessor control word as an integer. Only bits in C<new> which 1794are present in C<mask> are changed in the control word. 1795 1796=item OS2::get_control87() 1797 1798gets the coprocessor control word as an integer. 1799 1800=item C<OS2::set_control87_em(new=MCW_EM,mask=MCW_EM)> 1801 1802The variant of OS2::_control87() with default values good for 1803handling exception mask: if no C<mask>, uses exception mask part of C<new> 1804only. If no C<new>, disables all the floating point exceptions. 1805 1806See L</"Misfeatures"> for details. 1807 1808=item C<OS2::DLLname([how [, \&xsub]])> 1809 1810Gives the information about the Perl DLL or the DLL containing the C 1811function bound to by C<&xsub>. The meaning of C<how> is: default (2): 1812full name; 0: handle; 1: module name. 1813 1814=back 1815 1816(Note that some of these may be moved to different libraries - 1817eventually). 1818 1819 1820=head2 Prebuilt variables: 1821 1822=over 4 1823 1824=item $OS2::emx_rev 1825 1826numeric value is the same as _emx_rev of EMX, a string value the same 1827as _emx_vprt (similar to C<0.9c>). 1828 1829=item $OS2::emx_env 1830 1831same as _emx_env of EMX, a number similar to 0x8001. 1832 1833=item $OS2::os_ver 1834 1835a number C<OS_MAJOR + 0.001 * OS_MINOR>. 1836 1837=item $OS2::is_aout 1838 1839true if the Perl library was compiled in AOUT format. 1840 1841=item $OS2::can_fork 1842 1843true if the current executable is an AOUT EMX executable, so Perl can 1844fork. Do not use this, use the portable check for 1845$Config::Config{dfork}. 1846 1847=item $OS2::nsyserror 1848 1849This variable (default is 1) controls whether to enforce the contents 1850of $^E to start with C<SYS0003>-like id. If set to 0, then the string 1851value of $^E is what is available from the OS/2 message file. (Some 1852messages in this file have an C<SYS0003>-like id prepended, some not.) 1853 1854=back 1855 1856=head2 Misfeatures 1857 1858=over 4 1859 1860=item * 1861 1862Since L<flock(3)> is present in EMX, but is not functional, it is 1863emulated by perl. To disable the emulations, set environment variable 1864C<USE_PERL_FLOCK=0>. 1865 1866=item * 1867 1868Here is the list of things which may be "broken" on 1869EMX (from EMX docs): 1870 1871=over 4 1872 1873=item * 1874 1875The functions L<recvmsg(3)>, L<sendmsg(3)>, and L<socketpair(3)> are not 1876implemented. 1877 1878=item * 1879 1880L<sock_init(3)> is not required and not implemented. 1881 1882=item * 1883 1884L<flock(3)> is not yet implemented (dummy function). (Perl has a workaround.) 1885 1886=item * 1887 1888L<kill(3)>: Special treatment of PID=0, PID=1 and PID=-1 is not implemented. 1889 1890=item * 1891 1892L<waitpid(3)>: 1893 1894 WUNTRACED 1895 Not implemented. 1896 waitpid() is not implemented for negative values of PID. 1897 1898=back 1899 1900Note that C<kill -9> does not work with the current version of EMX. 1901 1902=item * 1903 1904See L</"Text-mode filehandles">. 1905 1906=item * 1907 1908Unix-domain sockets on OS/2 live in a pseudo-file-system C</sockets/...>. 1909To avoid a failure to create a socket with a name of a different form, 1910C<"/socket/"> is prepended to the socket name (unless it starts with this 1911already). 1912 1913This may lead to problems later in case the socket is accessed via the 1914"usual" file-system calls using the "initial" name. 1915 1916=item * 1917 1918Apparently, IBM used a compiler (for some period of time around '95?) which 1919changes FP mask right and left. This is not I<that> bad for IBM's 1920programs, but the same compiler was used for DLLs which are used with 1921general-purpose applications. When these DLLs are used, the state of 1922floating-point flags in the application is not predictable. 1923 1924What is much worse, some DLLs change the floating point flags when in 1925_DLLInitTerm() (e.g., F<TCP32IP>). This means that even if you do not I<call> 1926any function in the DLL, just the act of loading this DLL will reset your 1927flags. What is worse, the same compiler was used to compile some HOOK DLLs. 1928Given that HOOK dlls are executed in the context of I<all> the applications 1929in the system, this means a complete unpredictability of floating point 1930flags on systems using such HOOK DLLs. E.g., F<GAMESRVR.DLL> of B<DIVE> 1931origin changes the floating point flags on each write to the TTY of a VIO 1932(windowed text-mode) applications. 1933 1934Some other (not completely debugged) situations when FP flags change include 1935some video drivers (?), and some operations related to creation of the windows. 1936People who code B<OpenGL> may have more experience on this. 1937 1938Perl is generally used in the situation when all the floating-point 1939exceptions are ignored, as is the default under EMX. If they are not ignored, 1940some benign Perl programs would get a C<SIGFPE> and would die a horrible death. 1941 1942To circumvent this, Perl uses two hacks. They help against I<one> type of 1943damage only: FP flags changed when loading a DLL. 1944 1945One of the hacks is to disable floating point exceptions on Perl startup (as 1946is the default with EMX). This helps only with compile-time-linked DLLs 1947changing the flags before main() had a chance to be called. 1948 1949The other hack is to restore FP flags after a call to dlopen(). This helps 1950against similar damage done by DLLs _DLLInitTerm() at runtime. Currently 1951no way to switch these hacks off is provided. 1952 1953=back 1954 1955=head2 Modifications 1956 1957Perl modifies some standard C library calls in the following ways: 1958 1959=over 9 1960 1961=item C<popen> 1962 1963C<my_popen> uses F<sh.exe> if shell is required, cf. L</"C<PERL_SH_DIR>">. 1964 1965=item C<tmpnam> 1966 1967is created using C<TMP> or C<TEMP> environment variable, via 1968C<tempnam>. 1969 1970=item C<tmpfile> 1971 1972If the current directory is not writable, file is created using modified 1973C<tmpnam>, so there may be a race condition. 1974 1975=item C<ctermid> 1976 1977a dummy implementation. 1978 1979=item C<stat> 1980 1981C<os2_stat> special-cases F</dev/tty> and F</dev/con>. 1982 1983=item C<mkdir>, C<rmdir> 1984 1985these EMX functions do not work if the path contains a trailing C</>. 1986Perl contains a workaround for this. 1987 1988=item C<flock> 1989 1990Since L<flock(3)> is present in EMX, but is not functional, it is 1991emulated by perl. To disable the emulations, set environment variable 1992C<USE_PERL_FLOCK=0>. 1993 1994=back 1995 1996=head2 Identifying DLLs 1997 1998All the DLLs built with the current versions of Perl have ID strings 1999identifying the name of the extension, its version, and the version 2000of Perl required for this DLL. Run C<bldlevel DLL-name> to find this 2001info. 2002 2003=head2 Centralized management of resources 2004 2005Since to call certain OS/2 API one needs to have a correctly initialized 2006C<Win> subsystem, OS/2-specific extensions may require getting C<HAB>s and 2007C<HMQ>s. If an extension would do it on its own, another extension could 2008fail to initialize. 2009 2010Perl provides a centralized management of these resources: 2011 2012=over 2013 2014=item C<HAB> 2015 2016To get the HAB, the extension should call C<hab = perl_hab_GET()> in C. After 2017this call is performed, C<hab> may be accessed as C<Perl_hab>. There is 2018no need to release the HAB after it is used. 2019 2020If by some reasons F<perl.h> cannot be included, use 2021 2022 extern int Perl_hab_GET(void); 2023 2024instead. 2025 2026=item C<HMQ> 2027 2028There are two cases: 2029 2030=over 2031 2032=item * 2033 2034the extension needs an C<HMQ> only because some API will not work otherwise. 2035Use C<serve = 0> below. 2036 2037=item * 2038 2039the extension needs an C<HMQ> since it wants to engage in a PM event loop. 2040Use C<serve = 1> below. 2041 2042=back 2043 2044To get an C<HMQ>, the extension should call C<hmq = perl_hmq_GET(serve)> in C. 2045After this call is performed, C<hmq> may be accessed as C<Perl_hmq>. 2046 2047To signal to Perl that HMQ is not needed any more, call 2048C<perl_hmq_UNSET(serve)>. Perl process will automatically morph/unmorph itself 2049into/from a PM process if HMQ is needed/not-needed. Perl will automatically 2050enable/disable C<WM_QUIT> message during shutdown if the message queue is 2051served/not-served. 2052 2053B<NOTE>. If during a shutdown there is a message queue which did not disable 2054WM_QUIT, and which did not process the received WM_QUIT message, the 2055shutdown will be automatically cancelled. Do not call C<perl_hmq_GET(1)> 2056unless you are going to process messages on an orderly basis. 2057 2058=item Treating errors reported by OS/2 API 2059 2060There are two principal conventions (it is useful to call them C<Dos*> 2061and C<Win*> - though this part of the function signature is not always 2062determined by the name of the API) of reporting the error conditions 2063of OS/2 API. Most of C<Dos*> APIs report the error code as the result 2064of the call (so 0 means success, and there are many types of errors). 2065Most of C<Win*> API report success/fail via the result being 2066C<TRUE>/C<FALSE>; to find the reason for the failure one should call 2067WinGetLastError() API. 2068 2069Some C<Win*> entry points also overload a "meaningful" return value 2070with the error indicator; having a 0 return value indicates an error. 2071Yet some other C<Win*> entry points overload things even more, and 0 2072return value may mean a successful call returning a valid value 0, as 2073well as an error condition; in the case of a 0 return value one should 2074call WinGetLastError() API to distinguish a successful call from a 2075failing one. 2076 2077By convention, all the calls to OS/2 API should indicate their 2078failures by resetting $^E. All the Perl-accessible functions which 2079call OS/2 API may be broken into two classes: some die()s when an API 2080error is encountered, the other report the error via a false return 2081value (of course, this does not concern Perl-accessible functions 2082which I<expect> a failure of the OS/2 API call, having some workarounds 2083coded). 2084 2085Obviously, in the situation of the last type of the signature of an OS/2 2086API, it is must more convenient for the users if the failure is 2087indicated by die()ing: one does not need to check $^E to know that 2088something went wrong. If, however, this solution is not desirable by 2089some reason, the code in question should reset $^E to 0 before making 2090this OS/2 API call, so that the caller of this Perl-accessible 2091function has a chance to distinguish a success-but-0-return value from 2092a failure. (One may return undef as an alternative way of reporting 2093an error.) 2094 2095The macros to simplify this type of error propagation are 2096 2097=over 2098 2099=item C<CheckOSError(expr)> 2100 2101Returns true on error, sets $^E. Expects expr() be a call of 2102C<Dos*>-style API. 2103 2104=item C<CheckWinError(expr)> 2105 2106Returns true on error, sets $^E. Expects expr() be a call of 2107C<Win*>-style API. 2108 2109=item C<SaveWinError(expr)> 2110 2111Returns C<expr>, sets $^E from WinGetLastError() if C<expr> is false. 2112 2113=item C<SaveCroakWinError(expr,die,name1,name2)> 2114 2115Returns C<expr>, sets $^E from WinGetLastError() if C<expr> is false, 2116and die()s if C<die> and $^E are true. The message to die is the 2117concatenated strings C<name1> and C<name2>, separated by C<": "> from 2118the contents of $^E. 2119 2120=item C<WinError_2_Perl_rc> 2121 2122Sets C<Perl_rc> to the return value of WinGetLastError(). 2123 2124=item C<FillWinError> 2125 2126Sets C<Perl_rc> to the return value of WinGetLastError(), and sets $^E 2127to the corresponding value. 2128 2129=item C<FillOSError(rc)> 2130 2131Sets C<Perl_rc> to C<rc>, and sets $^E to the corresponding value. 2132 2133=back 2134 2135=item Loading DLLs and ordinals in DLLs 2136 2137Some DLLs are only present in some versions of OS/2, or in some 2138configurations of OS/2. Some exported entry points are present only 2139in DLLs shipped with some versions of OS/2. If these DLLs and entry 2140points were linked directly for a Perl executable/DLL or from a Perl 2141extensions, this binary would work only with the specified 2142versions/setups. Even if these entry points were not needed, the 2143I<load> of the executable (or DLL) would fail. 2144 2145For example, many newer useful APIs are not present in OS/2 v2; many 2146PM-related APIs require DLLs not available on floppy-boot setup. 2147 2148To make these calls fail I<only when the calls are executed>, one 2149should call these API via a dynamic linking API. There is a subsystem 2150in Perl to simplify such type of calls. A large number of entry 2151points available for such linking is provided (see C<entries_ordinals> 2152- and also C<PMWIN_entries> - in F<os2ish.h>). These ordinals can be 2153accessed via the APIs: 2154 2155 CallORD(), DeclFuncByORD(), DeclVoidFuncByORD(), 2156 DeclOSFuncByORD(), DeclWinFuncByORD(), AssignFuncPByORD(), 2157 DeclWinFuncByORD_CACHE(), DeclWinFuncByORD_CACHE_survive(), 2158 DeclWinFuncByORD_CACHE_resetError_survive(), 2159 DeclWinFunc_CACHE(), DeclWinFunc_CACHE_resetError(), 2160 DeclWinFunc_CACHE_survive(), DeclWinFunc_CACHE_resetError_survive() 2161 2162See the header files and the C code in the supplied OS/2-related 2163modules for the details on usage of these functions. 2164 2165Some of these functions also combine dynaloading semantic with the 2166error-propagation semantic discussed above. 2167 2168=back 2169 2170=head1 Perl flavors 2171 2172Because of idiosyncrasies of OS/2 one cannot have all the eggs in the 2173same basket (though EMX environment tries hard to overcome this 2174limitations, so the situation may somehow improve). There are 4 2175executables for Perl provided by the distribution: 2176 2177=head2 F<perl.exe> 2178 2179The main workhorse. This is a chimera executable: it is compiled as an 2180C<a.out>-style executable, but is linked with C<omf>-style dynamic 2181library F<perl.dll>, and with dynamic CRT DLL. This executable is a 2182VIO application. 2183 2184It can load perl dynamic extensions, and it can fork(). 2185 2186B<Note.> Keep in mind that fork() is needed to open a pipe to yourself. 2187 2188=head2 F<perl_.exe> 2189 2190This is a statically linked C<a.out>-style executable. It cannot 2191load dynamic Perl extensions. The executable supplied in binary 2192distributions has a lot of extensions prebuilt, thus the above restriction is 2193important only if you use custom-built extensions. This executable is a VIO 2194application. 2195 2196I<This is the only executable with does not require OS/2.> The 2197friends locked into C<M$> world would appreciate the fact that this 2198executable runs under DOS, Win0.3*, Win0.95 and WinNT with an 2199appropriate extender. See L</"Other OSes">. 2200 2201=head2 F<perl__.exe> 2202 2203This is the same executable as F<perl___.exe>, but it is a PM 2204application. 2205 2206B<Note.> Usually (unless explicitly redirected during the startup) 2207STDIN, STDERR, and STDOUT of a PM 2208application are redirected to F<nul>. However, it is possible to I<see> 2209them if you start C<perl__.exe> from a PM program which emulates a 2210console window, like I<Shell mode> of Emacs or EPM. Thus it I<is 2211possible> to use Perl debugger (see L<perldebug>) to debug your PM 2212application (but beware of the message loop lockups - this will not 2213work if you have a message queue to serve, unless you hook the serving 2214into the getc() function of the debugger). 2215 2216Another way to see the output of a PM program is to run it as 2217 2218 pm_prog args 2>&1 | cat - 2219 2220with a shell I<different> from F<cmd.exe>, so that it does not create 2221a link between a VIO session and the session of C<pm_porg>. (Such a link 2222closes the VIO window.) E.g., this works with F<sh.exe> - or with Perl! 2223 2224 open P, 'pm_prog args 2>&1 |' or die; 2225 print while <P>; 2226 2227The flavor F<perl__.exe> is required if you want to start your program without 2228a VIO window present, but not C<detach>ed (run C<help detach> for more info). 2229Very useful for extensions which use PM, like C<Perl/Tk> or C<OpenGL>. 2230 2231Note also that the differences between PM and VIO executables are only 2232in the I<default> behaviour. One can start I<any> executable in 2233I<any> kind of session by using the arguments C</fs>, C</pm> or 2234C</win> switches of the command C<start> (of F<CMD.EXE> or a similar 2235shell). Alternatively, one can use the numeric first argument of the 2236C<system> Perl function (see L<OS2::Process>). 2237 2238=head2 F<perl___.exe> 2239 2240This is an C<omf>-style executable which is dynamically linked to 2241F<perl.dll> and CRT DLL. I know no advantages of this executable 2242over C<perl.exe>, but it cannot fork() at all. Well, one advantage is 2243that the build process is not so convoluted as with C<perl.exe>. 2244 2245It is a VIO application. 2246 2247=head2 Why strange names? 2248 2249Since Perl processes the C<#!>-line (cf. 2250L<perlrun/DESCRIPTION>, L<perlrun/Command Switches>, 2251L<perldiag/"No Perl script found in input">), it should know when a 2252program I<is a Perl>. There is some naming convention which allows 2253Perl to distinguish correct lines from wrong ones. The above names are 2254almost the only names allowed by this convention which do not contain 2255digits (which have absolutely different semantics). 2256 2257=head2 Why dynamic linking? 2258 2259Well, having several executables dynamically linked to the same huge 2260library has its advantages, but this would not substantiate the 2261additional work to make it compile. The reason is the complicated-to-developers 2262but very quick and convenient-to-users "hard" dynamic linking used by OS/2. 2263 2264There are two distinctive features of the dyna-linking model of OS/2: 2265first, all the references to external functions are resolved at the compile time; 2266second, there is no runtime fixup of the DLLs after they are loaded into memory. 2267The first feature is an enormous advantage over other models: it avoids 2268conflicts when several DLLs used by an application export entries with 2269the same name. In such cases "other" models of dyna-linking just choose 2270between these two entry points using some random criterion - with predictable 2271disasters as results. But it is the second feature which requires the build 2272of F<perl.dll>. 2273 2274The address tables of DLLs are patched only once, when they are 2275loaded. The addresses of the entry points into DLLs are guaranteed to be 2276the same for all the programs which use the same DLL. This removes the 2277runtime fixup - once DLL is loaded, its code is read-only. 2278 2279While this allows some (significant?) performance advantages, this makes life 2280much harder for developers, since the above scheme makes it impossible 2281for a DLL to be "linked" to a symbol in the F<.EXE> file. Indeed, this 2282would need a DLL to have different relocations tables for the 2283(different) executables which use this DLL. 2284 2285However, a dynamically loaded Perl extension is forced to use some symbols 2286from the perl 2287executable, e.g., to know how to find the arguments to the functions: 2288the arguments live on the perl 2289internal evaluation stack. The solution is to put the main code of 2290the interpreter into a DLL, and make the F<.EXE> file which just loads 2291this DLL into memory and supplies command-arguments. The extension DLL 2292cannot link to symbols in F<.EXE>, but it has no problem linking 2293to symbols in the F<.DLL>. 2294 2295This I<greatly> increases the load time for the application (as well as 2296complexity of the compilation). Since interpreter is in a DLL, 2297the C RTL is basically forced to reside in a DLL as well (otherwise 2298extensions would not be able to use CRT). There are some advantages if 2299you use different flavors of perl, such as running F<perl.exe> and 2300F<perl__.exe> simultaneously: they share the memory of F<perl.dll>. 2301 2302B<NOTE>. There is one additional effect which makes DLLs more wasteful: 2303DLLs are loaded in the shared memory region, which is a scarse resource 2304given the 512M barrier of the "standard" OS/2 virtual memory. The code of 2305F<.EXE> files is also shared by all the processes which use the particular 2306F<.EXE>, but they are "shared in the private address space of the process"; 2307this is possible because the address at which different sections 2308of the F<.EXE> file are loaded is decided at compile-time, thus all the 2309processes have these sections loaded at same addresses, and no fixup 2310of internal links inside the F<.EXE> is needed. 2311 2312Since DLLs may be loaded at run time, to have the same mechanism for DLLs 2313one needs to have the address range of I<any of the loaded> DLLs in the 2314system to be available I<in all the processes> which did not load a particular 2315DLL yet. This is why the DLLs are mapped to the shared memory region. 2316 2317=head2 Why chimera build? 2318 2319Current EMX environment does not allow DLLs compiled using Unixish 2320C<a.out> format to export symbols for data (or at least some types of 2321data). This forces C<omf>-style compile of F<perl.dll>. 2322 2323Current EMX environment does not allow F<.EXE> files compiled in 2324C<omf> format to fork(). fork() is needed for exactly three Perl 2325operations: 2326 2327=over 4 2328 2329=item * 2330 2331explicit fork() in the script, 2332 2333=item * 2334 2335C<open FH, "|-"> 2336 2337=item * 2338 2339C<open FH, "-|">, in other words, opening pipes to itself. 2340 2341=back 2342 2343While these operations are not questions of life and death, they are 2344needed for a lot of 2345useful scripts. This forces C<a.out>-style compile of 2346F<perl.exe>. 2347 2348 2349=head1 ENVIRONMENT 2350 2351Here we list environment variables with are either OS/2- and DOS- and 2352Win*-specific, or are more important under OS/2 than under other OSes. 2353 2354=head2 C<PERLLIB_PREFIX> 2355 2356Specific for EMX port. Should have the form 2357 2358 path1;path2 2359 2360or 2361 2362 path1 path2 2363 2364If the beginning of some prebuilt path matches F<path1>, it is 2365substituted with F<path2>. 2366 2367Should be used if the perl library is moved from the default 2368location in preference to C<PERL(5)LIB>, since this would not leave wrong 2369entries in @INC. For example, if the compiled version of perl looks for @INC 2370in F<f:/perllib/lib>, and you want to install the library in 2371F<h:/opt/gnu>, do 2372 2373 set PERLLIB_PREFIX=f:/perllib/lib;h:/opt/gnu 2374 2375This will cause Perl with the prebuilt @INC of 2376 2377 f:/perllib/lib/5.00553/os2 2378 f:/perllib/lib/5.00553 2379 f:/perllib/lib/site_perl/5.00553/os2 2380 f:/perllib/lib/site_perl/5.00553 2381 . 2382 2383to use the following @INC: 2384 2385 h:/opt/gnu/5.00553/os2 2386 h:/opt/gnu/5.00553 2387 h:/opt/gnu/site_perl/5.00553/os2 2388 h:/opt/gnu/site_perl/5.00553 2389 . 2390 2391=head2 C<PERL_BADLANG> 2392 2393If 0, perl ignores setlocale() failing. May be useful with some 2394strange I<locale>s. 2395 2396=head2 C<PERL_BADFREE> 2397 2398If 0, perl would not warn of in case of unwarranted free(). With older 2399perls this might be 2400useful in conjunction with the module DB_File, which was buggy when 2401dynamically linked and OMF-built. 2402 2403Should not be set with newer Perls, since this may hide some I<real> problems. 2404 2405=head2 C<PERL_SH_DIR> 2406 2407Specific for EMX port. Gives the directory part of the location for 2408F<sh.exe>. 2409 2410=head2 C<USE_PERL_FLOCK> 2411 2412Specific for EMX port. Since L<flock(3)> is present in EMX, but is not 2413functional, it is emulated by perl. To disable the emulations, set 2414environment variable C<USE_PERL_FLOCK=0>. 2415 2416=head2 C<TMP> or C<TEMP> 2417 2418Specific for EMX port. Used as storage place for temporary files. 2419 2420=head1 Evolution 2421 2422Here we list major changes which could make you by surprise. 2423 2424=head2 Text-mode filehandles 2425 2426Starting from version 5.8, Perl uses a builtin translation layer for 2427text-mode files. This replaces the efficient well-tested EMX layer by 2428some code which should be best characterized as a "quick hack". 2429 2430In addition to possible bugs and an inability to follow changes to the 2431translation policy with off/on switches of TERMIO translation, this 2432introduces a serious incompatible change: before sysread() on 2433text-mode filehandles would go through the translation layer, now it 2434would not. 2435 2436=head2 Priorities 2437 2438C<setpriority> and C<getpriority> are not compatible with earlier 2439ports by Andreas Kaiser. See L</setpriority, getpriority>. 2440 2441=head2 DLL name mangling: pre 5.6.2 2442 2443With the release 5.003_01 the dynamically loadable libraries 2444should be rebuilt when a different version of Perl is compiled. In particular, 2445DLLs (including F<perl.dll>) are now created with the names 2446which contain a checksum, thus allowing workaround for OS/2 scheme of 2447caching DLLs. 2448 2449It may be possible to code a simple workaround which would 2450 2451=over 2452 2453=item * 2454 2455find the old DLLs looking through the old @INC; 2456 2457=item * 2458 2459mangle the names according to the scheme of new perl and copy the DLLs to 2460these names; 2461 2462=item * 2463 2464edit the internal C<LX> tables of DLL to reflect the change of the name 2465(probably not needed for Perl extension DLLs, since the internally coded names 2466are not used for "specific" DLLs, they used only for "global" DLLs). 2467 2468=item * 2469 2470edit the internal C<IMPORT> tables and change the name of the "old" 2471F<perl????.dll> to the "new" F<perl????.dll>. 2472 2473=back 2474 2475=head2 DLL name mangling: 5.6.2 and beyond 2476 2477In fact mangling of I<extension> DLLs was done due to misunderstanding 2478of the OS/2 dynaloading model. OS/2 (effectively) maintains two 2479different tables of loaded DLL: 2480 2481=over 2482 2483=item Global DLLs 2484 2485those loaded by the base name from C<LIBPATH>; including those 2486associated at link time; 2487 2488=item specific DLLs 2489 2490loaded by the full name. 2491 2492=back 2493 2494When resolving a request for a global DLL, the table of already-loaded 2495specific DLLs is (effectively) ignored; moreover, specific DLLs are 2496I<always> loaded from the prescribed path. 2497 2498There is/was a minor twist which makes this scheme fragile: what to do 2499with DLLs loaded from 2500 2501=over 2502 2503=item C<BEGINLIBPATH> and C<ENDLIBPATH> 2504 2505(which depend on the process) 2506 2507=item F<.> from C<LIBPATH> 2508 2509which I<effectively> depends on the process (although C<LIBPATH> is the 2510same for all the processes). 2511 2512=back 2513 2514Unless C<LIBPATHSTRICT> is set to C<T> (and the kernel is after 25152000/09/01), such DLLs are considered to be global. When loading a 2516global DLL it is first looked in the table of already-loaded global 2517DLLs. Because of this the fact that one executable loaded a DLL from 2518C<BEGINLIBPATH> and C<ENDLIBPATH>, or F<.> from C<LIBPATH> may affect 2519I<which> DLL is loaded when I<another> executable requests a DLL with 2520the same name. I<This> is the reason for version-specific mangling of 2521the DLL name for perl DLL. 2522 2523Since the Perl extension DLLs are always loaded with the full path, 2524there is no need to mangle their names in a version-specific ways: 2525their directory already reflects the corresponding version of perl, 2526and @INC takes into account binary compatibility with older version. 2527Starting from C<5.6.2> the name mangling scheme is fixed to be the 2528same as for Perl 5.005_53 (same as in a popular binary release). Thus 2529new Perls will be able to I<resolve the names> of old extension DLLs 2530if @INC allows finding their directories. 2531 2532However, this still does not guarantee that these DLL may be loaded. 2533The reason is the mangling of the name of the I<Perl DLL>. And since 2534the extension DLLs link with the Perl DLL, extension DLLs for older 2535versions would load an older Perl DLL, and would most probably 2536segfault (since the data in this DLL is not properly initialized). 2537 2538There is a partial workaround (which can be made complete with newer 2539OS/2 kernels): create a forwarder DLL with the same name as the DLL of 2540the older version of Perl, which forwards the entry points to the 2541newer Perl's DLL. Make this DLL accessible on (say) the C<BEGINLIBPATH> of 2542the new Perl executable. When the new executable accesses old Perl's 2543extension DLLs, they would request the old Perl's DLL by name, get the 2544forwarder instead, so effectively will link with the currently running 2545(new) Perl DLL. 2546 2547This may break in two ways: 2548 2549=over 2550 2551=item * 2552 2553Old perl executable is started when a new executable is running has 2554loaded an extension compiled for the old executable (ouph!). In this 2555case the old executable will get a forwarder DLL instead of the old 2556perl DLL, so would link with the new perl DLL. While not directly 2557fatal, it will behave the same as new executable. This beats the whole 2558purpose of explicitly starting an old executable. 2559 2560=item * 2561 2562A new executable loads an extension compiled for the old executable 2563when an old perl executable is running. In this case the extension 2564will not pick up the forwarder - with fatal results. 2565 2566=back 2567 2568With support for C<LIBPATHSTRICT> this may be circumvented - unless 2569one of DLLs is started from F<.> from C<LIBPATH> (I do not know 2570whether C<LIBPATHSTRICT> affects this case). 2571 2572B<REMARK>. Unless newer kernels allow F<.> in C<BEGINLIBPATH> (older 2573do not), this mess cannot be completely cleaned. (It turns out that 2574as of the beginning of 2002, F<.> is not allowed, but F<.\.> is - and 2575it has the same effect.) 2576 2577 2578B<REMARK>. C<LIBPATHSTRICT>, C<BEGINLIBPATH> and C<ENDLIBPATH> are 2579not environment variables, although F<cmd.exe> emulates them on C<SET 2580...> lines. From Perl they may be accessed by 2581L<Cwd::extLibpath|/Cwd::extLibpath([type])> and 2582L<Cwd::extLibpath_set|/Cwd::extLibpath_set( path [, type ] )>. 2583 2584=head2 DLL forwarder generation 2585 2586Assume that the old DLL is named F<perlE0AC.dll> (as is one for 25875.005_53), and the new version is 5.6.1. Create a file 2588F<perl5shim.def-leader> with 2589 2590 LIBRARY 'perlE0AC' INITINSTANCE TERMINSTANCE 2591 DESCRIPTION '@#perl5-porters@perl.org:5.006001#@ Perl module for 5.00553 -> Perl 5.6.1 forwarder' 2592 CODE LOADONCALL 2593 DATA LOADONCALL NONSHARED MULTIPLE 2594 EXPORTS 2595 2596modifying the versions/names as needed. Run 2597 2598 perl -wnle "next if 0../EXPORTS/; print qq( \"$1\") 2599 if /\"(\w+)\"/" perl5.def >lst 2600 2601in the Perl build directory (to make the DLL smaller replace perl5.def 2602with the definition file for the older version of Perl if present). 2603 2604 cat perl5shim.def-leader lst >perl5shim.def 2605 gcc -Zomf -Zdll -o perlE0AC.dll perl5shim.def -s -llibperl 2606 2607(ignore multiple C<warning L4085>). 2608 2609=head2 Threading 2610 2611As of release 5.003_01 perl is linked to multithreaded C RTL 2612DLL. If perl itself is not compiled multithread-enabled, so will not be perl's 2613malloc(). However, extensions may use multiple thread on their own 2614risk. 2615 2616This was needed to compile C<Perl/Tk> for XFree86-OS/2 out-of-the-box, and 2617link with DLLs for other useful libraries, which typically are compiled 2618with C<-Zmt -Zcrtdll>. 2619 2620=head2 Calls to external programs 2621 2622Due to a popular demand the perl external program calling has been 2623changed wrt Andreas Kaiser's port. I<If> perl needs to call an 2624external program I<via shell>, the F<f:/bin/sh.exe> will be called, or 2625whatever is the override, see L</"C<PERL_SH_DIR>">. 2626 2627Thus means that you need to get some copy of a F<sh.exe> as well (I 2628use one from pdksh). The path F<F:/bin> above is set up automatically during 2629the build to a correct value on the builder machine, but is 2630overridable at runtime, 2631 2632B<Reasons:> a consensus on C<perl5-porters> was that perl should use 2633one non-overridable shell per platform. The obvious choices for OS/2 2634are F<cmd.exe> and F<sh.exe>. Having perl build itself would be impossible 2635with F<cmd.exe> as a shell, thus I picked up C<sh.exe>. This assures almost 2636100% compatibility with the scripts coming from *nix. As an added benefit 2637this works as well under DOS if you use DOS-enabled port of pdksh 2638(see L</Prerequisites>). 2639 2640B<Disadvantages:> currently F<sh.exe> of pdksh calls external programs 2641via fork()/exec(), and there is I<no> functioning exec() on 2642OS/2. exec() is emulated by EMX by an asynchronous call while the caller 2643waits for child completion (to pretend that the C<pid> did not change). This 2644means that 1 I<extra> copy of F<sh.exe> is made active via fork()/exec(), 2645which may lead to some resources taken from the system (even if we do 2646not count extra work needed for fork()ing). 2647 2648Note that this a lesser issue now when we do not spawn F<sh.exe> 2649unless needed (metachars found). 2650 2651One can always start F<cmd.exe> explicitly via 2652 2653 system 'cmd', '/c', 'mycmd', 'arg1', 'arg2', ... 2654 2655If you need to use F<cmd.exe>, and do not want to hand-edit thousands of your 2656scripts, the long-term solution proposed on p5-p is to have a directive 2657 2658 use OS2::Cmd; 2659 2660which will override system(), exec(), C<``>, and 2661C<open(,'...|')>. With current perl you may override only system(), 2662readpipe() - the explicit version of C<``>, and maybe exec(). The code 2663will substitute the one-argument call to system() by 2664C<CORE::system('cmd.exe', '/c', shift)>. 2665 2666If you have some working code for C<OS2::Cmd>, please send it to me, 2667I will include it into distribution. I have no need for such a module, so 2668cannot test it. 2669 2670For the details of the current situation with calling external programs, 2671see L</Starting OSE<sol>2 (and DOS) programs under Perl>. Set us 2672mention a couple of features: 2673 2674=over 4 2675 2676=item * 2677 2678External scripts may be called by their basename. Perl will try the same 2679extensions as when processing B<-S> command-line switch. 2680 2681=item * 2682 2683External scripts starting with C<#!> or C<extproc > will be executed directly, 2684without calling the shell, by calling the program specified on the rest of 2685the first line. 2686 2687=back 2688 2689=head2 Memory allocation 2690 2691Perl uses its own malloc() under OS/2 - interpreters are usually malloc-bound 2692for speed, but perl is not, since its malloc is lightning-fast. 2693Perl-memory-usage-tuned benchmarks show that Perl's malloc is 5 times quicker 2694than EMX one. I do not have convincing data about memory footprint, but 2695a (pretty random) benchmark showed that Perl's one is 5% better. 2696 2697Combination of perl's malloc() and rigid DLL name resolution creates 2698a special problem with library functions which expect their return value to 2699be free()d by system's free(). To facilitate extensions which need to call 2700such functions, system memory-allocation functions are still available with 2701the prefix C<emx_> added. (Currently only DLL perl has this, it should 2702propagate to F<perl_.exe> shortly.) 2703 2704=head2 Threads 2705 2706One can build perl with thread support enabled by providing C<-D usethreads> 2707option to F<Configure>. Currently OS/2 support of threads is very 2708preliminary. 2709 2710Most notable problems: 2711 2712=over 4 2713 2714=item C<COND_WAIT> 2715 2716may have a race condition (but probably does not due to edge-triggered 2717nature of OS/2 Event semaphores). (Needs a reimplementation (in terms of chaining 2718waiting threads, with the linked list stored in per-thread structure?)?) 2719 2720=item F<os2.c> 2721 2722has a couple of static variables used in OS/2-specific functions. (Need to be 2723moved to per-thread structure, or serialized?) 2724 2725=back 2726 2727Note that these problems should not discourage experimenting, since they 2728have a low probability of affecting small programs. 2729 2730=head1 BUGS 2731 2732This description is not updated often (since 5.6.1?), see F<./os2/Changes> 2733for more info. 2734 2735=cut 2736 2737OS/2 extensions 2738~~~~~~~~~~~~~~~ 2739I include 3 extensions by Andreas Kaiser, OS2::REXX, OS2::UPM, and OS2::FTP, 2740into my ftp directory, mirrored on CPAN. I made 2741some minor changes needed to compile them by standard tools. I cannot 2742test UPM and FTP, so I will appreciate your feedback. Other extensions 2743there are OS2::ExtAttr, OS2::PrfDB for tied access to EAs and .INI 2744files - and maybe some other extensions at the time you read it. 2745 2746Note that OS2 perl defines 2 pseudo-extension functions 2747OS2::Copy::copy and DynaLoader::mod2fname (many more now, see 2748L</Prebuilt methods>). 2749 2750The -R switch of older perl is deprecated. If you need to call a REXX code 2751which needs access to variables, include the call into a REXX compartment 2752created by 2753 REXX_call {...block...}; 2754 2755Two new functions are supported by REXX code, 2756 REXX_eval 'string'; 2757 REXX_eval_with 'string', REXX_function_name => \&perl_sub_reference; 2758 2759If you have some other extensions you want to share, send the code to 2760me. At least two are available: tied access to EA's, and tied access 2761to system databases. 2762 2763=head1 AUTHOR 2764 2765Ilya Zakharevich, cpan@ilyaz.org 2766 2767=head1 SEE ALSO 2768 2769perl(1). 2770 2771=cut 2772 2773