CGI->redirect patch
[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 Win32
8
9 =head1 SYNOPSIS
10
11 These are instructions for building Perl under WindowsNT (versions
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).
18
19 =head1 DESCRIPTION
20
21 Before you start, you should glance through the README file
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
26 Also make sure you read the L<BUGS AND CAVEATS> section below for the
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
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.
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
59 compatible with that shell.  You are mostly on your own if you can
60 muster the temerity to attempt this with Windows95.
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
89 using Visual C++ versions between 2.0 and 4.0, do the following two
90 additional steps (these steps are not required if you are
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
98 in the win32\VC-2.0 directory.
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
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
141 testsuite (many tests will be skipped, and a few tests may fail).
142
143 To get a more detailed breakdown of the tests that failed, 
144 you may want to say:
145
146        cd ..\t
147        .\perl harness
148
149 This should produce a summary of the failed tests.  Currently, the
150 only known failure is lib\findbin.t:
151
152     Failed Test  Status Wstat Total Fail  Failed  List of failed
153     ------------------------------------------------------------------------------
154     lib/findbin.t                 1    1 100.00%  1
155     Failed 1/151 test scripts, 99.34% okay. 1/3902 subtests failed, 99.97% okay.
156
157
158 Check if any additional tests other than the ones shown here
159 failed, and report them as described under L<BUGS AND CAVEATS>.
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,
167 functionality that supports the Win32 environment may ultimately
168 be supported as either core modules or extensions.
169
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.
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()>,
185 C<dump()>, C<chown()>, C<link()>, C<symlink()>, C<chroot()>,
186 C<setpgrp()>, C<getpgrp()>, C<setpriority()>, C<getpriority()>,
187 C<syscall()>, C<fcntl()>, C<flock()>.  This list is possibly very
188 incomplete.
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
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.
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
267 Last updated: 04 April 1997
268
269 =cut
270