README.win32

If you read this file _as_is_, just ignore the funny characters you
see. It is written in the POD format (see pod/perlpod.pod) which is
specially designed to be readable as is.

=head1 NAME

perlwin32 - Perl under Win32

=head1 SYNOPSIS

These are instructions for building Perl under WindowsNT (versions
3.51 or 4.0), using Visual C++ (versions 2.0 through 5.0).  Currently,
this port may also build under Windows95, but you can expect problems
stemming from the unmentionable command shell that infests that
platform.  Note this caveat is only about B<building> perl.  Once
built, you should be able to B<use> it on either Win32 platform (modulo
the problems arising from the inferior command shell).

=head1 DESCRIPTION

Before you start, you should glance through the README file
found in the top-level directory where the Perl distribution
was extracted.  Make sure you read and understand the terms under
which this software is being distributed.

Also make sure you read the L<BUGS AND CAVEATS> section below for the
known limitations of this port.

The INSTALL file in the perl top-level has much information that is
only relevant to people building Perl on Unix-like systems.  In
particular, you can safely ignore any information that talks about
"Configure".

You should probably also read the README.os2 file, which gives a
different set of rules to build a Perl that will work on Win32
platforms.  That method will probably enable you to build a more
Unix-compatible perl, but you will also need to download and use
various other support software described in that file.

This set of instructions is meant to describe a so-called "native"
port of Perl to Win32 platforms.  The resulting Perl requires no
additional software to run (other than what came with your operating
system).  Currently, this port is only capable of using Microsoft's
Visual C++ compiler.  The ultimate goal is to support the other major
compilers that can be used to build Win32 applications.

This port currently supports MakeMaker (the set of modules that
is used to build extensions to perl).  Therefore, you should be
able to build and install most extensions found in the CPAN sites.

=head2 Setting Up

=over 4

=item *

Use the default "cmd" shell that comes with NT.  In particular, do
*not* use the 4DOS/NT shell.  The Makefile has commands that are not
compatible with that shell.  You are mostly on your own if you can
muster the temerity to attempt this with Windows95.

=item *

Run the VCVARS32.BAT file usually found somewhere like C:\MSDEV4.2\BIN.
This will set your build environment.

=item *

Depending on how you extracted the distribution, you have to make sure
all the files are writable by you.  The easiest way to make sure of
this is to execute:

	attrib -R *.* /S

from the perl toplevel directory.  You don't I<have> to do this if you
used the right tools to extract the files in the standard distribution,
but it doesn't hurt to do so.

=back

=head2 Building and Installation

=over 4

=item *

The "win32" directory contains *.mak files for use with the NMAKE that
comes with Visual C++ ver. 4.0 and above.  If you wish to build perl
using Visual C++ versions between 2.0 and 4.0, do the following two
additional steps (these steps are not required if you are
using Visual C++ versions 4.0 and above):

=over 8

=item 1.

Overwrite the *.mak files in the win32 subdirectory with the versions
in the win32\VC-2.0 directory.

=item 2.

Reset your INCLUDE environment variable to the MSVC include directory.
For example:

	set INCLUDE=E:\MSVC20\INCLUDE

This must have only one directory (a list of directories will not work).
VCVARS32.BAT may put multiple locations in there, which is why this step
is required.

=back

=item * 

Make sure you are in the "win32" subdirectory under the perl toplevel.

=item *

Type "nmake" while in the "win32" subdirectory.  This should build
everything.  Specifically, it will create perl.exe, perl.dll, and
perlglob.exe at the perl toplevel, and various other extension dll's
under the lib\auto directory.  If the make fails for any reason, make
sure you have done the previous steps correctly.

=item *

Type "nmake install".  This will put the newly built perl and the
libraries under C:\PERL.  If you want to alter this location, to say,
D:\FOO\PERL, you will have to say:

	nmake install INST_TOP=D:\FOO\PERL

instead.  To use the Perl you just installed, make sure you set your
PATH environment variable to C:\PERL\BIN (or D:\FOO\PERL\BIN).

=back

=head2 Testing

Type "nmake test".  This will run most of the tests from the
testsuite (many tests will be skipped, and but no test should fail).

If some tests do fail, it may be because you are using a different command
shell than the native "cmd.exe".  To get a more detailed breakdown of the
tests that failed, you may want to say:

       cd ..\t
       .\perl harness

Please report any failures as described under L<BUGS AND CAVEATS>.

=head1 BUGS AND CAVEATS

This is still very much an experimental port, and should be considered
alpha quality software.  You can expect changes in virtually all of
these areas: build process, installation structure, supported
utilities/modules, and supported perl functionality.  Specifically,
functionality specific to the Win32 environment may ultimately
be supported as either core modules or extensions.

If you have had prior exposure to Perl on Unix platforms, you will notice
this port exhibits behavior different from what is documented.  Most of the
differences fall under one of these categories.

=over 8

=item *

C<stat()> and C<lstat()> functions may not behave as documented.  They
may return values that bear no resemblance to those reported on Unix
platforms, and some fields may be completely bogus.

=item *

The following functions are currently unavailable: C<fork()>, C<exec()>,
C<dump()>, C<chown()>, C<link()>, C<symlink()>, C<chroot()>,
C<setpgrp()>, C<getpgrp()>, C<setpriority()>, C<getpriority()>,
C<syscall()>, C<fcntl()>, C<flock()>.  This list is possibly very
incomplete.

=item *

Various C<socket()> related calls are supported, but they may not
behave as on Unix platforms.

=item *

The four-argument C<select()> call is only supported on sockets.

=item *

The behavior of C<system()> or the C<qx[]> operator (a.k.a. "backticks"),
when used to call interactive commands, is ill-defined.

=item *

C<$?> ends up with the exitstatus of the subprocess (this is different
from Unix, where the exitstatus is actually given by "$? >> 8").
Failure to spawn() the subprocess is indicated by setting $? to 
"255<<8".  This is subject to change.

=item *

Building modules available on CPAN is mostly supported, but this
hasn't been tested much yet.  Expect strange problems, and be
prepared to deal with the consequences.

=item *

C<utime()>, C<times()> and process-related functions may not
behave as described in the documentation, and some of the
returned values or effects may be bogus.

=item *

Signal handling may not behave as on Unix platforms.

=item *

File globbing may not behave as on Unix platforms.

=item *

Not all of the utilities that come with the Perl distribution
are supported yet.

=back

Please send detailed descriptions of any problems and solutions that 
you may find to <F<perlbug@perl.com>>, along with the output produced
by C<perl -V>.

=head1 AUTHORS

=over 4

=item Gary Ng <F<71564.1743@CompuServe.COM>>

=item Gurusamy Sarathy <F<gsar@umich.edu>>

=item Nick Ing-Simmons <F<nick@ni-s.u-net.com>>

=back

=head1 SEE ALSO

L<perl>

=head1 HISTORY

This port was originally contributed by Gary Ng around 5.003_24,
and borrowed from the Hip Communications port that was available
at the time.

Nick Ing-Simmons and Gurusamy Sarathy have made numerous and
sundry hacks since then.

Last updated: 05 April 1997

=cut