[perl5.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 WindowsNT [XXX and perhaps under Windows95]

=head1 SYNOPSIS

These are instructions for building Perl under WindowsNT (versions
3.51 or 4.0), using Visual C++.

=head1 DESCRIPTION

Before you start, you should glance through the README file found
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.

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 on the platforms.

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

=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 three
additional steps (these three 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.  (The only difference in those makefiles
is in how the $(INCLUDE) variable is handled--VC 2.0 NMAKE does not
grok a path list in $(INCLUDE)).

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

=item 3.

Apply the patch found in win32\VC-2.0\vc2.patch, like so:

	cd win32
	patch -p2 -N < VC-2.0\vc2.patch

You may have to edit win32\win32.c manually if you don't have GNU patch.

=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 some tests will fail).
Most failures are due to UNIXisms in the standard perl testsuite.

To get a more detailed breakdown of the tests that failed, say:

       cd ..\t
       .\perl harness

This should produce a summary very similar to the following:

    Failed Test  Status Wstat Total Fail  Failed  List of failed
    ------------------------------------------------------------------------------
    io/fs.t                      26   16  61.54%  1-5, 7-11, 16-18, 23-25
    io/tell.t                    13    1   7.69%  10
    lib/anydbm.t                 12    1   8.33%  2
    lib/findbin.t                 1    1 100.00%  1
    lib/sdbm.t                   12    1   8.33%  2
    op/mkdir.t                    7    2  28.57%  3, 7
    op/runlevel.t                 8    1  12.50%  4
    op/stat.t                    56    3   5.36%  3-4, 20
    op/taint.t                   98   20  20.41%  1-6, 14, 16, 19-21, 24, 26, 35-3
    pragma/locale.t              98   40  40.82%  1, 13-14, 21-27, 33, 39, 45-53,
    Failed 10/149 test scripts, 93.29% okay. 86/3506 subtests failed, 97.55% okay.

Check if any additional tests other than the ones shown here
failed.  The standard testsuite will ultimately be modified so
that the testsuite avoids running irrelevant tests on Win32.

=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 be ultimately
be supported as either core modules or extensions.

Many tests from the standard testsuite either fail or produce different
results under this port.  Most of the problems 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<kill()>, 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 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<$!> doesn't work reliably yet.

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