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