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.
7 perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT.
11 One can read this document in the following formats:
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>.
21 To read the F<.INF> version of documentation (B<very> recommended)
22 outside of OS/2, one needs an IBM's reader (may be available on IBM
23 ftp sites (?) (URL anyone?)) or shipped with PC DOS 7.0 and IBM's
26 A copy of a Win* viewer is contained in the "Just add OS/2 Warp" package
28 ftp://ftp.software.ibm.com/ps/products/os2/tools/jaow/jaow.zip
30 in F<?:\JUST_ADD\view.exe>. This gives one an access to B<EMX>'s
31 F<.INF> docs as well (text form is available in F</emx/doc> in
32 B<EMX>'s distribution).
38 perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT.
46 - Starting Perl programs under OS/2
47 - Starting OS/2 programs under Perl
48 Frequently asked questions
49 - I cannot run external programs
50 - I cannot embed perl into my program, or use perl.dll from my program.
51 - `` and pipe-open do not work under DOS.
53 - Automatic binary installation
54 - Manual binary installation
56 Accessing documentation
67 - Application of the patches
71 - Installing the built perl
74 - Some / became \ in pdksh.
75 - 'errno' - unresolved external
77 - Some problem (forget which ;-)
78 - Library ... not found
80 Specific (mis)features of OS/2 port
81 - setpriority, getpriority
93 - Why dynamic linking?
105 - Calls to external programs
114 The target is to make OS/2 the best supported platform for
115 using/building/developing Perl and I<Perl applications>, as well as
116 make Perl the best language to use under OS/2.
118 The current state is quite close to this target. Known limitations:
124 Some *nix programs use fork() a lot, but currently fork() is not
125 supported after I<use>ing dynamically loaded extensions.
129 You need a separate perl executable F<perl__.exe> (see L<perl__.exe>)
130 to use PM code in your application (like the forthcoming Perl/Tk).
134 There is no simple way to access B<WPS> objects. The only way I know
135 is via C<OS2::REXX> extension (see L<OS2::REXX>), and we do not have access to
136 convenience methods of B<Object REXX>. (Is it possible at all? I know
137 of no B<Object-REXX> API.)
141 Please keep this list up-to-date by informing me about other items.
145 Since OS/2 port of perl uses a remarkable B<EMX> environment, it can
146 run (and build extensions, and - possibly - be build itself) under any
147 environment which can run EMX. The current list is DOS,
148 DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT. Out of many perl flavors,
149 only one works, see L<"perl_.exe">.
151 Note that not all features of Perl are available under these
152 environments. This depends on the features the I<extender> - most
153 probably C<RSX> - decided to implement.
155 Cf. L<Prerequisites>.
163 B<EMX> runtime is required (may be substituted by B<RSX>). Note that
164 it is possible to make F<perl_.exe> to run under DOS without any
165 external support by binding F<emx.exe>/F<rsx.exe> to it, see L<emxbind>. Note
166 that under DOS for best results one should use B<RSX> runtime, which
167 has much more functions working (like C<fork>, C<popen> and so on). In
168 fact B<RSX> is required if there is no C<VCPI> present. Note the
169 B<RSX> requires C<DPMI>.
171 Only the latest runtime is supported, currently C<0.9c>.
173 One can get different parts of B<EMX> from, say
175 ftp://ftp.cdrom.com/pub/os2/emx0.9c/
176 ftp://hobbes.nmsu.edu/os2/unix/gnu/
178 The runtime component should have the name F<emxrt.zip>.
180 B<NOTE>. It is enough to have F<emx.exe>/F<rsx.exe> on your path. One
181 does not need to specify them explicitly (though this
189 To run Perl on C<DPMI> platforms one needs B<RSX> runtime. This is
190 needed under DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT (see
191 L<"Other OSes">). B<RSX> would not work with C<VCPI>
192 only, as B<EMX> would, it requires C<DMPI>.
194 Having B<RSX> and the latest F<sh.exe> one gets a fully functional
195 B<*nix>-ish environment under DOS, say, C<fork>, C<``> and
196 pipe-C<open> work. In fact, MakeMaker works (for static build), so one
197 can have Perl development environment under DOS.
199 One can get B<RSX> from, say
201 ftp://ftp.cdrom.com/pub/os2/emx0.9c/contrib
202 ftp://ftp.uni-bielefeld.de/pub/systems/msdos/misc
204 Contact the author on C<rainer@mathematik.uni-bielefeld.de>.
206 The latest F<sh.exe> with DOS hooks is available at
208 ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/sh_dos.exe
212 Perl does not care about file systems, but to install the whole perl
213 library intact one needs a file system which supports long file names.
215 Note that if you do not plan to build the perl itself, it may be
216 possible to fool B<EMX> to truncate file names. This is not supported,
217 read B<EMX> docs to see how to do it.
221 =head2 Starting Perl programs under OS/2
223 Start your Perl program F<foo.pl> with arguments C<arg1 arg2 arg3> the
224 same way as on any other platform, by
226 perl foo.pl arg1 arg2 arg3
228 If you want to specify perl options C<-my_opts> to the perl itself (as
229 opposed to to your program), use
231 perl -my_opts foo.pl arg1 arg2 arg3
233 Alternately, if you use OS/2-ish shell, like C<CMD> or C<4os2>, put
234 the following at the start of your perl script:
237 #!/usr/bin/perl -my_opts
239 rename your program to F<foo.cmd>, and start it by typing
243 (Note that having *nixish full path to perl F</usr/bin/perl> is not
244 necessary, F<perl> would be enough, but having full path would make it
245 easier to use your script under *nix.)
247 Note that because of stupid OS/2 limitations the full path of the perl
248 script is not available when you use C<extproc>, thus you are forced to
249 use C<-S> perl switch, and your script should be on path. As a plus
250 side, if you know a full path to your script, you may still start it
253 perl -x ../../blah/foo.cmd arg1 arg2 arg3
255 (note that the argument C<-my_opts> is taken care of by the C<#!> line
258 To understand what the above I<magic> does, read perl docs about C<-S>
259 and C<-x> switches - see L<perlrun>, and cmdref about C<extproc>:
266 or whatever method you prefer.
268 There are also endless possibilities to use I<executable extensions> of
269 B<4OS2>, I<associations> of B<WPS> and so on... However, if you use
270 *nixish shell (like F<sh.exe> supplied in the binary distribution),
271 you need to follow the syntax specified in L<perlrun/"Switches">.
273 =head2 Starting OS/2 programs under Perl
275 This is what system() (see L<perlfunc/system>), C<``> (see
276 L<perlop/"I/O Operators">), and I<open pipe> (see L<perlfunc/open>)
277 are for. (Avoid exec() (see L<perlfunc/exec>) unless you know what you
280 Note however that to use some of these operators you need to have a
281 C<sh>-syntax shell installed (see L<"Pdksh">,
282 L<"Frequently asked questions">), and perl should be able to find it
283 (see L<"PERL_SH_DIR">).
285 The only cases when the shell is not used is the multi-argument
286 system() (see L<perlfunc/system>)/exec() (see L<perlfunc/exec>), and
287 one-argument version thereof without redirection and shell
290 =head1 Frequently asked questions
292 =head2 I cannot run external programs
298 Did you run your programs with C<-w> switch? See
299 L<Starting OS/2 programs under Perl>.
303 Do you try to run I<internal> shell commands, like C<`copy a b`>
304 (internal for F<cmd.exe>), or C<`glob a*b`> (internal for ksh)? You
305 need to specify your shell explicitly, like C<`cmd /c copy a b`>,
306 since Perl cannot deduce which commands are internal to your shell.
310 =head2 I cannot embed perl into my program, or use F<perl.dll> from my
315 =item Is your program B<EMX>-compiled with C<-Zmt -Zcrtdll>?
317 If not, you need to build a stand-alone DLL for perl. Contact me, I
318 did it once. Sockets would not work, as a lot of other stuff.
320 =item Did you use C<ExtUtils::Embed>?
322 I had reports it does not work. Somebody would need to fix it.
326 =head2 C<``> and pipe-C<open> do not work under DOS.
328 This may a variant of just L<"I cannot run external programs">, or a
329 deeper problem. Basically: you I<need> B<RSX> (see L<"Prerequisites">)
330 for these commands to work, and you may need a port of F<sh.exe> which
331 understands command arguments. One of such ports is listed in
332 L<"Prerequisites"> under B<RSX>.
334 C<DPMI> is required for B<RSX>.
338 =head2 Automatic binary installation
340 The most convenient way of installing perl is via perl installer
341 F<install.exe>. Just follow the instructions, and 99% of the
342 installation blues would go away.
344 Note however, that you need to have F<unzip.exe> on your path, and
345 B<EMX> environment I<running>. The latter means that if you just
346 installed B<EMX>, and made all the needed changes to F<Config.sys>,
347 you may need to reboot in between. Check B<EMX> runtime by running
351 A folder is created on your desktop which contains some useful
354 B<Things not taken care of by automatic binary installation:>
358 =item C<PERL_BADLANG>
360 may be needed if you change your codepage I<after> perl installation,
361 and the new value is not supported by B<EMX>. See L<"PERL_BADLANG">.
363 =item C<PERL_BADFREE>
365 see L<"PERL_BADFREE">.
369 This file resides somewhere deep in the location you installed your
370 perl library, find it out by
372 perl -MConfig -le "print $INC{'Config.pm'}"
374 While most important values in this file I<are> updated by the binary
375 installer, some of them may need to be hand-edited. I know no such
376 data, please keep me informed if you find one.
380 =head2 Manual binary installation
382 As of version 5.00305, OS/2 perl binary distribution comes split
383 into 11 components. Unfortunately, to enable configurable binary
384 installation, the file paths in the C<zip> files are not absolute, but
385 relative to some directory.
387 Note that the extraction with the stored paths is still necessary
388 (default with C<unzip>, specify C<-d> to C<pkunzip>). However, you
389 need to know where to extract the files. You need also to manually
390 change entries in F<Config.sys> to reflect where did you put the
391 files. Note that if you have some primitive unzipper (like
392 C<pkunzip>), you may get a lot of warnings/errors during
393 unzipping. Upgrade to C<(w)unzip>.
395 Below is the sample of what to do to reproduce the configuration on my
400 =item Perl VIO and PM executables (dynamically linked)
402 unzip perl_exc.zip *.exe *.ico -d f:/emx.add/bin
403 unzip perl_exc.zip *.dll -d f:/emx.add/dll
405 (have the directories with C<*.exe> on C<PATH>, and C<*.dll> on
408 =item Perl_ VIO executable (statically linked)
410 unzip perl_aou.zip -d f:/emx.add/bin
412 (have the directory on C<PATH>);
414 =item Executables for Perl utilities
416 unzip perl_utl.zip -d f:/emx.add/bin
418 (have the directory on C<PATH>);
420 =item Main Perl library
422 unzip perl_mlb.zip -d f:/perllib/lib
424 If this directory is preserved, you do not need to change
425 anything. However, for perl to find it if it is changed, you need to
426 C<set PERLLIB_PREFIX> in F<Config.sys>, see L<"PERLLIB_PREFIX">.
428 =item Additional Perl modules
430 unzip perl_ste.zip -d f:/perllib/lib/site_perl
432 If you do not change this directory, do nothing. Otherwise put this
433 directory and subdirectory F<./os2> in C<PERLLIB> or C<PERL5LIB>
434 variable. Do not use C<PERL5LIB> unless you have it set already. See
435 L<perl/"ENVIRONMENT">.
437 =item Tools to compile Perl modules
439 unzip perl_blb.zip -d f:/perllib/lib
441 If this directory is preserved, you do not need to change
442 anything. However, for perl to find it if it is changed, you need to
443 C<set PERLLIB_PREFIX> in F<Config.sys>, see L<"PERLLIB_PREFIX">.
445 =item Manpages for Perl and utilities
447 unzip perl_man.zip -d f:/perllib/man
449 This directory should better be on C<MANPATH>. You need to have a
450 working C<man> to access these files.
452 =item Manpages for Perl modules
454 unzip perl_mam.zip -d f:/perllib/man
456 This directory should better be on C<MANPATH>. You need to have a
457 working C<man> to access these files.
459 =item Source for Perl documentation
461 unzip perl_pod.zip -d f:/perllib/lib
463 This is used by by C<perldoc> program (see L<perldoc>), and may be used to
464 generate B<HTML> documentation usable by WWW browsers, and
465 documentation in zillions of other formats: C<info>, C<LaTeX>,
466 C<Acrobat>, C<FrameMaker> and so on.
468 =item Perl manual in .INF format
470 unzip perl_inf.zip -d d:/os2/book
472 This directory should better be on C<BOOKSHELF>.
476 unzip perl_sh.zip -d f:/bin
478 This is used by perl to run external commands which explicitly
479 require shell, like the commands using I<redirection> and I<shell
480 metacharacters>. It is also used instead of explicit F</bin/sh>.
482 Set C<PERL_SH_DIR> (see L<"PERL_SH_DIR">) if you move F<sh.exe> from
485 B<Note.> It may be possible to use some other C<sh>-compatible shell
490 After you installed the components you needed and updated the
491 F<Config.sys> correspondingly, you need to hand-edit
492 F<Config.pm>. This file resides somewhere deep in the location you
493 installed your perl library, find it out by
495 perl -MConfig -le "print $INC{'Config.pm'}"
497 You need to correct all the entries which look like file paths (they
498 currently start with C<f:/>).
502 The automatic and manual perl installation leave precompiled paths
503 inside perl executables. While these paths are overwriteable (see
504 L<"PERLLIB_PREFIX">, L<"PERL_SH_DIR">), one may get better results by
505 binary editing of paths inside the executables/DLLs.
507 =head1 Accessing documentation
509 Depending on how you built/installed perl you may have (otherwise
510 identical) Perl documentation in the following formats:
512 =head2 OS/2 F<.INF> file
514 Most probably the most convenient form. View it as
519 view perl ExtUtils::MakeMaker
521 (currently the last two may hit a wrong location, but this may improve
524 If you want to build the docs yourself, and have I<OS/2 toolkit>, run
528 in F</perllib/lib/pod> directory, then
532 (Expect a lot of errors during the both steps.) Now move it on your
537 If you have perl documentation in the source form, perl utilities
538 installed, and B<GNU> C<groff> installed, you may use
542 perldoc ExtUtils::MakeMaker
544 to access the perl documentation in the text form (note that you may get
545 better results using perl manpages).
547 Alternately, try running pod2text on F<.pod> files.
551 If you have C<man> installed on your system, and you installed perl
552 manpages, use something like this:
556 man ExtUtils.MakeMaker
558 to access documentation for different components of Perl. Start with
562 Note that dot (F<.>) is used as a package separator for documentation
563 for packages, and as usual, sometimes you need to give the section - C<3>
564 above - to avoid shadowing by the I<less(1) manpage>.
566 Make sure that the directory B<above> the directory with manpages is
567 on our C<MANPATH>, like this
569 set MANPATH=c:/man;f:/perllib/man
573 If you have some WWW browser available, installed the Perl
574 documentation in the source form, and Perl utilities, you can build
575 B<HTML> docs. Cd to directory with F<.pod> files, and do like this
577 cd f:/perllib/lib/pod
580 After this you can direct your browser the file F<perl.html> in this
581 directory, and go ahead with reading docs, like this:
583 explore file:///f:/perllib/lib/pod/perl.html
585 Alternatively you may be able to get these docs prebuilt from C<CPAN>.
587 =head2 B<GNU> C<info> files
589 Users of C<Emacs> would appreciate it very much, especially with
590 C<CPerl> mode loaded. You need to get latest C<pod2info> from C<CPAN>,
591 or, alternately, prebuilt info pages.
595 for C<Acrobat> are available on CPAN (for slightly old version of
600 can be constructed using C<pod2latex>.
604 Here we discuss how to build Perl under OS/2. There is an alternative
605 (but maybe older) view on L<http://www.shadow.net/~troc/os2perl.html>.
609 You need to have the latest B<EMX> development environment, the full
610 B<GNU> tool suite (C<gawk> renamed to C<awk>, and B<GNU> F<find.exe>
611 earlier on path than the OS/2 F<find.exe>, same with F<sort.exe>, to
617 ). You need the latest version of F<pdksh> installed as F<sh.exe>.
619 Possible locations to get this from are
621 ftp://hobbes.nmsu.edu/os2/unix/gnu/
622 ftp://ftp.cdrom.com/pub/os2/unix/
623 ftp://ftp.cdrom.com/pub/os2/dev32/
624 ftp://ftp.cdrom.com/pub/os2/emx0.9c/
627 Make sure that no copies or perl are currently running. Later steps
628 of the build may fail since an older version of perl.dll loaded into
631 Also make sure that you have F</tmp> directory on the current drive,
632 and F<.> directory in your C<LIBPATH>. One may try to correct the
637 if you use something like F<CMD.EXE> or latest versions of F<4os2.exe>.
639 Make sure your C<gcc> is good for C<-Zomf> linking: run C<omflibs>
640 script in F</emx/lib> directory.
642 Check that you have C<link386> installed. It comes standard with OS/2,
643 but may be not installed due to customization. If typing
647 shows you do not have it, do I<Selective install>, and choose C<Link
648 object modules> in I<Optional system utilities/More>. If you get into
649 C<link386>, press C<Ctrl-C>.
651 =head2 Getting perl source
653 You need to fetch the latest perl source (including developers
654 releases). With some probability it is located in
656 http://www.perl.com/CPAN/src/5.0
657 http://www.perl.com/CPAN/src/5.0/unsupported
659 If not, you may need to dig in the indices to find it in the directory
660 of the current maintainer.
662 Quick cycle of developers release may break the OS/2 build time to
665 http://www.perl.com/CPAN/ports/os2/ilyaz/
667 may indicate the latest release which was publicly released by the
668 maintainer. Note that the release may include some additional patches
669 to apply to the current source of perl.
673 tar vzxf perl5.00409.tar.gz
675 You may see a message about errors while extracting F<Configure>. This is
676 because there is a conflict with a similarly-named file F<configure>.
678 Rename F<configure> to F<configure.gnu>. Extract F<Configure> like this
680 tar --case-sensitive -vzxf perl5.00409.tar.gz perl5.00409/Configure
682 Change to the directory of extraction.
684 =head2 Application of the patches
686 You need to apply the patches in F<./os2/diff.*> and
687 F<./os2/POSIX.mkfifo> like this:
689 gnupatch -p0 < os2\POSIX.mkfifo
690 gnupatch -p0 < os2\diff.configure
692 You may also need to apply the patches supplied with the binary
693 distribution of perl.
695 Note also that the F<db.lib> and F<db.a> from the B<EMX> distribution
696 are not suitable for multi-threaded compile (note that currently perl
697 is not multithreaded, but is compiled as multithreaded for
698 compatibility with B<XFree86>-OS/2). Get a corrected one from
700 ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/db_mt.zip
704 You may look into the file F<./hints/os2.sh> and correct anything
705 wrong you find there. I do not expect it is needed anywhere.
709 sh Configure -des -D prefix=f:/perllib
711 Prefix means where to install the resulting perl library. Giving
712 correct prefix you may avoid the need to specify C<PERLLIB_PREFIX>,
713 see L<"PERLLIB_PREFIX">.
715 I<Ignore the message about missing C<ln>, and about C<-c> option to
716 C<tr>>. In fact if you can trace where the latter spurious warning
717 comes from, please inform me.
723 At some moment the built may die, reporting a I<version mismatch> or
724 I<unable to run F<perl>>. This means that most of the build has been
725 finished, and it is the time to move the constructed F<perl.dll> to
726 some I<absolute> location in C<LIBPATH>. After this done the build
727 should finish without a lot of fuss. I<One can avoid it if one has the
728 correct prebuilt version of F<perl.dll> on C<LIBPATH>.>
730 Warnings which are safe to ignore: I<mkfifo() redefined> inside
739 Some tests (4..6) should fail. Some perl invocations should end in a
740 segfault (system error C<SYS3175>). To get finer error reports,
743 perl -I ../lib harness
745 The report you get may look like
747 Failed Test Status Wstat Total Fail Failed List of failed
748 ---------------------------------------------------------------
749 io/fs.t 26 11 42.31% 2-5, 7-11, 18, 25
750 lib/io_pipe.t 3 768 6 ?? % ??
751 lib/io_sock.t 3 768 5 ?? % ??
752 op/stat.t 56 5 8.93% 3-4, 20, 35, 39
753 Failed 4/140 test scripts, 97.14% okay. 27/2937 subtests failed, 99.08% okay.
755 Note that using `make test' target two more tests may fail: C<op/exec:1>
756 because of (mis)feature of C<pdksh>, and C<lib/posix:15>, which checks
757 that the buffers are not flushed on C<_exit> (this is a bug in the test
758 which assumes that tty output is buffered).
760 I submitted a patch to B<EMX> which makes it possible to fork() with EMX
761 dynamic libraries loaded, which makes F<lib/io*> tests pass. This means
762 that soon the number of failing tests may decrease yet more.
764 However, the test F<lib/io_udp.t> is disabled, since it never terminates, I
765 do not know why. Comments/fixes welcome.
767 The reasons for failed tests are:
773 Checks I<file system> operations. Tests:
779 Check C<link()> and C<inode count> - nonesuch under OS/2.
783 Checks C<atime> and C<mtime> of C<stat()> - I could not understand this test.
787 Checks C<truncate()> on a filehandle just opened for write - I do not
788 know why this should or should not work.
792 =item F<lib/io_pipe.t>
794 Checks C<IO::Pipe> module. Some feature of B<EMX> - test fork()s with
795 dynamic extension loaded - unsupported now.
797 =item F<lib/io_sock.t>
799 Checks C<IO::Socket> module. Some feature of B<EMX> - test fork()s
800 with dynamic extension loaded - unsupported now.
804 Checks C<stat()>. Tests:
810 Checks C<inode count> - nonesuch under OS/2.
814 Checks C<mtime> and C<ctime> of C<stat()> - I could not understand this test.
818 Checks C<-x> - determined by the file extension only under OS/2.
826 Checks C<-t> of F</dev/null>. Should not fail!
832 In addition to errors, you should get a lot of warnings.
836 =item A lot of `bad free'
838 in databases related to Berkeley DB. This is a confirmed bug of
839 DB. You may disable this warnings, see L<"PERL_BADFREE">.
841 =item Process terminated by SIGTERM/SIGINT
843 This is a standard message issued by OS/2 applications. *nix
844 applications die in silence. It is considered a feature. One can
845 easily disable this by appropriate sighandlers.
847 However the test engine bleeds these message to screen in unexpected
848 moments. Two messages of this kind I<should> be present during
851 =item F<*/sh.exe>: ln: not found
853 =item C<ls>: /dev: No such file or directory
855 The last two should be self-explanatory. The test suite discovers that
856 the system it runs on is not I<that much> *nixish.
860 A lot of `bad free'... in databases, bug in DB confirmed on other
861 platforms. You may disable it by setting PERL_BADFREE environment variable
864 =head2 Installing the built perl
870 It would put the generated files into needed locations. Manually put
871 F<perl.exe>, F<perl__.exe> and F<perl___.exe> to a location on your
872 C<PATH>, F<perl.dll> to a location on your C<LIBPATH>.
876 make cmdscripts INSTALLCMDDIR=d:/ir/on/path
878 to convert perl utilities to F<.cmd> files and put them on
879 C<PATH>. You need to put F<.EXE>-utilities on path manually. They are
880 installed in C<$prefix/bin>, here C<$prefix> is what you gave to
881 F<Configure>, see L<Making>.
883 =head2 C<a.out>-style build
885 Proceed as above, but make F<perl_.exe> (see L<"perl_.exe">) by
894 Manually put F<perl_.exe> to a location on your C<PATH>.
896 Since C<perl_> has the extensions prebuilt, it does not suffer from
897 the I<dynamic extensions + fork()> syndrome, thus the failing tests
900 Failed Test Status Wstat Total Fail Failed List of failed
901 ---------------------------------------------------------------
902 io/fs.t 26 11 42.31% 2-5, 7-11, 18, 25
903 op/stat.t 56 5 8.93% 3-4, 20, 35, 39
904 Failed 2/118 test scripts, 98.31% okay. 16/2445 subtests failed, 99.35% okay.
906 B<Note.> The build process for C<perl_> I<does not know> about all the
907 dependencies, so you should make sure that anything is up-to-date,
916 =head2 Some C</> became C<\> in pdksh.
918 You have a very old pdksh. See L<Prerequisites>.
920 =head2 C<'errno'> - unresolved external
922 You do not have MT-safe F<db.lib>. See L<Prerequisites>.
924 =head2 Problems with C<tr>
926 reported with very old version of C<tr>.
928 =head2 Some problem (forget which ;-)
930 You have an older version of F<perl.dll> on your C<LIBPATH>, which
931 broke the build of extensions.
933 =head2 Library ... not found
935 You did not run C<omflibs>. See L<Prerequisites>.
937 =head2 Segfault in make
939 You use an old version of C<GNU> make. See L<Prerequisites>.
941 =head1 Specific (mis)features of OS/2 port
943 =head2 C<setpriority>, C<getpriority>
945 Note that these functions are compatible with *nix, not with the older
946 ports of '94 - 95. The priorities are absolute, go from 32 to -95,
947 lower is quicker. 0 is the default priority.
951 Multi-argument form of C<system()> allows an additional numeric
952 argument. The meaning of this argument is described in
955 =head2 Additional modules:
957 L<OS2::Process>, L<OS2::REXX>, L<OS2::PrfDB>, L<OS2::ExtAttr>. This
958 modules provide access to additional numeric argument for C<system>,
959 to DLLs having functions with REXX signature and to REXX runtime, to
960 OS/2 databases in the F<.INI> format, and to Extended Attributes.
962 Two additional extensions by Andreas Kaiser, C<OS2::UPM>, and
963 C<OS2::FTP>, are included into my ftp directory, mirrored on CPAN.
965 =head2 Prebuilt methods:
969 =item C<File::Copy::syscopy>
971 used by C<File::Copy::copy>, see L<File::Copy/copy>.
973 =item C<DynaLoader::mod2fname>
975 used by C<DynaLoader> for DLL name mangling.
977 =item C<Cwd::current_drive()>
981 =item C<Cwd::sys_chdir(name)>
983 leaves drive as it is.
985 =item C<Cwd::change_drive(name)>
988 =item C<Cwd::sys_is_absolute(name)>
990 means has drive letter and is_rooted.
992 =item C<Cwd::sys_is_rooted(name)>
994 means has leading C<[/\\]> (maybe after a drive-letter:).
996 =item C<Cwd::sys_is_relative(name)>
998 means changes with current dir.
1000 =item C<Cwd::sys_cwd(name)>
1002 Interface to cwd from B<EMX>. Used by C<Cwd::cwd>.
1004 =item C<Cwd::sys_abspath(name, dir)>
1006 Really really odious function to implement. Returns absolute name of
1007 file which would have C<name> if CWD were C<dir>. C<Dir> defaults to the
1010 =item C<Cwd::extLibpath([type])
1012 Get current value of extended library search path. If C<type> is
1013 present and I<true>, works with END_LIBPATH, otherwise with
1016 =item C<Cwd::extLibpath_set( path [, type ] )>
1018 Set current value of extended library search path. If C<type> is
1019 present and I<true>, works with END_LIBPATH, otherwise with
1024 (Note that some of these may be moved to different libraries -
1034 Since <flock> is present in B<EMX>, but is not functional, the same is
1035 true for perl. Here is the list of things which may be "broken" on
1036 EMX (from EMX docs):
1038 - The functions recvmsg(), sendmsg(), and socketpair() are not
1040 - sock_init() is not required and not implemented.
1041 - flock() is not yet implemented (dummy function).
1043 Special treatment of PID=0, PID=1 and PID=-1 is not implemented.
1047 waitpid() is not implemented for negative values of PID.
1049 Note that C<kill -9> does not work with the current version of EMX.
1053 Since F<sh.exe> is used for globing (see L<perlfunc/glob>), the bugs
1054 of F<sh.exe> plague perl as well.
1056 In particular, uppercase letters do not work in C<[...]>-patterns with
1057 the current C<pdksh>.
1061 =head2 Modifications
1063 Perl modifies some standard C library calls in the following ways:
1069 C<my_popen> uses F<sh.exe> if shell is required, cf. L<"PERL_SH_DIR">.
1073 is created using C<TMP> or C<TEMP> environment variable, via
1078 If the current directory is not writable, file is created using modified
1079 C<tmpnam>, so there may be a race condition.
1083 a dummy implementation.
1087 C<os2_stat> special-cases F</dev/tty> and F</dev/con>.
1093 Because of idiosyncrasies of OS/2 one cannot have all the eggs in the
1094 same basket (though C<EMX> environment tries hard to overcome this
1095 limitations, so the situation may somehow improve). There are 4
1096 executables for Perl provided by the distribution:
1100 The main workhorse. This is a chimera executable: it is compiled as an
1101 C<a.out>-style executable, but is linked with C<omf>-style dynamic
1102 library F<perl.dll>, and with dynamic B<CRT> DLL. This executable is a
1105 It can load perl dynamic extensions, and it can fork(). Unfortunately,
1106 with the current version of B<EMX> it cannot fork() with dynamic
1107 extensions loaded (may be fixed by patches to B<EMX>).
1109 B<Note.> Keep in mind that fork() is needed to open a pipe to yourself.
1113 This is a statically linked C<a.out>-style executable. It can fork(),
1114 but cannot load dynamic Perl extensions. The supplied executable has a
1115 lot of extensions prebuilt, thus there are situations when it can
1116 perform tasks not possible using F<perl.exe>, like fork()ing when
1117 having some standard extension loaded. This executable is a C<VIO>
1120 B<Note.> A better behaviour could be obtained from C<perl.exe> if it
1121 were statically linked with standard I<Perl extensions>, but
1122 dynamically linked with the I<Perl DLL> and C<CRT> DLL. Then it would
1123 be able to fork() with standard extensions, I<and> would be able to
1124 dynamically load arbitrary extensions. Some changes to Makefiles and
1125 hint files should be necessary to achieve this.
1127 I<This is also the only executable with does not require OS/2.> The
1128 friends locked into C<M$> world would appreciate the fact that this
1129 executable runs under DOS, Win0.3*, Win0.95 and WinNT with an
1130 appropriate extender. See L<"Other OSes">.
1132 =head2 F<perl__.exe>
1134 This is the same executable as <perl___.exe>, but it is a C<PM>
1137 B<Note.> Usually C<STDIN>, C<STDERR>, and C<STDOUT> of a C<PM>
1138 application are redirected to C<nul>. However, it is possible to see
1139 them if you start C<perl__.exe> from a PM program which emulates a
1140 console window, like I<Shell mode> of C<Emacs> or C<EPM>. Thus it I<is
1141 possible> to use Perl debugger (see L<perldebug>) to debug your PM
1144 This flavor is required if you load extensions which use C<PM>, like
1145 the forthcoming C<Perl/Tk>.
1147 =head2 F<perl___.exe>
1149 This is an C<omf>-style executable which is dynamically linked to
1150 F<perl.dll> and C<CRT> DLL. I know no advantages of this executable
1151 over C<perl.exe>, but it cannot fork() at all. Well, one advantage is
1152 that the build process is not so convoluted as with C<perl.exe>.
1154 It is a C<VIO> application.
1156 =head2 Why strange names?
1158 Since Perl processes the C<#!>-line (cf.
1159 L<perlrun/DESCRIPTION>, L<perlrun/Switches>,
1160 L<perldiag/"Not a perl script">,
1161 L<perldiag/"No Perl script found in input">), it should know when a
1162 program I<is a Perl>. There is some naming convention which allows
1163 Perl to distinguish correct lines from wrong ones. The above names are
1164 almost the only names allowed by this convention which do not contain
1165 digits (which have absolutely different semantics).
1167 =head2 Why dynamic linking?
1169 Well, having several executables dynamically linked to the same huge
1170 library has its advantages, but this would not substantiate the
1171 additional work to make it compile. The reason is stupid-but-quick
1172 "hard" dynamic linking used by OS/2.
1174 The address tables of DLLs are patched only once, when they are
1175 loaded. The addresses of entry points into DLLs are guaranteed to be
1176 the same for all programs which use the same DLL, which reduces the
1177 amount of runtime patching - once DLL is loaded, its code is
1180 While this allows some performance advantages, this makes life
1181 terrible for developers, since the above scheme makes it impossible
1182 for a DLL to be resolved to a symbol in the .EXE file, since this
1183 would need a DLL to have different relocations tables for the
1184 executables which use it.
1186 However, a Perl extension is forced to use some symbols from the perl
1187 executable, say to know how to find the arguments provided on the perl
1188 internal evaluation stack. The solution is that the main code of
1189 interpreter should be contained in a DLL, and the F<.EXE> file just loads
1190 this DLL into memory and supplies command-arguments.
1192 This I<greatly> increases the load time for the application (as well as
1193 the number of problems during compilation). Since interpreter is in a DLL,
1194 the C<CRT> is basically forced to reside in a DLL as well (otherwise
1195 extensions would not be able to use C<CRT>).
1197 =head2 Why chimera build?
1199 Current C<EMX> environment does not allow DLLs compiled using Unixish
1200 C<a.out> format to export symbols for data. This forces C<omf>-style
1201 compile of F<perl.dll>.
1203 Current C<EMX> environment does not allow F<.EXE> files compiled in
1204 C<omf> format to fork(). fork() is needed for exactly three Perl
1209 =item explicit fork()
1217 opening pipes to itself.
1221 While these operations are not questions of life and death, a lot of
1222 useful scripts use them. This forces C<a.out>-style compile of
1228 Here we list environment variables with are either OS/2-specific, or
1229 are more important under OS/2 than under other OSes.
1231 =head2 C<PERLLIB_PREFIX>
1233 Specific for OS/2. Should have the form
1241 If the beginning of some prebuilt path matches F<path1>, it is
1242 substituted with F<path2>.
1244 Should be used if the perl library is moved from the default
1245 location in preference to C<PERL(5)LIB>, since this would not leave wrong
1248 =head2 C<PERL_BADLANG>
1250 If 1, perl ignores setlocale() failing. May be useful with some
1253 =head2 C<PERL_BADFREE>
1255 If 1, perl would not warn of in case of unwarranted free(). May be
1256 useful in conjunction with the module DB_File, since Berkeley DB
1257 memory handling code is buggy.
1259 =head2 C<PERL_SH_DIR>
1261 Specific for OS/2. Gives the directory part of the location for
1264 =head2 C<TMP> or C<TEMP>
1266 Specific for OS/2. Used as storage place for temporary files, most
1267 notably C<-e> scripts.
1271 Here we list major changes which could make you by surprise.
1275 C<setpriority> and C<getpriority> are not compatible with earlier
1276 ports by Andreas Kaiser. See C<"setpriority, getpriority">.
1278 =head2 DLL name mangling
1280 With the release 5.003_01 the dynamically loadable libraries
1281 should be rebuilt. In particular, DLLs are now created with the names
1282 which contain a checksum, thus allowing workaround for OS/2 scheme of
1287 As of release 5.003_01 perl is linked to multithreaded C<CRT>
1288 DLL. Perl itself is not multithread-safe, as is not perl
1289 malloc(). However, extensions may use multiple thread on their own
1292 Needed to compile C<Perl/Tk> for C<XFreeOS/2> out-of-the-box.
1294 =head2 Calls to external programs
1296 Due to a popular demand the perl external program calling has been
1297 changed wrt Andreas Kaiser's port. I<If> perl needs to call an
1298 external program I<via shell>, the F<f:/bin/sh.exe> will be called, or
1299 whatever is the override, see L<"PERL_SH_DIR">.
1301 Thus means that you need to get some copy of a F<sh.exe> as well (I
1302 use one from pdksh). The drive F: above is set up automatically during
1303 the build to a correct value on the builder machine, but is
1304 overridable at runtime,
1306 B<Reasons:> a consensus on C<perl5-porters> was that perl should use
1307 one non-overridable shell per platform. The obvious choices for OS/2
1308 are F<cmd.exe> and F<sh.exe>. Having perl build itself would be impossible
1309 with F<cmd.exe> as a shell, thus I picked up C<sh.exe>. Thus assures almost
1310 100% compatibility with the scripts coming from *nix.
1312 B<Disadvantages:> currently F<sh.exe> of C<pdksh> calls external programs
1313 via fork()/exec(), and there is I<no> functioning exec() on
1314 OS/2. exec() is emulated by EMX by asyncroneous call while the caller
1315 waits for child completion (to pretend that the C<pid> did not change). This
1316 means that 1 I<extra> copy of F<sh.exe> is made active via fork()/exec(),
1317 which may lead to some resources taken from the system (even if we do
1318 not count extra work needed for fork()ing).
1320 Note that this a lesser issue now when we do not spawn F<sh.exe>
1321 unless needed (metachars found).
1323 One can always start F<cmd.exe> explicitly via
1325 system 'cmd', '/c', 'mycmd', 'arg1', 'arg2', ...
1327 If you need to use F<cmd.exe>, and do not want to hand-edit thousands of your
1328 scripts, the long-term solution proposed on p5-p is to have a directive
1332 which will override system(), exec(), C<``>, and
1333 C<open(,'...|')>. With current perl you may override only system(),
1334 readpipe() - the explicit version of C<``>, and maybe exec(). The code
1335 will substitute the one-argument call to system() by
1336 C<CORE::system('cmd.exe', '/c', shift)>.
1338 If you have some working code for C<OS2::Cmd>, please send it to me,
1339 I will include it into distribution. I have no need for such a module, so
1342 =head2 Memory allocation
1344 Perl uses its own malloc() under OS/2 - interpreters are usually malloc-bound
1345 for speed, but perl is not, since its malloc is lightning-fast.
1346 Unfortunately, it is also quite frivolous with memory usage as well.
1348 Since kitchen-top machines are usually low on memory, perl is compiled with
1349 all the possible memory-saving options. This probably makes perl's
1350 malloc() as greedy with memory as the neighbor's malloc(), but still
1351 much quickier. Note that this is true only for a "typical" usage,
1352 it is possible that the perl malloc will be worse for some very special usage.
1354 Combination of perl's malloc() and rigid DLL name resolution creates
1355 a special problem with library functions which expect their return value to
1356 be free()d by system's free(). To facilitate extensions which need to call
1357 such functions, system memory-allocation functions are still available with
1358 the prefix C<emx_> added. (Currently only DLL perl has this, it should
1359 propagate to F<perl_.exe> shortly.)
1365 I include 3 extensions by Andreas Kaiser, OS2::REXX, OS2::UPM, and OS2::FTP,
1366 into my ftp directory, mirrored on CPAN. I made
1367 some minor changes needed to compile them by standard tools. I cannot
1368 test UPM and FTP, so I will appreciate your feedback. Other extensions
1369 there are OS2::ExtAttr, OS2::PrfDB for tied access to EAs and .INI
1370 files - and maybe some other extensions at the time you read it.
1372 Note that OS2 perl defines 2 pseudo-extension functions
1373 OS2::Copy::copy and DynaLoader::mod2fname.
1375 The -R switch of older perl is deprecated. If you need to call a REXX code
1376 which needs access to variables, include the call into a REXX compartment
1378 REXX_call {...block...};
1380 Two new functions are supported by REXX code,
1382 REXX_eval_with 'string', REXX_function_name => \&perl_sub_reference;
1384 If you have some other extensions you want to share, send the code to
1385 me. At least two are available: tied access to EA's, and tied access
1386 to system databases.
1390 Ilya Zakharevich, ilya@math.ohio-state.edu