[p5sagit/p5-mst-13.2.git] / 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 a few tests may fail).

To get a more detailed breakdown of the tests that failed, 
you may want to say:

       cd ..\t
       .\perl harness

This should produce a summary of the failed tests.  Currently, the
only known failure is lib\findbin.t:

    Failed Test  Status Wstat Total Fail  Failed  List of failed
    ------------------------------------------------------------------------------
    lib/findbin.t                 1    1 100.00%  1
    Failed 1/151 test scripts, 99.34% okay. 1/3902 subtests failed, 99.97% okay.


Check if any additional tests other than the ones shown here
failed, and report them 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 that supports the Win32 environment may ultimately
be supported as either core modules or extensions.

If you have had prior exposure to Perl on Unix platforms, this port
may exhibit 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: 04 April 1997

=cut
Commit	Line	Data
68dc0745	1	If you read this file _as_is_, just ignore the funny characters you
	2	see. It is written in the POD format (see pod/perlpod.pod) which is
	3	specially designed to be readable as is.
	4
	5	=head1 NAME
	6
5aabfad6	7	perlwin32 - Perl under Win32
68dc0745	8
	9	=head1 SYNOPSIS
	10
	11	These are instructions for building Perl under WindowsNT (versions
5aabfad6	12	3.51 or 4.0), using Visual C++ (versions 2.0 through 5.0). Currently,
	13	this port may also build under Windows95, but you can expect problems
	14	stemming from the unmentionable command shell that infests that
	15	platform. Note this caveat is only about B<building> perl. Once
	16	built, you should be able to B<use> it on either Win32 platform (modulo
	17	the problems arising from the inferior command shell).
68dc0745	18
	19	=head1 DESCRIPTION
	20
3fe9a6f1	21	Before you start, you should glance through the README file
68dc0745	22	found in the top-level directory where the Perl distribution
	23	was extracted. Make sure you read and understand the terms under
	24	which this software is being distributed.
	25
3fe9a6f1	26	Also make sure you read the L<BUGS AND CAVEATS> section below for the
68dc0745	27	known limitations of this port.
	28
	29	The INSTALL file in the perl top-level has much information that is
	30	only relevant to people building Perl on Unix-like systems. In
	31	particular, you can safely ignore any information that talks about
	32	"Configure".
	33
	34	You should probably also read the README.os2 file, which gives a
	35	different set of rules to build a Perl that will work on Win32
	36	platforms. That method will probably enable you to build a more
	37	Unix-compatible perl, but you will also need to download and use
	38	various other support software described in that file.
	39
	40	This set of instructions is meant to describe a so-called "native"
	41	port of Perl to Win32 platforms. The resulting Perl requires no
	42	additional software to run (other than what came with your operating
	43	system). Currently, this port is only capable of using Microsoft's
	44	Visual C++ compiler. The ultimate goal is to support the other major
5aabfad6	45	compilers that can be used to build Win32 applications.
	46
	47	This port currently supports MakeMaker (the set of modules that
	48	is used to build extensions to perl). Therefore, you should be
	49	able to build and install most extensions found in the CPAN sites.
68dc0745	50
	51	=head2 Setting Up
	52
	53	=over 4
	54
	55	=item *
	56
	57	Use the default "cmd" shell that comes with NT. In particular, do
	58	not use the 4DOS/NT shell. The Makefile has commands that are not
5aabfad6	59	compatible with that shell. You are mostly on your own if you can
5aabfad6	60	muster the temerity to attempt this with Windows95.
68dc0745	61
	62	=item *
	63
	64	Run the VCVARS32.BAT file usually found somewhere like C:\MSDEV4.2\BIN.
	65	This will set your build environment.
	66
	67	=item *
	68
	69	Depending on how you extracted the distribution, you have to make sure
	70	all the files are writable by you. The easiest way to make sure of
	71	this is to execute:
	72
	73	attrib -R . /S
	74
	75	from the perl toplevel directory. You don't I<have> to do this if you
	76	used the right tools to extract the files in the standard distribution,
	77	but it doesn't hurt to do so.
	78
	79	=back
	80
	81	=head2 Building and Installation
	82
	83	=over 4
	84
	85	=item *
	86
	87	The "win32" directory contains *.mak files for use with the NMAKE that
	88	comes with Visual C++ ver. 4.0 and above. If you wish to build perl
3fe9a6f1	89	using Visual C++ versions between 2.0 and 4.0, do the following two
3fe9a6f1	90	additional steps (these steps are not required if you are
68dc0745	91	using Visual C++ versions 4.0 and above):
	92
	93	=over 8
	94
	95	=item 1.
	96
	97	Overwrite the *.mak files in the win32 subdirectory with the versions
3fe9a6f1	98	in the win32\VC-2.0 directory.
68dc0745	99
	100	=item 2.
	101
	102	Reset your INCLUDE environment variable to the MSVC include directory.
	103	For example:
	104
	105	set INCLUDE=E:\MSVC20\INCLUDE
	106
	107	This must have only one directory (a list of directories will not work).
	108	VCVARS32.BAT may put multiple locations in there, which is why this step
	109	is required.
	110
68dc0745	111	=back
	112
	113	=item *
	114
	115	Make sure you are in the "win32" subdirectory under the perl toplevel.
	116
	117	=item *
	118
	119	Type "nmake" while in the "win32" subdirectory. This should build
	120	everything. Specifically, it will create perl.exe, perl.dll, and
	121	perlglob.exe at the perl toplevel, and various other extension dll's
	122	under the lib\auto directory. If the make fails for any reason, make
	123	sure you have done the previous steps correctly.
	124
	125	=item *
	126
	127	Type "nmake install". This will put the newly built perl and the
	128	libraries under C:\PERL. If you want to alter this location, to say,
	129	D:\FOO\PERL, you will have to say:
	130
	131	nmake install INST_TOP=D:\FOO\PERL
	132
	133	instead. To use the Perl you just installed, make sure you set your
	134	PATH environment variable to C:\PERL\BIN (or D:\FOO\PERL\BIN).
	135
	136	=back
	137
	138	=head2 Testing
	139
	140	Type "nmake test". This will run most of the tests from the
5aabfad6	141	testsuite (many tests will be skipped, and a few tests may fail).
68dc0745	142
5aabfad6	143	To get a more detailed breakdown of the tests that failed,
5aabfad6	144	you may want to say:
68dc0745	145
	146	cd ..\t
	147	.\perl harness
	148
5aabfad6	149	This should produce a summary of the failed tests. Currently, the
5aabfad6	150	only known failure is lib\findbin.t:
68dc0745	151
	152	Failed Test Status Wstat Total Fail Failed List of failed
	153	------------------------------------------------------------------------------
68dc0745	154	lib/findbin.t 1 1 100.00% 1
5aabfad6	155	Failed 1/151 test scripts, 99.34% okay. 1/3902 subtests failed, 99.97% okay.
3fe9a6f1	156
68dc0745	157
68dc0745	158	Check if any additional tests other than the ones shown here
5aabfad6	159	failed, and report them as described under L<BUGS AND CAVEATS>.
68dc0745	160
	161	=head1 BUGS AND CAVEATS
	162
	163	This is still very much an experimental port, and should be considered
	164	alpha quality software. You can expect changes in virtually all of
	165	these areas: build process, installation structure, supported
	166	utilities/modules, and supported perl functionality. Specifically,
3fe9a6f1	167	functionality that supports the Win32 environment may ultimately
68dc0745	168	be supported as either core modules or extensions.
68dc0745	169
5aabfad6	170	If you have had prior exposure to Perl on Unix platforms, this port
	171	may exhibit behavior different from what is documented. Most of the
	172	differences fall under one of these categories.
68dc0745	173
	174	=over 8
	175
	176	=item *
	177
	178	C<stat()> and C<lstat()> functions may not behave as documented. They
	179	may return values that bear no resemblance to those reported on Unix
	180	platforms, and some fields may be completely bogus.
	181
	182	=item *
	183
	184	The following functions are currently unavailable: C<fork()>, C<exec()>,
5aabfad6	185	C<dump()>, C<chown()>, C<link()>, C<symlink()>, C<chroot()>,
68dc0745	186	C<setpgrp()>, C<getpgrp()>, C<setpriority()>, C<getpriority()>,
5aabfad6	187	C<syscall()>, C<fcntl()>, C<flock()>. This list is possibly very
5aabfad6	188	incomplete.
68dc0745	189
	190	=item *
	191
	192	Various C<socket()> related calls are supported, but they may not
	193	behave as on Unix platforms.
	194
	195	=item *
	196
	197	The four-argument C<select()> call is only supported on sockets.
	198
	199	=item *
	200
	201	The behavior of C<system()> or the C<qx[]> operator (a.k.a. "backticks"),
	202	when used to call interactive commands, is ill-defined.
	203
	204	=item *
	205
5aabfad6	206	C<$?> ends up with the exitstatus of the subprocess (this is different
	207	from Unix, where the exitstatus is actually given by "$? >> 8").
	208	Failure to spawn() the subprocess is indicated by setting $? to
	209	"255<<8". This is subject to change.
68dc0745	210
	211	=item *
	212
	213	Building modules available on CPAN is mostly supported, but this
	214	hasn't been tested much yet. Expect strange problems, and be
	215	prepared to deal with the consequences.
	216
	217	=item *
	218
	219	C<utime()>, C<times()> and process-related functions may not
	220	behave as described in the documentation, and some of the
	221	returned values or effects may be bogus.
	222
	223	=item *
	224
	225	Signal handling may not behave as on Unix platforms.
	226
	227	=item *
	228
	229	File globbing may not behave as on Unix platforms.
	230
	231	=item *
	232
	233	Not all of the utilities that come with the Perl distribution
	234	are supported yet.
	235
	236	=back
	237
	238	Please send detailed descriptions of any problems and solutions that
	239	you may find to <F<perlbug@perl.com>>, along with the output produced
	240	by C<perl -V>.
	241
	242	=head1 AUTHORS
	243
	244	=over 4
	245
	246	=item Gary Ng <F<71564.1743@CompuServe.COM>>
	247
	248	=item Gurusamy Sarathy <F<gsar@umich.edu>>
	249
	250	=item Nick Ing-Simmons <F<nick@ni-s.u-net.com>>
	251
	252	=back
	253
	254	=head1 SEE ALSO
	255
	256	L<perl>
	257
	258	=head1 HISTORY
	259
	260	This port was originally contributed by Gary Ng around 5.003_24,
	261	and borrowed from the Hip Communications port that was available
	262	at the time.
	263
	264	Nick Ing-Simmons and Gurusamy Sarathy have made numerous and
	265	sundry hacks since then.
	266
5aabfad6	267	Last updated: 04 April 1997
68dc0745	268
	269	=cut
	270