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