+If you read this file _as_is_, just ignore the funny characters you
+see. It is written in the POD format (see perlpod manpage) which is
+specially designed to be readable as is.
+
+=head1 NAME
+
+perlos2 - Perl under OS/2, Win0.31, Win0.95 and WinNT.
+
+=head1 SYNOPSIS
+
+One can read this document in the following formats:
+
+ man perlos2
+ view perl perlos2
+ explorer perlos2.html
+ info perlos2
+
+to list some (not all may be available simultaneously), or it may
+be read I<as is>: either as F<README.os2>, or F<pod/perlos2.pod>.
+
+=cut
+
+Contents
+
+ 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 extenal 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 mungling
+ - Threading
+ - Calls to external programs
+ AUTHOR
+ SEE ALSO
+
+=head1 DESCRIPTION
+
+=head2 Target
+
+The target is to make OS/2 the best supported platform for
+using/building/developping Perl and I<Perl applications>, as well as
+make Perl the best language to use under OS/2.
+
+The current state is quite close to this target. Known limitations:
+
+=over 5
+
+=item *
+
+Some *nix programs use fork() a lot, but currently fork() is not
+supported after I<use>ing dynamically loaded extensions.
+
+=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).
+
+=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
+convinience methods of B<Object REXX>. (Is it possible at all? I know
+of no B<Object-REXX> API.)
+
+=back
+
+Please keep this list up-to-date by informing me about other items.
+
+=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
+environment which can run EMX. The current list is DOS,
+DOS-inside-OS/2, Win0.31, 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.
+
+Cf. L<Prerequisites>.
+
+=head2 Prerequisites
+
+=over 6
+
+=item B<EMX>
+
+B<EMX> runtime is required. Note that it is possible to make F<perl_.exe>
+to run under DOS without any external support by binding F<emx.exe> to
+it, see L<emxbind>.
+
+Only the latest runtime is supported, currently C<0.9c>.
+
+One can get different parts of B<EMX> from, say
+
+ ftp://ftp.cdrom.com/pub/os2/emx0.9c/
+ ftp://hobbes.nmsu.edu/os2/unix/gnu/
+
+The runtime component should have the name F<emxrt.zip>.
+
+=item B<RSX>
+
+To run Perl on C<DPMS> platforms one needs B<RSX> runtime. This is
+needed under DOS-inside-OS/2, Win0.31, Win0.95 and WinNT (see
+L<"Other OSes">).
+
+One can get B<RSX> from, say
+
+ ftp://ftp.cdrom.com/pub/os2/emx0.9c/contrib
+ ftp://ftp.uni-bielefeld.de/pub/systems/msdos/misc
+
+Contact the author on C<rainer@mathematik.uni-bielefeld.de>.
+
+=item B<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.
+
+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.
+
+=back
+
+=head2 Starting Perl programs under OS/2
+
+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
+
+ perl -my_opts foo.pl arg1 arg2 arg3
+
+Alternately, if you use OS/2-ish shell, like C<CMD> or C<4os2>, put
+the following at the start of your perl script:
+
+ extproc perl -x -S
+ #!/usr/bin/perl -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
+side, if you know a full path to your script, you may still start it
+with
+
+ perl -x ../../blah/foo.cmd arg1 arg2 arg3
+
+(note that the argument C<-my_opts> is taken care of by the C<#!> line
+in your script).
+
+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>:
+
+ view perl perlrun
+ man perlrun
+ view cmdref extproc
+ help extproc
+
+or whatever method you prefer.
+
+There are also endless possibilites to use I<executable extensions> of
+B<4OS2>, I<associations> of B<WPS> and so on... However, if you use
+*nixish shell (like F<sh.exe> supplied in the binary distribution),
+you need follow the syntax specified in L<perlrun/"Switches">.
+
+=head2 Starting OS/2 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>)
+are for. (Avoid exec() (see L<perlfunc/exec>) unless you know what you
+do).
+
+Note however that to use some of these operators you need to have a
+C<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.
+
+=head1 Frequently asked questions
+
+=head2 I cannot run extenal programs
+
+Did you run your programs with C<-w> switch? See
+L<Starting OS/2 programs under Perl>.
+
+=head2 I cannot embed perl into my program, or use F<perl.dll> from my
+program.
+
+=over 4
+
+=item Is your program B<EMX>-compiled with C<-Zmt -Zcrtdll>?
+
+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.
+
+=item Did you use C<ExtUtils::Embed>?
+
+I had reports it does not work. Somebody would need to fix it.
+
+=back
+
+=head1 INSTALLATION
+
+=head2 Automatic binary installation
+
+The most convinient way of installing 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
+
+ emxrev
+
+A folder is created on your desktop which contains some useful
+objects.
+
+B<Things not taken care of by automatic binary installation:>
+
+=over 15
+
+=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">.
+
+=item C<PERL_BADFREE>
+
+see L<"PERL_BADFREE">.
+
+=item F<Config.pm>
+
+This file resides somewhere deep in the location you installed your
+perl library, find it out by
+
+ perl -MConfig -le "print $INC{'Config.pm'}"
+
+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.
+
+=back
+
+=head2 Manual binary installation
+
+As of version 5.00305, OS/2 perl binary distribution comes splitted
+into 11 components. Unfortunately, to enable configurable binary
+installation, the file paths in the C<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
+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.
+
+Below is the sample of what to do to reproduce the configuration on my
+machine:
+
+=over 3
+
+=item Perl VIO and PM executables (dynamically linked)
+
+ 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>);
+
+=item Perl_ VIO executable (statically linked)
+
+ unzip perl_aou.zip -d f:/emx.add/bin
+
+(have the directory on C<PATH>);
+
+=item Executables for Perl utilities
+
+ unzip perl_utl.zip -d f:/emx.add/bin
+
+(have the directory on C<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
+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
+
+If you do not change this directory, do nothing. Otherwise 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">.
+
+=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">.
+
+=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.
+
+=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.
+
+=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
+documentation in zillions of other formats: C<info>, C<LaTeX>,
+C<Acrobat>, C<FrameMaker> and so on.
+
+=item Perl manual in .INF format
+
+ unzip perl_inf.zip -d d:/os2/book
+
+This directory should better be on C<BOOKSHELF>.
+
+=item Pdksh
+
+ unzip perl_sh.zip -d f:/bin
+
+This is used by perl to run external commands which explicitely
+require shell, like the commands using I<redirection> and I<shell
+metacharacters>. It is also used instead of explicit F</bin/sh>.
+
+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>).
+
+=back
+
+After you installed the components you needed and updated the
+F<Config.sys> correspondingly, you need to hand-edit
+F<Config.pm>. This file resides somewhere deep in the location you
+installed your perl library, find it out by
+
+ perl -MConfig -le "print $INC{'Config.pm'}"
+
+You need to correct all the entries which look like file paths (they
+currently start with C<f:/>).
+
+=head2 B<Warning>
+
+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
+binary editing of paths inside the executables/DLLs.
+
+=head1 Accessing documentation
+
+Depending on how you built/installed perl you may have (otherwise
+identical) Perl documentation in the following formats:
+
+=head2 OS/2 F<.INF> file
+
+Most probably the most convinient form. View it as
+
+ view perl
+ view perl perlfunc
+ view perl less
+ view perl ExtUtils::MakeMaker
+
+(currently the last two may hit a wrong location, but this may improve
+soon).
+
+If you want to build the docs yourself, and have I<OS/2 toolkit>, run
+
+ pod2ipf > perl.ipf
+
+in F</perllib/lib/pod> directory, then
+
+ ipfc /inf perl.ipf
+
+(Expect a lot of errors during the both steps.) Now move it on your
+BOOKSHELF path.
+
+=head2 Plain text
+
+If you have perl documentation in the source form, perl utilities
+installed, and B<GNU> C<groff> installed, you may use
+
+ perldoc perlfunc
+ perldoc less
+ perldoc ExtUtils::MakeMaker
+
+to access the perl documention in the text form (note that you may get
+better results using perl manpages).
+
+Alternately, try running pod2text on F<.pod> files.
+
+=head2 Manpages
+
+If you have C<man> installed on your system, and you installed perl
+manpages, use something like this:
https://perl5.git.perl.org / perl5.git / blobdiff