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