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