Fix AUTOLOAD, or kill me
[perl.git] / README.win32
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
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 Also 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 two
80 additional steps (these 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.
89
90 =item 2.
91
92 Reset your INCLUDE environment variable to the MSVC include directory.
93 For example:
94
95         set INCLUDE=E:\MSVC20\INCLUDE
96
97 This must have only one directory (a list of directories will not work).
98 VCVARS32.BAT may put multiple locations in there, which is why this step
99 is required.
100
101 =back
102
103 =item * 
104
105 Make sure you are in the "win32" subdirectory under the perl toplevel.
106
107 =item *
108
109 Type "nmake" while in the "win32" subdirectory.  This should build
110 everything.  Specifically, it will create perl.exe, perl.dll, and
111 perlglob.exe at the perl toplevel, and various other extension dll's
112 under the lib\auto directory.  If the make fails for any reason, make
113 sure you have done the previous steps correctly.
114
115 =item *
116
117 Type "nmake install".  This will put the newly built perl and the
118 libraries under C:\PERL.  If you want to alter this location, to say,
119 D:\FOO\PERL, you will have to say:
120
121         nmake install INST_TOP=D:\FOO\PERL
122
123 instead.  To use the Perl you just installed, make sure you set your
124 PATH environment variable to C:\PERL\BIN (or D:\FOO\PERL\BIN).
125
126 =back
127
128 =head2 Testing
129
130 Type "nmake test".  This will run most of the tests from the
131 testsuite (many tests will be skipped, and some tests will fail).
132 Most failures are due to UNIXisms in the standard perl testsuite.
133
134 To get a more detailed breakdown of the tests that failed, say:
135
136        cd ..\t
137        .\perl harness
138
139 This should produce a summary very similar to the following:
140
141     Failed Test  Status Wstat Total Fail  Failed  List of failed
142     ------------------------------------------------------------------------------
143     io/fs.t                      26   16  61.54%  1-5, 7-11, 16-18, 23-25
144     lib/anydbm.t                 12    1   8.33%  2
145     lib/findbin.t                 1    1 100.00%  1
146     lib/sdbm.t                   12    1   8.33%  2
147     op/magic.t                   28    1   3.57%  16
148     op/mkdir.t                    7    2  28.57%  3, 7
149     op/runlevel.t                 8    1  12.50%  4
150     op/stat.t                    56    3   5.36%  2-3, 20
151     op/taint.t                   98   20  20.41%  1-6, 14, 16, 19-21, 24, 26, 35-3
152     pragma/locale.t              98   40  40.82%  1, 13-14, 21-27, 33, 39, 45-53,
153     Failed 10/149 test scripts, 93.29% okay. 86/3871 subtests failed, 97.78% okay.
154
155
156 Check if any additional tests other than the ones shown here
157 failed.  The standard testsuite will ultimately be modified so
158 that the testsuite avoids running irrelevant tests on Win32.
159
160 =head1 BUGS AND CAVEATS
161
162 This is still very much an experimental port, and should be considered
163 alpha quality software.  You can expect changes in virtually all of
164 these areas: build process, installation structure, supported
165 utilities/modules, and supported perl functionality.  Specifically,
166 functionality that supports the Win32 environment may ultimately
167 be supported as either core modules or extensions.
168
169 Many tests from the standard testsuite either fail or produce different
170 results under this port.  Most of the problems fall under one of these
171 categories
172
173 =over 8
174
175 =item *
176
177 C<stat()> and C<lstat()> functions may not behave as documented.  They
178 may return values that bear no resemblance to those reported on Unix
179 platforms, and some fields may be completely bogus.
180
181 =item *
182
183 The following functions are currently unavailable: C<fork()>, C<exec()>,
184 C<dump()>, C<kill()>, C<chown()>, C<link()>, C<symlink()>, C<chroot()>,
185 C<setpgrp()>, C<getpgrp()>, C<setpriority()>, C<getpriority()>,
186 C<syscall()>, C<fcntl()>, C<flock()>.  This list is possibly incomplete.
187
188 =item *
189
190 Various C<socket()> related calls are supported, but they may not
191 behave as on Unix platforms.
192
193 =item *
194
195 The four-argument C<select()> call is only supported on sockets.
196
197 =item *
198
199 The behavior of C<system()> or the C<qx[]> operator (a.k.a. "backticks"),
200 when used to call interactive commands, is ill-defined.
201
202 =item *
203
204 C<$!> doesn't work reliably yet.
205
206 =item *
207
208 Building modules available on CPAN is mostly supported, but this
209 hasn't been tested much yet.  Expect strange problems, and be
210 prepared to deal with the consequences.
211
212 =item *
213
214 C<utime()>, C<times()> and process-related functions may not
215 behave as described in the documentation, and some of the
216 returned values or effects may be bogus.
217
218 =item *
219
220 Signal handling may not behave as on Unix platforms.
221
222 =item *
223
224 File globbing may not behave as on Unix platforms.
225
226 =item *
227
228 Not all of the utilities that come with the Perl distribution
229 are supported yet.
230
231 =back
232
233 Please send detailed descriptions of any problems and solutions that 
234 you may find to <F<perlbug@perl.com>>, along with the output produced
235 by C<perl -V>.
236
237 =head1 AUTHORS
238
239 =over 4
240
241 =item Gary Ng <F<71564.1743@CompuServe.COM>>
242
243 =item Gurusamy Sarathy <F<gsar@umich.edu>>
244
245 =item Nick Ing-Simmons <F<nick@ni-s.u-net.com>>
246
247 =back
248
249 =head1 SEE ALSO
250
251 L<perl>
252
253 =head1 HISTORY
254
255 This port was originally contributed by Gary Ng around 5.003_24,
256 and borrowed from the Hip Communications port that was available
257 at the time.
258
259 Nick Ing-Simmons and Gurusamy Sarathy have made numerous and
260 sundry hacks since then.
261
262 Last updated: 19 March 1997
263
264 =cut
265