-w interacts badly with -Dt
[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 Windows NT (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 may also want to look at two other options for building
35 a perl that will work on Windows NT:  the README.cygwin32 and
36 README.os2 files, which give a different set of rules to build a
37 Perl that will work on Win32 platforms.  Those two methods will
38 probably enable you to build a more Unix-compatible perl, but you
39 will also need to download and use various other build-time and
40 run-time support software described in those files.
41
42 This set of instructions is meant to describe a so-called "native"
43 port of Perl to Win32 platforms.  The resulting Perl requires no
44 additional software to run (other than what came with your operating
45 system).  Currently, this port is only capable of using Microsoft's
46 Visual C++ compiler.  The ultimate goal is to support the other major
47 compilers that can generally be used to build Win32 applications.
48
49 This port currently supports MakeMaker (the set of modules that
50 is used to build extensions to perl).  Therefore, you should be
51 able to build and install most extensions found in the CPAN sites.
52 See L<Usage Hints> below for general hints about this.
53
54 =head2 Setting Up
55
56 =over 4
57
58 =item *
59
60 Use the default "cmd" shell that comes with NT.  In particular, do
61 *not* use the 4DOS/NT shell.  The Makefile has commands that are not
62 compatible with that shell.  The Makefile also has known
63 incompatibilites with the default shell that comes with Windows95,
64 so building under Windows95 should be considered "unsupported".
65
66 =item *
67
68 If you did not choose to always initialize the Visual C++ compilation
69 environment variables when you installed Visual C++ on your system, you
70 will need to run the VCVARS32.BAT file usually found somewhere like
71 C:\MSDEV4.2\BIN.  This will set your build environment.
72
73 =item *
74
75 Depending on how you extracted the distribution, you have to make sure
76 some of the files are writable by you.  The easiest way to make sure of
77 this is to execute:
78
79         attrib -R *.* /S
80
81 from the perl toplevel directory.  You don't I<have> to do this if you
82 used the right tools to extract the files in the standard distribution,
83 but it doesn't hurt to do so.
84
85 =back
86
87 =head2 Building
88
89 =over 4
90
91 =item *
92
93 Make sure you are in the "win32" subdirectory under the perl toplevel.
94 This directory contains a "Makefile" that will work with
95 versions of NMAKE that come with Visual C++ ver. 2.0 and above.
96
97 =item *
98
99 Edit the Makefile and change the values of INST_DRV and INST_TOP
100 if you want perl to be installed in a location other than "C:\PERL".
101
102 If you want to build a perl capable of running on the Windows95
103 platform, you will have to uncomment the line that sets "RUNTIME=-MT".
104 (The default settings use the Microsoft-recommended -MD option for
105 compiling, which uses the DLL version of the C RunTime Library.  There
106 currently exists a bug in the Microsoft CRTL that causes failure of
107 the socket calls only on the Windows95 platform.  This bug cannot be
108 worked around if the DLL version of the CRTL is used, which is why you
109 need to enable the -MT flag.)  Perl compiled with -MT can be used on
110 both Windows NT and Windows95.
111
112 If you are using Visual C++ ver. 2.0, uncomment the line that
113 sets "CCTYPE=MSVC20".
114
115 =item *
116
117 Type "nmake".
118
119 This should build everything.  Specifically, it will create perl.exe,
120 perl.dll, and perlglob.exe at the perl toplevel, and various other
121 extension dll's under the lib\auto directory.  If the build fails for
122 any reason, make sure you have done the previous steps correctly.
123
124 =back
125
126 =head2 Testing
127
128 Type "nmake test".  This will run most of the tests from the
129 testsuite (many tests will be skipped, and but no test should fail).
130
131 If some tests do fail, it may be because you are using a different command
132 shell than the native "cmd.exe".
133
134 Please report any failures as described under L<BUGS AND CAVEATS>.
135
136 =head2 Installation
137
138 Type "nmake install".  This will put the newly built perl and the
139 libraries under "C:\perl" (actually whatever you set C<INST_TOP> to
140 in the Makefile).  It will also install the pod documentation under
141 C<$INST_TOP\lib\pod> and HTML versions of the same under
142 C<$INST_TOP\lib\pod\html>.  To use the Perl you just installed, set your
143 PATH environment variable to "C:\perl\bin" (or C<$INST_TOP\bin>, if you
144 changed the default as above).
145
146 =head2 Usage Hints
147
148 =over 4
149
150 =item Environment Variables
151
152 The installation paths that you set during the build get compiled
153 into perl, so you don't have to do anything additional to start
154 using that perl (except add its location to your PATH variable).
155
156 If you put extensions in unusual places, you can set PERL5LIB
157 to a list of paths separated by semicolons where you want perl
158 to look for libraries.  Look for descriptions of other environment
159 variables you can set in the perlrun podpage.
160
161 Sometime in the future, some of the configuration information
162 for perl will be moved into the Windows registry.
163
164 =item Using perl from the command line
165
166 If you are accustomed to using perl from various command-line
167 shells found in UNIX environments, you will be less than pleased
168 with what Windows NT offers by way of a command shell.
169
170 The crucial thing to understand about the "cmd" shell (which is
171 the default on Windows NT) is that it does not do any wildcard
172 expansions of command-line arguments (so wildcards need not be
173 quoted).  It also provides only rudimentary quoting.  The only
174 (useful) quote character is the double quote (").  It can be used to
175 protect spaces in arguments and other special characters.  The
176 Windows NT documentation has almost no description of how the
177 quoting rules are implemented, but here are some general observations
178 based on experiments:  The shell breaks arguments at spaces and
179 passes them to programs in argc/argv.  Doublequotes can be used
180 to prevent arguments with spaces in them from being split up.
181 You can put a double quote in an argument by escaping it with
182 a backslash and enclosing the whole argument within double quotes.
183 The backslash and the pair of double quotes surrounding the
184 argument will be stripped by the shell.
185
186 The file redirection characters "<", ">", and "|" cannot be quoted
187 by double quotes (there are probably more such).  Single quotes
188 will protect those three file redirection characters, but the
189 single quotes don't get stripped by the shell (just to make this
190 type of quoting completely useless).  The caret "^" has also
191 been observed to behave as a quoting character (and doesn't get
192 stripped by the shell also).
193
194 Here are some examples of usage of the "cmd" shell:
195
196 This prints two doublequotes:
197
198     perl -e "print '\"\"' "
199
200 This does the same:
201
202     perl -e "print \"\\\"\\\"\" "
203
204 This prints "bar" and writes "foo" to the file "blurch":
205
206     perl -e "print 'foo'; print STDERR 'bar'" > blurch
207
208 This prints "foo" ("bar" disappears into nowhereland):
209
210     perl -e "print 'foo'; print STDERR 'bar'" 2> nul
211
212 This prints "bar" and writes "foo" into the file "blurch":
213
214     perl -e "print 'foo'; print STDERR 'bar'" 1> blurch
215
216 This prints "foo" and writes "bar" to the file "blurch":
217
218     perl -e "print 'foo'; print STDERR 'bar'" 2> blurch
219
220 This pipes "foo" to the "less" pager and prints "bar" on the console:
221
222     perl -e "print 'foo'; print STDERR 'bar'" | less
223
224 This pipes "foo\nbar\n" to the less pager:
225
226     perl -le "print 'foo'; print STDERR 'bar'" |& less
227
228 This does the same thing as the above:
229
230     perl -le "print 'foo'; print STDERR 'bar'" 2>&1 | less
231
232 This pipes "foo" to the pager and writes "bar" in the file "blurch":
233
234     perl -e "print 'foo'; print STDERR 'bar'" 2> blurch | less
235
236
237 Discovering the usage of the "command.com" shell on Windows95
238 is left as an exercise to the reader :)
239
240 =item Building Extensions
241
242 The Comprehensive Perl Archive Network (CPAN) offers a wealth
243 of extensions, some of which require a C compiler to build.
244 Look in http://www.perl.com/ for more information on CPAN.
245
246 Most extensions (whether they require a C compiler or not) can
247 be built, tested and installed with the standard mantra:
248
249     perl Makefile.PL
250     nmake
251     nmake test
252     nmake install
253
254 Note the NMAKE that comes with Visual C++ is required.  Some
255 extensions may not provide a testsuite (so "nmake test"
256 may not do anything, or fail), but most serious ones do.
257
258 If a module implements XSUBs, you will need a C compiler (Visual C++
259 versions 2.0 and above are currently supported).  You must make sure
260 you have set up the environment for the compiler for command-line
261 compilation.
262
263 If a module does not build for some reason, carefully look at
264 why it failed, and report problems to the module author.  If
265 it looks like the extension building support is at fault, report
266 that with full details of how the build failed using the perlbug
267 utility.
268
269 =item Win32 Specific Extensions
270
271 A number of extensions specific to the Win32 platform are available
272 from CPAN.  You may find that many of these extensions are meant to
273 be used under the Activeware port of Perl, which used to be the only
274 native port for the Win32 platform.  Since the Activeware port does not
275 have adequate support for Perl's extension building tools, these
276 extensions typically do not support those tools either, and therefore
277 cannot be built using the generic steps shown in the previous section.
278
279 To ensure smooth transitioning of existing code that uses the
280 Activeware port, there is a bundle of Win32 extensions that contains
281 all of the Activeware extensions and most other Win32 extensions from
282 CPAN in source form, along with many added bugfixes, and with MakeMaker
283 support.  This bundle is available at:
284
285    http://www.perl.com/CPAN/authors/id/GSAR/libwin32-0.06.tar.gz
286
287 See the README in that distribution for building and installation
288 instructions.  Look for later versions that may be available at the
289 same location.
290
291 It is expected that authors of Win32 specific extensions will begin
292 distributing their work in MakeMaker compatible form subsequent to
293 the 5.004 release of perl, at which point the need for a dedicated
294 bundle such as the above should diminish.
295
296 =item Miscellaneous Things
297
298 A full set of HTML documentation is installed, so you should be
299 able to use it if you have a web browser installed on your
300 system.
301
302 C<perldoc> is also a useful tool for browsing information contained
303 in the documentation, especially in conjunction with a pager
304 like C<less> (recent versions of which have Win32 support).  You may
305 have to set the PAGER environment variable to use a specific pager.
306 "perldoc -f foo" will print information about the perl operator
307 "foo".
308
309 If you find bugs in perl, you can run C<perlbug> to create a
310 bug report (you may have to send it manually if C<perlbug> cannot
311 find a mailer on your system).
312
313 =back
314
315 =head1 BUGS AND CAVEATS
316
317 This port has not been tested as extensively as we'd like, and
318 therefore should be considered beta quality software.  You should
319 expect changes in virtually all of these areas: build process,
320 installation structure, supported utilities/modules, and supported
321 perl functionality.  In particular, functionality specific to the
322 Win32 environment may ultimately be supported as either core modules
323 or extensions.  This means that you should be prepared to recompile
324 extensions when binary incompatibilites arise due to changes in the
325 internal structure of the code.
326
327 If you have had prior exposure to Perl on Unix platforms, you will notice
328 this port exhibits behavior different from what is documented.  Most of the
329 differences fall under one of these categories.  We do not consider
330 any of them to be serious limitations (especially when compared to the
331 limited nature of some of the Win32 OSes themselves :)
332
333 =over 8
334
335 =item *
336
337 C<stat()> and C<lstat()> functions may not behave as documented.  They
338 may return values that bear no resemblance to those reported on Unix
339 platforms, and some fields (like the the one for inode) may be completely
340 bogus.
341
342 =item *
343
344 The following functions are currently unavailable: C<fork()>, C<exec()>,
345 C<dump()>, C<chown()>, C<link()>, C<symlink()>, C<chroot()>,
346 C<setpgrp()>, C<getpgrp()>, C<setpriority()>, C<getpriority()>,
347 C<syscall()>, C<fcntl()>, C<flock()>.  This list is possibly very
348 incomplete.
349
350 =item *
351
352 Various C<socket()> related calls are supported, but they may not
353 behave as on Unix platforms.
354
355 =item *
356
357 The four-argument C<select()> call is only supported on sockets.
358
359 =item *
360
361 C<$?> ends up with the exitstatus of the subprocess (this is different
362 from Unix, where the exitstatus is actually given by "$? >> 8").
363 Failure to spawn() the subprocess is indicated by setting $? to 
364 "255<<8".  This is subject to change.
365
366 =item *
367
368 Building modules available on CPAN is mostly supported, but this
369 hasn't been tested much yet.  Expect strange problems, and be
370 prepared to deal with the consequences.
371
372 =item *
373
374 C<utime()>, C<times()> and process-related functions may not
375 behave as described in the documentation, and some of the
376 returned values or effects may be bogus.
377
378 =item *
379
380 Signal handling may not behave as on Unix platforms.
381
382 =item *
383
384 File globbing may not behave as on Unix platforms.  In particular,
385 globbing does not understand wildcards in the pathname component,
386 but only in the filename component.  In other words, something like
387 "print <*/*.pl>" will not print all the perl scripts in all the
388 subdirectories one level under the current one (like it does on
389 UNIX platforms).
390
391 =back
392
393 Please send detailed descriptions of any problems and solutions that 
394 you may find to <F<perlbug@perl.com>>, along with the output produced
395 by C<perl -V>.
396
397 =head1 AUTHORS
398
399 =over 4
400
401 =item Gary Ng <F<71564.1743@CompuServe.COM>>
402
403 =item Gurusamy Sarathy <F<gsar@umich.edu>>
404
405 =item Nick Ing-Simmons <F<nick@ni-s.u-net.com>>
406
407 =back
408
409 =head1 SEE ALSO
410
411 L<perl>
412
413 =head1 HISTORY
414
415 This port was originally contributed by Gary Ng around 5.003_24,
416 and borrowed from the Hip Communications port that was available
417 at the time.
418
419 Nick Ing-Simmons and Gurusamy Sarathy have made numerous and
420 sundry hacks since then.
421
422 Last updated: 15 May 1997
423
424 =cut