avoid creating new files during make install
[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).  Currently, this port is reported to build under
13 Windows95 using the 4DOS shell--the default shell that infests
14 Windows95 may not work fully (but see below).  Note that this caveat
15 is only about B<building> perl.  Once built, you should be able to
16 B<use> it on either Win32 platform (modulo the problems arising from
17 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 L<BUGS AND CAVEATS> 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.cygwin and
36 README.os2 files, which each give a different set of rules to build
37 a 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 capable of using one of the
46 following compilers:
47
48       Borland C++               version 5.02 or later
49       Microsoft Visual C++      version 4.2 or later
50       Mingw32 with EGCS         versions 1.0.2, 1.1
51       Mingw32 with GCC          version 2.8.1
52
53 The last two of these are high quality freeware compilers.  Support
54 for them is still experimental.
55
56 This port currently supports MakeMaker (the set of modules that
57 is used to build extensions to perl).  Therefore, you should be
58 able to build and install most extensions found in the CPAN sites.
59 See L<Usage Hints> below for general hints about this.
60
61 =head2 Setting Up
62
63 =over 4
64
65 =item Command Shell
66
67 Use the default "cmd" shell that comes with NT.  Some versions of the
68 popular 4DOS/NT shell have incompatibilities that may cause you trouble.
69 If the build fails under that shell, try building again with the cmd
70 shell.  The nmake Makefile also has known incompatibilites with the
71 "command.com" shell that comes with Windows95.
72
73 However, there have been reports of successful build attempts using
74 4DOS/NT version 6.01 under Windows95, using dmake, but your mileage
75 may vary.  There is also some basic support for building using dmake
76 under command.com.  Nevertheless, if building under command.com
77 doesn't work, try 4DOS/NT.
78
79 The surest way to build it is on Windows NT, using the cmd shell.
80
81 Make sure the path to the build directory does not contain spaces.  The
82 build usually works in this circumstance, but some tests will fail.
83
84 =item Borland C++
85
86 If you are using the Borland compiler, you will need dmake, a freely
87 available make that has very nice macro features and parallelability.
88 (The make that Borland supplies is seriously crippled, and will not
89 work for MakeMaker builds.)
90
91 A port of dmake for win32 platforms is available from:
92
93     ftp://ftp.linux.activestate.com/pub/staff/gsar/dmake-4.1-win32.zip
94
95 Fetch and install dmake somewhere on your path (follow the instructions
96 in the README.NOW file).
97
98 =item Microsoft Visual C++
99
100 The nmake that comes with Visual C++ will suffice for building.
101 You will need to run the VCVARS32.BAT file usually found somewhere
102 like C:\MSDEV4.2\BIN.  This will set your build environment.
103
104 You can also use dmake to build using Visual C++, provided:
105 you set OSRELEASE to "microsft" (or whatever the directory name
106 under which the Visual C dmake configuration lives) in your environment,
107 and edit win32/config.vc to change "make=nmake" into "make=dmake".  The
108 latter step is only essential if you want to use dmake as your default
109 make for building extensions using MakeMaker.
110
111 =item Mingw32 with EGCS or GCC
112
113 ECGS binaries can be downloaded from:
114
115     ftp://ftp.xraylith.wisc.edu/pub/khan/gnu-win32/mingw32/
116
117 GCC-2.8.1 binaries are available from:
118
119     http://agnes.dida.physik.uni-essen.de/~janjaap/mingw32/
120
121 You only need either one of those, not both.  Both bundles come with
122 Mingw32 libraries and headers.  While both of them work to build perl,
123 the EGCS binaries are currently favored by the maintainers, since they
124 come with more up-to-date Mingw32 libraries.
125
126 Make sure you install the binaries as indicated in the web sites
127 above.  You will need to set up a few environment variables (usually
128 run from a batch file).
129
130 You also need dmake.  See L</"Borland C++"> above on how to get it.
131
132 =back
133
134 =head2 Building
135
136 =over 4
137
138 =item *
139
140 Make sure you are in the "win32" subdirectory under the perl toplevel.
141 This directory contains a "Makefile" that will work with
142 versions of nmake that come with Visual C++, and a dmake "makefile.mk"
143 that will work for all supported compilers.  The defaults in the dmake
144 makefile are setup to build using the Borland compiler.
145
146 =item *
147
148 Edit the makefile.mk (or Makefile, if using nmake) and change the values
149 of INST_DRV and INST_TOP.   You can also enable various build
150 flags.
151
152 Beginning with version 5.005, there is experimental support for building
153 a perl interpreter that supports the Perl Object abstraction (courtesy
154 ActiveState Tool Corp.)  PERL_OBJECT uses C++, and the binaries are
155 therefore incompatible with the regular C build.  However, the
156 PERL_OBJECT build does provide something called the C-API, for linking
157 it with extensions that won't compile under PERL_OBJECT. Using the C_API
158 is typically requested through:
159
160     perl Makefile.PL CAPI=TRUE
161
162 PERL_OBJECT requires VC++ 5.0 (Service Pack 3 recommended) or later. It
163 is not yet supported under GCC or EGCS.  WARNING:  Binaries built with
164 PERL_OBJECT enabled are B<not> compatible with binaries built without.
165 Perl installs PERL_OBJECT binaries under a distinct architecture name,
166 so they B<can> coexist, though.
167
168 Beginning with version 5.005, there is experimental support for building
169 a perl interpreter that is capable of native threading.  Binaries built
170 with thread support enabled are also incompatible with the vanilla C
171 build.  WARNING:  Binaries built with threads enabled are B<not> compatible
172 with binaries built without.  Perl installs threads enabled binaries under
173 a distinct architecture name, so they B<can> coexist, though.
174
175 At the present time, you cannot enable both threading and PERL_OBJECT.
176 You can get only one of them in a Perl interpreter.
177
178 If you have either the source or a library that contains des_fcrypt(),
179 enable the appropriate option in the makefile.  des_fcrypt() is not
180 bundled with the distribution due to US Government restrictions
181 on the export of cryptographic software.  Nevertheless, this routine
182 is part of the "libdes" library (written by Ed Young) which is widely
183 available worldwide, usually along with SSLeay (for example:
184 "ftp://fractal.mta.ca/pub/crypto/SSLeay/DES/").  Set CRYPT_SRC to the
185 name of the file that implements des_fcrypt().  Alternatively, if
186 you have built a library that contains des_fcrypt(), you can set
187 CRYPT_LIB to point to the library name.  The location above contains
188 many versions of the "libdes" library, all with slightly different
189 implementations of des_fcrypt().  Older versions have a single,
190 self-contained file (fcrypt.c) that implements crypt(), so they may be
191 easier to use.  A patch against the fcrypt.c found in libdes-3.06 is
192 in des_fcrypt.patch.
193
194 Perl will also build without des_fcrypt(), but the crypt() builtin will
195 fail at run time.
196
197 You will also have to make sure CCHOME points to wherever you installed
198 your compiler.
199
200 The default value for CCHOME in the makefiles for Visual C++
201 may not be correct for some versions.  Make sure the default exists
202 and is valid.
203
204 Other options are explained in the makefiles.  Be sure to read the
205 instructions carefully.
206
207 =item *
208
209 Type "dmake" (or "nmake" if you are using that make).
210
211 This should build everything.  Specifically, it will create perl.exe,
212 perl.dll (or perl56.dll), and perlglob.exe at the perl toplevel, and
213 various other extension dll's under the lib\auto directory.  If the build
214 fails for any reason, make sure you have done the previous steps correctly.
215
216 The build process may produce "harmless" compiler warnings (more or
217 less copiously, depending on how picky your compiler gets).  The
218 maintainers are aware of these warnings, thankyouverymuch. :)
219
220 When building using Visual C++, a perl95.exe will also get built.  This
221 executable is only needed on Windows95, and should be used instead of
222 perl.exe, and then only if you want sockets to work properly on Windows95.
223 This is necessitated by a bug in the Microsoft C Runtime that cannot be
224 worked around in the "normal" perl.exe.  perl95.exe gets built with its
225 own private copy of the C Runtime that is not accessible to extensions
226 (which see the DLL version of the CRT).  Be aware, therefore, that this
227 perl95.exe will have esoteric problems with extensions like perl/Tk that
228 themselves use the C Runtime heavily, or want to free() pointers
229 malloc()-ed by perl.
230
231 You can avoid the perl95.exe problems completely if you either enable
232 USE_PERLCRT with Visual C++, or use Borland C++ for building perl.  In
233 those cases, perl95.exe is not needed and will not be built.
234
235 =back
236
237 =head2 Testing
238
239 Type "dmake test" (or "nmake test").  This will run most of the tests from
240 the testsuite (many tests will be skipped, and but no test should fail).
241
242 If some tests do fail, it may be because you are using a different command
243 shell than the native "cmd.exe", or because you are building from a path
244 that contains spaces.  So don't do that.
245
246 If you are running the tests from a emacs shell window, you may see
247 failures in op/stat.t.  Run "dmake test-notty" in that case.
248
249 If you're using the Borland compiler, you may see a failure in op/taint.t
250 arising from the inability to find the Borland Runtime DLLs on the system
251 default path.  You will need to copy the DLLs reported by the messages
252 from where Borland chose to install it, into the Windows system directory
253 (usually somewhere like C:\WINNT\SYSTEM32), and rerun the test.
254
255 The Visual C runtime apparently has a bug that causes posix.t to fail
256 test#2.  This usually happens only if you extracted the files in text
257 mode.  Enable the USE_PERLCRT option in the Makefile to fix this bug.
258
259 Please report any other failures as described under L<BUGS AND CAVEATS>.
260
261 =head2 Installation
262
263 Type "dmake install" (or "nmake install").  This will put the newly
264 built perl and the libraries under whatever C<INST_TOP> points to in the
265 Makefile.  It will also install the pod documentation under
266 C<$INST_TOP\$VERSION\lib\pod> and HTML versions of the same under
267 C<$INST_TOP\$VERSION\lib\pod\html>.  To use the Perl you just installed,
268 you will need to add two components to your PATH environment variable,
269 C<$INST_TOP\$VERSION\bin>, and C<$INST_TOP\$VERSION\bin\$ARCHNAME>.
270 For example:
271
272     set PATH c:\perl\5.005\bin;c:\perl\5.005\bin\MSWin32-x86;%PATH%
273
274
275 =head2 Usage Hints
276
277 =over 4
278
279 =item Environment Variables
280
281 The installation paths that you set during the build get compiled
282 into perl, so you don't have to do anything additional to start
283 using that perl (except add its location to your PATH variable).
284
285 If you put extensions in unusual places, you can set PERL5LIB
286 to a list of paths separated by semicolons where you want perl
287 to look for libraries.  Look for descriptions of other environment
288 variables you can set in L<perlrun>.
289
290 You can also control the shell that perl uses to run system() and
291 backtick commands via PERL5SHELL.  See L<perlrun>.
292
293 Perl does not depend on the registry, but it can look up certain default
294 values if you choose to put them there.  Perl attempts to read entries from
295 C<HKEY_CURRENT_USER\Software\Perl> and C<HKEY_LOCAL_MACHINE\Software\Perl>.
296 Entries in the former override entries in the latter.  One or more of the
297 following entries (of type REG_SZ or REG_EXPAND_SZ) may be set:
298
299     lib-$]              version-specific path to add to @INC
300     lib                 path to add to @INC
301     sitelib-$]          version-specific path to add to @INC
302     sitelib             path to add to @INC
303     PERL*               fallback for all %ENV lookups that begin with "PERL"
304
305 Note the C<$]> in the above is not literal.  Substitute whatever version
306 of perl you want to honor that entry, e.g. C<5.00502>.  Paths must be
307 separated with semicolons, as usual on win32.
308
309 =item File Globbing
310
311 By default, perl spawns an external program to do file globbing.
312 The install process installs both a perlglob.exe and a perlglob.bat
313 that perl can use for this purpose.  Note that with the default
314 installation, perlglob.exe will be found by the system before
315 perlglob.bat.
316
317 perlglob.exe relies on the argv expansion done by the C Runtime of
318 the particular compiler you used, and therefore behaves very
319 differently depending on the Runtime used to build it.  To preserve
320 compatiblity, perlglob.bat (a perl script that can be used portably)
321 is installed.  Besides being portable, perlglob.bat also offers
322 enhanced globbing functionality.
323
324 If you want perl to use perlglob.bat instead of perlglob.exe, just
325 delete perlglob.exe from the install location (or move it somewhere
326 perl cannot find).  Using File::DosGlob.pm (which implements the core
327 functionality of perlglob.bat) to override the internal CORE::glob()
328 works about 10 times faster than spawing perlglob.exe, and you should
329 take this approach when writing new modules.  See File::DosGlob for
330 details.
331
332 =item Using perl from the command line
333
334 If you are accustomed to using perl from various command-line
335 shells found in UNIX environments, you will be less than pleased
336 with what Windows NT offers by way of a command shell.
337
338 The crucial thing to understand about the "cmd" shell (which is
339 the default on Windows NT) is that it does not do any wildcard
340 expansions of command-line arguments (so wildcards need not be
341 quoted).  It also provides only rudimentary quoting.  The only
342 (useful) quote character is the double quote (").  It can be used to
343 protect spaces in arguments and other special characters.  The
344 Windows NT documentation has almost no description of how the
345 quoting rules are implemented, but here are some general observations
346 based on experiments:  The shell breaks arguments at spaces and
347 passes them to programs in argc/argv.  Doublequotes can be used
348 to prevent arguments with spaces in them from being split up.
349 You can put a double quote in an argument by escaping it with
350 a backslash and enclosing the whole argument within double quotes.
351 The backslash and the pair of double quotes surrounding the
352 argument will be stripped by the shell.
353
354 The file redirection characters "<", ">", and "|" cannot be quoted
355 by double quotes (there are probably more such).  Single quotes
356 will protect those three file redirection characters, but the
357 single quotes don't get stripped by the shell (just to make this
358 type of quoting completely useless).  The caret "^" has also
359 been observed to behave as a quoting character (and doesn't get
360 stripped by the shell also).
361
362 Here are some examples of usage of the "cmd" shell:
363
364 This prints two doublequotes:
365
366     perl -e "print '\"\"' "
367
368 This does the same:
369
370     perl -e "print \"\\\"\\\"\" "
371
372 This prints "bar" and writes "foo" to the file "blurch":
373
374     perl -e "print 'foo'; print STDERR 'bar'" > blurch
375
376 This prints "foo" ("bar" disappears into nowhereland):
377
378     perl -e "print 'foo'; print STDERR 'bar'" 2> nul
379
380 This prints "bar" and writes "foo" into the file "blurch":
381
382     perl -e "print 'foo'; print STDERR 'bar'" 1> blurch
383
384 This pipes "foo" to the "less" pager and prints "bar" on the console:
385
386     perl -e "print 'foo'; print STDERR 'bar'" | less
387
388 This pipes "foo\nbar\n" to the less pager:
389
390     perl -le "print 'foo'; print STDERR 'bar'" 2>&1 | less
391
392 This pipes "foo" to the pager and writes "bar" in the file "blurch":
393
394     perl -e "print 'foo'; print STDERR 'bar'" 2> blurch | less
395
396
397 Discovering the usefulness of the "command.com" shell on Windows95
398 is left as an exercise to the reader :)
399
400 =item Building Extensions
401
402 The Comprehensive Perl Archive Network (CPAN) offers a wealth
403 of extensions, some of which require a C compiler to build.
404 Look in http://www.perl.com/ for more information on CPAN.
405
406 Most extensions (whether they require a C compiler or not) can
407 be built, tested and installed with the standard mantra:
408
409     perl Makefile.PL
410     $MAKE
411     $MAKE test
412     $MAKE install
413
414 where $MAKE is whatever 'make' program you have configured perl to
415 use.  Use "perl -V:make" to find out what this is.  Some extensions
416 may not provide a testsuite (so "$MAKE test" may not do anything, or
417 fail), but most serious ones do.
418
419 It is important that you use a supported 'make' program, and
420 ensure Config.pm knows about it.  If you don't have nmake, you can
421 either get dmake from the location mentioned earlier, or get an
422 old version of nmake reportedly available from:
423
424     ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe
425
426 Another option is to use the make written in Perl, available from
427 CPAN:
428
429     http://www.perl.com/CPAN/authors/id/NI-S/Make-0.03.tar.gz
430
431 Note that MakeMaker actually emits makefiles with different syntax
432 depending on what 'make' it thinks you are using.  Therefore, it is
433 important that one of the following values appears in Config.pm:
434
435     make='nmake'        # MakeMaker emits nmake syntax
436     make='dmake'        # MakeMaker emits dmake syntax
437     any other value     # MakeMaker emits generic make syntax
438                             (e.g GNU make, or Perl make)
439
440 If the value doesn't match the 'make' program you want to use,
441 edit Config.pm to fix it.
442
443 If a module implements XSUBs, you will need one of the supported
444 C compilers.  You must make sure you have set up the environment for
445 the compiler for command-line compilation.
446
447 If a module does not build for some reason, look carefully for
448 why it failed, and report problems to the module author.  If
449 it looks like the extension building support is at fault, report
450 that with full details of how the build failed using the perlbug
451 utility.
452
453 =item Command-line Wildcard Expansion
454
455 The default command shells on DOS descendant operating systems (such
456 as they are) usually do not expand wildcard arguments supplied to
457 programs.  They consider it the application's job to handle that.
458 This is commonly achieved by linking the application (in our case,
459 perl) with startup code that the C runtime libraries usually provide.
460 However, doing that results in incompatible perl versions (since the
461 behavior of the argv expansion code differs depending on the
462 compiler, and it is even buggy on some compilers).  Besides, it may
463 be a source of frustration if you use such a perl binary with an
464 alternate shell that *does* expand wildcards.
465
466 Instead, the following solution works rather well. The nice things
467 about it: 1) you can start using it right away 2) it is more powerful,
468 because it will do the right thing with a pattern like */*/*.c
469 3) you can decide whether you do/don't want to use it 4) you can
470 extend the method to add any customizations (or even entirely
471 different kinds of wildcard expansion).
472
473         C:\> copy con c:\perl\lib\Wild.pm
474         # Wild.pm - emulate shell @ARGV expansion on shells that don't
475         use File::DosGlob;
476         @ARGV = map {
477                       my @g = File::DosGlob::glob($_) if /[*?]/;
478                       @g ? @g : $_;
479                     } @ARGV;
480         1;
481         ^Z
482         C:\> set PERL5OPT=-MWild
483         C:\> perl -le "for (@ARGV) { print }" */*/perl*.c
484         p4view/perl/perl.c
485         p4view/perl/perlio.c
486         p4view/perl/perly.c
487         perl5.005/win32/perlglob.c
488         perl5.005/win32/perllib.c
489         perl5.005/win32/perlglob.c
490         perl5.005/win32/perllib.c
491         perl5.005/win32/perlglob.c
492         perl5.005/win32/perllib.c
493
494 Note there are two distinct steps there: 1) You'll have to create
495 Wild.pm and put it in your perl lib directory. 2) You'll need to
496 set the PERL5OPT environment variable.  If you want argv expansion
497 to be the default, just set PERL5OPT in your default startup
498 environment.
499
500 If you are using the Visual C compiler, you can get the C runtime's
501 command line wildcard expansion built into perl binary.  The resulting
502 binary will always expand unquoted command lines, which may not be
503 what you want if you use a shell that does that for you.  The expansion
504 done is also somewhat less powerful than the approach suggested above.
505
506 =item Win32 Specific Extensions
507
508 A number of extensions specific to the Win32 platform are available
509 from CPAN.  You may find that many of these extensions are meant to
510 be used under the Activeware port of Perl, which used to be the only
511 native port for the Win32 platform.  Since the Activeware port does not
512 have adequate support for Perl's extension building tools, these
513 extensions typically do not support those tools either, and therefore
514 cannot be built using the generic steps shown in the previous section.
515
516 To ensure smooth transitioning of existing code that uses the
517 ActiveState port, there is a bundle of Win32 extensions that contains
518 all of the ActiveState extensions and most other Win32 extensions from
519 CPAN in source form, along with many added bugfixes, and with MakeMaker
520 support.  This bundle is available at:
521
522    http://www.perl.com/CPAN/authors/id/GSAR/libwin32-0.14.zip
523
524 See the README in that distribution for building and installation
525 instructions.  Look for later versions that may be available at the
526 same location.
527
528 =item Running Perl Scripts
529
530 Perl scripts on UNIX use the "#!" (a.k.a "shebang") line to
531 indicate to the OS that it should execute the file using perl.
532 Win32 has no comparable means to indicate arbitrary files are
533 executables.
534
535 Instead, all available methods to execute plain text files on
536 Win32 rely on the file "extension".  There are three methods
537 to use this to execute perl scripts:
538
539 =over 8
540
541 =item 1
542
543 There is a facility called "file extension associations" that will
544 work in Windows NT 4.0.  This can be manipulated via the two
545 commands "assoc" and "ftype" that come standard with Windows NT
546 4.0.  Type "ftype /?" for a complete example of how to set this
547 up for perl scripts (Say what?  You thought Windows NT wasn't
548 perl-ready? :).
549
550 =item 2
551
552 Since file associations don't work everywhere, and there are
553 reportedly bugs with file associations where it does work, the
554 old method of wrapping the perl script to make it look like a
555 regular batch file to the OS, may be used.  The install process
556 makes available the "pl2bat.bat" script which can be used to wrap
557 perl scripts into batch files.  For example:
558
559         pl2bat foo.pl
560
561 will create the file "FOO.BAT".  Note "pl2bat" strips any
562 .pl suffix and adds a .bat suffix to the generated file.
563
564 If you use the 4DOS/NT or similar command shell, note that
565 "pl2bat" uses the "%*" variable in the generated batch file to
566 refer to all the command line arguments, so you may need to make
567 sure that construct works in batch files.  As of this writing,
568 4DOS/NT users will need a "ParameterChar = *" statement in their
569 4NT.INI file, or will need to execute "setdos /p*" in the 4DOS/NT
570 startup file to enable this to work.
571
572 =item 3
573
574 Using "pl2bat" has a few problems:  the file name gets changed,
575 so scripts that rely on C<$0> to find what they must do may not
576 run properly; running "pl2bat" replicates the contents of the
577 original script, and so this process can be maintenance intensive
578 if the originals get updated often.  A different approach that
579 avoids both problems is possible.
580
581 A script called "runperl.bat" is available that can be copied
582 to any filename (along with the .bat suffix).  For example,
583 if you call it "foo.bat", it will run the file "foo" when it is
584 executed.  Since you can run batch files on Win32 platforms simply
585 by typing the name (without the extension), this effectively
586 runs the file "foo", when you type either "foo" or "foo.bat".
587 With this method, "foo.bat" can even be in a different location
588 than the file "foo", as long as "foo" is available somewhere on
589 the PATH.  If your scripts are on a filesystem that allows symbolic
590 links, you can even avoid copying "runperl.bat".
591
592 Here's a diversion:  copy "runperl.bat" to "runperl", and type
593 "runperl".  Explain the observed behavior, or lack thereof. :)
594 Hint: .gnidnats llits er'uoy fi ,"lrepnur" eteled :tniH
595
596 =back
597
598 =item Miscellaneous Things
599
600 A full set of HTML documentation is installed, so you should be
601 able to use it if you have a web browser installed on your
602 system.
603
604 C<perldoc> is also a useful tool for browsing information contained
605 in the documentation, especially in conjunction with a pager
606 like C<less> (recent versions of which have Win32 support).  You may
607 have to set the PAGER environment variable to use a specific pager.
608 "perldoc -f foo" will print information about the perl operator
609 "foo".
610
611 If you find bugs in perl, you can run C<perlbug> to create a
612 bug report (you may have to send it manually if C<perlbug> cannot
613 find a mailer on your system).
614
615 =back
616
617 =head1 BUGS AND CAVEATS
618
619 An effort has been made to ensure that the DLLs produced by the two
620 supported compilers are compatible with each other (despite the
621 best efforts of the compiler vendors).  Extension binaries produced
622 by one compiler should also coexist with a perl binary built by
623 a different compiler.  In order to accomplish this, PERL.DLL provides
624 a layer of runtime code that uses the C Runtime that perl was compiled
625 with.  Extensions which include "perl.h" will transparently access
626 the functions in this layer, thereby ensuring that both perl and
627 extensions use the same runtime functions.
628
629 If you have had prior exposure to Perl on Unix platforms, you will notice
630 this port exhibits behavior different from what is documented.  Most of the
631 differences fall under one of these categories.  We do not consider
632 any of them to be serious limitations (especially when compared to the
633 limited nature of some of the Win32 OSes themselves :)
634
635 =over 8
636
637 =item *
638
639 C<stat()> and C<lstat()> functions may not behave as documented.  They
640 may return values that bear no resemblance to those reported on Unix
641 platforms, and some fields (like the the one for inode) may be completely
642 bogus.
643
644 =item *
645
646 The following functions are currently unavailable: C<fork()>,
647 C<dump()>, C<chown()>, C<link()>, C<symlink()>, C<chroot()>,
648 C<setpgrp()> and related security functions, C<setpriority()>,
649 C<getpriority()>, C<syscall()>, C<fcntl()>, C<getpw*()>,
650 C<msg*()>, C<shm*()>, C<sem*()>, C<alarm()>, C<socketpair()>,
651 C<*netent()>, C<*protoent()>, C<*servent()>, C<*hostent()>,
652 C<getnetby*()>.
653 This list is possibly incomplete.
654
655 =item *
656
657 Various C<socket()> related calls are supported, but they may not
658 behave as on Unix platforms.
659
660 =item *
661
662 The four-argument C<select()> call is only supported on sockets.
663
664 =item *
665
666 The C<ioctl()> call is only supported on sockets (where it provides the
667 functionality of ioctlsocket() in the Winsock API).
668
669 =item *
670
671 Failure to spawn() a subprocess is indicated by setting $? to "255 << 8".
672 C<$?> is set in a way compatible with Unix (i.e. the exitstatus of the
673 subprocess is obtained by "$? >> 8", as described in the documentation).
674
675 =item *
676
677 You can expect problems building modules available on CPAN if you
678 build perl itself with -DUSE_THREADS.  These problems should be resolved
679 as we get closer to 5.005.
680
681 =item *
682
683 C<utime()>, C<times()> and process-related functions may not
684 behave as described in the documentation, and some of the
685 returned values or effects may be bogus.
686
687 =item *
688
689 Signal handling may not behave as on Unix platforms (where it
690 doesn't exactly "behave", either :).  For instance, calling C<die()>
691 or C<exit()> from signal handlers will cause an exception, since most
692 implementations of C<signal()> on Win32 are severely crippled.
693 Thus, signals may work only for simple things like setting a flag
694 variable in the handler.  Using signals under this port should
695 currently be considered unsupported.
696
697 =item *
698
699 C<kill()> is implemented, but doesn't have the semantics of
700 C<raise()>, i.e. it doesn't send a signal to the identified process
701 like it does on Unix platforms.  Instead it immediately calls
702 C<TerminateProcess(process,signal)>.  Thus the signal argument is
703 used to set the exit-status of the terminated process.  In particular,
704 C<kill(0,$pid)> will kill the process identified by C<$pid> (unlike
705 on Unix).  This behavior may change in future.
706
707 =item *
708
709 File globbing may not behave as on Unix platforms.  In particular,
710 if you don't use perlglob.bat for globbing, it will understand
711 wildcards only in the filename component (and not in the pathname).
712 In other words, something like "print <*/*.pl>" will not print all the
713 perl scripts in all the subdirectories one level under the current one
714 (like it does on UNIX platforms).  perlglob.exe is also dependent on
715 the particular implementation of wildcard expansion in the vendor
716 libraries used to build it (which varies wildly at the present time).
717 Using perlglob.bat (or File::DosGlob) avoids these limitations, but
718 still only provides DOS semantics (read "warts") for globbing.
719
720 =back
721
722 Please send detailed descriptions of any problems and solutions that 
723 you may find to <F<perlbug@perl.com>>, along with the output produced
724 by C<perl -V>.
725
726 =head1 AUTHORS
727
728 =over 4
729
730 Gary Ng E<lt>71564.1743@CompuServe.COME<gt>
731
732 Gurusamy Sarathy E<lt>gsar@activestate.comE<gt>
733
734 Nick Ing-Simmons E<lt>nick@ni-s.u-net.comE<gt>
735
736 =back
737
738 This document is maintained by Gurusamy Sarathy.
739
740 =head1 SEE ALSO
741
742 L<perl>
743
744 =head1 HISTORY
745
746 This port was originally contributed by Gary Ng around 5.003_24,
747 and borrowed from the Hip Communications port that was available
748 at the time.
749
750 Nick Ing-Simmons and Gurusamy Sarathy have made numerous and
751 sundry hacks since then.
752
753 Borland support was added in 5.004_01 (Gurusamy Sarathy).
754
755 GCC/mingw32 support was added in 5.005 (Nick Ing-Simmons).
756
757 Support for PERL_OBJECT was added in 5.005 (ActiveState Tool Corp).
758
759 Last updated: 18 January 1999
760
761 =cut
762