--- ./README.os2-pre	Tue Sep 30 09:09:48 2003
+++ ./README.os2	Mon Dec 15 02:34:14 2003
@@ -869,7 +869,10 @@ compatibility with XFree86-OS/2). Get a 
 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. 
+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
@@ -1088,6 +1091,160 @@ 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.  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.
+
+=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
+
+  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
+in subdirectories may be buggy, and would not run as "child" scripts.  The
+interdependency of modules can strike you; however, since non-XS modules
+are already installed, the prerequisites of most modules have a very good
+chance to be present.
+
+If you discover some glitches, move directories of problematic modules to a
+different location; if these modules are non-XS modules, you may just ignore
+them - they are already installed; the remaining, XS, modules you need to
+install manually one by one.
+
+After each such removal you need to rerun the C<Makefile.PL>/C<make> process;
+usually this procedure converges soon.  (But be sure to convert all the
+necessary external C libraries from F<.lib> format to F<.a> format: run one of
+
+  emxaout foo.lib
+  emximp -o foo.a foo.lib
+
+whichever is appropriate.)
+
+When you are satisfied with the results of tests, install the build C libraries
+for extensions:
+
+  make install |& tee 00aout_i
+
+Now you can rename the file C<./perl.exe> generated during the C<test> phase
+to C<perl_5.8.2.exe>; if there is an inter-dependency between some XS modules,
+you may need to repeat the C<test>/C<install> loop with this new executable
+and some excluded modules - until the procedure converges.
+
+When it converges, you got a functional variant of C<perl_5.8.2.exe>; copy it
+to C<perl_.exe>.  You are done with generation of the local Perl installation.
+
+=item 8.
+
+Make sure that the installed modules are actually installed in the location
+of the new Perl, and are not inherited from entries of @INC given for
+inheritance from the older versions of Perl: set C<PERLLIB_582_PREFIX> to
+redirect the new version of Perl to a new location, and move the installed
+files to this new location.  Redo the tests to make sure that the versions of
+modules inherited from older versions of Perl are not needed.
+
+=item 9.
+
+Now you can generate the binary distribution.  This is done by running the
+test of the CPAN distribution C<OS2::SoftInstaller>.  Tune up the file
+F<test.pl> to suit the layout of current version of Perl first.  Do not
+forget to pack the necessary external DLLs accordingly.  Include the
+description of the bugs and test suite failures you could not fix.  Include
+the small-stack versions of Perl executables from Perl build directory.
+
+=item 10.
+
+Share what you did with the other people.  Relax.  Enjoy fruits of your work.
+
+=item 11.
+
+Brace yourself for thanks, bug reports, hate mail and spam coming as result
+of the previous step.  No good deed should remain unpunished!
+
+=back
 
 =head1 Build FAQ
 
