perlos2.pod

MSYS在windows下模拟了一个类unix的终端

same file, 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 correctly start PM programs from VIO (=text-mode) Perl process;
the opposite is not true: when you start a non-PM program from a PM
Perl process, it 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 *

Did you run your programs with C<-w> switch? See 
L<Starting OS/2 (and DOS) programs under Perl>.

=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
need to specify your shell explicitly, like C<`cmd /c copy a b`>,
since Perl cannot deduce which commands are internal to your shell.

=back

=head2 I cannot embed perl into my program, or use F<perl.dll> from my
program. 

=over 4

=item Is your program 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 L<ExtUtils::Embed>?

I had reports it does not work. Somebody would need to fix it.

=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> 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 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>

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. In fact F<find.exe> cannot be started at all
using C library API only. Otherwise the following command-lines would be
equivalent:

  find "pattern" file
  find pattern file

=head1 INSTALLATION

=head2 Automatic binary installation

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
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.

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 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

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 zip files are not absolute, but
relative to some directory.

Note that the extraction with the stored paths is still necessary
(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
pkunzip), 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:

=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 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 PATH);

=item Executables for Perl utilities

  unzip perl_utl.zip -d f:/emx.add/bin

(have the directory on PATH);

=item Main Perl library

  unzip perl_mlb.zip -d f:/perllib/lib

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/5.8.3/

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">.

=item Tools to compile Perl modules

  unzip perl_blb.zip -d f:/perllib/lib

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 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 man to access these files.

=item Source for Perl documentation

  unzip perl_pod.zip -d f:/perllib/lib

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.

=item Perl manual in F<.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 explicitly
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 sh-compatible shell
(file globbing - if done via shell - may break).

=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 convenient form. Under OS/2 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). Under Win* see L<"SYNOPSIS">.

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 GNU groff installed, you may use 

	perldoc perlfunc
	perldoc less
	perldoc ExtUtils::MakeMaker

to access the perl documentation 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 man installed on your system, and you installed perl
manpages, use something like this:

	man perlfunc
	man 3 less
	man ExtUtils.MakeMaker

to access documentation for different components of Perl. Start with

	man perl

Note that dot (F<.>) is used as a package separator for documentation
for packages, and as usual, sometimes you need to give the section - C<3>
above - to avoid shadowing by the I<less(1) manpage>.

Make sure that the directory B<above> the directory with manpages is
on our C<MANPATH>, like this

  set MANPATH=c:/man;f:/perllib/man

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
HTML docs. Cd to directory with F<.pod> files, and do like this

	cd f:/perllib/lib/pod
	pod2html

After this you can direct your browser the file F<perl.html> in this
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 CPAN.

=head2 GNU C<info> files

Users of 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.

=head2 F<.PDF> files

for C<Acrobat> are available on CPAN (for slightly old version of
perl).

=head2 C<LaTeX> docs

can be constructed using C<pod2latex>.

=head1 BUILD

Here we discuss how to build Perl under OS/2. There is an alternative
(but maybe older) view on 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 F<*> is
a not-very-meaningful hex checksum), and run

  make installcmd INSTALLCMDDIR=d:/ir/on/path

What follows is a detailed guide through these steps.

=head2 Prerequisites

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