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