X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=README.os2;h=bb1adb12488ac69d7e5b5ca4ae9456feebf0fe39;hb=ca9279baf07d6843f58a31f1ce3ff7dc875faf1a;hp=e6782e3dc127220ae031b4dfd98614d09fac5888;hpb=df3ef7a9a68db503d1aecd7cb40d5f974fa0066b;p=p5sagit%2Fp5-mst-13.2.git
diff --git a/README.os2 b/README.os2
index e6782e3..bb1adb1 100644
--- a/README.os2
+++ b/README.os2
@@ -27,93 +27,114 @@ 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. This gives one an access to B's
+in F. This gives one an access to EMX's
F<.INF> docs as well (text form is available in F in
-B's distribution).
+EMX's distribution). There is also a different viewer named xview.
+
+Note that if you have F or F 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
+working by setting C environment variable as it is described
+in EMX docs).
=cut
-Contents
+Contents (This may be a little bit obsolete)
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
- - 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.
- - `` and pipe-open do not work under DOS.
- 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
- - Modifications
- 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
- - Memory allocation
- AUTHOR
- SEE ALSO
-
+ 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, 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 hard).
The current state is quite close to this target. Known limitations:
@@ -121,20 +142,33 @@ 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 Iing 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
+Iing dynamically loading extensions would not work with I old
+versions of EMX.
=item *
You need a separate perl executable F (see L)
-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 from a text-mode window is possible
+too, I have seen cases when this causes degradation of the system stability.
+Using F avoids such a degradation.
=item *
-There is no simple way to access B objects. The only way I know
-is via C extension (see L), and we do not have access to
-convenience methods of B. (Is it possible at all? I know
-of no B API.)
+There is no simple way to access WPS objects. The only way I know
+is via C and C extensions (see L, L).
+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 extension (currently in alpha-text)
+may eventually remove this shortcoming; however, due to the fact that
+DII is not supported by the C module, using C is not as
+convenient as one would like it.
=back
@@ -142,15 +176,15 @@ 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 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 - most
-probably C - decided to implement.
+probably RSX - decided to implement.
Cf. L.
@@ -158,67 +192,87 @@ Cf. L.
=over 6
-=item B
+=item EMX
-B runtime is required (may be substituted by B). Note that
+EMX runtime is required (may be substituted by RSX). Note that
it is possible to make F to run under DOS without any
external support by binding F/F to it, see L. Note
-that under DOS for best results one should use B runtime, which
+that under DOS for best results one should use RSX runtime, which
has much more functions working (like C, C and so on). In
-fact B is required if there is no C present. Note the
-B requires C.
+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 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.
-B. It is enough to have F/F on your path. One
+B. When using F/F, 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
+=item RSX
-To run Perl on C platforms one needs B 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 would not work with C
-only, as B would, it requires C.
+L<"Other OSes">). RSX would not work with VCPI
+only, as EMX would, it requires DMPI.
-Having B and the latest F one gets a fully functional
+Having RSX and the latest F one gets a fully functional
B<*nix>-ish environment under DOS, say, C, C<``> and
pipe-C work. In fact, MakeMaker works (for static build), so one
can have Perl development environment under DOS.
-One can get B 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.
-The latest F with DOS hooks is available at
+The latest F with DOS hooks is available in
- ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/sh_dos.exe
+ http://www.ilyaz.org/software/os2/
-=item B
+as F or under similar names starting with C, C etc.
-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.
+=item HPFS
+
+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 to truncate file names. This is not supported,
-read B 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, and located
+either in the wired-in-during-compile locations (usually F),
+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) 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 with arguments C the
same way as on any other platform, by
@@ -226,37 +280,32 @@ 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 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, and start it by typing
foo arg1 arg2 arg3
-(Note that having *nixish full path to perl F is not
-necessary, F 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, 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. 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 line
+in your script, see L on the first line>).
To understand what the above I does, read perl docs about C<-S>
-and C<-x> switches - see L, and cmdref about C:
+switch - see L, and cmdref about C:
view perl perlrun
man perlrun
@@ -266,11 +315,14 @@ and C<-x> switches - see L, and cmdref about C:
or whatever method you prefer.
There are also endless possibilities to use I of
-B<4OS2>, I of B and so on... However, if you use
+4os2, I of WPS and so on... However, if you use
*nixish shell (like F supplied in the binary distribution),
you need to follow the syntax specified in L.
-=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), C<``> (see
L), and I (see L)
@@ -278,27 +330,116 @@ are for. (Avoid exec() (see L) unless you know what you
do).
Note however that to use some of these operators you need to have a
-C-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)/exec() (see L), 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), exec() (see L)
+with redirection or shell meta-characters;
+
+=item 2
+
+Pipe-open (see L) with the command which contains redirection
+or shell meta-characters;
+
+=item 3
+
+Backticks C<``> (see L) 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 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, L)
+(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 or C<#!> directly, without an intervention of shell. Perl uses the
+same algorithm to find the executable as F: 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. To find arguments for these scripts
+Perl uses a different algorithm than F: 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, Perl uses
+the same algorithm as F: 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 will not look for a script if
+there is an executable file F I on C. In
+other words, C 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 and F denote the
+same file (at list on FAT and HPFS file systems), to start an executable residing in file F (no
+extension) give an argument C (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, or start it using
+optional arguments to system() documented in C module. This
+is considered to be a feature.
=head1 Frequently asked questions
+=head2 "It does not work"
+
+Perl binary distributions come with a F 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.
+L.
-=item
+=item *
Do you try to run I shell commands, like C<`copy a b`>
(internal for F), or C<`glob a*b`> (internal for ksh)? You
@@ -312,44 +453,81 @@ program.
=over 4
-=item Is your program B-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), 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?
+=item Did you use L?
-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 do not work under DOS.
This may a variant of just L<"I cannot run external programs">, or a
-deeper problem. Basically: you I B (see L<"Prerequisites">)
+deeper problem. Basically: you I RSX (see L<"Prerequisites">)
for these commands to work, and you may need a port of F which
understands command arguments. One of such ports is listed in
-L<"Prerequisites"> under B.
+L<"Prerequisites"> under RSX. Do not forget to set variable
+C> as well.
+
+DPMI is required for RSX.
-C is required for B.
+=head2 Cannot start C
+
+The whole idea of the "standard C API to start applications" is that
+the forms C and C<"foo"> of program arguments are completely
+interchangable. F breaks this paradigm;
+
+ find "pattern" file
+ find pattern file
+
+are not equivalent; F 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 via F via C via
+C, 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. Just follow the instructions, and 99% of the
installation blues would go away.
Note however, that you need to have F on your path, and
-B environment I. The latter means that if you just
-installed B, and made all the needed changes to F,
-you may need to reboot in between. Check B runtime by running
+EMX environment I. The latter means that if you just
+installed EMX, and made all the needed changes to F,
+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. 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
@@ -358,7 +536,7 @@ B
=item C
may be needed if you change your codepage I perl installation,
-and the new value is not supported by B. See L<"PERL_BADLANG">.
+and the new value is not supported by EMX. See L<"PERL_BADLANG">.
=item C
@@ -373,19 +551,25 @@ perl library, find it out by
While most important values in this file I 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. Because of a typo the binary installer of 5.00305
+would install a variable C into F. Please
+remove this variable and put C> 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 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, specify C<-d> to C). 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 to reflect where did you put the
files. Note that if you have some primitive unzipper (like
@@ -393,7 +577,14 @@ C), you may get a lot of warnings/errors during
unzipping. Upgrade to C<(w)unzip>.
Below is the sample of what to do to reproduce the configuration on my
-machine:
+machine. In F you can press C now, and
+cut-and-paste from the resulting file - created in the directory you
+started F 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
@@ -402,70 +593,76 @@ machine:
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, and C<*.dll> on
-C);
+(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);
+(have the directory on PATH);
=item Executables for Perl utilities
unzip perl_utl.zip -d f:/emx.add/bin
-(have the directory on C);
+(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, you do not need to change
+anything. However, for perl to find the library if you use a different
+path, you need to
C in F, 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.8.3/
-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), you
+need to put this
directory and subdirectory F<./os2> in C or C
variable. Do not use C unless you have it set already. See
-L.
+L.
+
+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 in F, see L<"PERLLIB_PREFIX">.
+Same remark as for F.
=item Manpages for Perl and utilities
unzip perl_man.zip -d f:/perllib/man
This directory should better be on C. You need to have a
-working C to access these files.
+working F to access these files.
=item Manpages for Perl modules
unzip perl_mam.zip -d f:/perllib/man
This directory should better be on C. You need to have a
-working C 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 program (see L), and may be used to
-generate B documentation usable by WWW browsers, and
+This is used by the C program (see L), and may be used to
+generate HTML documentation usable by WWW browsers, and
documentation in zillions of other formats: C, C,
-C, C and so on.
+C, C and so on. [Use programs such as
+F etc.]
-=item Perl manual in .INF format
+=item Perl manual in F<.INF> format
unzip perl_inf.zip -d d:/os2/book
@@ -482,8 +679,7 @@ metacharacters>. It is also used instead of explicit F.
Set C (see L<"PERL_SH_DIR">) if you move F from
the above location.
-B It may be possible to use some other C-compatible shell
-(I).
+B It may be possible to use some other sh-compatible shell (untested).
=back
@@ -501,7 +697,7 @@ currently start with C ).
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
@@ -511,7 +707,7 @@ identical) Perl documentation in the following formats:
=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
@@ -519,7 +715,7 @@ Most probably the most convenient form. View it as
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, run
@@ -535,7 +731,7 @@ BOOKSHELF path.
=head2 Plain text
If you have perl documentation in the source form, perl utilities
-installed, and B C installed, you may use
+installed, and GNU groff installed, you may use
perldoc perlfunc
perldoc less
@@ -548,7 +744,7 @@ Alternately, try running pod2text on F<.pod> files.
=head2 Manpages
-If you have C installed on your system, and you installed perl
+If you have F installed on your system, and you installed perl
manpages, use something like this:
man perlfunc
@@ -568,11 +764,13 @@ on our C, like this
set MANPATH=c:/man;f:/perllib/man
-=head2 B
+for Perl manpages in C 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 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
@@ -582,17 +780,17 @@ directory, and go ahead with reading docs, like this:
explore file:///f:/perllib/lib/pod/perl.html
-Alternatively you may be able to get these docs prebuilt from C.
+Alternatively you may be able to get these docs prebuilt from CPAN.
-=head2 B C files
+=head2 GNU C files
-Users of C would appreciate it very much, especially with
-C mode loaded. You need to get latest C from C,
-or, alternately, prebuilt info pages.
+Users of Emacs would appreciate it very much, especially with
+C mode loaded. You need to get latest C from C,
+or, alternately, the prebuilt info pages.
-=head2 F<.PDF> files
+=head2 F files
-for C are available on CPAN (for slightly old version of
+for C are available on CPAN (may be for slightly older version of
perl).
=head2 C docs
@@ -604,10 +802,37 @@ can be constructed using C.
Here we discuss how to build Perl under OS/2. There is an alternative
(but maybe older) view on L.
+=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, manually move the built F to C (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-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 development environment, the full
-B tool suite (C