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