README.os2

   1 If you read this file _as_is_, just ignore the funny characters you
   2 see. It is written in the POD format (see perlpod manpage) which is
   3 specially designed to be readable as is.
   4
   5 =head1 NAME
   6
   7 perlos2 - Perl under OS/2, Win0.31, Win0.95 and WinNT.
   8
   9 =head1 SYNOPSIS
  10
  11 One can read this document in the following formats:
  12
  13         man perlos2
  14         view perl perlos2
  15         explorer perlos2.html
  16         info perlos2
  17
  18 to list some (not all may be available simultaneously), or it may
  19 be read I<as is>: either as F<README.os2>, or F<pod/perlos2.pod>.
  20
  21 =cut
  22
  23 Contents
  24
  25  perlos2 - Perl under OS/2
  26
  27        NAME
  28        SYNOPSIS
  29        DESCRIPTION
  30          -  Target
  31          -  Other OSes
  32          -  Prerequisites
  33          -  Starting Perl programs under OS/2
  34          -  Starting OS/2 programs under Perl
  35        Frequently asked questions
  36          -  I cannot run extenal programs
  37          -  I cannot embed perl into my program, or use perl.dll from my program.
  38        INSTALLATION
  39          -  Automatic binary installation
  40          -  Manual binary installation
  41          -  Warning
  42        Accessing documentation
  43          -  OS/2 .INF file
  44          -  Plain text
  45          -  Manpages
  46          -  HTML
  47          -  GNU info files
  48          -  .PDF files
  49          -  LaTeX docs
  50        BUILD
  51          -  Prerequisites
  52          -  Getting perl source
  53          -  Application of the patches
  54          -  Hand-editing
  55          -  Making
  56          -  Testing
  57          -  Installing the built perl
  58          -  a.out-style build
  59        Build FAQ
  60          -  Some / became \ in pdksh.
  61          -  'errno' - unresolved external
  62          -  Problems with tr
  63          -  Some problem (forget which ;-)
  64          -  Library ... not found
  65          -  Segfault in make
  66        Specific (mis)features of OS/2 port
  67          -  setpriority, getpriority
  68          -  system()
  69          -  Additional modules:
  70          -  Prebuilt methods:
  71          -  Misfeatures
  72        Perl flavors
  73          -  perl.exe
  74          -  perl_.exe
  75          -  perl__.exe
  76          -  perl___.exe
  77          -  Why strange names?
  78          -  Why dynamic linking?
  79          -  Why chimera build?
  80        ENVIRONMENT
  81          -  PERLLIB_PREFIX
  82          -  PERL_BADLANG
  83          -  PERL_BADFREE
  84          -  PERL_SH_DIR
  85          -  TMP or TEMP
  86        Evolution
  87          -  Priorities
  88          -  DLL name mungling
  89          -  Threading
  90          -  Calls to external programs
  91        AUTHOR
  92        SEE ALSO
  93
  94 =head1 DESCRIPTION
  95
  96 =head2 Target
  97
  98 The target is to make OS/2 the best supported platform for
  99 using/building/developping Perl and I<Perl applications>, as well as
 100 make Perl the best language to use under OS/2.
 101
 102 The current state is quite close to this target. Known limitations:
 103
 104 =over 5
 105
 106 =item *
 107
 108 Some *nix programs use fork() a lot, but currently fork() is not
 109 supported after I<use>ing dynamically loaded extensions.
 110
 111 =item *
 112
 113 You need a separate perl executable F<perl__.exe> (see L<perl__.exe>)
 114 to use PM code in your application (like the forthcoming Perl/Tk).
 115
 116 =item *
 117
 118 There is no simple way to access B<WPS> objects. The only way I know
 119 is via C<OS2::REXX> extension (see L<OS2::REXX>), and we do not have access to
 120 convinience methods of B<Object REXX>. (Is it possible at all? I know
 121 of no B<Object-REXX> API.)
 122
 123 =back
 124
 125 Please keep this list up-to-date by informing me about other items.
 126
 127 =head2 Other OSes
 128
 129 Since OS/2 port of perl uses a remarkable B<EMX> environment, it can
 130 run (and build extensions, and - possibly - be build itself) under any
 131 environment which can run EMX. The current list is DOS,
 132 DOS-inside-OS/2, Win0.31, Win0.95 and WinNT. Out of many perl flavors,
 133 only one works, see L<"perl_.exe">.
 134
 135 Note that not all features of Perl are available under these
 136 environments. This depends on the features the I<extender> - most
 137 probably C<RSX> - decided to implement.
 138
 139 Cf. L<Prerequisites>.
 140
 141 =head2 Prerequisites
 142
 143 =over 6
 144
 145 =item B<EMX>
 146
 147 B<EMX> runtime is required. Note that it is possible to make F<perl_.exe>
 148 to run under DOS without any external support by binding F<emx.exe> to
 149 it, see L<emxbind>.
 150
 151 Only the latest runtime is supported, currently C<0.9c>.
 152
 153 One can get different parts of B<EMX> from, say
 154
 155   ftp://ftp.cdrom.com/pub/os2/emx0.9c/
 156   ftp://hobbes.nmsu.edu/os2/unix/gnu/
 157
 158 The runtime component should have the name F<emxrt.zip>.
 159
 160 =item B<RSX>
 161
 162 To run Perl on C<DPMS> platforms one needs B<RSX> runtime. This is
 163 needed under DOS-inside-OS/2, Win0.31, Win0.95 and WinNT (see
 164 L<"Other OSes">).
 165
 166 One can get B<RSX> from, say
 167
 168   ftp://ftp.cdrom.com/pub/os2/emx0.9c/contrib
 169   ftp://ftp.uni-bielefeld.de/pub/systems/msdos/misc
 170
 171 Contact the author on C<rainer@mathematik.uni-bielefeld.de>.
 172
 173 =item B<HPFS>
 174
 175 Perl does not care about file systems, but to install the whole perl
 176 library intact one needs a file system which supports long file names.
 177
 178 Note that if you do not plan to build the perl itself, it may be
 179 possible to fool B<EMX> to truncate file names. This is not supported,
 180 read B<EMX> docs to see how to do it.
 181
 182 =back
 183
 184 =head2 Starting Perl programs under OS/2
 185
 186 Start your Perl program F<foo.pl> with arguments C<arg1 arg2 arg3> the
 187 same way as on any other platform, by
 188
 189         perl foo.pl arg1 arg2 arg3
 190
 191 If you want to specify perl options C<-my_opts> to the perl itself (as
 192 opposed to to your program), use
 193
 194         perl -my_opts foo.pl arg1 arg2 arg3
 195
 196 Alternately, if you use OS/2-ish shell, like C<CMD> or C<4os2>, put
 197 the following at the start of your perl script:
 198
 199         extproc perl -x -S
 200         #!/usr/bin/perl -my_opts
 201
 202 rename your program to F<foo.cmd>, and start it by typing
 203
 204         foo arg1 arg2 arg3
 205
 206 (Note that having *nixish full path to perl F</usr/bin/perl> is not
 207 necessary, F<perl> would be enough, but having full path would make it
 208 easier to use your script under *nix.)
 209
 210 Note that because of stupid OS/2 limitations the full path of the perl
 211 script is not available when you use C<extproc>, thus you are forced to
 212 use C<-S> perl switch, and your script should be on path. As a plus
 213 side, if you know a full path to your script, you may still start it
 214 with
 215
 216         perl -x ../../blah/foo.cmd arg1 arg2 arg3
 217
 218 (note that the argument C<-my_opts> is taken care of by the C<#!> line
 219 in your script).
 220
 221 To understand what the above I<magic> does, read perl docs about C<-S>
 222 and C<-x> switches - see L<perlrun>, and cmdref about C<extproc>:
 223
 224         view perl perlrun
 225         man perlrun
 226         view cmdref extproc
 227         help extproc
 228
 229 or whatever method you prefer.
 230
 231 There are also endless possibilites to use I<executable extensions> of
 232 B<4OS2>, I<associations> of B<WPS> and so on... However, if you use
 233 *nixish shell (like F<sh.exe> supplied in the binary distribution),
 234 you need follow the syntax specified in L<perlrun/"Switches">.
 235
 236 =head2 Starting OS/2 programs under Perl
 237
 238 This is what system() (see L<perlfunc/system>), C<``> (see
 239 L<perlop/"I/O Operators">), and I<open pipe> (see L<perlfunc/open>)
 240 are for. (Avoid exec() (see L<perlfunc/exec>) unless you know what you
 241 do).
 242
 243 Note however that to use some of these operators you need to have a
 244 C<sh>-syntax shell installed (see L<"Pdksh">,
 245 L<"Frequently asked questions">), and perl should be able to find it
 246 (see L<"PERL_SH_DIR">).
 247
 248 The only cases when the shell is not used is the multi-argument
 249 system() (see L<perlfunc/system>)/exec() (see L<perlfunc/exec>), and
 250 one-argument version thereof without redirection and shell
 251 meta-characters.
 252
 253 =head1 Frequently asked questions
 254
 255 =head2 I cannot run extenal programs
 256
 257 Did you run your programs with C<-w> switch? See
 258 L<Starting OS/2 programs under Perl>.
 259
 260 =head2 I cannot embed perl into my program, or use F<perl.dll> from my
 261 program.
 262
 263 =over 4
 264
 265 =item Is your program B<EMX>-compiled with C<-Zmt -Zcrtdll>?
 266
 267 If not, you need to build a stand-alone DLL for perl. Contact me, I
 268 did it once. Sockets would not work, as a lot of other stuff.
 269
 270 =item Did you use C<ExtUtils::Embed>?
 271
 272 I had reports it does not work. Somebody would need to fix it.
 273
 274 =back
 275
 276 =head1 INSTALLATION
 277
 278 =head2 Automatic binary installation
 279
 280 The most convinient way of installing perl is via perl installer
 281 F<install.exe>. Just follow the instructions, and 99% of the
 282 installation blues would go away.
 283
 284 Note however, that you need to have F<unzip.exe> on your path, and
 285 B<EMX> environment I<running>. The latter means that if you just
 286 installed B<EMX>, and made all the needed changes to F<Config.sys>,
 287 you may need to reboot in between. Check B<EMX> runtime by running
 288
 289         emxrev
 290
 291 A folder is created on your desktop which contains some useful
 292 objects.
 293
 294 B<Things not taken care of by automatic binary installation:>
 295
 296 =over 15
 297
 298 =item C<PERL_BADLANG>
 299
 300 may be needed if you change your codepage I<after> perl installation,
 301 and the new value is not supported by B<EMX>. See L<"PERL_BADLANG">.
 302
 303 =item C<PERL_BADFREE>
 304
 305 see L<"PERL_BADFREE">.
 306
 307 =item F<Config.pm>
 308
 309 This file resides somewhere deep in the location you installed your
 310 perl library, find it out by
 311
 312   perl -MConfig -le "print $INC{'Config.pm'}"
 313
 314 While most important values in this file I<are> updated by the binary
 315 installer, some of them may need to be hand-edited. I know no such
 316 data, please keep me informed if you find one.
 317
 318 =back
 319
 320 =head2 Manual binary installation
 321
 322 As of version 5.00305, OS/2 perl binary distribution comes splitted
 323 into 11 components. Unfortunately, to enable configurable binary
 324 installation, the file paths in the C<zip> files are not absolute, but
 325 relative to some directory.
 326
 327 Note that the extraction with the stored paths is still necessary
 328 (default with C<unzip>, specify C<-d> to C<pkunzip>). However, you
 329 need to know where to extract the files. You need also to manually
 330 change entries in F<Config.sys> to reflect where did you put the
 331 files.
 332
 333 Below is the sample of what to do to reproduce the configuration on my
 334 machine:
 335
 336 =over 3
 337
 338 =item Perl VIO and PM executables (dynamically linked)
 339
 340   unzip perl_exc.zip *.exe *.ico -d f:/emx.add/bin
 341   unzip perl_exc.zip *.dll -d f:/emx.add/dll
 342
 343 (have the directories with C<*.exe> on C<PATH>, and C<*.dll> on
 344 C<LIBPATH>);
 345
 346 =item Perl_ VIO executable (statically linked)
 347
 348   unzip perl_aou.zip -d f:/emx.add/bin
 349
 350 (have the directory on C<PATH>);
 351
 352 =item Executables for Perl utilities
 353
 354   unzip perl_utl.zip -d f:/emx.add/bin
 355
 356 (have the directory on C<PATH>);
 357
 358 =item Main Perl library
 359
 360   unzip perl_mlb.zip -d f:/perllib/lib
 361
 362 If this directory is preserved, you do not need to change
 363 anything. However, for perl to find it if it is changed, you need to
 364 C<set PERLLIB_PREFIX> in F<Config.sys>, see L<"PERLLIB_PREFIX">.
 365
 366 =item Additional Perl modules
 367
 368   unzip perl_ste.zip -d f:/perllib/lib/site_perl
 369
 370 If you do not change this directory, do nothing. Otherwise put this
 371 directory and subdirectory F<./os2> in C<PERLLIB> or C<PERL5LIB>
 372 variable. Do not use C<PERL5LIB> unless you have it set already. See
 373 L<perl/"ENVIRONMENT">.
 374
 375 =item Tools to compile Perl modules
 376
 377   unzip perl_blb.zip -d f:/perllib/lib
 378
 379 If this directory is preserved, you do not need to change
 380 anything. However, for perl to find it if it is changed, you need to
 381 C<set PERLLIB_PREFIX> in F<Config.sys>, see L<"PERLLIB_PREFIX">.
 382
 383 =item Manpages for Perl and utilities
 384
 385   unzip perl_man.zip -d f:/perllib/man
 386
 387 This directory should better be on C<MANPATH>. You need to have a
 388 working C<man> to access these files.
 389
 390 =item Manpages for Perl modules
 391
 392   unzip perl_mam.zip -d f:/perllib/man
 393
 394 This directory should better be on C<MANPATH>. You need to have a
 395 working C<man> to access these files.
 396
 397 =item Source for Perl documentation
 398
 399   unzip perl_pod.zip -d f:/perllib/lib
 400
 401 This is used by by C<perldoc> program (see L<perldoc>), and may be used to
 402 generate B<HTML> documentation usable by WWW browsers, and
 403 documentation in zillions of other formats: C<info>, C<LaTeX>,
 404 C<Acrobat>, C<FrameMaker> and so on.
 405
 406 =item Perl manual in .INF format
 407
 408   unzip perl_inf.zip -d d:/os2/book
 409
 410 This directory should better be on C<BOOKSHELF>.
 411
 412 =item Pdksh
 413
 414   unzip perl_sh.zip -d f:/bin
 415
 416 This is used by perl to run external commands which explicitely
 417 require shell, like the commands using I<redirection> and I<shell
 418 metacharacters>. It is also used instead of explicit F</bin/sh>.
 419
 420 Set C<PERL_SH_DIR> (see L<"PERL_SH_DIR">) if you move F<sh.exe> from
 421 the above location.
 422
 423 B<Note.> It may be possible to use some other C<sh>-compatible shell
 424 (I<not tested>).
 425
 426 =back
 427
 428 After you installed the components you needed and updated the
 429 F<Config.sys> correspondingly, you need to hand-edit
 430 F<Config.pm>. This file resides somewhere deep in the location you
 431 installed your perl library, find it out by
 432
 433   perl -MConfig -le "print $INC{'Config.pm'}"
 434
 435 You need to correct all the entries which look like file paths (they
 436 currently start with C<f:/>).
 437
 438 =head2 B<Warning>
 439
 440 The automatic and manual perl installation leave precompiled paths
 441 inside perl executables. While these paths are overwriteable (see
 442 L<"PERLLIB_PREFIX">, L<"PERL_SH_DIR">), one may get better results by
 443 binary editing of paths inside the executables/DLLs.
 444
 445 =head1 Accessing documentation
 446
 447 Depending on how you built/installed perl you may have (otherwise
 448 identical) Perl documentation in the following formats:
 449
 450 =head2 OS/2 F<.INF> file
 451
 452 Most probably the most convinient form. View it as
 453
 454   view perl
 455   view perl perlfunc
 456   view perl less
 457   view perl ExtUtils::MakeMaker
 458
 459 (currently the last two may hit a wrong location, but this may improve
 460 soon).
 461
 462 If you want to build the docs yourself, and have I<OS/2 toolkit>, run
 463
 464         pod2ipf > perl.ipf
 465
 466 in F</perllib/lib/pod> directory, then
 467
 468         ipfc /inf perl.ipf
 469
 470 (Expect a lot of errors during the both steps.) Now move it on your
 471 BOOKSHELF path.
 472
 473 =head2 Plain text
 474
 475 If you have perl documentation in the source form, perl utilities
 476 installed, and B<GNU> C<groff> installed, you may use
 477
 478         perldoc perlfunc
 479         perldoc less
 480         perldoc ExtUtils::MakeMaker
 481
 482 to access the perl documention in the text form (note that you may get
 483 better results using perl manpages).
 484
 485 Alternately, try running pod2text on F<.pod> files.
 486
 487 =head2 Manpages
 488
 489 If you have C<man> installed on your system, and you installed perl
 490 manpages, use something like this:
 491
 492         man perlfunc
 493         man 3 less
 494         man ExtUtils.MakeMaker
 495
 496 to access documentation for different components of Perl. Start with
 497
 498         man perl
 499
 500 Note that dot (F<.>) is used as a package separator for documentation
 501 for packages, and as usual, sometimes you need to give the section - C<3>
 502 above - to avoid shadowing by the I<less(1) manpage>.
 503
 504 Make sure that the directory B<above> the directory with manpages is
 505 on our C<MANPATH>, like this
 506
 507   set MANPATH=c:/man;f:/perllib/man
 508
 509 =head2 B<HTML>
 510
 511 If you have some WWW browser available, installed the Perl
 512 documentation in the source form, and Perl utilities, you can build
 513 B<HTML> docs. Cd to directory with F<.pod> files, and do like this
 514
 515         cd f:/perllib/lib/pod
 516         pod2html
 517
 518 After this you can direct your browser the file F<perl.html> in this
 519 directory, and go ahead with reading docs, like this:
 520
 521         explore file:///f:/perllib/lib/pod/perl.html
 522
 523 Alternatively you may be able to get these docs prebuild from C<CPAN>.
 524
 525 =head2 B<GNU> C<info> files
 526
 527 Users of C<Emacs> would appreciate it very much, especially with
 528 C<CPerl> mode loaded. You need to get latest C<pod2info> from C<CPAN>,
 529 or, alternately, prebuilt info pages.
 530
 531 =head2 F<.PDF> files
 532
 533 for C<Acrobat> are available on CPAN (for slightly old version of
 534 perl).
 535
 536 =head2 C<LaTeX> docs
 537
 538 can be constructed using C<pod2latex>.
 539
 540 =head1 BUILD
 541
 542 Here we discuss how to build Perl under OS/2. There is an alternative
 543 (but maybe older) view on L<http://www.shadow.net/~troc/os2perl.html>.
 544
 545 =head2 Prerequisites
 546
 547 You need to have the latest B<EMX> development environment, the full
 548 B<GNU> tool suite (C<gawk> renamed to C<awk>, and B<GNU> F<find.exe>
 549 earlier on path than the OS/2 F<find.exe>, same with F<sort.exe>, to
 550 check use
 551
 552   find --version
 553   sort --version
 554
 555 ). You need the latest version of F<pdksh> installed as F<sh.exe>.
 556
 557 Possible locations to get this from are
 558
 559   ftp://hobbes.nmsu.edu/os2/unix/gnu/
 560   ftp://ftp.cdrom.com/pub/os2/unix/
 561   ftp://ftp.cdrom.com/pub/os2/dev32/
 562   ftp://ftp.cdrom.com/pub/os2/emx0.9c/
 563
 564
 565 Make sure that no copies or perl are currently running.  Later steps
 566 of the build may fail since an older version of perl.dll loaded into
 567 memory may be found.
 568
 569 Also make sure that you have F</tmp> directory on the current drive,
 570 and F<.> directory in your C<LIBPATH>. One may try to correct the
 571 latter condition by
 572
 573   set BEGINLIBPATH .
 574
 575 if you use something like F<CMD.EXE> or latest versions of F<4os2.exe>.
 576
 577 Make sure your C<gcc> is good for C<-Zomf> linking: run C<omflibs>
 578 script in F</emx/lib> directory.
 579
 580 Check that you have C<link386> installed. It comes standard with OS/2,
 581 but may be not installed due to customization. If typing
 582
 583   link386
 584
 585 shows you do not have it, do I<Selective install>, and choose C<Link
 586 object modules> in I<Optional system utilites/More>. If you get into
 587 C<link386>, press C<Ctrl-C>.
 588
 589 =head2 Getting perl source
 590
 591 You need to fetch the latest perl source (including developpers
 592 releases). With some probability it is located in
 593
 594   http://www.perl.com/CPAN/src/5.0
 595   http://www.perl.com/CPAN/src/5.0/unsupported
 596
 597 If not, you may need to dig in the indices to find it in the directory
 598 of the current maintainer.
 599
 600 Quick cycle of developpers release may break the OS/2 build time to
 601 time, looking into
 602
 603   http://www.perl.com/CPAN/ports/os2/ilyaz/
 604
 605 may indicate the latest release which was publicly released by the
 606 maintainer. Note that the release may include some additional patches
 607 to apply to the current source of perl.
 608
 609 Extract it like this
 610
 611   tar vzxf perl5.00409.tar.gz
 612
 613 You may see a message about errors while extracting F<Configure>. This is
 614 because there is a conflict with a similarly-named file F<configure>.
 615
 616 Rename F<configure> to F<configure.gnu>. Extract F<Configure> like this
 617
 618   tar --case-sensitive -vzxf perl5.00409.tar.gz perl5.00409/Configure
 619
 620 Change to the directory of extraction.
 621
 622 =head2 Application of the patches
 623
 624 You need to apply the patches in F<./os2/diff.*> and
 625 F<./os2/POSIX.mkfifo> like this:
 626
 627   gnupatch -p0 < os2\POSIX.mkfifo
 628   gnupatch -p0 < os2\os2\diff.configure
 629
 630 You may also need to apply the patches supplied with the binary
 631 distribution of perl.
 632
 633 Note also that the F<db.lib> and F<db.a> from the B<EMX> distribution
 634 are not suitable for multi-threaded compile (note that currently perl
 635 is not multithreaded, but is compiled as multithreaded for
 636 compatibility with B<XFree86>-OS/2). Get a corrected one from
 637
 638   ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/db_mt.zip
 639
 640 =head2 Hand-editing
 641
 642 You may look into the file F<./hints/os2.sh> and correct anything
 643 wrong you find there. I do not expect it is needed anywhere.
 644
 645 =head2 Making
 646
 647   sh Configure -des -D prefix=f:/perllib
 648
 649 Prefix means where to install the resulting perl library. Giving
 650 correct prefix you may avoid the need to specify C<PERLLIB_PREFIX>,
 651 see L<"PERLLIB_PREFIX">.
 652
 653 I<Ignore the message about missing C<ln>, and about C<-c> option to
 654 C<tr>>. In fact if you can trace where the latter spurious warning
 655 comes from, please inform me.
 656
 657 Now
 658
 659   make
 660
 661 At some moment the built may die, reporting a I<version mismatch> or
 662 I<unable to run F<perl>>. This means that most of the build has been
 663 finished, and it is the time to move the constructed F<perl.dll> to
 664 some I<absolute> location in C<LIBPATH>. After this done the build
 665 should finish without a lot of fuss. I<One can avoid it if one has the
 666 correct prebuilt version of F<perl.dll> on C<LIBPATH>.>
 667
 668 Warnings which are safe to ignore: I<mkfifo() redefined> inside
 669 F<POSIX.c>.
 670
 671 =head2 Testing
 672
 673 Now run
 674
 675   make test
 676
 677 Some tests (4..6) should fail. Some perl invocations should end in a
 678 segfault (system error C<SYS3175>). To get finer error reports,
 679
 680   cd t
 681   perl -I ../lib harness
 682
 683 The report you get may look like
 684
 685   Failed Test  Status Wstat Total Fail  Failed  List of failed
 686   ---------------------------------------------------------------
 687   io/fs.t                      26   11  42.31%  2-5, 7-11, 18, 25
 688   lib/io_pipe.t     3   768     6   ??       %  ??
 689   lib/io_sock.t     3   768     5   ??       %  ??
 690   op/stat.t                    56    5   8.93%  3-4, 20, 35, 39
 691   Failed 4/118 test scripts, 96.61% okay. 27/2445 subtests failed, 98.90% okay.
 692
 693 Note that using `make test' target two more tests may fail: C<op/exec:1>
 694 because of (mis)feature of C<pdksh>, and C<lib/posix:15>, which checks
 695 that the buffers are not flushed on C<_exit>.
 696
 697 The reasons for failed tests are:
 698
 699 =over 8
 700
 701 =item F<io/fs.t>
 702
 703 Checks I<file system> operations. Tests:
 704
 705 =over 10
 706
 707 =item 2-5, 7-11
 708
 709 Check C<link()> and C<inode count> - nonesuch under OS/2.
 710
 711 =item 18
 712
 713 Checks C<atime> and C<mtime> of C<stat()> - I could not understand this test.
 714
 715 =item 25
 716
 717 Checks C<truncate()> on a filehandle just opened for write - I do not
 718 know why this should or should not work.
 719
 720 =back
 721
 722 =item F<lib/io_pipe.t>
 723
 724 Checks C<IO::Pipe> module. Some feature of B<EMX> - test fork()s with
 725 dynamic extension loaded - unsupported now.
 726
 727 =item F<lib/io_sock.t>
 728
 729 Checks C<IO::Socket> module. Some feature of B<EMX> - test fork()s
 730 with dynamic extension loaded - unsupported now.
 731
 732 =item F<op/stat.t>
 733
 734 Checks C<stat()>. Tests:
 735
 736 =over 4
 737
 738 =item 3
 739
 740 Checks C<inode count> - nonesuch under OS/2.
 741
 742 =item 4
 743
 744 Checks C<mtime> and C<ctime> of C<stat()> - I could not understand this test.
 745
 746 =item 20
 747
 748 Checks C<-x> - determined by the file extension only under OS/2.
 749
 750 =item 35
 751
 752 Needs F</usr/bin>.
 753
 754 =item 39
 755
 756 Checks C<-t> of F</dev/null>. Should not fail!
 757
 758 =back
 759
 760 =back
 761
 762 In addition to errors, you should get a lot of warnings.
 763
 764 =over 4
 765
 766 =item A lot of `bad free'
 767
 768 in databases related to Berkeley DB. This is a confirmed bug of
 769 DB. You may disable this warnings, see L<"PERL_BADFREE">.
 770
 771 =item Process terminated by SIGTERM/SIGINT
 772
 773 This is a standard message issued by OS/2 applications. *nix
 774 applications die in silence. It is considered a feature. One can
 775 easily disable this by appropriate sighandlers.
 776
 777 However the test engine bleeds these message to screen in unexpected
 778 moments. Two messages of this kind I<should> be present during
 779 testing.
 780
 781 =item F<*/sh.exe>: ln: not found
 782
 783 =item C<ls>: /dev: No such file or directory
 784
 785 The last two should be self-explanatory. The test suite discovers that
 786 the system it runs on is not I<that much> *nixish.
 787
 788 =back
 789
 790 A lot of `bad free'... in databases, bug in DB confirmed on other
 791 platforms. You may disable it by setting PERL_BADFREE environment variable
 792 to 1.
 793
 794 =head2 Installing the built perl
 795
 796 Run
 797
 798   make install
 799
 800 It would put the generated files into needed locations. Manually put
 801 F<perl.exe>, F<perl__.exe> and F<perl___.exe> to a location on your
 802 C<PATH>, F<perl.dll> to a location on your C<LIBPATH>.
 803
 804 Run
 805
 806   make cmdscripts INSTALLCMDDIR=d:/ir/on/path
 807
 808 to convert perl utilities to F<.cmd> files and put them on
 809 C<PATH>. You need to put F<.EXE>-utilities on path manually. They are
 810 installed in C<$prefix/bin>, here C<$prefix> is what you gave to
 811 F<Configure>, see L<Making>.
 812
 813 =head2 C<a.out>-style build
 814
 815 Proceed as above, but make F<perl_.exe> (see L<"perl_.exe">) by
 816
 817   make perl_
 818
 819 test and install by
 820
 821   make aout_test
 822   make aout_install
 823
 824 Manually put F<perl_.exe> to a location on your C<PATH>.
 825
 826 Since C<perl_> has the extensions prebuilt, it does not suffer from
 827 the I<dynamic extensions + fork()> syndrom, thus the failing tests
 828 look like
 829
 830   Failed Test  Status Wstat Total Fail  Failed  List of failed
 831   ---------------------------------------------------------------
 832   io/fs.t                      26   11  42.31%  2-5, 7-11, 18, 25
 833   op/stat.t                    56    5   8.93%  3-4, 20, 35, 39
 834   Failed 2/118 test scripts, 98.31% okay. 16/2445 subtests failed, 99.35% okay.
 835
 836 B<Note.> The build process for C<perl_> I<does not know> about all the
 837 dependencies, so you should make sure that anything is up-to-date,
 838 say, by doing
 839
 840   make perl.dll
 841
 842 first.
 843
 844 =head1 Build FAQ
 845
 846 =head2 Some C</> became C<\> in pdksh.
 847
 848 You have a very old pdksh. See L<Prerequisites>.
 849
 850 =head2 C<'errno'> - unresolved external
 851
 852 You do not have MT-safe F<db.lib>. See L<Prerequisites>.
 853
 854 =head2 Problems with C<tr>
 855
 856 reported with very old version of C<tr>.
 857
 858 =head2 Some problem (forget which ;-)
 859
 860 You have an older version of F<perl.dll> on your C<LIBPATH>, which
 861 broke the build of extensions.
 862
 863 =head2 Library ... not found
 864
 865 You did not run C<omflibs>. See L<Prerequisites>.
 866
 867 =head2 Segfault in make
 868
 869 You use an old version of C<GNU> make. See L<Prerequisites>.
 870
 871 =head1 Specific (mis)features of OS/2 port
 872
 873 =head2 C<setpriority>, C<getpriority>
 874
 875 Note that these functions are compatible with *nix, not with the older
 876 ports of '94 - 95. The priorities are absolute, go from 32 to -95,
 877 lower is quickier. 0 is the default priority.
 878
 879 =head2 C<system()>
 880
 881 Multi-argument form of C<system()> allows an additional numeric
 882 argument. The meaning of this argument is described in
 883 L<OS2::Process>.
 884
 885 =head2 Additional modules:
 886
 887 L<OS2::Process>, L<OS2::REXX>, L<OS2::PrfDB>, L<OS2::ExtAttr>. This
 888 modules provide access to additional numeric argument for C<system>,
 889 to DLLs having functions with REXX signature and to REXX runtime, to
 890 OS/2 databases in the F<.INI> format, and to Extended Attributes.
 891
 892 Two additional extensions by Andread Kaiser, C<OS2::UPM>, and
 893 C<OS2::FTP>, are included into my ftp directory, mirrored on CPAN.
 894
 895 =head2 Prebuilt methods:
 896
 897 =over 4
 898
 899 =item C<File::Copy::syscopy>
 900
 901 used by C<File::Copy::copy>, see L<File::Copy/copy>.
 902
 903 =item C<DynaLoader::mod2fname>
 904
 905 used by C<DynaLoader> for DLL name mungling.
 906
 907 =item  C<Cwd::current_drive()>
 908
 909 Self explanatory.
 910
 911 =item  C<Cwd::sys_chdir(name)>
 912
 913 leaves drive as it is.
 914
 915 =item  C<Cwd::change_drive(name)>
 916
 917
 918 =item  C<Cwd::sys_is_absolute(name)>
 919
 920 means has drive letter and is_rooted.
 921
 922 =item  C<Cwd::sys_is_rooted(name)>
 923
 924 means has leading C<[/\\]> (maybe after a drive-letter:).
 925
 926 =item  C<Cwd::sys_is_relative(name)>
 927
 928 means changes with current dir.
 929
 930 =item  C<Cwd::sys_cwd(name)>
 931
 932 Interface to cwd from B<EMX>. Used by C<Cwd::cwd>.
 933
 934 =item  C<Cwd::sys_abspath(name, dir)>
 935
 936 Really really odious function to implement. Returns absolute name of
 937 file which would have C<name> if CWD were C<dir>.  C<Dir> defaults to the
 938 current dir.
 939
 940 =item  C<Cwd::extLibpath([type])
 941
 942 Get current value of extended library search path. If C<type> is
 943 present and I<true>, works with END_LIBPATH, otherwise with
 944 C<BEGIN_LIBPATH>.
 945
 946 =item  C<Cwd::extLibpath_set( path [, type ] )>
 947
 948 Set current value of extended library search path. If C<type> is
 949 present and I<true>, works with END_LIBPATH, otherwise with
 950 C<BEGIN_LIBPATH>.
 951
 952 =back
 953
 954 (Note that some of these may be moved to different libraries -
 955 eventually).
 956
 957
 958 =head2 Misfeatures
 959
 960 =over 4
 961
 962 =item
 963
 964 Since <lockf> is present in B<EMX>, but is not functional, the same is
 965 true for perl.
 966
 967 =item
 968
 969 Since F<sh.exe> is used for globbing (see L<perlfunc/glob>), the bugs
 970 of F<sh.exe> plague perl as well.
 971
 972 In particular, uppercase letters do not work in C<[...]>-patterns with
 973 the current C<pdksh>.
 974
 975 =back
 976
 977 =head1 Perl flavors
 978
 979 Because of ideosyncrasies of OS/2 one cannot have all the eggs in the
 980 same basket (though C<EMX> environment tries hard to overcome this
 981 limitations, so the situation may somehow improve). There are 4
 982 executables for Perl provided by the distribution:
 983
 984 =head2 F<perl.exe>
 985
 986 The main workhorse. This is a chimera executable: it is compiled as an
 987 C<a.out>-style executable, but is linked with C<omf>-style dynamic
 988 library F<perl.dll>, and with dynamic B<CRT> DLL. This executable is a
 989 C<VIO> application.
 990
 991 It can load perl dynamic extensions, and it can fork(). Unfortunately,
 992 currently it cannot fork() with dynamic extensions loaded.
 993
 994 B<Note.> Keep in mind that fork() is needed to open a pipe to yourself.
 995
 996 =head2 F<perl_.exe>
 997
 998 This is a statically linked C<a.out>-style executable. It can fork(),
 999 but cannot load dynamic Perl extensions. The supplied executable has a
1000 lot of extensions prebuilt, thus there are situations when it can
1001 perform tasks not possible using F<perl.exe>, like fork()ing when
1002 having some standard extension loaded. This executable is a C<VIO>
1003 application.
1004
1005 B<Note.> A better behaviour could be obtained from C<perl.exe> if it
1006 were statically linked with standard I<Perl extensions>, but
1007 dynamically linked with the I<Perl DLL> and C<CRT> DLL. Then it would
1008 be able to fork() with standard extensions, I<and> would be able to
1009 dynamically load arbitrary extensions. Some changes to Makefiles and
1010 hint files should be necessary to achieve this.
1011
1012 I<This is also the only executable with does not require OS/2.> The
1013 friends locked into C<M$> world would appreciate the fact that this
1014 executable runs under DOS, Win0.31, Win0.95 and WinNT with an
1015 appropriate extender. See L<"Other OSes">.
1016
1017 =head2 F<perl__.exe>
1018
1019 This is the same executable as <perl___.exe>, but it is a C<PM>
1020 application.
1021
1022 B<Note.> Usually C<STDIN>, C<STDERR>, and C<STDOUT> of a C<PM>
1023 application are redirected to C<nul>. However, it is possible to see
1024 them if you start C<perl__.exe> from a PM program which emulates a
1025 console window, like I<Shell mode> of C<Emacs> or C<EPM>. Thus it I<is
1026 possible> to use Perl debugger (see L<perldebug>) to debug your PM
1027 application.
1028
1029 This flavor is required if you load extensions which use C<PM>, like
1030 the forthcoming C<Perl/Tk>.
1031
1032 =head2 F<perl___.exe>
1033
1034 This is an C<omf>-style executable which is dynamically linked to
1035 F<perl.dll> and C<CRT> DLL. I know no advantages of this executable
1036 over C<perl.exe>, but it cannot fork() at all. Well, one advantage is
1037 that the build process is not so convoluted as with C<perl.exe>.
1038
1039 It is a C<VIO> application.
1040
1041 =head2 Why strange names?
1042
1043 Since Perl processes the C<#!>-line (cf.
1044 L<perlrun/DESCRIPTION>, L<perlrun/Switches>,
1045 L<perldiag/"Not a perl script">,
1046 L<perldiag/"No Perl script found in input">), it should know when a
1047 program I<is a Perl>. There is some naming convention which allows
1048 Perl to distinguish correct lines from wrong ones. The above names are
1049 almost the only names allowed by this convension which do not contain
1050 digits (which have absolutely different semantics).
1051
1052 =head2 Why dynamic linking?
1053
1054 Well, having several executables dynamically linked to the same huge
1055 library has its advantages, but this would not substantiate the
1056 additional work to make it compile. The reason is stupid-but-quick
1057 "hard" dynamic linking used by OS/2.
1058
1059 The address tables of DLLs are patches only once, when they are
1060 loaded. The addresses of entry points into DLLs are guarantied to be
1061 the same for all programs which use the same DLL, which reduces the
1062 amount of runtime patching - once DLL is loaded, its code is
1063 read-only.
1064
1065 While this allows some performance advantages, this makes life
1066 terrible for developpers, since the above scheme makes it impossible
1067 for a DLL to be resolved to a symbol in the .EXE file, since this
1068 would need a DLL to have different relocations tables for the
1069 executables which use it.
1070
1071 However, a Perl extension is forced to use some symbols from the perl
1072 executable, say to know how to find the arguments provided on the perl
1073 internal evaluation stack. The solution is that the main code of
1074 interpreter should be contained in a DLL, and the F<.EXE> file just loads
1075 this DLL into memory and supplies command-arguments.
1076
1077 This I<greately> increases the load time for the application (as well as
1078 the number of problems during compilation). Since interpreter is in a DLL,
1079 the C<CRT> is basically forced to reside in a DLL as well (otherwise
1080 extensions would not be able to use C<CRT>).
1081
1082 =head2 Why chimera build?
1083
1084 Current C<EMX> environment does not allow DLLs compiled using Unixish
1085 C<a.out> format to export symbols for data. This forces C<omf>-style
1086 compile of F<perl.dll>.
1087
1088 Current C<EMX> environment does not allow F<.EXE> files compiled in
1089 C<omf> format to fork(). fork() is needed for exactly three Perl
1090 operations:
1091
1092 =over 4
1093
1094 =item explicit fork()
1095
1096 in the script, and
1097
1098 =item open FH, "|-"
1099
1100 =item open FH, "-|"
1101
1102 opening pipes to itself.
1103
1104 =back
1105
1106 While these operations are not questions of life and death, a lot of
1107 useful scripts use them. This forces C<a.out>-style compile of
1108 F<perl.exe>.
1109
1110
1111 =head1 ENVIRONMENT
1112
1113 Here we list environment variables with are either OS/2-specific, or
1114 are more important under OS/2 than under other OSes.
1115
1116 =head2 C<PERLLIB_PREFIX>
1117
1118 Specific for OS/2. Should have the form
1119
1120   path1;path2
1121
1122 or
1123
1124   path1 path2
1125
1126 If the beginning of some prebuilt path matches F<path1>, it is
1127 substituted with F<path2>.
1128
1129 Should be used if the perl library is moved from the default
1130 location in preference to C<PERL(5)LIB>, since this would not leave wrong
1131 entries in <@INC>.
1132
1133 =head2 C<PERL_BADLANG>
1134
1135 If 1, perl ignores setlocale() failing. May be useful with some
1136 strange I<locale>s.
1137
1138 =head2 C<PERL_BADFREE>
1139
1140 If 1, perl would not warn of in case of unwarranted free(). May be
1141 useful in conjunction with the module DB_File, since Berkeley DB
1142 memory handling code is buggy.
1143
1144 =head2 C<PERL_SH_DIR>
1145
1146 Specific for OS/2. Gives the directory part of the location for
1147 F<sh.exe>.
1148
1149 =head2 C<TMP> or C<TEMP>
1150
1151 Specific for OS/2. Used as storage place for temporary files, most
1152 notably C<-e> scripts.
1153
1154 =head1 Evolution
1155
1156 Here we list major changes which could make you by surprise.
1157
1158 =head2 Priorities
1159
1160 C<setpriority> and C<getpriority> are not compatible with earlier
1161 ports by Andreas Kaiser. See C<"setpriority, getpriority">.
1162
1163 =head2 DLL name mungling
1164
1165 With the release 5.003_01 the dynamically loadable libraries
1166 should be rebuilt. In particular, DLLs are now created with the names
1167 which contain a checksum, thus allowing workaround for OS/2 scheme of
1168 caching DLLs.
1169
1170 =head2 Threading
1171
1172 As of release 5.003_01 perl is linked to multithreaded C<CRT>
1173 DLL. Perl itself is not multithread-safe, as is not perl
1174 malloc(). However, extensions may use multiple thread on their own
1175 risk.
1176
1177 Needed to compile C<Perl/Tk> for C<XFreeOS/2> out-of-the-box.
1178
1179 =head2 Calls to external programs
1180
1181 Due to a popular demand the perl external program calling has been
1182 changed wrt Andread Kaiser's port.  I<If> perl needs to call an
1183 external program I<via shell>, the F<f:/bin/sh.exe> will be called, or
1184 whatever is the override, see L<"PERL_SH_DIR">.
1185
1186 Thus means that you need to get some copy of a F<sh.exe> as well (I
1187 use one from pdksh). The drive F: above is set up automatically during
1188 the build to a correct value on the builder machine, but is
1189 overridable at runtime,
1190
1191 B<Reasons:> a consensus on C<perl5-porters> was that perl should use
1192 one non-overridable shell per platform. The obvious choices for OS/2
1193 are F<cmd.exe> and F<sh.exe>. Having perl build itself would be impossible
1194 with F<cmd.exe> as a shell, thus I picked up C<sh.exe>. Thus assures almost
1195 100% compatibility with the scripts coming from *nix.
1196
1197 B<Disadvantages:> currently F<sh.exe> of C<pdksh> calls external programs
1198 via fork()/exec(), and there is I<no> functioning exec() on
1199 OS/2. exec() is emulated by EMX by asyncroneous call while the caller
1200 waits for child completion (to pretend that the pid did not change). This
1201 means that 1 I<extra> copy of F<sh.exe> is made active via fork()/exec(),
1202 which may lead to some resources taken from the system (even if we do
1203 not count extra work needed for fork()ing).
1204
1205 One can always start F<cmd.exe> explicitely via
1206
1207   system 'cmd', '/c', 'mycmd', 'arg1', 'arg2', ...
1208
1209 If you need to use F<cmd.exe>, and do not want to hand-edit thousends of your
1210 scripts, the long-term solution proposed on p5-p is to have a directive
1211
1212   use OS2::Cmd;
1213
1214 which will override system(), exec(), C<``>, and
1215 C<open(,'...|')>. With current perl you may override only system(),
1216 readpipe() - the explicit version of C<``>, and maybe exec(). The code
1217 will substitute the one-argument call to system() by
1218 C<CORE::system('cmd.exe', '/c', shift)>.
1219
1220 If you have some working code for C<OS2::Cmd>, please send it to me,
1221 I will include it into distribution. I have no need for such a module, so
1222 cannot test it.
1223
1224 =cut
1225
1226 OS/2 extensions
1227 ~~~~~~~~~~~~~~~
1228 I include 3 extensions by Andread Kaiser, OS2::REXX, OS2::UPM, and OS2::FTP,
1229 into my ftp directory, mirrored on CPAN. I made
1230 some minor changes needed to compile them by standard tools. I cannot
1231 test UPM and FTP, so I will appreciate your feedback. Other extensions
1232 there are OS2::ExtAttr, OS2::PrfDB for tied access to EAs and .INI
1233 files - and maybe some other extensions at the time you read it.
1234
1235 Note that OS2 perl defines 2 pseudo-extension functions
1236 OS2::Copy::copy and DynaLoader::mod2fname.
1237
1238 The -R switch of older perl is deprecated. If you need to call a REXX code
1239 which needs access to variables, include the call into a REXX compartment
1240 created by
1241         REXX_call {...block...};
1242
1243 Two new functions are supported by REXX code,
1244         REXX_eval 'string';
1245         REXX_eval_with 'string', REXX_function_name => \&perl_sub_reference;
1246
1247 If you have some other extensions you want to share, send the code to
1248 me.  At least two are available: tied access to EA's, and tied access
1249 to system databases.
1250
1251 =head1 AUTHOR
1252
1253 Ilya Zakharevich, ilya@math.ohio-state.edu
1254
1255 =head1 SEE ALSO
1256
1257 perl(1).
1258
1259 =cut
1260