To read the F<.INF> version of documentation (B<very> recommended)
outside of OS/2, one needs an IBM's reader (may be available on IBM
-ftp sites (?) (URL anyone?)) or shipped with PC DOS 7.0.
+ftp sites (?) (URL anyone?)) or shipped with PC DOS 7.0 and IBM's
+Visual Age C++ 3.5.
+
+A copy of a Win* viewer is contained in the "Just add OS/2 Warp" package
+
+ ftp://ftp.software.ibm.com/ps/products/os2/tools/jaow/jaow.zip
+
+in F<?:\JUST_ADD\view.exe>. This gives one an access to EMX's
+F<.INF> docs as well (text form is available in F</emx/doc> in
+EMX's distribution). There is also a different viewer named xview.
+
+Note that if you have F<lynx.exe> or F<netscape.exe> installed, you can follow WWW links
+from this document in F<.INF> format. If you have EMX docs installed
+correctly, you can follow library links (you need to have C<view emxbook>
+working by setting C<EMXBOOK> environment variable as it is described
+in EMX docs).
=cut
-Contents
+Contents (This may be a little bit obsolete)
- perlos2 - Perl under OS/2
-
- NAME
- SYNOPSIS
- DESCRIPTION
- - Target
- - Other OSes
- - Prerequisites
- - Starting Perl programs under OS/2
- - Starting OS/2 programs under Perl
- Frequently asked questions
- - I cannot run external programs
- - I cannot embed perl into my program, or use perl.dll from my program.
- INSTALLATION
- - Automatic binary installation
- - Manual binary installation
- - Warning
- Accessing documentation
- - OS/2 .INF file
- - Plain text
- - Manpages
- - HTML
- - GNU info files
- - .PDF files
- - LaTeX docs
- BUILD
- - Prerequisites
- - Getting perl source
- - Application of the patches
- - Hand-editing
- - Making
- - Testing
- - Installing the built perl
- - a.out-style build
- Build FAQ
- - Some / became \ in pdksh.
- - 'errno' - unresolved external
- - Problems with tr
- - Some problem (forget which ;-)
- - Library ... not found
- - Segfault in make
- Specific (mis)features of OS/2 port
- - setpriority, getpriority
- - system()
- - Additional modules:
- - Prebuilt methods:
- - Misfeatures
- Perl flavors
- - perl.exe
- - perl_.exe
- - perl__.exe
- - perl___.exe
- - Why strange names?
- - Why dynamic linking?
- - Why chimera build?
- ENVIRONMENT
- - PERLLIB_PREFIX
- - PERL_BADLANG
- - PERL_BADFREE
- - PERL_SH_DIR
- - TMP or TEMP
- Evolution
- - Priorities
- - DLL name mangling
- - Threading
- - Calls to external programs
- AUTHOR
- SEE ALSO
+ perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT.
+
+ NAME
+ SYNOPSIS
+ DESCRIPTION
+ - Target
+ - Other OSes
+ - Prerequisites
+ - Starting Perl programs under OS/2 (and DOS and...)
+ - Starting OS/2 (and DOS) programs under Perl
+ Frequently asked questions
+ - "It does not work"
+ - I cannot run external programs
+ - I cannot embed perl into my program, or use perl.dll from my
+ - `` and pipe-open do not work under DOS.
+ - Cannot start find.exe "pattern" file
+ INSTALLATION
+ - Automatic binary installation
+ - Manual binary installation
+ - Warning
+ Accessing documentation
+ - OS/2 .INF file
+ - Plain text
+ - Manpages
+ - HTML
+ - GNU info files
+ - PDF files
+ - LaTeX docs
+ BUILD
+ - The short story
+ - Prerequisites
+ - Getting perl source
+ - Application of the patches
+ - Hand-editing
+ - Making
+ - Testing
+ - Installing the built perl
+ - a.out-style build
+ Build FAQ
+ - Some / became \ in pdksh.
+ - 'errno' - unresolved external
+ - Problems with tr or sed
+ - Some problem (forget which ;-)
+ - Library ... not found
+ - Segfault in make
+ - op/sprintf test failure
+ Specific (mis)features of OS/2 port
+ - setpriority, getpriority
+ - system()
+ - extproc on the first line
+ - Additional modules:
+ - Prebuilt methods:
+ - Prebuilt variables:
+ - Misfeatures
+ - Modifications
+ - Identifying DLLs
+ - Centralized management of resources
+ Perl flavors
+ - perl.exe
+ - perl_.exe
+ - perl__.exe
+ - perl___.exe
+ - Why strange names?
+ - Why dynamic linking?
+ - Why chimera build?
+ ENVIRONMENT
+ - PERLLIB_PREFIX
+ - PERL_BADLANG
+ - PERL_BADFREE
+ - PERL_SH_DIR
+ - USE_PERL_FLOCK
+ - TMP or TEMP
+ Evolution
+ - Text-mode filehandles
+ - Priorities
+ - DLL name mangling: pre 5.6.2
+ - DLL name mangling: 5.6.2 and beyond
+ - DLL forwarder generation
+ - Threading
+ - Calls to external programs
+ - Memory allocation
+ - Threads
+ BUGS
+ AUTHOR
+ SEE ALSO
=head1 DESCRIPTION
=head2 Target
-The target is to make OS/2 the best supported platform for
+The target is to make OS/2 one of the best supported platform for
using/building/developing Perl and I<Perl applications>, as well as
-make Perl the best language to use under OS/2.
+make Perl the best language to use under OS/2. The secondary target is
+to try to make this work under DOS and Win* as well (but not B<too> hard).
The current state is quite close to this target. Known limitations:
=item *
-Some *nix programs use fork() a lot, but currently fork() is not
-supported after I<use>ing dynamically loaded extensions.
+Some *nix programs use fork() a lot; with the mostly useful flavors of
+perl for OS/2 (there are several built simultaneously) this is
+supported; but some flavors do not support this (e.g., when Perl is
+called from inside REXX). Using fork() after
+I<use>ing dynamically loading extensions would not work with I<very> old
+versions of EMX.
=item *
You need a separate perl executable F<perl__.exe> (see L<perl__.exe>)
-to use PM code in your application (like the forthcoming Perl/Tk).
+if you want to use PM code in your application (as Perl/Tk or OpenGL
+Perl modules do) without having a text-mode window present.
+
+While using the standard F<perl.exe> from a text-mode window is possible
+too, I have seen cases when this causes degradation of the system stability.
+Using F<perl__.exe> avoids such a degradation.
=item *
-There is no simple way to access B<WPS> objects. The only way I know
-is via C<OS2::REXX> extension (see L<OS2::REXX>), and we do not have access to
-convenience methods of B<Object REXX>. (Is it possible at all? I know
-of no B<Object-REXX> API.)
+There is no simple way to access WPS objects. The only way I know
+is via C<OS2::REXX> and C<SOM> extensions (see L<OS2::REXX>, L<Som>).
+However, we do not have access to
+convenience methods of Object-REXX. (Is it possible at all? I know
+of no Object-REXX API.) The C<SOM> extension (currently in alpha-text)
+may eventually remove this shortcoming; however, due to the fact that
+DII is not supported by the C<SOM> module, using C<SOM> is not as
+convenient as one would like it.
=back
=head2 Other OSes
-Since OS/2 port of perl uses a remarkable B<EMX> environment, it can
-run (and build extensions, and - possibly - be build itself) under any
+Since OS/2 port of perl uses a remarkable EMX environment, it can
+run (and build extensions, and - possibly - be built itself) under any
environment which can run EMX. The current list is DOS,
DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT. Out of many perl flavors,
only one works, see L<"perl_.exe">.
Note that not all features of Perl are available under these
environments. This depends on the features the I<extender> - most
-probably C<RSX> - decided to implement.
+probably RSX - decided to implement.
Cf. L<Prerequisites>.
=over 6
-=item B<EMX>
+=item EMX
-B<EMX> runtime is required (may be substituted by B<RSX>). Note that
+EMX runtime is required (may be substituted by RSX). Note that
it is possible to make F<perl_.exe> to run under DOS without any
external support by binding F<emx.exe>/F<rsx.exe> to it, see L<emxbind>. Note
-that under DOS for best results one should use B<RSX> runtime, which
+that under DOS for best results one should use RSX runtime, which
has much more functions working (like C<fork>, C<popen> and so on). In
-fact B<RSX> is required if there is no C<VCPI> present. Note the
-B<RSX> requires C<DPMI>.
+fact RSX is required if there is no VCPI present. Note the
+RSX requires DPMI. Many implementations of DPMI are known to be very
+buggy, beware!
-Only the latest runtime is supported, currently C<0.9c>.
+Only the latest runtime is supported, currently C<0.9d fix 03>. Perl may run
+under earlier versions of EMX, but this is not tested.
-One can get different parts of B<EMX> from, say
+One can get different parts of EMX from, say
- ftp://ftp.cdrom.com/pub/os2/emx0.9c/
- ftp://hobbes.nmsu.edu/os2/unix/gnu/
+ http://www.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/
+ http://powerusersbbs.com/pub/os2/dev/ [EMX+GCC Development]
+ http://hobbes.nmsu.edu/pub/os2/dev/emx/v0.9d/
The runtime component should have the name F<emxrt.zip>.
-B<NOTE>. It is enough to have F<emx.exe>/F<rsx.exe> on your path. One
+B<NOTE>. When using F<emx.exe>/F<rsx.exe>, it is enough to have them on your path. One
does not need to specify them explicitly (though this
emx perl_.exe -de 0
will work as well.)
-=item B<RSX>
+=item RSX
-To run Perl on C<DPMI> platforms one needs B<RSX> runtime. This is
+To run Perl on DPMI platforms one needs RSX runtime. This is
needed under DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT (see
-L<"Other OSes">). B<RSX> would not work with C<VCPI>
-only, as B<EMX> would, it requires C<DMPI>.
+L<"Other OSes">). RSX would not work with VCPI
+only, as EMX would, it requires DMPI.
-Having B<RSX> and the latest F<sh.exe> one gets a fully functional
+Having RSX and the latest F<sh.exe> one gets a fully functional
B<*nix>-ish environment under DOS, say, C<fork>, C<``> and
pipe-C<open> work. In fact, MakeMaker works (for static build), so one
can have Perl development environment under DOS.
-One can get B<RSX> from, say
+One can get RSX from, say
- ftp://ftp.cdrom.com/pub/os2/emx0.9c/contrib
+ ftp://ftp.cdrom.com/pub/os2/emx09c/contrib
ftp://ftp.uni-bielefeld.de/pub/systems/msdos/misc
+ ftp://ftp.leo.org/pub/comp/os/os2/leo/devtools/emx+gcc/contrib
Contact the author on C<rainer@mathematik.uni-bielefeld.de>.
-The latest F<sh.exe> with DOS hooks is available at
+The latest F<sh.exe> with DOS hooks is available in
+
+ http://www.ilyaz.org/software/os2/
- ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/sh_dos.exe
+as F<sh_dos.zip> or under similar names starting with C<sh>, C<pdksh> etc.
-=item B<HPFS>
+=item HPFS
-Perl does not care about file systems, but to install the whole perl
-library intact one needs a file system which supports long file names.
+Perl does not care about file systems, but the perl library contains
+many files with long names, so to install it intact one needs a file
+system which supports long file names.
Note that if you do not plan to build the perl itself, it may be
-possible to fool B<EMX> to truncate file names. This is not supported,
-read B<EMX> docs to see how to do it.
+possible to fool EMX to truncate file names. This is not supported,
+read EMX docs to see how to do it.
+
+=item pdksh
+
+To start external programs with complicated command lines (like with
+pipes in between, and/or quoting of arguments), Perl uses an external
+shell. With EMX port such shell should be named F<sh.exe>, and located
+either in the wired-in-during-compile locations (usually F<F:/bin>),
+or in configurable location (see L<"PERL_SH_DIR">).
+
+For best results use EMX pdksh. The standard binary (5.2.14 or later) runs
+under DOS (with L<RSX>) as well, see
+
+ http://www.ilyaz.org/software/os2/
=back
-=head2 Starting Perl programs under OS/2
+=head2 Starting Perl programs under OS/2 (and DOS and...)
Start your Perl program F<foo.pl> with arguments C<arg1 arg2 arg3> the
same way as on any other platform, by
perl foo.pl arg1 arg2 arg3
If you want to specify perl options C<-my_opts> to the perl itself (as
-opposed to to your program), use
+opposed to your program), use
perl -my_opts foo.pl arg1 arg2 arg3
-Alternately, if you use OS/2-ish shell, like C<CMD> or C<4os2>, put
+Alternately, if you use OS/2-ish shell, like CMD or 4os2, put
the following at the start of your perl script:
- extproc perl -x -S
- #!/usr/bin/perl -my_opts
+ extproc perl -S -my_opts
rename your program to F<foo.cmd>, and start it by typing
foo arg1 arg2 arg3
-(Note that having *nixish full path to perl F</usr/bin/perl> is not
-necessary, F<perl> would be enough, but having full path would make it
-easier to use your script under *nix.)
-
Note that because of stupid OS/2 limitations the full path of the perl
script is not available when you use C<extproc>, thus you are forced to
-use C<-S> perl switch, and your script should be on path. As a plus
+use C<-S> perl switch, and your script should be on the C<PATH>. As a plus
side, if you know a full path to your script, you may still start it
with
- perl -x ../../blah/foo.cmd arg1 arg2 arg3
+ perl ../../blah/foo.cmd arg1 arg2 arg3
-(note that the argument C<-my_opts> is taken care of by the C<#!> line
-in your script).
+(note that the argument C<-my_opts> is taken care of by the C<extproc> line
+in your script, see L<C<extproc> on the first line>).
To understand what the above I<magic> does, read perl docs about C<-S>
-and C<-x> switches - see L<perlrun>, and cmdref about C<extproc>:
+switch - see L<perlrun>, and cmdref about C<extproc>:
view perl perlrun
man perlrun
or whatever method you prefer.
There are also endless possibilities to use I<executable extensions> of
-B<4OS2>, I<associations> of B<WPS> and so on... However, if you use
+4os2, I<associations> of WPS and so on... However, if you use
*nixish shell (like F<sh.exe> supplied in the binary distribution),
you need to follow the syntax specified in L<perlrun/"Switches">.
-=head2 Starting OS/2 programs under Perl
+Note that B<-S> switch supports scripts with additional extensions
+F<.cmd>, F<.btm>, F<.bat>, F<.pl> as well.
+
+=head2 Starting OS/2 (and DOS) programs under Perl
This is what system() (see L<perlfunc/system>), C<``> (see
L<perlop/"I/O Operators">), and I<open pipe> (see L<perlfunc/open>)
do).
Note however that to use some of these operators you need to have a
-C<sh>-syntax shell installed (see L<"Pdksh">,
+sh-syntax shell installed (see L<"Pdksh">,
L<"Frequently asked questions">), and perl should be able to find it
(see L<"PERL_SH_DIR">).
-The only cases when the shell is not used is the multi-argument
-system() (see L<perlfunc/system>)/exec() (see L<perlfunc/exec>), and
-one-argument version thereof without redirection and shell
-meta-characters.
+The cases when the shell is used are:
+
+=over
+
+=item 1
+
+One-argument system() (see L<perlfunc/system>), exec() (see L<perlfunc/exec>)
+with redirection or shell meta-characters;
+
+=item 2
+
+Pipe-open (see L<perlfunc/open>) with the command which contains redirection
+or shell meta-characters;
+
+=item 3
+
+Backticks C<``> (see L<perlop/"I/O Operators">) with the command which contains
+redirection or shell meta-characters;
+
+=item 4
+
+If the executable called by system()/exec()/pipe-open()/C<``> is a script
+with the "magic" C<#!> line or C<extproc> line which specifies shell;
+
+=item 5
+
+If the executable called by system()/exec()/pipe-open()/C<``> is a script
+without "magic" line, and C<$ENV{EXECSHELL}> is set to shell;
+
+=item 6
+
+If the executable called by system()/exec()/pipe-open()/C<``> is not
+found (is not this remark obsolete?);
+
+=item 7
+
+For globbing (see L<perlfunc/glob>, L<perlop/"I/O Operators">)
+(obsolete? Perl uses builtin globbing nowadays...).
+
+=back
+
+For the sake of speed for a common case, in the above algorithms
+backslashes in the command name are not considered as shell metacharacters.
+
+Perl starts scripts which begin with cookies
+C<extproc> or C<#!> directly, without an intervention of shell. Perl uses the
+same algorithm to find the executable as F<pdksh>: if the path
+on C<#!> line does not work, and contains C</>, then the directory
+part of the executable is ignored, and the executable
+is searched in F<.> and on C<PATH>. To find arguments for these scripts
+Perl uses a different algorithm than F<pdksh>: up to 3 arguments are
+recognized, and trailing whitespace is stripped.
+
+If a script
+does not contain such a cooky, then to avoid calling F<sh.exe>, Perl uses
+the same algorithm as F<pdksh>: if C<$ENV{EXECSHELL}> is set, the
+script is given as the first argument to this command, if not set, then
+C<$ENV{COMSPEC} /c> is used (or a hardwired guess if C<$ENV{COMSPEC}> is
+not set).
+
+When starting scripts directly, Perl uses exactly the same algorithm as for
+the search of script given by B<-S> command-line option: it will look in
+the current directory, then on components of C<$ENV{PATH}> using the
+following order of appended extensions: no extension, F<.cmd>, F<.btm>,
+F<.bat>, F<.pl>.
+
+Note that Perl will start to look for scripts only if OS/2 cannot start the
+specified application, thus C<system 'blah'> will not look for a script if
+there is an executable file F<blah.exe> I<anywhere> on C<PATH>. In
+other words, C<PATH> is essentially searched twice: once by the OS for
+an executable, then by Perl for scripts.
+
+Note also that executable files on OS/2 can have an arbitrary extension,
+but F<.exe> will be automatically appended if no dot is present in the name.
+The workaround is as simple as that: since F<blah.> and F<blah> denote the
+same file (at list on FAT and HPFS file systems), to start an executable residing in file F<n:/bin/blah> (no
+extension) give an argument C<n:/bin/blah.> (dot appended) to system().
+
+Perl will start PM programs from VIO (=text-mode) Perl process in a
+separate PM session;
+the opposite is not true: when you start a non-PM program from a PM
+Perl process, Perl would not run it in a separate session. If a separate
+session is desired, either ensure
+that shell will be used, as in C<system 'cmd /c myprog'>, or start it using
+optional arguments to system() documented in C<OS2::Process> module. This
+is considered to be a feature.
=head1 Frequently asked questions
+=head2 "It does not work"
+
+Perl binary distributions come with a F<testperl.cmd> script which tries
+to detect common problems with misconfigured installations. There is a
+pretty large chance it will discover which step of the installation you
+managed to goof. C<;-)>
+
=head2 I cannot run external programs
=over 4
-=item
+=item *
Did you run your programs with C<-w> switch? See
-L<Starting OS/2 programs under Perl>.
+L<Starting OS/2 (and DOS) programs under Perl>.
-=item
+=item *
Do you try to run I<internal> shell commands, like C<`copy a b`>
(internal for F<cmd.exe>), or C<`glob a*b`> (internal for ksh)? You
=over 4
-=item Is your program B<EMX>-compiled with C<-Zmt -Zcrtdll>?
+=item Is your program EMX-compiled with C<-Zmt -Zcrtdll>?
+
+Well, nowadays Perl DLL should be usable from a differently compiled
+program too... If you can run Perl code from REXX scripts (see
+L<OS2::REXX>), then there are some other aspect of interaction which
+are overlooked by the current hackish code to support
+differently-compiled principal programs.
-If not, you need to build a stand-alone DLL for perl. Contact me, I
-did it once. Sockets would not work, as a lot of other stuff.
+If everything else fails, you need to build a stand-alone DLL for
+perl. Contact me, I did it once. Sockets would not work, as a lot of
+other stuff.
-=item Did you use C<ExtUtils::Embed>?
+=item Did you use L<ExtUtils::Embed>?
-I had reports it does not work. Somebody would need to fix it.
+Some time ago I had reports it does not work. Nowadays it is checked
+in the Perl test suite, so grep F<./t> subdirectory of the build tree
+(as well as F<*.t> files in the F<./lib> subdirectory) to find how it
+should be done "correctly".
=back
=head2 C<``> and pipe-C<open> do not work under DOS.
This may a variant of just L<"I cannot run external programs">, or a
-deeper problem. Basically: you I<need> B<RSX> (see L<"Prerequisites">)
+deeper problem. Basically: you I<need> RSX (see L<"Prerequisites">)
for these commands to work, and you may need a port of F<sh.exe> which
understands command arguments. One of such ports is listed in
-L<"Prerequisites"> under B<RSX>.
+L<"Prerequisites"> under RSX. Do not forget to set variable
+C<L<"PERL_SH_DIR">> as well.
+
+DPMI is required for RSX.
+
+=head2 Cannot start C<find.exe "pattern" file>
-C<DPMI> is required for B<RSX>.
+The whole idea of the "standard C API to start applications" is that
+the forms C<foo> and C<"foo"> of program arguments are completely
+interchangable. F<find> breaks this paradigm;
+
+ find "pattern" file
+ find pattern file
+
+are not equivalent; F<find> cannot be started directly using the above
+API. One needs a way to surround the doublequotes in some other
+quoting construction, necessarily having an extra non-Unixish shell in
+between.
+
+Use one of
+
+ system 'cmd', '/c', 'find "pattern" file';
+ `cmd /c 'find "pattern" file'`
+
+This would start F<find.exe> via F<cmd.exe> via C<sh.exe> via
+C<perl.exe>, but this is a price to pay if you want to use
+non-conforming program.
=head1 INSTALLATION
=head2 Automatic binary installation
-The most convenient way of installing perl is via perl installer
+The most convenient way of installing a binary distribution of perl is via perl installer
F<install.exe>. Just follow the instructions, and 99% of the
installation blues would go away.
Note however, that you need to have F<unzip.exe> on your path, and
-B<EMX> environment I<running>. The latter means that if you just
-installed B<EMX>, and made all the needed changes to F<Config.sys>,
-you may need to reboot in between. Check B<EMX> runtime by running
+EMX environment I<running>. The latter means that if you just
+installed EMX, and made all the needed changes to F<Config.sys>,
+you may need to reboot in between. Check EMX runtime by running
emxrev
-A folder is created on your desktop which contains some useful
-objects.
+Binary installer also creates a folder on your desktop with some useful
+objects. If you need to change some aspects of the work of the binary
+installer, feel free to edit the file F<Perl.pkg>. This may be useful
+e.g., if you need to run the installer many times and do not want to
+make many interactive changes in the GUI.
B<Things not taken care of by automatic binary installation:>
=item C<PERL_BADLANG>
may be needed if you change your codepage I<after> perl installation,
-and the new value is not supported by B<EMX>. See L<"PERL_BADLANG">.
+and the new value is not supported by EMX. See L<"PERL_BADLANG">.
=item C<PERL_BADFREE>
While most important values in this file I<are> updated by the binary
installer, some of them may need to be hand-edited. I know no such
-data, please keep me informed if you find one.
+data, please keep me informed if you find one. Moreover, manual
+changes to the installed version may need to be accompanied by an edit
+of this file.
=back
+B<NOTE>. Because of a typo the binary installer of 5.00305
+would install a variable C<PERL_SHPATH> into F<Config.sys>. Please
+remove this variable and put C<L<PERL_SH_DIR>> instead.
+
=head2 Manual binary installation
As of version 5.00305, OS/2 perl binary distribution comes split
into 11 components. Unfortunately, to enable configurable binary
-installation, the file paths in the C<zip> files are not absolute, but
+installation, the file paths in the zip files are not absolute, but
relative to some directory.
Note that the extraction with the stored paths is still necessary
-(default with C<unzip>, specify C<-d> to C<pkunzip>). However, you
+(default with unzip, specify C<-d> to pkunzip). However, you
need to know where to extract the files. You need also to manually
change entries in F<Config.sys> to reflect where did you put the
files. Note that if you have some primitive unzipper (like
unzipping. Upgrade to C<(w)unzip>.
Below is the sample of what to do to reproduce the configuration on my
-machine:
+machine. In F<VIEW.EXE> you can press C<Ctrl-Insert> now, and
+cut-and-paste from the resulting file - created in the directory you
+started F<VIEW.EXE> from.
+
+For each component, we mention environment variables related to each
+installation directory. Either choose directories to match your
+values of the variables, or create/append-to variables to take into
+account the directories.
=over 3
unzip perl_exc.zip *.exe *.ico -d f:/emx.add/bin
unzip perl_exc.zip *.dll -d f:/emx.add/dll
-(have the directories with C<*.exe> on C<PATH>, and C<*.dll> on
-C<LIBPATH>);
+(have the directories with C<*.exe> on PATH, and C<*.dll> on
+LIBPATH);
=item Perl_ VIO executable (statically linked)
unzip perl_aou.zip -d f:/emx.add/bin
-(have the directory on C<PATH>);
+(have the directory on PATH);
=item Executables for Perl utilities
unzip perl_utl.zip -d f:/emx.add/bin
-(have the directory on C<PATH>);
+(have the directory on PATH);
=item Main Perl library
unzip perl_mlb.zip -d f:/perllib/lib
-If this directory is preserved, you do not need to change
-anything. However, for perl to find it if it is changed, you need to
+If this directory is exactly the same as the prefix which was compiled
+into F<perl.exe>, you do not need to change
+anything. However, for perl to find the library if you use a different
+path, you need to
C<set PERLLIB_PREFIX> in F<Config.sys>, see L<"PERLLIB_PREFIX">.
=item Additional Perl modules
- unzip perl_ste.zip -d f:/perllib/lib/site_perl
+ unzip perl_ste.zip -d f:/perllib/lib/site_perl/5.11.0/
-If you do not change this directory, do nothing. Otherwise put this
+Same remark as above applies. Additionally, if this directory is not
+one of directories on @INC (and @INC is influenced by C<PERLLIB_PREFIX>), you
+need to put this
directory and subdirectory F<./os2> in C<PERLLIB> or C<PERL5LIB>
variable. Do not use C<PERL5LIB> unless you have it set already. See
-L<perl/"ENVIRONMENT">.
+L<perl/"ENVIRONMENT">.
+
+B<[Check whether this extraction directory is still applicable with
+the new directory structure layout!]>
=item Tools to compile Perl modules
unzip perl_blb.zip -d f:/perllib/lib
-If this directory is preserved, you do not need to change
-anything. However, for perl to find it if it is changed, you need to
-C<set PERLLIB_PREFIX> in F<Config.sys>, see L<"PERLLIB_PREFIX">.
+Same remark as for F<perl_ste.zip>.
=item Manpages for Perl and utilities
unzip perl_man.zip -d f:/perllib/man
This directory should better be on C<MANPATH>. You need to have a
-working C<man> to access these files.
+working F<man> to access these files.
=item Manpages for Perl modules
unzip perl_mam.zip -d f:/perllib/man
This directory should better be on C<MANPATH>. You need to have a
-working C<man> to access these files.
+working man to access these files.
=item Source for Perl documentation
unzip perl_pod.zip -d f:/perllib/lib
-This is used by by C<perldoc> program (see L<perldoc>), and may be used to
-generate B<HTML> documentation usable by WWW browsers, and
+This is used by the C<perldoc> program (see L<perldoc>), and may be used to
+generate HTML documentation usable by WWW browsers, and
documentation in zillions of other formats: C<info>, C<LaTeX>,
-C<Acrobat>, C<FrameMaker> and so on.
+C<Acrobat>, C<FrameMaker> and so on. [Use programs such as
+F<pod2latex> etc.]
-=item Perl manual in .INF format
+=item Perl manual in F<.INF> format
unzip perl_inf.zip -d d:/os2/book
Set C<PERL_SH_DIR> (see L<"PERL_SH_DIR">) if you move F<sh.exe> from
the above location.
-B<Note.> It may be possible to use some other C<sh>-compatible shell
-(I<not tested>).
+B<Note.> It may be possible to use some other sh-compatible shell (untested).
=back
The automatic and manual perl installation leave precompiled paths
inside perl executables. While these paths are overwriteable (see
-L<"PERLLIB_PREFIX">, L<"PERL_SH_DIR">), one may get better results by
+L<"PERLLIB_PREFIX">, L<"PERL_SH_DIR">), some people may prefer
binary editing of paths inside the executables/DLLs.
=head1 Accessing documentation
=head2 OS/2 F<.INF> file
-Most probably the most convenient form. View it as
+Most probably the most convenient form. Under OS/2 view it as
view perl
view perl perlfunc
view perl ExtUtils::MakeMaker
(currently the last two may hit a wrong location, but this may improve
-soon).
+soon). Under Win* see L<"SYNOPSIS">.
If you want to build the docs yourself, and have I<OS/2 toolkit>, run
=head2 Plain text
If you have perl documentation in the source form, perl utilities
-installed, and B<GNU> C<groff> installed, you may use
+installed, and GNU groff installed, you may use
perldoc perlfunc
perldoc less
=head2 Manpages
-If you have C<man> installed on your system, and you installed perl
+If you have F<man> installed on your system, and you installed perl
manpages, use something like this:
man perlfunc
set MANPATH=c:/man;f:/perllib/man
-=head2 B<HTML>
+for Perl manpages in C<f:/perllib/man/man1/> etc.
+
+=head2 HTML
If you have some WWW browser available, installed the Perl
documentation in the source form, and Perl utilities, you can build
-B<HTML> docs. Cd to directory with F<.pod> files, and do like this
+HTML docs. Cd to directory with F<.pod> files, and do like this
cd f:/perllib/lib/pod
pod2html
explore file:///f:/perllib/lib/pod/perl.html
-Alternatively you may be able to get these docs prebuilt from C<CPAN>.
+Alternatively you may be able to get these docs prebuilt from CPAN.
-=head2 B<GNU> C<info> files
+=head2 GNU C<info> files
-Users of C<Emacs> would appreciate it very much, especially with
-C<CPerl> mode loaded. You need to get latest C<pod2info> from C<CPAN>,
-or, alternately, prebuilt info pages.
+Users of Emacs would appreciate it very much, especially with
+C<CPerl> mode loaded. You need to get latest C<pod2texi> from C<CPAN>,
+or, alternately, the prebuilt info pages.
-=head2 F<.PDF> files
+=head2 F<PDF> files
-for C<Acrobat> are available on CPAN (for slightly old version of
+for C<Acrobat> are available on CPAN (may be for slightly older version of
perl).
=head2 C<LaTeX> docs
Here we discuss how to build Perl under OS/2. There is an alternative
(but maybe older) view on L<http://www.shadow.net/~troc/os2perl.html>.
+=head2 The short story
+
+Assume that you are a seasoned porter, so are sure that all the necessary
+tools are already present on your system, and you know how to get the Perl
+source distribution. Untar it, change to the extract directory, and
+
+ gnupatch -p0 < os2\diff.configure
+ sh Configure -des -D prefix=f:/perllib
+ make
+ make test
+ make install
+ make aout_test
+ make aout_install
+
+This puts the executables in f:/perllib/bin. Manually move them to the
+C<PATH>, manually move the built F<perl*.dll> to C<LIBPATH> (here for
+Perl DLL F<*> is a not-very-meaningful hex checksum), and run
+
+ make installcmd INSTALLCMDDIR=d:/ir/on/path
+
+Assuming that the C<man>-files were put on an appropriate location,
+this completes the installation of minimal Perl system. (The binary
+distribution contains also a lot of additional modules, and the
+documentation in INF format.)
+
+What follows is a detailed guide through these steps.
+
=head2 Prerequisites
-You need to have the latest B<EMX> development environment, the full
-B<GNU> tool suite (C<gawk> renamed to C<awk>, and B<GNU> F<find.exe>
+You need to have the latest EMX development environment, the full
+GNU tool suite (gawk renamed to awk, and GNU F<find.exe>
earlier on path than the OS/2 F<find.exe>, same with F<sort.exe>, to
check use
). You need the latest version of F<pdksh> installed as F<sh.exe>.
-Possible locations to get this from are
+Check that you have B<BSD> libraries and headers installed, and -
+optionally - Berkeley DB headers and libraries, and crypt.
- ftp://hobbes.nmsu.edu/os2/unix/gnu/
+Possible locations to get the files:
+
+ ftp://hobbes.nmsu.edu/os2/unix/
ftp://ftp.cdrom.com/pub/os2/unix/
ftp://ftp.cdrom.com/pub/os2/dev32/
- ftp://ftp.cdrom.com/pub/os2/emx0.9c/
+ ftp://ftp.cdrom.com/pub/os2/emx09c/
+
+It is reported that the following archives contain enough utils to
+build perl: F<gnufutil.zip>, F<gnusutil.zip>, F<gnututil.zip>, F<gnused.zip>,
+F<gnupatch.zip>, F<gnuawk.zip>, F<gnumake.zip>, F<gnugrep.zip>, F<bsddev.zip> and
+F<ksh527rt.zip> (or a later version). Note that all these utilities are
+known to be available from LEO:
+
+ ftp://ftp.leo.org/pub/comp/os/os2/leo/gnu
+
+Note also that the F<db.lib> and F<db.a> from the EMX distribution
+are not suitable for multi-threaded compile (even single-threaded
+flavor of Perl uses multi-threaded C RTL, for
+compatibility with XFree86-OS/2). Get a corrected one from
+ http://www.ilyaz.org/software/os2/db_mt.zip
-Make sure that no copies or perl are currently running. Later steps
-of the build may fail since an older version of perl.dll loaded into
-memory may be found.
+If you have I<exactly the same version of Perl> installed already,
+make sure that no copies or perl are currently running. Later steps
+of the build may fail since an older version of F<perl.dll> loaded into
+memory may be found. Running C<make test> becomes meaningless, since
+the test are checking a previous build of perl (this situation is detected
+and reported by F<lib/os2_base.t> test). Do not forget to unset
+C<PERL_EMXLOAD_SEC> in environment.
Also make sure that you have F</tmp> directory on the current drive,
and F<.> directory in your C<LIBPATH>. One may try to correct the
latter condition by
- set BEGINLIBPATH .
+ set BEGINLIBPATH .\.
-if you use something like F<CMD.EXE> or latest versions of F<4os2.exe>.
+if you use something like F<CMD.EXE> or latest versions of
+F<4os2.exe>. (Setting BEGINLIBPATH to just C<.> is ignored by the
+OS/2 kernel.)
-Make sure your C<gcc> is good for C<-Zomf> linking: run C<omflibs>
+Make sure your gcc is good for C<-Zomf> linking: run C<omflibs>
script in F</emx/lib> directory.
-Check that you have C<link386> installed. It comes standard with OS/2,
+Check that you have link386 installed. It comes standard with OS/2,
but may be not installed due to customization. If typing
link386
shows you do not have it, do I<Selective install>, and choose C<Link
object modules> in I<Optional system utilities/More>. If you get into
-C<link386>, press C<Ctrl-C>.
+link386 prompts, press C<Ctrl-C> to exit.
=head2 Getting perl source
You need to fetch the latest perl source (including developers
releases). With some probability it is located in
- http://www.perl.com/CPAN/src/5.0
- http://www.perl.com/CPAN/src/5.0/unsupported
+ http://www.cpan.org/src/5.0
+ http://www.cpan.org/src/5.0/unsupported
If not, you may need to dig in the indices to find it in the directory
of the current maintainer.
Quick cycle of developers release may break the OS/2 build time to
time, looking into
- http://www.perl.com/CPAN/ports/os2/ilyaz/
+ http://www.cpan.org/ports/os2/
may indicate the latest release which was publicly released by the
maintainer. Note that the release may include some additional patches
You may see a message about errors while extracting F<Configure>. This is
because there is a conflict with a similarly-named file F<configure>.
-Rename F<configure> to F<configure.gnu>. Extract F<Configure> like this
-
- tar --case-sensitive -vzxf perl5.00409.tar.gz perl5.00409/Configure
-
Change to the directory of extraction.
=head2 Application of the patches
-You need to apply the patches in F<./os2/diff.*> and
-F<./os2/POSIX.mkfifo> like this:
+You need to apply the patches in F<./os2/diff.*> like this:
- gnupatch -p0 < os2\POSIX.mkfifo
- gnupatch -p0 < os2\os2\diff.configure
+ gnupatch -p0 < os2\diff.configure
You may also need to apply the patches supplied with the binary
-distribution of perl.
-
-Note also that the F<db.lib> and F<db.a> from the B<EMX> distribution
-are not suitable for multi-threaded compile (note that currently perl
-is not multithreaded, but is compiled as multithreaded for
-compatibility with B<XFree86>-OS/2). Get a corrected one from
-
- ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/db_mt.zip
+distribution of perl. It also makes sense to look on the
+perl5-porters mailing list for the latest OS/2-related patches (see
+L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/>). Such
+patches usually contain strings C</os2/> and C<patch>, so it makes
+sense looking for these strings.
=head2 Hand-editing
sh Configure -des -D prefix=f:/perllib
-Prefix means where to install the resulting perl library. Giving
+C<prefix> means: where to install the resulting perl library. Giving
correct prefix you may avoid the need to specify C<PERLLIB_PREFIX>,
see L<"PERLLIB_PREFIX">.
I<Ignore the message about missing C<ln>, and about C<-c> option to
-C<tr>>. In fact if you can trace where the latter spurious warning
-comes from, please inform me.
+tr>. The latter is most probably already fixed, if you see it and can trace
+where the latter spurious warning comes from, please inform me.
Now
make
At some moment the built may die, reporting a I<version mismatch> or
-I<unable to run F<perl>>. This means that most of the build has been
-finished, and it is the time to move the constructed F<perl.dll> to
-some I<absolute> location in C<LIBPATH>. After this done the build
-should finish without a lot of fuss. I<One can avoid it if one has the
-correct prebuilt version of F<perl.dll> on C<LIBPATH>.>
-
-Warnings which are safe to ignore: I<mkfifo() redefined> inside
-F<POSIX.c>.
+I<unable to run F<perl>>. This means that you do not have F<.> in
+your LIBPATH, so F<perl.exe> cannot find the needed F<perl67B2.dll> (treat
+these hex digits as line noise). After this is fixed the build
+should finish without a lot of fuss.
=head2 Testing
make test
-Some tests (4..6) should fail. Some perl invocations should end in a
-segfault (system error C<SYS3175>). To get finer error reports,
+All tests should succeed (with some of them skipped). If you have the
+same version of Perl installed, it is crucial that you have C<.> early
+in your LIBPATH (or in BEGINLIBPATH), otherwise your tests will most
+probably test the wrong version of Perl.
- cd t
- perl -I ../lib harness
+Some tests may generate extra messages similar to
-The report you get may look like
+=over 4
- Failed Test Status Wstat Total Fail Failed List of failed
- ---------------------------------------------------------------
- io/fs.t 26 11 42.31% 2-5, 7-11, 18, 25
- lib/io_pipe.t 3 768 6 ?? % ??
- lib/io_sock.t 3 768 5 ?? % ??
- op/stat.t 56 5 8.93% 3-4, 20, 35, 39
- Failed 4/140 test scripts, 97.14% okay. 27/2937 subtests failed, 99.08% okay.
+=item A lot of C<bad free>
-Note that using `make test' target two more tests may fail: C<op/exec:1>
-because of (mis)feature of C<pdksh>, and C<lib/posix:15>, which checks
-that the buffers are not flushed on C<_exit> (this is a bug in the test
-which assumes that tty output is buffered).
+in database tests related to Berkeley DB. I<This should be fixed already.>
+If it persists, you may disable this warnings, see L<"PERL_BADFREE">.
-I submitted a patch to B<EMX> which makes it possible to fork() with EMX
-dynamic libraries loaded, which makes F<lib/io*> tests pass. This means
-that soon the number of failing tests may decrease yet more.
+=item Process terminated by SIGTERM/SIGINT
-However, the test F<lib/io_udp.t> is disabled, since it never ends, I
-do not know why.
+This is a standard message issued by OS/2 applications. *nix
+applications die in silence. It is considered to be a feature. One can
+easily disable this by appropriate sighandlers.
-The reasons for failed tests are:
+However the test engine bleeds these message to screen in unexpected
+moments. Two messages of this kind I<should> be present during
+testing.
-=over 8
+=back
+
+To get finer test reports, call
-=item F<io/fs.t>
+ perl t/harness
-Checks I<file system> operations. Tests:
+The report with F<io/pipe.t> failing may look like this:
-=over 10
+ Failed Test Status Wstat Total Fail Failed List of failed
+ ------------------------------------------------------------
+ io/pipe.t 12 1 8.33% 9
+ 7 tests skipped, plus 56 subtests skipped.
+ Failed 1/195 test scripts, 99.49% okay. 1/6542 subtests failed, 99.98% okay.
+
+The reasons for most important skipped tests are:
-=item 2-5, 7-11
+=over 8
-Check C<link()> and C<inode count> - nonesuch under OS/2.
+=item F<op/fs.t>
+
+=over 4
=item 18
-Checks C<atime> and C<mtime> of C<stat()> - I could not understand this test.
+Checks C<atime> and C<mtime> of C<stat()> - unfortunately, HPFS
+provides only 2sec time granularity (for compatibility with FAT?).
=item 25
=back
-=item F<lib/io_pipe.t>
+=item F<op/stat.t>
-Checks C<IO::Pipe> module. Some feature of B<EMX> - test fork()s with
-dynamic extension loaded - unsupported now.
+Checks C<stat()>. Tests:
-=item F<lib/io_sock.t>
+=over 4
-Checks C<IO::Socket> module. Some feature of B<EMX> - test fork()s
-with dynamic extension loaded - unsupported now.
+=item 4
-=item F<op/stat.t>
+Checks C<atime> and C<mtime> of C<stat()> - unfortunately, HPFS
+provides only 2sec time granularity (for compatibility with FAT?).
-Checks C<stat()>. Tests:
+=back
-=over 4
+=back
-=item 3
+=head2 Installing the built perl
-Checks C<inode count> - nonesuch under OS/2.
+If you haven't yet moved C<perl*.dll> onto LIBPATH, do it now.
-=item 4
+Run
-Checks C<mtime> and C<ctime> of C<stat()> - I could not understand this test.
+ make install
-=item 20
+It would put the generated files into needed locations. Manually put
+F<perl.exe>, F<perl__.exe> and F<perl___.exe> to a location on your
+PATH, F<perl.dll> to a location on your LIBPATH.
-Checks C<-x> - determined by the file extension only under OS/2.
+Run
-=item 35
+ make installcmd INSTALLCMDDIR=d:/ir/on/path
-Needs F</usr/bin>.
+to convert perl utilities to F<.cmd> files and put them on
+PATH. You need to put F<.EXE>-utilities on path manually. They are
+installed in C<$prefix/bin>, here C<$prefix> is what you gave to
+F<Configure>, see L<Making>.
-=item 39
+If you use C<man>, either move the installed F<*/man/> directories to
+your C<MANPATH>, or modify C<MANPATH> to match the location. (One
+could have avoided this by providing a correct C<manpath> option to
+F<./Configure>, or editing F<./config.sh> between configuring and
+making steps.)
-Checks C<-t> of F</dev/null>. Should not fail!
+=head2 C<a.out>-style build
-=back
+Proceed as above, but make F<perl_.exe> (see L<"perl_.exe">) by
-=back
+ make perl_
-In addition to errors, you should get a lot of warnings.
+test and install by
-=over 4
+ make aout_test
+ make aout_install
-=item A lot of `bad free'
+Manually put F<perl_.exe> to a location on your PATH.
-in databases related to Berkeley DB. This is a confirmed bug of
-DB. You may disable this warnings, see L<"PERL_BADFREE">.
+B<Note.> The build process for C<perl_> I<does not know> about all the
+dependencies, so you should make sure that anything is up-to-date,
+say, by doing
-=item Process terminated by SIGTERM/SIGINT
+ make perl_dll
-This is a standard message issued by OS/2 applications. *nix
-applications die in silence. It is considered a feature. One can
-easily disable this by appropriate sighandlers.
+first.
-However the test engine bleeds these message to screen in unexpected
-moments. Two messages of this kind I<should> be present during
-testing.
+=head1 Building a binary distribution
-=item F<*/sh.exe>: ln: not found
+[This section provides a short overview only...]
-=item C<ls>: /dev: No such file or directory
+Building should proceed differently depending on whether the version of perl
+you install is already present and used on your system, or is a new version
+not yet used. The description below assumes that the version is new, so
+installing its DLLs and F<.pm> files will not disrupt the operation of your
+system even if some intermediate steps are not yet fully working.
-The last two should be self-explanatory. The test suite discovers that
-the system it runs on is not I<that much> *nixish.
+The other cases require a little bit more convoluted procedures. Below I
+suppose that the current version of Perl is C<5.8.2>, so the executables are
+named accordingly.
-=back
+=over
-A lot of `bad free'... in databases, bug in DB confirmed on other
-platforms. You may disable it by setting PERL_BADFREE environment variable
-to 1.
+=item 1.
-=head2 Installing the built perl
+Fully build and test the Perl distribution. Make sure that no tests are
+failing with C<test> and C<aout_test> targets; fix the bugs in Perl and
+the Perl test suite detected by these tests. Make sure that C<all_test>
+make target runs as clean as possible. Check that C<os2/perlrexx.cmd>
+runs fine.
-Run
+=item 2.
+
+Fully install Perl, including C<installcmd> target. Copy the generated DLLs
+to C<LIBPATH>; copy the numbered Perl executables (as in F<perl5.8.2.exe>)
+to C<PATH>; copy C<perl_.exe> to C<PATH> as C<perl_5.8.2.exe>. Think whether
+you need backward-compatibility DLLs. In most cases you do not need to install
+them yet; but sometime this may simplify the following steps.
+
+=item 3.
+
+Make sure that C<CPAN.pm> can download files from CPAN. If not, you may need
+to manually install C<Net::FTP>.
+
+=item 4.
+
+Install the bundle C<Bundle::OS2_default>
+
+ perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_1
+
+This may take a couple of hours on 1GHz processor (when run the first time).
+And this should not be necessarily a smooth procedure. Some modules may not
+specify required dependencies, so one may need to repeat this procedure several
+times until the results stabilize.
+
+ perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_2
+ perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_3
+
+Even after they stabilize, some tests may fail.
+
+Fix as many discovered bugs as possible. Document all the bugs which are not
+fixed, and all the failures with unknown reasons. Inspect the produced logs
+F<00cpan_i_1> to find suspiciously skipped tests, and other fishy events.
+Keep in mind that I<installation> of some modules may fail too: for example,
+the DLLs to update may be already loaded by F<CPAN.pm>. Inspect the C<install>
+logs (in the example above F<00cpan_i_1> etc) for errors, and install things
+manually, as in
+
+ cd $CPANHOME/.cpan/build/Digest-MD5-2.31
make install
-It would put the generated files into needed locations. Manually put
-F<perl.exe>, F<perl__.exe> and F<perl___.exe> to a location on your
-C<PATH>, F<perl.dll> to a location on your C<LIBPATH>.
+Some distributions may fail some tests, but you may want to install them
+anyway (as above, or via C<force install> command of C<CPAN.pm> shell-mode).
-Run
+Since this procedure may take quite a long time to complete, it makes sense
+to "freeze" your CPAN configuration by disabling periodic updates of the
+local copy of CPAN index: set C<index_expire> to some big value (I use 365),
+then save the settings
- make cmdscripts INSTALLCMDDIR=d:/ir/on/path
+ CPAN> o conf index_expire 365
+ CPAN> o conf commit
-to convert perl utilities to F<.cmd> files and put them on
-C<PATH>. You need to put F<.EXE>-utilities on path manually. They are
-installed in C<$prefix/bin>, here C<$prefix> is what you gave to
-F<Configure>, see L<Making>.
+Reset back to the default value C<1> when you are finished.
-=head2 C<a.out>-style build
+=item 5.
-Proceed as above, but make F<perl_.exe> (see L<"perl_.exe">) by
+When satisfied with the results, rerun the C<installcmd> target. Now you
+can copy C<perl5.8.2.exe> to C<perl.exe>, and install the other OMF-build
+executables: C<perl__.exe> etc. They are ready to be used.
- make perl_
+=item 6.
-test and install by
+Change to the C<./pod> directory of the build tree, download the Perl logo
+F<CamelGrayBig.BMP>, and run
- make aout_test
- make aout_install
+ ( perl2ipf > perl.ipf ) |& tee 00ipf
+ ipfc /INF perl.ipf |& tee 00inf
-Manually put F<perl_.exe> to a location on your C<PATH>.
+This produces the Perl docs online book C<perl.INF>. Install in on
+C<BOOKSHELF> path.
-Since C<perl_> has the extensions prebuilt, it does not suffer from
-the I<dynamic extensions + fork()> syndrome, thus the failing tests
-look like
+=item 7.
- Failed Test Status Wstat Total Fail Failed List of failed
- ---------------------------------------------------------------
- io/fs.t 26 11 42.31% 2-5, 7-11, 18, 25
- op/stat.t 56 5 8.93% 3-4, 20, 35, 39
- Failed 2/118 test scripts, 98.31% okay. 16/2445 subtests failed, 99.35% okay.
+Now is the time to build statically linked executable F<perl_.exe> which
+includes newly-installed via C<Bundle::OS2_default> modules. Doing testing
+via C<CPAN.pm> is going to be painfully slow, since it statically links
+a new executable per XS extension.
-B<Note.> The build process for C<perl_> I<does not know> about all the
-dependencies, so you should make sure that anything is up-to-date,
-say, by doing
+Here is a possible workaround: create a toplevel F<Makefile.PL> in
+F<$CPANHOME/.cpan/build/> with contents being (compare with L<Making
+executables with a custom collection of statically loaded extensions>)
- make perl.dll
+ use ExtUtils::MakeMaker;
+ WriteMakefile NAME => 'dummy';
+
+execute this as
+
+ perl_5.8.2.exe Makefile.PL <nul |& tee 00aout_c1
+ make -k all test <nul |& 00aout_t1
+
+Again, this procedure should not be absolutely smooth. Some C<Makefile.PL>'s
+in subdirectories may be buggy, and would not run as "child" scripts. The
+interdependency of modules can strike you; however, since non-XS modules
+are already installed, the prerequisites of most modules have a very good
+chance to be present.
+
+If you discover some glitches, move directories of problematic modules to a
+different location; if these modules are non-XS modules, you may just ignore
+them - they are already installed; the remaining, XS, modules you need to
+install manually one by one.
+
+After each such removal you need to rerun the C<Makefile.PL>/C<make> process;
+usually this procedure converges soon. (But be sure to convert all the
+necessary external C libraries from F<.lib> format to F<.a> format: run one of
+
+ emxaout foo.lib
+ emximp -o foo.a foo.lib
+
+whichever is appropriate.) Also, make sure that the DLLs for external
+libraries are usable with with executables compiled without C<-Zmtd> options.
+
+When you are sure that only a few subdirectories
+lead to failures, you may want to add C<-j4> option to C<make> to speed up
+skipping subdirectories with already finished build.
+
+When you are satisfied with the results of tests, install the build C libraries
+for extensions:
+
+ make install |& tee 00aout_i
+
+Now you can rename the file F<./perl.exe> generated during the last phase
+to F<perl_5.8.2.exe>; place it on C<PATH>; if there is an inter-dependency
+between some XS modules, you may need to repeat the C<test>/C<install> loop
+with this new executable and some excluded modules - until the procedure
+converges.
+
+Now you have all the necessary F<.a> libraries for these Perl modules in the
+places where Perl builder can find it. Use the perl builder: change to an
+empty directory, create a "dummy" F<Makefile.PL> again, and run
+
+ perl_5.8.2.exe Makefile.PL |& tee 00c
+ make perl |& tee 00p
+
+This should create an executable F<./perl.exe> with all the statically loaded
+extensions built in. Compare the generated F<perlmain.c> files to make sure
+that during the iterations the number of loaded extensions only increases.
+Rename F<./perl.exe> to F<perl_5.8.2.exe> on C<PATH>.
+
+When it converges, you got a functional variant of F<perl_5.8.2.exe>; copy it
+to C<perl_.exe>. You are done with generation of the local Perl installation.
+
+=item 8.
+
+Make sure that the installed modules are actually installed in the location
+of the new Perl, and are not inherited from entries of @INC given for
+inheritance from the older versions of Perl: set C<PERLLIB_582_PREFIX> to
+redirect the new version of Perl to a new location, and copy the installed
+files to this new location. Redo the tests to make sure that the versions of
+modules inherited from older versions of Perl are not needed.
+
+Actually, the log output of L<pod2ipf> during the step 6 gives a very detailed
+info about which modules are loaded from which place; so you may use it as
+an additional verification tool.
+
+Check that some temporary files did not make into the perl install tree.
+Run something like this
+
+ pfind . -f "!(/\.(pm|pl|ix|al|h|a|lib|txt|pod|imp|bs|dll|ld|bs|inc|xbm|yml|cgi|uu|e2x|skip|packlist|eg|cfg|html|pub|enc|all|ini|po|pot)$/i or /^\w+$/") | less
+
+in the install tree (both top one and F<sitelib> one).
+
+Compress all the DLLs with F<lxlite>. The tiny F<.exe> can be compressed with
+C</c:max> (the bug only appears when there is a fixup in the last 6 bytes of a
+page (?); since the tiny executables are much smaller than a page, the bug
+will not hit). Do not compress C<perl_.exe> - it would not work under DOS.
+
+=item 9.
+
+Now you can generate the binary distribution. This is done by running the
+test of the CPAN distribution C<OS2::SoftInstaller>. Tune up the file
+F<test.pl> to suit the layout of current version of Perl first. Do not
+forget to pack the necessary external DLLs accordingly. Include the
+description of the bugs and test suite failures you could not fix. Include
+the small-stack versions of Perl executables from Perl build directory.
+
+Include F<perl5.def> so that people can relink the perl DLL preserving
+the binary compatibility, or can create compatibility DLLs. Include the diff
+files (C<diff -pu old new>) of fixes you did so that people can rebuild your
+version. Include F<perl5.map> so that one can use remote debugging.
+
+=item 10.
+
+Share what you did with the other people. Relax. Enjoy fruits of your work.
+
+=item 11.
+
+Brace yourself for thanks, bug reports, hate mail and spam coming as result
+of the previous step. No good deed should remain unpunished!
+
+=back
+
+=head1 Building custom F<.EXE> files
+
+The Perl executables can be easily rebuilt at any moment. Moreover, one can
+use the I<embedding> interface (see L<perlembed>) to make very customized
+executables.
+
+=head2 Making executables with a custom collection of statically loaded extensions
+
+It is a little bit easier to do so while I<decreasing> the list of statically
+loaded extensions. We discuss this case only here.
+
+=over
+
+=item 1.
+
+Change to an empty directory, and create a placeholder <Makefile.PL>:
+
+ use ExtUtils::MakeMaker;
+ WriteMakefile NAME => 'dummy';
+
+=item 2.
+
+Run it with the flavor of Perl (F<perl.exe> or F<perl_.exe>) you want to
+rebuild.
+
+ perl_ Makefile.PL
+
+=item 3.
+
+Ask it to create new Perl executable:
+
+ make perl
+
+(you may need to manually add C<PERLTYPE=-DPERL_CORE> to this commandline on
+some versions of Perl; the symptom is that the command-line globbing does not
+work from OS/2 shells with the newly-compiled executable; check with
+
+ .\perl.exe -wle "print for @ARGV" *
+
+).
+
+=item 4.
+
+The previous step created F<perlmain.c> which contains a list of newXS() calls
+near the end. Removing unnecessary calls, and rerunning
+
+ make perl
+
+will produce a customized executable.
+
+=back
+
+=head2 Making executables with a custom search-paths
+
+The default perl executable is flexible enough to support most usages.
+However, one may want something yet more flexible; for example, one may want
+to find Perl DLL relatively to the location of the EXE file; or one may want
+to ignore the environment when setting the Perl-library search patch, etc.
+
+If you fill comfortable with I<embedding> interface (see L<perlembed>), such
+things are easy to do repeating the steps outlined in L<Making
+executables with a custom collection of statically loaded extensions>, and
+doing more comprehensive edits to main() of F<perlmain.c>. The people with
+little desire to understand Perl can just rename main(), and do necessary
+modification in a custom main() which calls the renamed function in appropriate
+time.
+
+However, there is a third way: perl DLL exports the main() function and several
+callbacks to customize the search path. Below is a complete example of a
+"Perl loader" which
+
+=over
+
+=item 1.
+
+Looks for Perl DLL in the directory C<$exedir/../dll>;
+
+=item 2.
+
+Prepends the above directory to C<BEGINLIBPATH>;
+
+=item 3.
+
+Fails if the Perl DLL found via C<BEGINLIBPATH> is different from what was
+loaded on step 1; e.g., another process could have loaded it from C<LIBPATH>
+or from a different value of C<BEGINLIBPATH>. In these cases one needs to
+modify the setting of the system so that this other process either does not
+run, or loads the DLL from C<BEGINLIBPATH> with C<LIBPATHSTRICT=T> (available
+with kernels after September 2000).
+
+=item 4.
+
+Loads Perl library from C<$exedir/../dll/lib/>.
+
+=item 5.
+
+Uses Bourne shell from C<$exedir/../dll/sh/ksh.exe>.
+
+=back
+
+For best results compile the C file below with the same options as the Perl
+DLL. However, a lot of functionality will work even if the executable is not
+an EMX applications, e.g., if compiled with
+
+ gcc -Wall -DDOSISH -DOS2=1 -O2 -s -Zomf -Zsys perl-starter.c -DPERL_DLL_BASENAME=\"perl312F\" -Zstack 8192 -Zlinker /PM:VIO
+
+Here is the sample C file:
+
+ #define INCL_DOS
+ #define INCL_NOPM
+ /* These are needed for compile if os2.h includes os2tk.h, not os2emx.h */
+ #define INCL_DOSPROCESS
+ #include <os2.h>
+
+ #include "EXTERN.h"
+ #define PERL_IN_MINIPERLMAIN_C
+ #include "perl.h"
+
+ static char *me;
+ HMODULE handle;
+
+ static void
+ die_with(char *msg1, char *msg2, char *msg3, char *msg4)
+ {
+ ULONG c;
+ char *s = " error: ";
+
+ DosWrite(2, me, strlen(me), &c);
+ DosWrite(2, s, strlen(s), &c);
+ DosWrite(2, msg1, strlen(msg1), &c);
+ DosWrite(2, msg2, strlen(msg2), &c);
+ DosWrite(2, msg3, strlen(msg3), &c);
+ DosWrite(2, msg4, strlen(msg4), &c);
+ DosWrite(2, "\r\n", 2, &c);
+ exit(255);
+ }
+
+ typedef ULONG (*fill_extLibpath_t)(int type, char *pre, char *post, int replace, char *msg);
+ typedef int (*main_t)(int type, char *argv[], char *env[]);
+ typedef int (*handler_t)(void* data, int which);
+
+ #ifndef PERL_DLL_BASENAME
+ # define PERL_DLL_BASENAME "perl"
+ #endif
+
+ static HMODULE
+ load_perl_dll(char *basename)
+ {
+ char buf[300], fail[260];
+ STRLEN l, dirl;
+ fill_extLibpath_t f;
+ ULONG rc_fullname;
+ HMODULE handle, handle1;
+
+ if (_execname(buf, sizeof(buf) - 13) != 0)
+ die_with("Can't find full path: ", strerror(errno), "", "");
+ /* XXXX Fill `me' with new value */
+ l = strlen(buf);
+ while (l && buf[l-1] != '/' && buf[l-1] != '\\')
+ l--;
+ dirl = l - 1;
+ strcpy(buf + l, basename);
+ l += strlen(basename);
+ strcpy(buf + l, ".dll");
+ if ( (rc_fullname = DosLoadModule(fail, sizeof fail, buf, &handle)) != 0
+ && DosLoadModule(fail, sizeof fail, basename, &handle) != 0 )
+ die_with("Can't load DLL ", buf, "", "");
+ if (rc_fullname)
+ return handle; /* was loaded with short name; all is fine */
+ if (DosQueryProcAddr(handle, 0, "fill_extLibpath", (PFN*)&f))
+ die_with(buf, ": DLL exports no symbol ", "fill_extLibpath", "");
+ buf[dirl] = 0;
+ if (f(0 /*BEGINLIBPATH*/, buf /* prepend */, NULL /* append */,
+ 0 /* keep old value */, me))
+ die_with(me, ": prepending BEGINLIBPATH", "", "");
+ if (DosLoadModule(fail, sizeof fail, basename, &handle1) != 0)
+ die_with(me, ": finding perl DLL again via BEGINLIBPATH", "", "");
+ buf[dirl] = '\\';
+ if (handle1 != handle) {
+ if (DosQueryModuleName(handle1, sizeof(fail), fail))
+ strcpy(fail, "???");
+ die_with(buf, ":\n\tperl DLL via BEGINLIBPATH is different: \n\t",
+ fail,
+ "\n\tYou may need to manipulate global BEGINLIBPATH and LIBPATHSTRICT"
+ "\n\tso that the other copy is loaded via BEGINLIBPATH.");
+ }
+ return handle;
+ }
+
+ int
+ main(int argc, char **argv, char **env)
+ {
+ main_t f;
+ handler_t h;
+
+ me = argv[0];
+ /**/
+ handle = load_perl_dll(PERL_DLL_BASENAME);
+
+ if (DosQueryProcAddr(handle, 0, "Perl_OS2_handler_install", (PFN*)&h))
+ die_with(PERL_DLL_BASENAME, ": DLL exports no symbol ", "Perl_OS2_handler_install", "");
+ if ( !h((void *)"~installprefix", Perlos2_handler_perllib_from)
+ || !h((void *)"~dll", Perlos2_handler_perllib_to)
+ || !h((void *)"~dll/sh/ksh.exe", Perlos2_handler_perl_sh) )
+ die_with(PERL_DLL_BASENAME, ": Can't install @INC manglers", "", "");
+
+ if (DosQueryProcAddr(handle, 0, "dll_perlmain", (PFN*)&f))
+ die_with(PERL_DLL_BASENAME, ": DLL exports no symbol ", "dll_perlmain", "");
+ return f(argc, argv, env);
+ }
-first.
=head1 Build FAQ
You do not have MT-safe F<db.lib>. See L<Prerequisites>.
-=head2 Problems with C<tr>
+=head2 Problems with tr or sed
-reported with very old version of C<tr>.
+reported with very old version of tr and sed.
=head2 Some problem (forget which ;-)
-You have an older version of F<perl.dll> on your C<LIBPATH>, which
+You have an older version of F<perl.dll> on your LIBPATH, which
broke the build of extensions.
=head2 Library ... not found
=head2 Segfault in make
-You use an old version of C<GNU> make. See L<Prerequisites>.
+You use an old version of GNU make. See L<Prerequisites>.
+
+=head2 op/sprintf test failure
+
+This can result from a bug in emx sprintf which was fixed in 0.9d fix 03.
=head1 Specific (mis)features of OS/2 port
ports of '94 - 95. The priorities are absolute, go from 32 to -95,
lower is quicker. 0 is the default priority.
+B<WARNING>. Calling C<getpriority> on a non-existing process could lock
+the system before Warp3 fixpak22. Starting with Warp3, Perl will use
+a workaround: it aborts getpriority() if the process is not present.
+This is not possible on older versions C<2.*>, and has a race
+condition anyway.
+
=head2 C<system()>
Multi-argument form of C<system()> allows an additional numeric
argument. The meaning of this argument is described in
L<OS2::Process>.
+When finding a program to run, Perl first asks the OS to look for executables
+on C<PATH> (OS/2 adds extension F<.exe> if no extension is present).
+If not found, it looks for a script with possible extensions
+added in this order: no extension, F<.cmd>, F<.btm>,
+F<.bat>, F<.pl>. If found, Perl checks the start of the file for magic
+strings C<"#!"> and C<"extproc ">. If found, Perl uses the rest of the
+first line as the beginning of the command line to run this script. The
+only mangling done to the first line is extraction of arguments (currently
+up to 3), and ignoring of the path-part of the "interpreter" name if it can't
+be found using the full path.
+
+E.g., C<system 'foo', 'bar', 'baz'> may lead Perl to finding
+F<C:/emx/bin/foo.cmd> with the first line being
+
+ extproc /bin/bash -x -c
+
+If F</bin/bash.exe> is not found, then Perl looks for an executable F<bash.exe> on
+C<PATH>. If found in F<C:/emx.add/bin/bash.exe>, then the above system() is
+translated to
+
+ system qw(C:/emx.add/bin/bash.exe -x -c C:/emx/bin/foo.cmd bar baz)
+
+One additional translation is performed: instead of F</bin/sh> Perl uses
+the hardwired-or-customized shell (see C<L<"PERL_SH_DIR">>).
+
+The above search for "interpreter" is recursive: if F<bash> executable is not
+found, but F<bash.btm> is found, Perl will investigate its first line etc.
+The only hardwired limit on the recursion depth is implicit: there is a limit
+4 on the number of additional arguments inserted before the actual arguments
+given to system(). In particular, if no additional arguments are specified
+on the "magic" first lines, then the limit on the depth is 4.
+
+If Perl finds that the found executable is of PM type when the
+current session is not, it will start the new process in a separate session of
+necessary type. Call via C<OS2::Process> to disable this magic.
+
+B<WARNING>. Due to the described logic, you need to explicitly
+specify F<.com> extension if needed. Moreover, if the executable
+F<perl5.6.1> is requested, Perl will not look for F<perl5.6.1.exe>.
+[This may change in the future.]
+
+=head2 C<extproc> on the first line
+
+If the first chars of a Perl script are C<"extproc ">, this line is treated
+as C<#!>-line, thus all the switches on this line are processed (twice
+if script was started via cmd.exe). See L<perlrun/DESCRIPTION>.
+
=head2 Additional modules:
-L<OS2::Process>, L<OS2::REXX>, L<OS2::PrfDB>, L<OS2::ExtAttr>. This
-modules provide access to additional numeric argument for C<system>,
-to DLLs having functions with REXX signature and to REXX runtime, to
+L<OS2::Process>, L<OS2::DLL>, L<OS2::REXX>, L<OS2::PrfDB>, L<OS2::ExtAttr>. These
+modules provide access to additional numeric argument for C<system>
+and to the information about the running process,
+to DLLs having functions with REXX signature and to the REXX runtime, to
OS/2 databases in the F<.INI> format, and to Extended Attributes.
Two additional extensions by Andreas Kaiser, C<OS2::UPM>, and
-C<OS2::FTP>, are included into my ftp directory, mirrored on CPAN.
+C<OS2::FTP>, are included into C<ILYAZ> directory, mirrored on CPAN.
+Other OS/2-related extensions are available too.
=head2 Prebuilt methods:
=item C<File::Copy::syscopy>
-used by C<File::Copy::copy>, see L<File::Copy/copy>.
+used by C<File::Copy::copy>, see L<File::Copy>.
=item C<DynaLoader::mod2fname>
=item C<Cwd::change_drive(name)>
+chanes the "current" drive.
=item C<Cwd::sys_is_absolute(name)>
=item C<Cwd::sys_cwd(name)>
-Interface to cwd from B<EMX>. Used by C<Cwd::cwd>.
+Interface to cwd from EMX. Used by C<Cwd::cwd>.
=item C<Cwd::sys_abspath(name, dir)>
file which would have C<name> if CWD were C<dir>. C<Dir> defaults to the
current dir.
-=item C<Cwd::extLibpath([type])
+=item C<Cwd::extLibpath([type])>
Get current value of extended library search path. If C<type> is
-present and I<true>, works with END_LIBPATH, otherwise with
-C<BEGIN_LIBPATH>.
+present and positive, works with C<END_LIBPATH>, if negative, works
+with C<LIBPATHSTRICT>, otherwise with C<BEGIN_LIBPATH>.
=item C<Cwd::extLibpath_set( path [, type ] )>
Set current value of extended library search path. If C<type> is
-present and I<true>, works with END_LIBPATH, otherwise with
-C<BEGIN_LIBPATH>.
+present and positive, works with <END_LIBPATH>, if negative, works
+with C<LIBPATHSTRICT>, otherwise with C<BEGIN_LIBPATH>.
+
+=item C<OS2::Error(do_harderror,do_exception)>
+
+Returns C<undef> if it was not called yet, otherwise bit 1 is
+set if on the previous call do_harderror was enabled, bit
+2 is set if on previous call do_exception was enabled.
+
+This function enables/disables error popups associated with
+hardware errors (Disk not ready etc.) and software exceptions.
+
+I know of no way to find out the state of popups I<before> the first call
+to this function.
+
+=item C<OS2::Errors2Drive(drive)>
+
+Returns C<undef> if it was not called yet, otherwise return false if errors
+were not requested to be written to a hard drive, or the drive letter if
+this was requested.
+
+This function may redirect error popups associated with hardware errors
+(Disk not ready etc.) and software exceptions to the file POPUPLOG.OS2 at
+the root directory of the specified drive. Overrides OS2::Error() specified
+by individual programs. Given argument undef will disable redirection.
+
+Has global effect, persists after the application exits.
+
+I know of no way to find out the state of redirection of popups to the disk
+I<before> the first call to this function.
+
+=item OS2::SysInfo()
+
+Returns a hash with system information. The keys of the hash are
+
+ MAX_PATH_LENGTH, MAX_TEXT_SESSIONS, MAX_PM_SESSIONS,
+ MAX_VDM_SESSIONS, BOOT_DRIVE, DYN_PRI_VARIATION,
+ MAX_WAIT, MIN_SLICE, MAX_SLICE, PAGE_SIZE,
+ VERSION_MAJOR, VERSION_MINOR, VERSION_REVISION,
+ MS_COUNT, TIME_LOW, TIME_HIGH, TOTPHYSMEM, TOTRESMEM,
+ TOTAVAILMEM, MAXPRMEM, MAXSHMEM, TIMER_INTERVAL,
+ MAX_COMP_LENGTH, FOREGROUND_FS_SESSION,
+ FOREGROUND_PROCESS
+
+=item OS2::BootDrive()
+
+Returns a letter without colon.
+
+=item C<OS2::MorphPM(serve)>, C<OS2::UnMorphPM(serve)>
+
+Transforms the current application into a PM application and back.
+The argument true means that a real message loop is going to be served.
+OS2::MorphPM() returns the PM message queue handle as an integer.
+
+See L<"Centralized management of resources"> for additional details.
+
+=item C<OS2::Serve_Messages(force)>
+
+Fake on-demand retrieval of outstanding PM messages. If C<force> is false,
+will not dispatch messages if a real message loop is known to
+be present. Returns number of messages retrieved.
+
+Dies with "QUITing..." if WM_QUIT message is obtained.
+
+=item C<OS2::Process_Messages(force [, cnt])>
+
+Retrieval of PM messages until window creation/destruction.
+If C<force> is false, will not dispatch messages if a real message loop
+is known to be present.
+
+Returns change in number of windows. If C<cnt> is given,
+it is incremented by the number of messages retrieved.
+
+Dies with "QUITing..." if WM_QUIT message is obtained.
+
+=item C<OS2::_control87(new,mask)>
+
+the same as L<_control87(3)> of EMX. Takes integers as arguments, returns
+the previous coprocessor control word as an integer. Only bits in C<new> which
+are present in C<mask> are changed in the control word.
+
+=item OS2::get_control87()
+
+gets the coprocessor control word as an integer.
+
+=item C<OS2::set_control87_em(new=MCW_EM,mask=MCW_EM)>
+
+The variant of OS2::_control87() with default values good for
+handling exception mask: if no C<mask>, uses exception mask part of C<new>
+only. If no C<new>, disables all the floating point exceptions.
+
+See L<"Misfeatures"> for details.
+
+=item C<OS2::DLLname([how [, \&xsub]])>
+
+Gives the information about the Perl DLL or the DLL containing the C
+function bound to by C<&xsub>. The meaning of C<how> is: default (2):
+full name; 0: handle; 1: module name.
=back
eventually).
+=head2 Prebuilt variables:
+
+=over 4
+
+=item $OS2::emx_rev
+
+numeric value is the same as _emx_rev of EMX, a string value the same
+as _emx_vprt (similar to C<0.9c>).
+
+=item $OS2::emx_env
+
+same as _emx_env of EMX, a number similar to 0x8001.
+
+=item $OS2::os_ver
+
+a number C<OS_MAJOR + 0.001 * OS_MINOR>.
+
+=item $OS2::is_aout
+
+true if the Perl library was compiled in AOUT format.
+
+=item $OS2::can_fork
+
+true if the current executable is an AOUT EMX executable, so Perl can
+fork. Do not use this, use the portable check for
+$Config::Config{dfork}.
+
+=item $OS2::nsyserror
+
+This variable (default is 1) controls whether to enforce the contents
+of $^E to start with C<SYS0003>-like id. If set to 0, then the string
+value of $^E is what is available from the OS/2 message file. (Some
+messages in this file have an C<SYS0003>-like id prepended, some not.)
+
+=back
+
=head2 Misfeatures
=over 4
-=item
+=item *
+
+Since L<flock(3)> is present in EMX, but is not functional, it is
+emulated by perl. To disable the emulations, set environment variable
+C<USE_PERL_FLOCK=0>.
+
+=item *
-Since <flock> is present in B<EMX>, but is not functional, the same is
-true for perl. Here is the list of things which may be "broken" on
+Here is the list of things which may be "broken" on
EMX (from EMX docs):
- - The functions recvmsg(), sendmsg(), and socketpair() are not
- implemented.
- - sock_init() is not required and not implemented.
- - flock() is not yet implemented (dummy function).
- - kill:
- Special treatment of PID=0, PID=1 and PID=-1 is not implemented.
- - waitpid:
+=over 4
+
+=item *
+
+The functions L<recvmsg(3)>, L<sendmsg(3)>, and L<socketpair(3)> are not
+implemented.
+
+=item *
+
+L<sock_init(3)> is not required and not implemented.
+
+=item *
+
+L<flock(3)> is not yet implemented (dummy function). (Perl has a workaround.)
+
+=item *
+
+L<kill(3)>: Special treatment of PID=0, PID=1 and PID=-1 is not implemented.
+
+=item *
+
+L<waitpid(3)>:
+
WUNTRACED
Not implemented.
waitpid() is not implemented for negative values of PID.
+=back
+
Note that C<kill -9> does not work with the current version of EMX.
-=item
+=item *
+
+See L<"Text-mode filehandles">.
+
+=item *
-Since F<sh.exe> is used for globing (see L<perlfunc/glob>), the bugs
-of F<sh.exe> plague perl as well.
+Unix-domain sockets on OS/2 live in a pseudo-file-system C</sockets/...>.
+To avoid a failure to create a socket with a name of a different form,
+C<"/socket/"> is prepended to the socket name (unless it starts with this
+already).
-In particular, uppercase letters do not work in C<[...]>-patterns with
-the current C<pdksh>.
+This may lead to problems later in case the socket is accessed via the
+"usual" file-system calls using the "initial" name.
+
+=item *
+
+Apparently, IBM used a compiler (for some period of time around '95?) which
+changes FP mask right and left. This is not I<that> bad for IBM's
+programs, but the same compiler was used for DLLs which are used with
+general-purpose applications. When these DLLs are used, the state of
+floating-point flags in the application is not predictable.
+
+What is much worse, some DLLs change the floating point flags when in
+_DLLInitTerm() (e.g., F<TCP32IP>). This means that even if you do not I<call>
+any function in the DLL, just the act of loading this DLL will reset your
+flags. What is worse, the same compiler was used to compile some HOOK DLLs.
+Given that HOOK dlls are executed in the context of I<all> the applications
+in the system, this means a complete unpredictablity of floating point
+flags on systems using such HOOK DLLs. E.g., F<GAMESRVR.DLL> of B<DIVE>
+origin changes the floating point flags on each write to the TTY of a VIO
+(windowed text-mode) applications.
+
+Some other (not completely debugged) situations when FP flags change include
+some video drivers (?), and some operations related to creation of the windows.
+People who code B<OpenGL> may have more experience on this.
+
+Perl is generally used in the situation when all the floating-point
+exceptions are ignored, as is the default under EMX. If they are not ignored,
+some benign Perl programs would get a C<SIGFPE> and would die a horrible death.
+
+To circumvent this, Perl uses two hacks. They help against I<one> type of
+damage only: FP flags changed when loading a DLL.
+
+One of the hacks is to disable floating point exceptions on Perl startup (as
+is the default with EMX). This helps only with compile-time-linked DLLs
+changing the flags before main() had a chance to be called.
+
+The other hack is to restore FP flags after a call to dlopen(). This helps
+against similar damage done by DLLs _DLLInitTerm() at runtime. Currently
+no way to switch these hacks off is provided.
=back
C<os2_stat> special-cases F</dev/tty> and F</dev/con>.
+=item C<mkdir>, C<rmdir>
+
+these EMX functions do not work if the path contains a trailing C</>.
+Perl contains a workaround for this.
+
+=item C<flock>
+
+Since L<flock(3)> is present in EMX, but is not functional, it is
+emulated by perl. To disable the emulations, set environment variable
+C<USE_PERL_FLOCK=0>.
+
+=back
+
+=head2 Identifying DLLs
+
+All the DLLs built with the current versions of Perl have ID strings
+identifying the name of the extension, its version, and the version
+of Perl required for this DLL. Run C<bldlevel DLL-name> to find this
+info.
+
+=head2 Centralized management of resources
+
+Since to call certain OS/2 API one needs to have a correctly initialized
+C<Win> subsystem, OS/2-specific extensions may require getting C<HAB>s and
+C<HMQ>s. If an extension would do it on its own, another extension could
+fail to initialize.
+
+Perl provides a centralized management of these resources:
+
+=over
+
+=item C<HAB>
+
+To get the HAB, the extension should call C<hab = perl_hab_GET()> in C. After
+this call is performed, C<hab> may be accessed as C<Perl_hab>. There is
+no need to release the HAB after it is used.
+
+If by some reasons F<perl.h> cannot be included, use
+
+ extern int Perl_hab_GET(void);
+
+instead.
+
+=item C<HMQ>
+
+There are two cases:
+
+=over
+
+=item *
+
+the extension needs an C<HMQ> only because some API will not work otherwise.
+Use C<serve = 0> below.
+
+=item *
+
+the extension needs an C<HMQ> since it wants to engage in a PM event loop.
+Use C<serve = 1> below.
+
+=back
+
+To get an C<HMQ>, the extension should call C<hmq = perl_hmq_GET(serve)> in C.
+After this call is performed, C<hmq> may be accessed as C<Perl_hmq>.
+
+To signal to Perl that HMQ is not needed any more, call
+C<perl_hmq_UNSET(serve)>. Perl process will automatically morph/unmorph itself
+into/from a PM process if HMQ is needed/not-needed. Perl will automatically
+enable/disable C<WM_QUIT> message during shutdown if the message queue is
+served/not-served.
+
+B<NOTE>. If during a shutdown there is a message queue which did not disable
+WM_QUIT, and which did not process the received WM_QUIT message, the
+shutdown will be automatically cancelled. Do not call C<perl_hmq_GET(1)>
+unless you are going to process messages on an orderly basis.
+
+=item * Treating errors reported by OS/2 API
+
+There are two principal conventions (it is useful to call them C<Dos*>
+and C<Win*> - though this part of the function signature is not always
+determined by the name of the API) of reporting the error conditions
+of OS/2 API. Most of C<Dos*> APIs report the error code as the result
+of the call (so 0 means success, and there are many types of errors).
+Most of C<Win*> API report success/fail via the result being
+C<TRUE>/C<FALSE>; to find the reason for the failure one should call
+WinGetLastError() API.
+
+Some C<Win*> entry points also overload a "meaningful" return value
+with the error indicator; having a 0 return value indicates an error.
+Yet some other C<Win*> entry points overload things even more, and 0
+return value may mean a successful call returning a valid value 0, as
+well as an error condition; in the case of a 0 return value one should
+call WinGetLastError() API to distinguish a successful call from a
+failing one.
+
+By convention, all the calls to OS/2 API should indicate their
+failures by resetting $^E. All the Perl-accessible functions which
+call OS/2 API may be broken into two classes: some die()s when an API
+error is encountered, the other report the error via a false return
+value (of course, this does not concern Perl-accessible functions
+which I<expect> a failure of the OS/2 API call, having some workarounds
+coded).
+
+Obviously, in the situation of the last type of the signature of an OS/2
+API, it is must more convenient for the users if the failure is
+indicated by die()ing: one does not need to check $^E to know that
+something went wrong. If, however, this solution is not desirable by
+some reason, the code in question should reset $^E to 0 before making
+this OS/2 API call, so that the caller of this Perl-accessible
+function has a chance to distinguish a success-but-0-return value from
+a failure. (One may return undef as an alternative way of reporting
+an error.)
+
+The macros to simplify this type of error propagation are
+
+=over
+
+=item C<CheckOSError(expr)>
+
+Returns true on error, sets $^E. Expects expr() be a call of
+C<Dos*>-style API.
+
+=item C<CheckWinError(expr)>
+
+Returns true on error, sets $^E. Expects expr() be a call of
+C<Win*>-style API.
+
+=item C<SaveWinError(expr)>
+
+Returns C<expr>, sets $^E from WinGetLastError() if C<expr> is false.
+
+=item C<SaveCroakWinError(expr,die,name1,name2)>
+
+Returns C<expr>, sets $^E from WinGetLastError() if C<expr> is false,
+and die()s if C<die> and $^E are true. The message to die is the
+concatenated strings C<name1> and C<name2>, separated by C<": "> from
+the contents of $^E.
+
+=item C<WinError_2_Perl_rc>
+
+Sets C<Perl_rc> to the return value of WinGetLastError().
+
+=item C<FillWinError>
+
+Sets C<Perl_rc> to the return value of WinGetLastError(), and sets $^E
+to the corresponding value.
+
+=item C<FillOSError(rc)>
+
+Sets C<Perl_rc> to C<rc>, and sets $^E to the corresponding value.
+
+=back
+
+=item * Loading DLLs and ordinals in DLLs
+
+Some DLLs are only present in some versions of OS/2, or in some
+configurations of OS/2. Some exported entry points are present only
+in DLLs shipped with some versions of OS/2. If these DLLs and entry
+points were linked directly for a Perl executable/DLL or from a Perl
+extensions, this binary would work only with the specified
+versions/setups. Even if these entry points were not needed, the
+I<load> of the executable (or DLL) would fail.
+
+For example, many newer useful APIs are not present in OS/2 v2; many
+PM-related APIs require DLLs not available on floppy-boot setup.
+
+To make these calls fail I<only when the calls are executed>, one
+should call these API via a dynamic linking API. There is a subsystem
+in Perl to simplify such type of calls. A large number of entry
+points available for such linking is provided (see C<entries_ordinals>
+- and also C<PMWIN_entries> - in F<os2ish.h>). These ordinals can be
+accessed via the APIs:
+
+ CallORD(), DeclFuncByORD(), DeclVoidFuncByORD(),
+ DeclOSFuncByORD(), DeclWinFuncByORD(), AssignFuncPByORD(),
+ DeclWinFuncByORD_CACHE(), DeclWinFuncByORD_CACHE_survive(),
+ DeclWinFuncByORD_CACHE_resetError_survive(),
+ DeclWinFunc_CACHE(), DeclWinFunc_CACHE_resetError(),
+ DeclWinFunc_CACHE_survive(), DeclWinFunc_CACHE_resetError_survive()
+
+See the header files and the C code in the supplied OS/2-related
+modules for the details on usage of these functions.
+
+Some of these functions also combine dynaloading semantic with the
+error-propagation semantic discussed above.
+
=back
=head1 Perl flavors
Because of idiosyncrasies of OS/2 one cannot have all the eggs in the
-same basket (though C<EMX> environment tries hard to overcome this
+same basket (though EMX environment tries hard to overcome this
limitations, so the situation may somehow improve). There are 4
executables for Perl provided by the distribution:
The main workhorse. This is a chimera executable: it is compiled as an
C<a.out>-style executable, but is linked with C<omf>-style dynamic
-library F<perl.dll>, and with dynamic B<CRT> DLL. This executable is a
-C<VIO> application.
+library F<perl.dll>, and with dynamic CRT DLL. This executable is a
+VIO application.
-It can load perl dynamic extensions, and it can fork(). Unfortunately,
-with the current version of B<EMX> it cannot fork() with dynamic
-extensions loaded (may be fixed by patches to B<EMX>).
+It can load perl dynamic extensions, and it can fork().
B<Note.> Keep in mind that fork() is needed to open a pipe to yourself.
=head2 F<perl_.exe>
-This is a statically linked C<a.out>-style executable. It can fork(),
-but cannot load dynamic Perl extensions. The supplied executable has a
-lot of extensions prebuilt, thus there are situations when it can
-perform tasks not possible using F<perl.exe>, like fork()ing when
-having some standard extension loaded. This executable is a C<VIO>
+This is a statically linked C<a.out>-style executable. It cannot
+load dynamic Perl extensions. The executable supplied in binary
+distributions has a lot of extensions prebuilt, thus the above restriction is
+important only if you use custom-built extensions. This executable is a VIO
application.
-B<Note.> A better behaviour could be obtained from C<perl.exe> if it
-were statically linked with standard I<Perl extensions>, but
-dynamically linked with the I<Perl DLL> and C<CRT> DLL. Then it would
-be able to fork() with standard extensions, I<and> would be able to
-dynamically load arbitrary extensions. Some changes to Makefiles and
-hint files should be necessary to achieve this.
-
-I<This is also the only executable with does not require OS/2.> The
+I<This is the only executable with does not require OS/2.> The
friends locked into C<M$> world would appreciate the fact that this
executable runs under DOS, Win0.3*, Win0.95 and WinNT with an
appropriate extender. See L<"Other OSes">.
=head2 F<perl__.exe>
-This is the same executable as <perl___.exe>, but it is a C<PM>
+This is the same executable as F<perl___.exe>, but it is a PM
application.
-B<Note.> Usually C<STDIN>, C<STDERR>, and C<STDOUT> of a C<PM>
-application are redirected to C<nul>. However, it is possible to see
+B<Note.> Usually (unless explicitly redirected during the startup)
+STDIN, STDERR, and STDOUT of a PM
+application are redirected to F<nul>. However, it is possible to I<see>
them if you start C<perl__.exe> from a PM program which emulates a
-console window, like I<Shell mode> of C<Emacs> or C<EPM>. Thus it I<is
+console window, like I<Shell mode> of Emacs or EPM. Thus it I<is
possible> to use Perl debugger (see L<perldebug>) to debug your PM
-application.
+application (but beware of the message loop lockups - this will not
+work if you have a message queue to serve, unless you hook the serving
+into the getc() function of the debugger).
+
+Another way to see the output of a PM program is to run it as
+
+ pm_prog args 2>&1 | cat -
+
+with a shell I<different> from F<cmd.exe>, so that it does not create
+a link between a VIO session and the session of C<pm_porg>. (Such a link
+closes the VIO window.) E.g., this works with F<sh.exe> - or with Perl!
-This flavor is required if you load extensions which use C<PM>, like
-the forthcoming C<Perl/Tk>.
+ open P, 'pm_prog args 2>&1 |' or die;
+ print while <P>;
+
+The flavor F<perl__.exe> is required if you want to start your program without
+a VIO window present, but not C<detach>ed (run C<help detach> for more info).
+Very useful for extensions which use PM, like C<Perl/Tk> or C<OpenGL>.
+
+Note also that the differences between PM and VIO executables are only
+in the I<default> behaviour. One can start I<any> executable in
+I<any> kind of session by using the arguments C</fs>, C</pm> or
+C</win> switches of the command C<start> (of F<CMD.EXE> or a similar
+shell). Alternatively, one can use the numeric first argument of the
+C<system> Perl function (see L<OS2::Process>).
=head2 F<perl___.exe>
This is an C<omf>-style executable which is dynamically linked to
-F<perl.dll> and C<CRT> DLL. I know no advantages of this executable
+F<perl.dll> and CRT DLL. I know no advantages of this executable
over C<perl.exe>, but it cannot fork() at all. Well, one advantage is
that the build process is not so convoluted as with C<perl.exe>.
-It is a C<VIO> application.
+It is a VIO application.
=head2 Why strange names?
Well, having several executables dynamically linked to the same huge
library has its advantages, but this would not substantiate the
-additional work to make it compile. The reason is stupid-but-quick
-"hard" dynamic linking used by OS/2.
+additional work to make it compile. The reason is the complicated-to-developers
+but very quick and convenient-to-users "hard" dynamic linking used by OS/2.
+
+There are two distinctive features of the dyna-linking model of OS/2:
+first, all the references to external functions are resolved at the compile time;
+second, there is no runtime fixup of the DLLs after they are loaded into memory.
+The first feature is an enormous advantage over other models: it avoids
+conflicts when several DLLs used by an application export entries with
+the same name. In such cases "other" models of dyna-linking just choose
+between these two entry points using some random criterion - with predictable
+disasters as results. But it is the second feature which requires the build
+of F<perl.dll>.
The address tables of DLLs are patched only once, when they are
-loaded. The addresses of entry points into DLLs are guaranteed to be
-the same for all programs which use the same DLL, which reduces the
-amount of runtime patching - once DLL is loaded, its code is
-read-only.
-
-While this allows some performance advantages, this makes life
-terrible for developers, since the above scheme makes it impossible
-for a DLL to be resolved to a symbol in the .EXE file, since this
-would need a DLL to have different relocations tables for the
-executables which use it.
+loaded. The addresses of the entry points into DLLs are guaranteed to be
+the same for all the programs which use the same DLL. This removes the
+runtime fixup - once DLL is loaded, its code is read-only.
-However, a Perl extension is forced to use some symbols from the perl
-executable, say to know how to find the arguments provided on the perl
-internal evaluation stack. The solution is that the main code of
-interpreter should be contained in a DLL, and the F<.EXE> file just loads
-this DLL into memory and supplies command-arguments.
+While this allows some (significant?) performance advantages, this makes life
+much harder for developers, since the above scheme makes it impossible
+for a DLL to be "linked" to a symbol in the F<.EXE> file. Indeed, this
+would need a DLL to have different relocations tables for the
+(different) executables which use this DLL.
+
+However, a dynamically loaded Perl extension is forced to use some symbols
+from the perl
+executable, e.g., to know how to find the arguments to the functions:
+the arguments live on the perl
+internal evaluation stack. The solution is to put the main code of
+the interpreter into a DLL, and make the F<.EXE> file which just loads
+this DLL into memory and supplies command-arguments. The extension DLL
+cannot link to symbols in F<.EXE>, but it has no problem linking
+to symbols in the F<.DLL>.
This I<greatly> increases the load time for the application (as well as
-the number of problems during compilation). Since interpreter is in a DLL,
-the C<CRT> is basically forced to reside in a DLL as well (otherwise
-extensions would not be able to use C<CRT>).
+complexity of the compilation). Since interpreter is in a DLL,
+the C RTL is basically forced to reside in a DLL as well (otherwise
+extensions would not be able to use CRT). There are some advantages if
+you use different flavors of perl, such as running F<perl.exe> and
+F<perl__.exe> simultaneously: they share the memory of F<perl.dll>.
+
+B<NOTE>. There is one additional effect which makes DLLs more wasteful:
+DLLs are loaded in the shared memory region, which is a scarse resource
+given the 512M barrier of the "standard" OS/2 virtual memory. The code of
+F<.EXE> files is also shared by all the processes which use the particular
+F<.EXE>, but they are "shared in the private address space of the process";
+this is possible because the address at which different sections
+of the F<.EXE> file are loaded is decided at compile-time, thus all the
+processes have these sections loaded at same addresses, and no fixup
+of internal links inside the F<.EXE> is needed.
+
+Since DLLs may be loaded at run time, to have the same mechanism for DLLs
+one needs to have the address range of I<any of the loaded> DLLs in the
+system to be available I<in all the processes> which did not load a particular
+DLL yet. This is why the DLLs are mapped to the shared memory region.
=head2 Why chimera build?
-Current C<EMX> environment does not allow DLLs compiled using Unixish
-C<a.out> format to export symbols for data. This forces C<omf>-style
-compile of F<perl.dll>.
+Current EMX environment does not allow DLLs compiled using Unixish
+C<a.out> format to export symbols for data (or at least some types of
+data). This forces C<omf>-style compile of F<perl.dll>.
-Current C<EMX> environment does not allow F<.EXE> files compiled in
+Current EMX environment does not allow F<.EXE> files compiled in
C<omf> format to fork(). fork() is needed for exactly three Perl
operations:
=over 4
-=item explicit fork()
+=item *
+
+explicit fork() in the script,
-in the script, and
+=item *
-=item open FH, "|-"
+C<open FH, "|-">
-=item open FH, "-|"
+=item *
-opening pipes to itself.
+C<open FH, "-|">, in other words, opening pipes to itself.
=back
-While these operations are not questions of life and death, a lot of
-useful scripts use them. This forces C<a.out>-style compile of
+While these operations are not questions of life and death, they are
+needed for a lot of
+useful scripts. This forces C<a.out>-style compile of
F<perl.exe>.
=head1 ENVIRONMENT
-Here we list environment variables with are either OS/2-specific, or
-are more important under OS/2 than under other OSes.
+Here we list environment variables with are either OS/2- and DOS- and
+Win*-specific, or are more important under OS/2 than under other OSes.
=head2 C<PERLLIB_PREFIX>
-Specific for OS/2. Should have the form
+Specific for EMX port. Should have the form
path1;path2
Should be used if the perl library is moved from the default
location in preference to C<PERL(5)LIB>, since this would not leave wrong
-entries in <@INC>.
+entries in @INC. For example, if the compiled version of perl looks for @INC
+in F<f:/perllib/lib>, and you want to install the library in
+F<h:/opt/gnu>, do
+
+ set PERLLIB_PREFIX=f:/perllib/lib;h:/opt/gnu
+
+This will cause Perl with the prebuilt @INC of
+
+ f:/perllib/lib/5.00553/os2
+ f:/perllib/lib/5.00553
+ f:/perllib/lib/site_perl/5.00553/os2
+ f:/perllib/lib/site_perl/5.00553
+ .
+
+to use the following @INC:
+
+ h:/opt/gnu/5.00553/os2
+ h:/opt/gnu/5.00553
+ h:/opt/gnu/site_perl/5.00553/os2
+ h:/opt/gnu/site_perl/5.00553
+ .
=head2 C<PERL_BADLANG>
-If 1, perl ignores setlocale() failing. May be useful with some
+If 0, perl ignores setlocale() failing. May be useful with some
strange I<locale>s.
=head2 C<PERL_BADFREE>
-If 1, perl would not warn of in case of unwarranted free(). May be
-useful in conjunction with the module DB_File, since Berkeley DB
-memory handling code is buggy.
+If 0, perl would not warn of in case of unwarranted free(). With older
+perls this might be
+useful in conjunction with the module DB_File, which was buggy when
+dynamically linked and OMF-built.
+
+Should not be set with newer Perls, since this may hide some I<real> problems.
=head2 C<PERL_SH_DIR>
-Specific for OS/2. Gives the directory part of the location for
+Specific for EMX port. Gives the directory part of the location for
F<sh.exe>.
+=head2 C<USE_PERL_FLOCK>
+
+Specific for EMX port. Since L<flock(3)> is present in EMX, but is not
+functional, it is emulated by perl. To disable the emulations, set
+environment variable C<USE_PERL_FLOCK=0>.
+
=head2 C<TMP> or C<TEMP>
-Specific for OS/2. Used as storage place for temporary files, most
-notably C<-e> scripts.
+Specific for EMX port. Used as storage place for temporary files.
=head1 Evolution
Here we list major changes which could make you by surprise.
+=head2 Text-mode filehandles
+
+Starting from version 5.8, Perl uses a builtin translation layer for
+text-mode files. This replaces the efficient well-tested EMX layer by
+some code which should be best characterized as a "quick hack".
+
+In addition to possible bugs and an inability to follow changes to the
+translation policy with off/on switches of TERMIO translation, this
+introduces a serious incompatible change: before sysread() on
+text-mode filehandles would go through the translation layer, now it
+would not.
+
=head2 Priorities
C<setpriority> and C<getpriority> are not compatible with earlier
ports by Andreas Kaiser. See C<"setpriority, getpriority">.
-=head2 DLL name mangling
+=head2 DLL name mangling: pre 5.6.2
With the release 5.003_01 the dynamically loadable libraries
-should be rebuilt. In particular, DLLs are now created with the names
+should be rebuilt when a different version of Perl is compiled. In particular,
+DLLs (including F<perl.dll>) are now created with the names
which contain a checksum, thus allowing workaround for OS/2 scheme of
caching DLLs.
+It may be possible to code a simple workaround which would
+
+=over
+
+=item *
+
+find the old DLLs looking through the old @INC;
+
+=item *
+
+mangle the names according to the scheme of new perl and copy the DLLs to
+these names;
+
+=item *
+
+edit the internal C<LX> tables of DLL to reflect the change of the name
+(probably not needed for Perl extension DLLs, since the internally coded names
+are not used for "specific" DLLs, they used only for "global" DLLs).
+
+=item *
+
+edit the internal C<IMPORT> tables and change the name of the "old"
+F<perl????.dll> to the "new" F<perl????.dll>.
+
+=back
+
+=head2 DLL name mangling: 5.6.2 and beyond
+
+In fact mangling of I<extension> DLLs was done due to misunderstanding
+of the OS/2 dynaloading model. OS/2 (effectively) maintains two
+different tables of loaded DLL:
+
+=over
+
+=item Global DLLs
+
+those loaded by the base name from C<LIBPATH>; including those
+associated at link time;
+
+=item specific DLLs
+
+loaded by the full name.
+
+=back
+
+When resolving a request for a global DLL, the table of already-loaded
+specific DLLs is (effectively) ignored; moreover, specific DLLs are
+I<always> loaded from the prescribed path.
+
+There is/was a minor twist which makes this scheme fragile: what to do
+with DLLs loaded from
+
+=over
+
+=item C<BEGINLIBPATH> and C<ENDLIBPATH>
+
+(which depend on the process)
+
+=item F<.> from C<LIBPATH>
+
+which I<effectively> depends on the process (although C<LIBPATH> is the
+same for all the processes).
+
+=back
+
+Unless C<LIBPATHSTRICT> is set to C<T> (and the kernel is after
+2000/09/01), such DLLs are considered to be global. When loading a
+global DLL it is first looked in the table of already-loaded global
+DLLs. Because of this the fact that one executable loaded a DLL from
+C<BEGINLIBPATH> and C<ENDLIBPATH>, or F<.> from C<LIBPATH> may affect
+I<which> DLL is loaded when I<another> executable requests a DLL with
+the same name. I<This> is the reason for version-specific mangling of
+the DLL name for perl DLL.
+
+Since the Perl extension DLLs are always loaded with the full path,
+there is no need to mangle their names in a version-specific ways:
+their directory already reflects the corresponding version of perl,
+and @INC takes into account binary compatibility with older version.
+Starting from C<5.6.2> the name mangling scheme is fixed to be the
+same as for Perl 5.005_53 (same as in a popular binary release). Thus
+new Perls will be able to I<resolve the names> of old extension DLLs
+if @INC allows finding their directories.
+
+However, this still does not guarantee that these DLL may be loaded.
+The reason is the mangling of the name of the I<Perl DLL>. And since
+the extension DLLs link with the Perl DLL, extension DLLs for older
+versions would load an older Perl DLL, and would most probably
+segfault (since the data in this DLL is not properly initialized).
+
+There is a partial workaround (which can be made complete with newer
+OS/2 kernels): create a forwarder DLL with the same name as the DLL of
+the older version of Perl, which forwards the entry points to the
+newer Perl's DLL. Make this DLL accessible on (say) the C<BEGINLIBPATH> of
+the new Perl executable. When the new executable accesses old Perl's
+extension DLLs, they would request the old Perl's DLL by name, get the
+forwarder instead, so effectively will link with the currently running
+(new) Perl DLL.
+
+This may break in two ways:
+
+=over
+
+=item *
+
+Old perl executable is started when a new executable is running has
+loaded an extension compiled for the old executable (ouph!). In this
+case the old executable will get a forwarder DLL instead of the old
+perl DLL, so would link with the new perl DLL. While not directly
+fatal, it will behave the same as new executable. This beats the whole
+purpose of explicitly starting an old executable.
+
+=item *
+
+A new executable loads an extension compiled for the old executable
+when an old perl executable is running. In this case the extension
+will not pick up the forwarder - with fatal results.
+
+=back
+
+With support for C<LIBPATHSTRICT> this may be circumvented - unless
+one of DLLs is started from F<.> from C<LIBPATH> (I do not know
+whether C<LIBPATHSTRICT> affects this case).
+
+B<REMARK>. Unless newer kernels allow F<.> in C<BEGINLIBPATH> (older
+do not), this mess cannot be completely cleaned. (It turns out that
+as of the beginning of 2002, F<.> is not allowed, but F<.\.> is - and
+it has the same effect.)
+
+
+B<REMARK>. C<LIBPATHSTRICT>, C<BEGINLIBPATH> and C<ENDLIBPATH> are
+not environment variables, although F<cmd.exe> emulates them on C<SET
+...> lines. From Perl they may be accessed by L<Cwd::extLibpath> and
+L<Cwd::extLibpath_set>.
+
+=head2 DLL forwarder generation
+
+Assume that the old DLL is named F<perlE0AC.dll> (as is one for
+5.005_53), and the new version is 5.6.1. Create a file
+F<perl5shim.def-leader> with
+
+ LIBRARY 'perlE0AC' INITINSTANCE TERMINSTANCE
+ DESCRIPTION '@#perl5-porters@perl.org:5.006001#@ Perl module for 5.00553 -> Perl 5.6.1 forwarder'
+ CODE LOADONCALL
+ DATA LOADONCALL NONSHARED MULTIPLE
+ EXPORTS
+
+modifying the versions/names as needed. Run
+
+ perl -wnle "next if 0../EXPORTS/; print qq( \"$1\") if /\"(\w+)\"/" perl5.def >lst
+
+in the Perl build directory (to make the DLL smaller replace perl5.def
+with the definition file for the older version of Perl if present).
+
+ cat perl5shim.def-leader lst >perl5shim.def
+ gcc -Zomf -Zdll -o perlE0AC.dll perl5shim.def -s -llibperl
+
+(ignore multiple C<warning L4085>).
+
=head2 Threading
-As of release 5.003_01 perl is linked to multithreaded C<CRT>
-DLL. Perl itself is not multithread-safe, as is not perl
+As of release 5.003_01 perl is linked to multithreaded C RTL
+DLL. If perl itself is not compiled multithread-enabled, so will not be perl's
malloc(). However, extensions may use multiple thread on their own
risk.
-Needed to compile C<Perl/Tk> for C<XFreeOS/2> out-of-the-box.
+This was needed to compile C<Perl/Tk> for XFree86-OS/2 out-of-the-box, and
+link with DLLs for other useful libraries, which typically are compiled
+with C<-Zmt -Zcrtdll>.
=head2 Calls to external programs
whatever is the override, see L<"PERL_SH_DIR">.
Thus means that you need to get some copy of a F<sh.exe> as well (I
-use one from pdksh). The drive F: above is set up automatically during
+use one from pdksh). The path F<F:/bin> above is set up automatically during
the build to a correct value on the builder machine, but is
overridable at runtime,
B<Reasons:> a consensus on C<perl5-porters> was that perl should use
one non-overridable shell per platform. The obvious choices for OS/2
are F<cmd.exe> and F<sh.exe>. Having perl build itself would be impossible
-with F<cmd.exe> as a shell, thus I picked up C<sh.exe>. Thus assures almost
-100% compatibility with the scripts coming from *nix.
+with F<cmd.exe> as a shell, thus I picked up C<sh.exe>. This assures almost
+100% compatibility with the scripts coming from *nix. As an added benefit
+this works as well under DOS if you use DOS-enabled port of pdksh
+(see L<"Prerequisites">).
-B<Disadvantages:> currently F<sh.exe> of C<pdksh> calls external programs
+B<Disadvantages:> currently F<sh.exe> of pdksh calls external programs
via fork()/exec(), and there is I<no> functioning exec() on
-OS/2. exec() is emulated by EMX by asyncroneous call while the caller
+OS/2. exec() is emulated by EMX by an asynchronous call while the caller
waits for child completion (to pretend that the C<pid> did not change). This
means that 1 I<extra> copy of F<sh.exe> is made active via fork()/exec(),
which may lead to some resources taken from the system (even if we do
I will include it into distribution. I have no need for such a module, so
cannot test it.
+For the details of the current situation with calling external programs,
+see L<Starting OS/2 (and DOS) programs under Perl>. Set us mention a couple
+of features:
+
+=over 4
+
+=item *
+
+External scripts may be called by their basename. Perl will try the same
+extensions as when processing B<-S> command-line switch.
+
+=item *
+
+External scripts starting with C<#!> or C<extproc > will be executed directly,
+without calling the shell, by calling the program specified on the rest of
+the first line.
+
+=back
+
+=head2 Memory allocation
+
+Perl uses its own malloc() under OS/2 - interpreters are usually malloc-bound
+for speed, but perl is not, since its malloc is lightning-fast.
+Perl-memory-usage-tuned benchmarks show that Perl's malloc is 5 times quicker
+than EMX one. I do not have convincing data about memory footprint, but
+a (pretty random) benchmark showed that Perl's one is 5% better.
+
+Combination of perl's malloc() and rigid DLL name resolution creates
+a special problem with library functions which expect their return value to
+be free()d by system's free(). To facilitate extensions which need to call
+such functions, system memory-allocation functions are still available with
+the prefix C<emx_> added. (Currently only DLL perl has this, it should
+propagate to F<perl_.exe> shortly.)
+
+=head2 Threads
+
+One can build perl with thread support enabled by providing C<-D usethreads>
+option to F<Configure>. Currently OS/2 support of threads is very
+preliminary.
+
+Most notable problems:
+
+=over 4
+
+=item C<COND_WAIT>
+
+may have a race condition (but probably does not due to edge-triggered
+nature of OS/2 Event semaphores). (Needs a reimplementation (in terms of chaining
+waiting threads, with the linked list stored in per-thread structure?)?)
+
+=item F<os2.c>
+
+has a couple of static variables used in OS/2-specific functions. (Need to be
+moved to per-thread structure, or serialized?)
+
+=back
+
+Note that these problems should not discourage experimenting, since they
+have a low probability of affecting small programs.
+
+=head1 BUGS
+
+This description is not updated often (since 5.6.1?), see F<./os2/Changes>
+(L<perlos2delta>) for more info.
+
=cut
OS/2 extensions
files - and maybe some other extensions at the time you read it.
Note that OS2 perl defines 2 pseudo-extension functions
-OS2::Copy::copy and DynaLoader::mod2fname.
+OS2::Copy::copy and DynaLoader::mod2fname (many more now, see
+L<Prebuilt methods>).
The -R switch of older perl is deprecated. If you need to call a REXX code
which needs access to variables, include the call into a REXX compartment
=head1 AUTHOR
-Ilya Zakharevich, ilya@math.ohio-state.edu
+Ilya Zakharevich, cpan@ilyaz.org
=head1 SEE ALSO