perlos2.pod

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

  find --version
  sort --version

). You need the latest version of F<pdksh> installed as F<sh.exe>.

Check that you have B<BSD> libraries and headers installed, and - 
optionally - Berkeley DB headers and libraries, and crypt.

Possible locations to get this from are

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

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. 

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 .

if you use something like F<CMD.EXE> or latest versions of F<4os2.exe>.

Make sure your gcc is good for C<-Zomf> linking: run C<omflibs>
script in F</emx/lib> directory.

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

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/

may indicate the latest release which was publicly released by the
maintainer. Note that the release may include some additional patches
to apply to the current source of perl.

Extract it like this

  tar vzxf perl5.00409.tar.gz

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

Change to the directory of extraction.

=head2 Application of the patches

You need to apply the patches in F<./os2/diff.*> like this:

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

  ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/db_mt.zip

=head2 Hand-editing

You may look into the file F<./hints/os2.sh> and correct anything
wrong you find there. I do not expect it is needed anywhere.

=head2 Making

  sh Configure -des -D prefix=f:/perllib

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

Now run

  make test

All tests should succeed (with some of them skipped).

Some tests may generate extra messages similar to

=over 4

=item A lot of C<bad free>

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

=item Process terminated by SIGTERM/SIGINT

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. 

However the test engine bleeds these message to screen in unexpected
moments. Two messages of this kind I<should> be present during
testing.

=back

To get finer test reports, call

  perl t/harness

The report with F<io/pipe.t> failing may look like this:

  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:

=over 8

=item F<op/fs.t>

=over 4

=item 18

Checks C<atime> and C<mtime> of C<stat()> - unfortunately, HPFS
provides only 2sec time granularity (for compatibility with FAT?).

=item 25

Checks C<truncate()> on a filehandle just opened for write - I do not
know why this should or should not work.

=back

=item F<op/stat.t>

Checks C<stat()>. Tests:

=over 4

=item 4

Checks C<atime> and C<mtime> of C<stat()> - unfortunately, HPFS
provides only 2sec time granularity (for compatibility with FAT?).

=back

=back

=head2 Installing the built perl

If you haven't yet moved perl.dll onto LIBPATH, do it now.

Run

  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
PATH, F<perl.dll> to a location on your LIBPATH.

Run

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

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

=head2 C<a.out>-style build

Proceed as above, but make F<perl_.exe> (see L<"perl_.exe">) by

  make perl_

test and install by

  make aout_test
  make aout_install

Manually put F<perl_.exe> to a location on your PATH.

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

  make perl_dll

first.

=head1 Build FAQ

=head2 Some C</> became C<\> in pdksh.

You have a very old pdksh. See L<Prerequisites>.

=head2 C<'errno'> - unresolved external

You do not have MT-safe F<db.lib>. See L<Prerequisites>.

=head2 Problems with tr or sed

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 LIBPATH, which
broke the build of extensions.

=head2 Library ... not found

You did not run C<omflibs>. See L<Prerequisites>.

=head2 Segfault in make

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

=head2 C<setpriority>, C<getpriority>

Note that these functions are compatible with *nix, not with the older
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 can lock the
system before Warp3 fixpak22.

=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>.  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> is not found, and appending of executable extensions to
F</bin/bash> does not help either, then Perl looks for an executable F<bash> 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 different type than the
current session, it will start the new process in a separate session of
necessary type.  Call via C<OS2::Process> to disable this magic.

=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::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 C<ILYAZ> directory, mirrored on CPAN.

=head2 Prebuilt methods:

=over 4

=item C<File::Copy::syscopy>

used by C<File::Copy::copy>, see L<File::Copy>.

=item C<DynaLoader::mod2fname>

used by C<DynaLoader> for DLL name mangling.

=item  C<Cwd::current_drive()>

Self explanatory.

=item  C<Cwd::sys_chdir(name)>

leaves drive as it is.

=item  C<Cwd::change_drive(name)>

chanes the "current" drive.

=item  C<Cwd::sys_is_absolute(name)>

means has drive letter and is_rooted.

=item  C<Cwd::sys_is_rooted(name)>

means has leading C<[/\\]> (maybe after a drive-letter:).

=item  C<Cwd::sys_is_relative(name)>

means changes with current dir.

=item  C<Cwd::sys_cwd(name)>

Interface to cwd from EMX. Used by C<Cwd::cwd>.

=item  C<Cwd::sys_abspath(name, dir)>

Really really odious function to implement. Returns absolute name of
file which would have C<name> if CWD were C<dir>.  C<Dir> defaults to the
current dir.

=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