perlos2.pod

视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.

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

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

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

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

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

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

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

=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 Building a binary distribution

[This section provides a short overview only...]

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

=over

=item 1.

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.

=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

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

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

  CPAN> o conf index_expire 365
  CPAN> o conf commit

Reset back to the default value C<1> when you are finished.

=item 5.

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.

=item 6.

Change to the C<./pod> directory of the build tree, download the Perl logo
F<CamelGrayBig.BMP>, and run

  ( perl2ipf > perl.ipf ) |& tee 00ipf
  ipfc /INF perl.ipf |& tee 00inf

This produces the Perl docs online book C<perl.INF>.  Install in on
C<BOOKSHELF> path.

=item 7.

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.

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

  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