Maintenance 5.004_04 changes
[p5sagit/p5-mst-13.2.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) or Borland
13 C++ (version 5.x).  Currently, this port may also build under Windows95,
14 but you can expect problems stemming from the unmentionable command
15 shell that infests that platform.  Note this caveat is only about
16 B<building> perl.  Once built, you should be able to B<use> it on
17 either Win32 platform (modulo the problems arising from the inferior
18 command shell).
19
20 =head1 DESCRIPTION
21
22 Before you start, you should glance through the README file
23 found in the top-level directory where the Perl distribution
24 was extracted.  Make sure you read and understand the terms under
25 which this software is being distributed.
26
27 Also make sure you read L<BUGS AND CAVEATS> below for the
28 known limitations of this port.
29
30 The INSTALL file in the perl top-level has much information that is
31 only relevant to people building Perl on Unix-like systems.  In
32 particular, you can safely ignore any information that talks about
33 "Configure".
34
35 You may also want to look at two other options for building
36 a perl that will work on Windows NT:  the README.cygwin32 and
37 README.os2 files, which each give a different set of rules to build
38 a Perl that will work on Win32 platforms.  Those two methods will
39 probably enable you to build a more Unix-compatible perl, but you
40 will also need to download and use various other build-time and
41 run-time support software described in those files.
42
43 This set of instructions is meant to describe a so-called "native"
44 port of Perl to Win32 platforms.  The resulting Perl requires no
45 additional software to run (other than what came with your operating
46 system).  Currently, this port is capable of using either the
47 Microsoft Visual C++ compiler, or the Borland C++ compiler.  The
48 ultimate goal is to support the other major compilers that can
49 generally be used to build Win32 applications.
50
51 This port currently supports MakeMaker (the set of modules that
52 is used to build extensions to perl).  Therefore, you should be
53 able to build and install most extensions found in the CPAN sites.
54 See L<Usage Hints> below for general hints about this.
55
56 =head2 Setting Up
57
58 =over 4
59
60 =item Command Shell
61
62 Use the default "cmd" shell that comes with NT.  In particular, do
63 *not* use the 4DOS/NT shell.  The Makefile has commands that are not
64 compatible with that shell.  The Makefile also has known
65 incompatibilites with the default shell that comes with Windows95,
66 so building under Windows95 should be considered "unsupported".
67
68 =item Borland C++
69
70 If you are using the Borland compiler, you will need dmake, a freely
71 available make that has very nice macro features and parallelability.
72 (The make that Borland supplies is seriously crippled, and will not
73 work for MakeMaker builds--if you *have* to bug someone about this,
74 I suggest you bug Borland to fix their make :)
75
76 A port of dmake for win32 platforms is available from
77 "http://www-personal.umich.edu/~gsar/dmake-4.0-win32.tar.gz".
78 Fetch and install dmake somewhere on your path.  Also make sure you
79 copy the Borland dmake.ini file to some location where you keep
80 *.ini files.  If you use the binary that comes with the above port, you
81 will need to set INIT in your environment to the directory where you
82 put the dmake.ini file.
83
84 =item Microsoft Visual C++
85
86 The NMAKE that comes with Visual C++ will suffice for building.
87 If you did not choose to always initialize the Visual C++ compilation
88 environment variables when you installed Visual C++ on your system, you
89 will need to run the VCVARS32.BAT file usually found somewhere like
90 C:\MSDEV4.2\BIN.  This will set your build environment.
91
92 You can also use dmake to build using Visual C++, provided: you
93 copied the dmake.ini for Visual C++; set INIT to point to the
94 directory where you put it, as above; and edit win32/config.vc
95 and change "make=nmake" to "make=dmake".  The last step is only
96 essential if you want to use dmake to be your default make for
97 building extensions using MakeMaker.
98
99 =item Permissions
100
101 Depending on how you extracted the distribution, you have to make sure
102 some of the files are writable by you.  The easiest way to make sure of
103 this is to execute:
104
105         attrib -R *.* /S
106
107 from the perl toplevel directory.  You don't I<have> to do this if you
108 used the right tools to extract the files in the standard distribution,
109 but it doesn't hurt to do so.
110
111 =back
112
113 =head2 Building
114
115 =over 4
116
117 =item *
118
119 Make sure you are in the "win32" subdirectory under the perl toplevel.
120 This directory contains a "Makefile" that will work with
121 versions of NMAKE that come with Visual C++ ver. 2.0 and above, and
122 a dmake "makefile.mk" that will work for both Borland and Visual C++
123 builds.  The defaults in the dmake makefile are setup to build using the
124 Borland compiler.
125
126 =item *
127
128 Edit the Makefile (or makefile.mk, if using dmake) and change the values
129 of INST_DRV and INST_TOP if you want perl to be installed in a location
130 other than "C:\PERL".  If you are using Visual C++ ver. 2.0, uncomment
131 the line that sets "CCTYPE=MSVC20".
132
133 You will also have to make sure CCHOME points to wherever you installed
134 your compiler.
135
136 =item *
137
138 Type "nmake" (or "dmake" if you are using that make).
139
140 This should build everything.  Specifically, it will create perl.exe,
141 perl.dll, and perlglob.exe at the perl toplevel, and various other
142 extension dll's under the lib\auto directory.  If the build fails for
143 any reason, make sure you have done the previous steps correctly.
144
145 The build process may produce "harmless" compiler warnings (more or
146 less copiously, depending on how picky your compiler gets).  The
147 maintainers are aware of these warnings, thankyouverymuch. :)
148
149 When building using Visual C++, a perl95.exe will also get built.  This
150 executable is only needed on Windows95, and should be used instead of
151 perl.exe, and then only if you want sockets to work properly on Windows95.
152 This is necessitated by a bug in the Microsoft C Runtime that cannot be
153 worked around in the "normal" perl.exe.  Again, if this bugs you, please
154 bug Microsoft :). perl95.exe gets built with its own private copy of the
155 C Runtime that is not accessible to extensions (which see the DLL version
156 of the CRT).  Be aware, therefore, that this perl95.exe will have
157 esoteric problems with extensions like perl/Tk that themselves use the C
158 Runtime heavily, or want to free() pointers malloc()-ed by perl.
159
160 You can avoid the perl95.exe problems completely if you use Borland
161 C++ for building perl (perl95.exe is not needed and will not be built
162 in that case).
163
164 =back
165
166 =head2 Testing
167
168 Type "nmake test" (or "dmake test").  This will run most of the tests from
169 the testsuite (many tests will be skipped, and but no test should fail).
170
171 If some tests do fail, it may be because you are using a different command
172 shell than the native "cmd.exe".
173
174 If you used the Borland compiler, you may see a failure in op/taint.t
175 arising from the inability to find the Borland Runtime DLLs on the system
176 default path.  You will need to copy the DLLs reported by the messages
177 from where Borland chose to install it, into the Windows system directory
178 (usually somewhere like C:\WINNT\SYSTEM32), and rerun the test.
179
180 Please report any other failures as described under L<BUGS AND CAVEATS>.
181
182 =head2 Installation
183
184 Type "nmake install" (or "dmake install").  This will put the newly
185 built perl and the libraries under "C:\perl" (actually whatever you set
186 C<INST_TOP> to in the Makefile).  It will also install the pod
187 documentation under C<$INST_TOP\lib\pod> and HTML versions of the same
188 under C<$INST_TOP\lib\pod\html>.  To use the Perl you just installed,
189 set your PATH environment variable to "C:\perl\bin" (or C<$INST_TOP\bin>,
190 if you changed the default as above).
191
192 =head2 Usage Hints
193
194 =over 4
195
196 =item Environment Variables
197
198 The installation paths that you set during the build get compiled
199 into perl, so you don't have to do anything additional to start
200 using that perl (except add its location to your PATH variable).
201
202 If you put extensions in unusual places, you can set PERL5LIB
203 to a list of paths separated by semicolons where you want perl
204 to look for libraries.  Look for descriptions of other environment
205 variables you can set in the perlrun podpage.
206
207 Sometime in the future, some of the configuration information
208 for perl will be moved into the Windows registry.
209
210 =item File Globbing
211
212 By default, perl spawns an external program to do file globbing.
213 The install process installs both a perlglob.exe and a perlglob.bat
214 that perl can use for this purpose.  Note that with the default
215 installation, perlglob.exe will be found by the system before
216 perlglob.bat.
217
218 perlglob.exe relies on the argv expansion done by the C Runtime of
219 the particular compiler you used, and therefore behaves very
220 differently depending on the Runtime used to build it.  To preserve
221 compatiblity, perlglob.bat (a perl script/module that can be
222 used portably) is installed.  Besides being portable, perlglob.bat
223 also offers enhanced globbing functionality.
224
225 If you want perl to use perlglob.bat instead of perlglob.exe, just
226 delete perlglob.exe from the install location (or move it somewhere
227 perl cannot find).  Using File::DosGlob.pm (which is the same
228 as perlglob.bat) to override the internal CORE::glob() works about 10
229 times faster than spawing perlglob.exe, and you should take this
230 approach when writing new modules.  See File::DosGlob for details.
231
232 =item Using perl from the command line
233
234 If you are accustomed to using perl from various command-line
235 shells found in UNIX environments, you will be less than pleased
236 with what Windows NT offers by way of a command shell.
237
238 The crucial thing to understand about the "cmd" shell (which is
239 the default on Windows NT) is that it does not do any wildcard
240 expansions of command-line arguments (so wildcards need not be
241 quoted).  It also provides only rudimentary quoting.  The only
242 (useful) quote character is the double quote (").  It can be used to
243 protect spaces in arguments and other special characters.  The
244 Windows NT documentation has almost no description of how the
245 quoting rules are implemented, but here are some general observations
246 based on experiments:  The shell breaks arguments at spaces and
247 passes them to programs in argc/argv.  Doublequotes can be used
248 to prevent arguments with spaces in them from being split up.
249 You can put a double quote in an argument by escaping it with
250 a backslash and enclosing the whole argument within double quotes.
251 The backslash and the pair of double quotes surrounding the
252 argument will be stripped by the shell.
253
254 The file redirection characters "<", ">", and "|" cannot be quoted
255 by double quotes (there are probably more such).  Single quotes
256 will protect those three file redirection characters, but the
257 single quotes don't get stripped by the shell (just to make this
258 type of quoting completely useless).  The caret "^" has also
259 been observed to behave as a quoting character (and doesn't get
260 stripped by the shell also).
261
262 Here are some examples of usage of the "cmd" shell:
263
264 This prints two doublequotes:
265
266     perl -e "print '\"\"' "
267
268 This does the same:
269
270     perl -e "print \"\\\"\\\"\" "
271
272 This prints "bar" and writes "foo" to the file "blurch":
273
274     perl -e "print 'foo'; print STDERR 'bar'" > blurch
275
276 This prints "foo" ("bar" disappears into nowhereland):
277
278     perl -e "print 'foo'; print STDERR 'bar'" 2> nul
279
280 This prints "bar" and writes "foo" into the file "blurch":
281
282     perl -e "print 'foo'; print STDERR 'bar'" 1> blurch
283
284 This pipes "foo" to the "less" pager and prints "bar" on the console:
285
286     perl -e "print 'foo'; print STDERR 'bar'" | less
287
288 This pipes "foo\nbar\n" to the less pager:
289
290     perl -le "print 'foo'; print STDERR 'bar'" 2>&1 | less
291
292 This pipes "foo" to the pager and writes "bar" in the file "blurch":
293
294     perl -e "print 'foo'; print STDERR 'bar'" 2> blurch | less
295
296
297 Discovering the usefulness of the "command.com" shell on Windows95
298 is left as an exercise to the reader :)
299
300 =item Building Extensions
301
302 The Comprehensive Perl Archive Network (CPAN) offers a wealth
303 of extensions, some of which require a C compiler to build.
304 Look in http://www.perl.com/ for more information on CPAN.
305
306 Most extensions (whether they require a C compiler or not) can
307 be built, tested and installed with the standard mantra:
308
309     perl Makefile.PL
310     $MAKE
311     $MAKE test
312     $MAKE install
313
314 where $MAKE stands for NMAKE or DMAKE.  Some extensions may not
315 provide a testsuite (so "$MAKE test" may not do anything, or fail),
316 but most serious ones do.
317
318 If a module implements XSUBs, you will need one of the supported
319 C compilers.  You must make sure you have set up the environment for
320 the compiler for command-line compilation.
321
322 If a module does not build for some reason, look carefully for
323 why it failed, and report problems to the module author.  If
324 it looks like the extension building support is at fault, report
325 that with full details of how the build failed using the perlbug
326 utility.
327
328 =item Win32 Specific Extensions
329
330 A number of extensions specific to the Win32 platform are available
331 from CPAN.  You may find that many of these extensions are meant to
332 be used under the Activeware port of Perl, which used to be the only
333 native port for the Win32 platform.  Since the Activeware port does not
334 have adequate support for Perl's extension building tools, these
335 extensions typically do not support those tools either, and therefore
336 cannot be built using the generic steps shown in the previous section.
337
338 To ensure smooth transitioning of existing code that uses the
339 Activeware port, there is a bundle of Win32 extensions that contains
340 all of the Activeware extensions and most other Win32 extensions from
341 CPAN in source form, along with many added bugfixes, and with MakeMaker
342 support.  This bundle is available at:
343
344    http://www.perl.com/CPAN/authors/id/GSAR/libwin32-0.08.tar.gz
345
346 See the README in that distribution for building and installation
347 instructions.  Look for later versions that may be available at the
348 same location.
349
350 It is expected that authors of Win32 specific extensions will begin
351 distributing their work in MakeMaker compatible form subsequent to
352 the 5.004 release of perl, at which point the need for a dedicated
353 bundle such as the above should diminish.
354
355 =item Running Perl Scripts
356
357 Perl scripts on UNIX use the "#!" (a.k.a "shebang") line to
358 indicate to the OS that it should execute the file using perl.
359 Win32 has no comparable means to indicate arbitrary files are
360 executables.
361
362 Instead, all available methods to execute plain text files on
363 Win32 rely on the file "extension".  There are three methods
364 to use this to execute perl scripts:
365
366 =over 8
367
368 =item 1
369
370 There is a facility called "file extension associations" that will
371 work in Windows NT 4.0.  This can be manipulated via the two
372 commands "assoc" and "ftype" that come standard with Windows NT
373 4.0.  Type "ftype /?" for a complete example of how to set this
374 up for perl scripts (Say what?  You thought Windows NT wasn't
375 perl-ready? :).
376
377 =item 2
378
379 Since file associations don't work everywhere, and there are
380 reportedly bugs with file associations where it does work, the
381 old method of wrapping the perl script to make it look like a
382 regular batch file to the OS, may be used.  The install process
383 makes available the "pl2bat.bat" script which can be used to wrap
384 perl scripts into batch files.  For example:
385
386         pl2bat foo.pl
387
388 will create the file "FOO.BAT".  Note "pl2bat" strips any
389 .pl suffix and adds a .bat suffix to the generated file.
390
391 If you use the 4DOS/NT or similar command shell, note that
392 "pl2bat" uses the "%*" variable in the generated batch file to
393 refer to all the command line arguments, so you may need to make
394 sure that construct works in batch files.  As of this writing,
395 4DOS/NT users will need a "ParameterChar = *" statement in their
396 4NT.INI file, or will need to execute "setdos /p*" in the 4DOS/NT
397 startup file to enable this to work.
398
399 =item 3
400
401 Using "pl2bat" has a few problems:  the file name gets changed,
402 so scripts that rely on C<$0> to find what they must do may not
403 run properly; running "pl2bat" replicates the contents of the
404 original script, and so this process can be maintenance intensive
405 if the originals get updated often.  A different approach that
406 avoids both problems is possible.
407
408 A script called "runperl.bat" is available that can be copied
409 to any filename (along with the .bat suffix).  For example,
410 if you call it "foo.bat", it will run the file "foo" when it is
411 executed.  Since you can run batch files on Win32 platforms simply
412 by typing the name (without the extension), this effectively
413 runs the file "foo", when you type either "foo" or "foo.bat".
414 With this method, "foo.bat" can even be in a different location
415 than the file "foo", as long as "foo" is available somewhere on
416 the PATH.  If your scripts are on a filesystem that allows symbolic
417 links, you can even avoid copying "runperl.bat".
418
419 Here's a diversion:  copy "runperl.bat" to "runperl", and type
420 "runperl".  Explain the observed behavior, or lack thereof. :)
421 Hint: .gnidnats llits er'uoy fi ,"lrepnur" eteled :tniH
422
423 =back
424
425 =item Miscellaneous Things
426
427 A full set of HTML documentation is installed, so you should be
428 able to use it if you have a web browser installed on your
429 system.
430
431 C<perldoc> is also a useful tool for browsing information contained
432 in the documentation, especially in conjunction with a pager
433 like C<less> (recent versions of which have Win32 support).  You may
434 have to set the PAGER environment variable to use a specific pager.
435 "perldoc -f foo" will print information about the perl operator
436 "foo".
437
438 If you find bugs in perl, you can run C<perlbug> to create a
439 bug report (you may have to send it manually if C<perlbug> cannot
440 find a mailer on your system).
441
442 =back
443
444 =head1 BUGS AND CAVEATS
445
446 This port should be considered beta quality software at the present
447 time because some details are still in flux and there may be
448 changes in any of these areas: build process, installation structure,
449 supported utilities/modules, and supported perl functionality.
450 In particular, functionality specific to the Win32 environment may
451 ultimately be supported as either core modules or extensions.  The
452 beta status implies, among other things, that you should be prepared
453 to recompile extensions when binary incompatibilites arise due to
454 changes in the internal structure of the code.
455
456 An effort has been made to ensure that the DLLs produced by the two
457 supported compilers are compatible with each other (despite the
458 best efforts of the compiler vendors).  Extension binaries produced
459 by one compiler should also coexist with a perl binary built by
460 a different compiler.  In order to accomplish this, PERL.DLL provides
461 a layer of runtime code that uses the C Runtime that perl was compiled
462 with.  Extensions which include "perl.h" will transparently access
463 the functions in this layer, thereby ensuring that both perl and
464 extensions use the same runtime functions.
465
466 If you have had prior exposure to Perl on Unix platforms, you will notice
467 this port exhibits behavior different from what is documented.  Most of the
468 differences fall under one of these categories.  We do not consider
469 any of them to be serious limitations (especially when compared to the
470 limited nature of some of the Win32 OSes themselves :)
471
472 =over 8
473
474 =item *
475
476 C<stat()> and C<lstat()> functions may not behave as documented.  They
477 may return values that bear no resemblance to those reported on Unix
478 platforms, and some fields (like the the one for inode) may be completely
479 bogus.
480
481 =item *
482
483 The following functions are currently unavailable: C<fork()>,
484 C<dump()>, C<chown()>, C<link()>, C<symlink()>, C<chroot()>,
485 C<setpgrp()>, C<getpgrp()>, C<setpriority()>, C<getpriority()>,
486 C<syscall()>, C<fcntl()>.  This list is possibly very incomplete.
487
488 =item *
489
490 crypt() is not available due to silly export restrictions.  It may
491 become available when the laws change.  Meanwhile, look in CPAN for
492 extensions that provide it.
493
494 =item *
495
496 Various C<socket()> related calls are supported, but they may not
497 behave as on Unix platforms.
498
499 =item *
500
501 The four-argument C<select()> call is only supported on sockets.
502
503 =item *
504
505 C<$?> ends up with the exitstatus of the subprocess (this is different
506 from Unix, where the exitstatus is actually given by "$? >> 8").
507 Failure to spawn() the subprocess is indicated by setting $? to 
508 "255<<8".  This is subject to change.
509
510 =item *
511
512 Building modules available on CPAN is mostly supported, but this
513 hasn't been tested much yet.  Expect strange problems, and be
514 prepared to deal with the consequences.
515
516 =item *
517
518 C<utime()>, C<times()> and process-related functions may not
519 behave as described in the documentation, and some of the
520 returned values or effects may be bogus.
521
522 =item *
523
524 Signal handling may not behave as on Unix platforms (where it
525 doesn't exactly "behave", either :).  For instance, calling C<die()>
526 or C<exit()> from signal handlers will cause an exception, since most
527 implementations of C<signal()> on Win32 are severely crippled.
528 Thus, signals may work only for simple things like setting a flag
529 variable in the handler.  Using signals under this port should
530 currently be considered unsupported.
531
532 =item *
533
534 File globbing may not behave as on Unix platforms.  In particular,
535 if you don't use perlglob.bat for globbing, it will understand
536 wildcards only in the filename component (and not in the pathname).
537 In other words, something like "print <*/*.pl>" will not print all the
538 perl scripts in all the subdirectories one level under the current one
539 (like it does on UNIX platforms).  perlglob.exe is also dependent on
540 the particular implementation of wildcard expansion in the vendor
541 libraries used to build it (which varies wildly at the present time).
542 Using perlglob.bat (or File::DosGlob) avoids these limitations, but
543 still only provides DOS semantics (read "warts") for globbing.
544
545 =back
546
547 Please send detailed descriptions of any problems and solutions that 
548 you may find to <F<perlbug@perl.com>>, along with the output produced
549 by C<perl -V>.
550
551 =head1 AUTHORS
552
553 =over 4
554
555 Gary Ng E<lt>71564.1743@CompuServe.COME<gt>
556
557 Gurusamy Sarathy E<lt>gsar@umich.eduE<gt>
558
559 Nick Ing-Simmons E<lt>nick@ni-s.u-net.comE<gt>
560
561 =back
562
563 This document is maintained by Gurusamy Sarathy.
564
565 =head1 SEE ALSO
566
567 L<perl>
568
569 =head1 HISTORY
570
571 This port was originally contributed by Gary Ng around 5.003_24,
572 and borrowed from the Hip Communications port that was available
573 at the time.
574
575 Nick Ing-Simmons and Gurusamy Sarathy have made numerous and
576 sundry hacks since then.
577
578 Borland support was added in 5.004_01 (Gurusamy Sarathy).
579
580 Last updated: 25 July 1997
581
582 =cut
583