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