Welcome to the binary distribution of Perl for the Win32 platform.
This distribution has been compiled using the Borland C++ compiler
(version 5.02).  It is built around the latest production release of
Perl, version 5.004_02, which comes with Win32 support.

Please note that this distribution is not to be confused with
the pre-5.004 Perl port by the Activeware folks, or the binaries
they distribute (which are mostly referred to by "build" numbers).

This bundle contains almost everything you will need for using Perl
on Win32 platforms.  It also contains everything needed to build,
test and install additional perl modules from CPAN that you may not
find in here, provided they use the standard MakeMaker extension
build tools.  Since MakeMaker needs a `make' utility, a Win32 binary
of Dennis Vadura's `dmake' tool is supplied (see below for more on
`dmake').  For using this distribution to build extensions that need
a C compiler, you will also need either Borland C++ 5.02, or Visual
C++ (version 2.0 and later).


WHY WOULD YOU WANT THIS?
------------------------

  + You want to use perl on WindowsNT or Windows95, but you have
    no C compiler (or at least not one that will build perl).
 
  + You seem to have the compiler stuff, but not the patience or
    knowledge to deal with compiling perl and the various extensions.
    And you are happy to continue using the binary distributions that
    you know people are going to keep putting out once every half
    moon. [May not be exactly every half moon, but you'll keep the
    faith.  Remember to give away that compiler you don't use :)]
 
  + You have one of the supported compilers that will build Perl,
    but you want to jump-start your XSsively hardcore perl module
    development by taking this shortcut.  [But see the notes below
    on `USING IT WITH YOUR C COMPILER' for some caveats about doing
    this.]

  + You want a perl that is capable of doing sockets on Windows95,
    and you just have Visual C++. [The Visual C++ libraries known to
    date have a problem with sockets on Windows95, which might cause
    you trouble.  The Borland libraries, which this distribution was
    built with, do not have the problem.]
 

INSTALLATION
------------

To install:

   * Extract the archive so that the directory structure of the
     files is preserved.

   * `cd' to the top level directory.

   * Type `install' (if in the command shell) or click on
     `install.bat' (from the Explorer).  If that refuses to run for
     some reason, you can instead type `perl\bin\perl install.bat'
     in the command shell.  The setup process will ask a few
     questions and will offer to generate HTML documentation from
     the various files in the distribution.  A full installation
     requires about 20 megabytes of free space.

   * Add the installed location of PERL.EXE to your `PATH'.
     For instance, if you asked for things to be installed under
     `e:\perl', add `e:\perl\bin' to your PATH.

   * You will need to edit the contents of %NetConfig in
     `lib\site\Net\Config.pm' to set the names of the servers
     used by the libnet package.


PLATFORMS
---------

This binary distribution has been extensively tested only on WindowsNT.
Based on reports from others, I believe it also works on Windows95,
but I personally did not test it on that platform.  Note the supplied
binaries are for the x86 architecture.


WHAT IT CONTAINS
----------------

It includes the following packages:

	perl5.004_02
	dmake-4.1

	Alias-2.3
	Bit-Vector-4.2
	Curses-1.01                          [*]
	Data-Dumper-2.07
	DateCalc-3.2
	DateManip-5.10
	DBD-ODBC-0.16
	DBI-0.89
	Devel-Peek-0.83
	Devel-Symdump-2.00
	DProf-19970614                       [*]
	GD-1.14                              [*]
	libnet-1.0505                        [*]
	libwin32-0.08
	libwww-perl-5.11
	MD5-1.7
	MIME-Base64-2.03
	MLDBM-1.23
	Storable-0.5                         [*]
	String-Approx-2.1
	Tk402.002

NOTES:

[*] These packages needed porting or other fixes to compile and
    run properly.  All changes are included in the form of patches
    (the kind that can be applied using the GNU patch utility) in
    the `patches' subdirectory.  The full sources of all of
    these packages (with the exception of dmake, see below for that)
    can be found on the Comprehensive Perl Archive Network (CPAN).
    Point your web browser at "http://www.perl.com/CPAN" to find the
    CPAN site nearest you.

The package subdirectories under `distfiles' also contain other
documentation and testsuites that came with the package.  These are
not installed, so you may want to save them for later reference.

Please note that the patches are for information purposes only.
You don't have to apply them (or even know what a patch is) to use
this distribution.

In case you find yourself needing to build things from source, there
is a win32 port of GNU patch-2.1 at:
   http://www-personal.umich.edu/~gsar/patch2_1-win32.tar.gz
that can be used to apply the included patches.

The modules in the distribution doubtless reflect my own personal
pattern of use.  In some cases, I made a conscious decision not to
include modules that don't contain C or XS source, since it should be
possible to obtain, build and install such modules from CPAN without
too much trouble (or a C compiler), using perl and `dmake'.
Nevertheless, I shall add specific modules to the distribution if
there is demand.


DEMOS
-----

After you install the distribution and add its location to your PATH,
you can run the `widget' demo to check if your installed perl is
working properly.  To make sure your new PATH setting takes effect,
you may have to reboot.  Afterward, just type `widget' in the command
shell, or double-click on `widget.bat' from the Explorer.


DOCUMENTATION
-------------

If you choose, the installation process converts all the Plain Old
Documentation it can find into HTML pages.  There are normally stored
in the `html' subdirectory under the install location.  You can start
browsing the main perl documentation at `html/lib/pod/perl.html'.

If you choose not to install HTML, you can still browse almost
all of the perl documentation from the command line using `perldoc'.
Type `perldoc perldoc' to get started.

The `distfiles' area of the distribution also contains much HTML
documentation that is not handled by the install process.  You
may want to selectively copy parts of it to wherever you normally
install your web documents.


USING IT WITH YOUR C COMPILER
-----------------------------

If you don't have a supported C compiler, this section doesn't
apply to you.  If you have one, and intend using it to build
other modules that require a C compiler, then read on.

This distribution was compiled with Borland C++ 5.02, using `dmake'.
If you too have that compiler (or a later version), there are
no caveats about using this distribution for further builds of
extensions.  (I have heard earlier versions of Borland C++ have
a buggy linker that doesn't like the module definition files that
perl generates, so your mileage may vary if you're using
versions earlier than 5.02.)

If you don't have the Borland compiler, it is also possible to build
and use extension binaries compiled with Visual C++.  The converse--
using a perl binary built under Visual C++ with extension binaries
built under Borland C++--does not work due to a bug in the Visual
C++ linker (present as of version 5.0).  In other words, if you have
the Visual C++ compiler *and* you plan to use some pre-built
extensions in this distribution *and* compile some of your own using
the Visual C++ compiler, you will need the perl binaries that came
with this distribution.  So don't overwrite the perl binary with
one that you may have built yourself using the Visual C++ compiler.

The setup procedure will do the necessary things to make sure the
installed version of the `lib\Config.pm' file will work with your
compiler for future extension builds.
 

TERMS OF USE
------------

Perl can be freely distributed under the `Artistic License' or the
`GNU General Public Licence', described in the two files `Artistic'
and `Copying' respectively.  Most of the modules have statements to
the effect that they can be distributed under the same terms as Perl,
but you should download and check the individual module's sources to
be sure.

The included dmake tool is compiled from the latest public release of
dmake-4.1 available from `ftp://plg.uwaterloo.ca/pub/dmake/'.  The
binary is completely unsupported.  Full (commercial) support for dmake
may be obtained from its author.  See `http://dmake.wticorp.com/' for
the latest.  Note that public version of dmake-4.1 can only be
distributed under the GNU General Public Licence.

The remaining parts of this binary distribution itself can be
distributed under the same terms as Perl.  Beware that it is provided
"as is", and comes with absolutely no warranty of any kind, either
express or implied.  If you use the contents of this distribution, you
do so at your own risk, and you agree to free the author(s) of any
consequences arising from such use, either intended or otherwise.


BEING NICE TO NICE BEINGS
-------------------------

Perl is the creation of Larry Wall.  Continuing refinement of Perl
is made possible by the unceasing efforts of many fine folk who have
banded together with Larry in endless perlesque banter, collectively
calling themselves "The Perl Porters".  If you find perl useful
in getting your job done, you may want to drop them a note of
appreciation at <perl-thanks@perl.org>.  Be sure to recount
any war stories about how Perl helped you win your battles :)

Another fine way to encourage development of perl is to become a
member of The Perl Institute, a non-profit organization which helps
"people help Perl help people" (or something like that).  See
http://www.perl.org/ for details.

If you plan to put this on a CDROM or other similar media, I request
that you send me a brief message.  Note that some modules explicitly
require that you obtain permission from the module author to do that
sort of thing, so you should.  Altered versions of this distribution
must be clearly marked as such.

Enjoy!


Gurusamy Sarathy (Just Another Perl Porter)
gsar@umich.edu
08-AUG-1997

