This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
vendorlib support for Windows; regen win32/config*
[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 standard library path to add to @INC
279     lib                 standard library path to add to @INC
280     sitelib-$]          version-specific site library path to add to @INC
281     sitelib             site library path to add to @INC
282     vendorlib-$]        version-specific vendor library path to add to @INC
283     vendorlib           vendor library path to add to @INC
284     PERL*               fallback for all %ENV lookups that begin with "PERL"
285
286 Note the C<$]> in the above is not literal.  Substitute whatever version
287 of perl you want to honor that entry, e.g. C<5.6.0>.  Paths must be
288 separated with semicolons, as usual on win32.
289
290 =item File Globbing
291
292 By default, perl spawns an external program to do file globbing.
293 The install process installs both a perlglob.exe and a perlglob.bat
294 that perl can use for this purpose.  Note that with the default
295 installation, perlglob.exe will be found by the system before
296 perlglob.bat.
297
298 perlglob.exe relies on the argv expansion done by the C Runtime of
299 the particular compiler you used, and therefore behaves very
300 differently depending on the Runtime used to build it.  To preserve
301 compatiblity, perlglob.bat (a perl script that can be used portably)
302 is installed.  Besides being portable, perlglob.bat also offers
303 enhanced globbing functionality.
304
305 If you want perl to use perlglob.bat instead of perlglob.exe, just
306 delete perlglob.exe from the install location (or move it somewhere
307 perl cannot find).  Using File::DosGlob.pm (which implements the core
308 functionality of perlglob.bat) to override the internal CORE::glob()
309 works about 10 times faster than spawing perlglob.exe, and you should
310 take this approach when writing new modules.  See File::DosGlob for
311 details.
312
313 =item Using perl from the command line
314
315 If you are accustomed to using perl from various command-line
316 shells found in UNIX environments, you will be less than pleased
317 with what Windows NT offers by way of a command shell.
318
319 The crucial thing to understand about the "cmd" shell (which is
320 the default on Windows NT) is that it does not do any wildcard
321 expansions of command-line arguments (so wildcards need not be
322 quoted).  It also provides only rudimentary quoting.  The only
323 (useful) quote character is the double quote (").  It can be used to
324 protect spaces in arguments and other special characters.  The
325 Windows NT documentation has almost no description of how the
326 quoting rules are implemented, but here are some general observations
327 based on experiments:  The shell breaks arguments at spaces and
328 passes them to programs in argc/argv.  Doublequotes can be used
329 to prevent arguments with spaces in them from being split up.
330 You can put a double quote in an argument by escaping it with
331 a backslash and enclosing the whole argument within double quotes.
332 The backslash and the pair of double quotes surrounding the
333 argument will be stripped by the shell.
334
335 The file redirection characters "<", ">", and "|" cannot be quoted
336 by double quotes (there are probably more such).  Single quotes
337 will protect those three file redirection characters, but the
338 single quotes don't get stripped by the shell (just to make this
339 type of quoting completely useless).  The caret "^" has also
340 been observed to behave as a quoting character (and doesn't get
341 stripped by the shell also).
342
343 Here are some examples of usage of the "cmd" shell:
344
345 This prints two doublequotes:
346
347     perl -e "print '\"\"' "
348
349 This does the same:
350
351     perl -e "print \"\\\"\\\"\" "
352
353 This prints "bar" and writes "foo" to the file "blurch":
354
355     perl -e "print 'foo'; print STDERR 'bar'" > blurch
356
357 This prints "foo" ("bar" disappears into nowhereland):
358
359     perl -e "print 'foo'; print STDERR 'bar'" 2> nul
360
361 This prints "bar" and writes "foo" into the file "blurch":
362
363     perl -e "print 'foo'; print STDERR 'bar'" 1> blurch
364
365 This pipes "foo" to the "less" pager and prints "bar" on the console:
366
367     perl -e "print 'foo'; print STDERR 'bar'" | less
368
369 This pipes "foo\nbar\n" to the less pager:
370
371     perl -le "print 'foo'; print STDERR 'bar'" 2>&1 | less
372
373 This pipes "foo" to the pager and writes "bar" in the file "blurch":
374
375     perl -e "print 'foo'; print STDERR 'bar'" 2> blurch | less
376
377
378 Discovering the usefulness of the "command.com" shell on Windows95
379 is left as an exercise to the reader :)
380
381 =item Building Extensions
382
383 The Comprehensive Perl Archive Network (CPAN) offers a wealth
384 of extensions, some of which require a C compiler to build.
385 Look in http://www.perl.com/ for more information on CPAN.
386
387 Most extensions (whether they require a C compiler or not) can
388 be built, tested and installed with the standard mantra:
389
390     perl Makefile.PL
391     $MAKE
392     $MAKE test
393     $MAKE install
394
395 where $MAKE is whatever 'make' program you have configured perl to
396 use.  Use "perl -V:make" to find out what this is.  Some extensions
397 may not provide a testsuite (so "$MAKE test" may not do anything, or
398 fail), but most serious ones do.
399
400 It is important that you use a supported 'make' program, and
401 ensure Config.pm knows about it.  If you don't have nmake, you can
402 either get dmake from the location mentioned earlier, or get an
403 old version of nmake reportedly available from:
404
405     ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe
406
407 Another option is to use the make written in Perl, available from
408 CPAN:
409
410     http://www.perl.com/CPAN/authors/id/NI-S/Make-0.03.tar.gz
411
412 You may also use dmake.  See L</"Borland C++"> above on how to get it.
413
414 Note that MakeMaker actually emits makefiles with different syntax
415 depending on what 'make' it thinks you are using.  Therefore, it is
416 important that one of the following values appears in Config.pm:
417
418     make='nmake'        # MakeMaker emits nmake syntax
419     make='dmake'        # MakeMaker emits dmake syntax
420     any other value     # MakeMaker emits generic make syntax
421                             (e.g GNU make, or Perl make)
422
423 If the value doesn't match the 'make' program you want to use,
424 edit Config.pm to fix it.
425
426 If a module implements XSUBs, you will need one of the supported
427 C compilers.  You must make sure you have set up the environment for
428 the compiler for command-line compilation.
429
430 If a module does not build for some reason, look carefully for
431 why it failed, and report problems to the module author.  If
432 it looks like the extension building support is at fault, report
433 that with full details of how the build failed using the perlbug
434 utility.
435
436 =item Command-line Wildcard Expansion
437
438 The default command shells on DOS descendant operating systems (such
439 as they are) usually do not expand wildcard arguments supplied to
440 programs.  They consider it the application's job to handle that.
441 This is commonly achieved by linking the application (in our case,
442 perl) with startup code that the C runtime libraries usually provide.
443 However, doing that results in incompatible perl versions (since the
444 behavior of the argv expansion code differs depending on the
445 compiler, and it is even buggy on some compilers).  Besides, it may
446 be a source of frustration if you use such a perl binary with an
447 alternate shell that *does* expand wildcards.
448
449 Instead, the following solution works rather well. The nice things
450 about it: 1) you can start using it right away 2) it is more powerful,
451 because it will do the right thing with a pattern like */*/*.c
452 3) you can decide whether you do/don't want to use it 4) you can
453 extend the method to add any customizations (or even entirely
454 different kinds of wildcard expansion).
455
456         C:\> copy con c:\perl\lib\Wild.pm
457         # Wild.pm - emulate shell @ARGV expansion on shells that don't
458         use File::DosGlob;
459         @ARGV = map {
460                       my @g = File::DosGlob::glob($_) if /[*?]/;
461                       @g ? @g : $_;
462                     } @ARGV;
463         1;
464         ^Z
465         C:\> set PERL5OPT=-MWild
466         C:\> perl -le "for (@ARGV) { print }" */*/perl*.c
467         p4view/perl/perl.c
468         p4view/perl/perlio.c
469         p4view/perl/perly.c
470         perl5.005/win32/perlglob.c
471         perl5.005/win32/perllib.c
472         perl5.005/win32/perlglob.c
473         perl5.005/win32/perllib.c
474         perl5.005/win32/perlglob.c
475         perl5.005/win32/perllib.c
476
477 Note there are two distinct steps there: 1) You'll have to create
478 Wild.pm and put it in your perl lib directory. 2) You'll need to
479 set the PERL5OPT environment variable.  If you want argv expansion
480 to be the default, just set PERL5OPT in your default startup
481 environment.
482
483 If you are using the Visual C compiler, you can get the C runtime's
484 command line wildcard expansion built into perl binary.  The resulting
485 binary will always expand unquoted command lines, which may not be
486 what you want if you use a shell that does that for you.  The expansion
487 done is also somewhat less powerful than the approach suggested above.
488
489 =item Win32 Specific Extensions
490
491 A number of extensions specific to the Win32 platform are available
492 from CPAN.  You may find that many of these extensions are meant to
493 be used under the Activeware port of Perl, which used to be the only
494 native port for the Win32 platform.  Since the Activeware port does not
495 have adequate support for Perl's extension building tools, these
496 extensions typically do not support those tools either, and therefore
497 cannot be built using the generic steps shown in the previous section.
498
499 To ensure smooth transitioning of existing code that uses the
500 ActiveState port, there is a bundle of Win32 extensions that contains
501 all of the ActiveState extensions and most other Win32 extensions from
502 CPAN in source form, along with many added bugfixes, and with MakeMaker
503 support.  This bundle is available at:
504
505    http://www.perl.com/CPAN/authors/id/GSAR/libwin32-0.14.zip
506
507 See the README in that distribution for building and installation
508 instructions.  Look for later versions that may be available at the
509 same location.
510
511 =item Running Perl Scripts
512
513 Perl scripts on UNIX use the "#!" (a.k.a "shebang") line to
514 indicate to the OS that it should execute the file using perl.
515 Win32 has no comparable means to indicate arbitrary files are
516 executables.
517
518 Instead, all available methods to execute plain text files on
519 Win32 rely on the file "extension".  There are three methods
520 to use this to execute perl scripts:
521
522 =over 8
523
524 =item 1
525
526 There is a facility called "file extension associations" that will
527 work in Windows NT 4.0.  This can be manipulated via the two
528 commands "assoc" and "ftype" that come standard with Windows NT
529 4.0.  Type "ftype /?" for a complete example of how to set this
530 up for perl scripts (Say what?  You thought Windows NT wasn't
531 perl-ready? :).
532
533 =item 2
534
535 Since file associations don't work everywhere, and there are
536 reportedly bugs with file associations where it does work, the
537 old method of wrapping the perl script to make it look like a
538 regular batch file to the OS, may be used.  The install process
539 makes available the "pl2bat.bat" script which can be used to wrap
540 perl scripts into batch files.  For example:
541
542         pl2bat foo.pl
543
544 will create the file "FOO.BAT".  Note "pl2bat" strips any
545 .pl suffix and adds a .bat suffix to the generated file.
546
547 If you use the 4DOS/NT or similar command shell, note that
548 "pl2bat" uses the "%*" variable in the generated batch file to
549 refer to all the command line arguments, so you may need to make
550 sure that construct works in batch files.  As of this writing,
551 4DOS/NT users will need a "ParameterChar = *" statement in their
552 4NT.INI file, or will need to execute "setdos /p*" in the 4DOS/NT
553 startup file to enable this to work.
554
555 =item 3
556
557 Using "pl2bat" has a few problems:  the file name gets changed,
558 so scripts that rely on C<$0> to find what they must do may not
559 run properly; running "pl2bat" replicates the contents of the
560 original script, and so this process can be maintenance intensive
561 if the originals get updated often.  A different approach that
562 avoids both problems is possible.
563
564 A script called "runperl.bat" is available that can be copied
565 to any filename (along with the .bat suffix).  For example,
566 if you call it "foo.bat", it will run the file "foo" when it is
567 executed.  Since you can run batch files on Win32 platforms simply
568 by typing the name (without the extension), this effectively
569 runs the file "foo", when you type either "foo" or "foo.bat".
570 With this method, "foo.bat" can even be in a different location
571 than the file "foo", as long as "foo" is available somewhere on
572 the PATH.  If your scripts are on a filesystem that allows symbolic
573 links, you can even avoid copying "runperl.bat".
574
575 Here's a diversion:  copy "runperl.bat" to "runperl", and type
576 "runperl".  Explain the observed behavior, or lack thereof. :)
577 Hint: .gnidnats llits er'uoy fi ,"lrepnur" eteled :tniH
578
579 =back
580
581 =item Miscellaneous Things
582
583 A full set of HTML documentation is installed, so you should be
584 able to use it if you have a web browser installed on your
585 system.
586
587 C<perldoc> is also a useful tool for browsing information contained
588 in the documentation, especially in conjunction with a pager
589 like C<less> (recent versions of which have Win32 support).  You may
590 have to set the PAGER environment variable to use a specific pager.
591 "perldoc -f foo" will print information about the perl operator
592 "foo".
593
594 If you find bugs in perl, you can run C<perlbug> to create a
595 bug report (you may have to send it manually if C<perlbug> cannot
596 find a mailer on your system).
597
598 =back
599
600 =head1 BUGS AND CAVEATS
601
602 An effort has been made to ensure that the DLLs produced by the two
603 supported compilers are compatible with each other (despite the
604 best efforts of the compiler vendors).  Extension binaries produced
605 by one compiler should also coexist with a perl binary built by
606 a different compiler.  In order to accomplish this, PERL.DLL provides
607 a layer of runtime code that uses the C Runtime that perl was compiled
608 with.  Extensions which include "perl.h" will transparently access
609 the functions in this layer, thereby ensuring that both perl and
610 extensions use the same runtime functions.
611
612 If you have had prior exposure to Perl on Unix platforms, you will notice
613 this port exhibits behavior different from what is documented.  Most of the
614 differences fall under one of these categories.  We do not consider
615 any of them to be serious limitations (especially when compared to the
616 limited nature of some of the Win32 OSes themselves :)
617
618 =over 8
619
620 =item *
621
622 C<stat()> and C<lstat()> functions may not behave as documented.  They
623 may return values that bear no resemblance to those reported on Unix
624 platforms, and some fields (like the the one for inode) may be completely
625 bogus.
626
627 =item *
628
629 The following functions are currently unavailable: C<fork()>,
630 C<dump()>, C<chown()>, C<link()>, C<symlink()>, C<chroot()>,
631 C<setpgrp()> and related security functions, C<setpriority()>,
632 C<getpriority()>, C<syscall()>, C<fcntl()>, C<getpw*()>,
633 C<msg*()>, C<shm*()>, C<sem*()>, C<alarm()>, C<socketpair()>,
634 C<*netent()>, C<*protoent()>, C<*servent()>, C<*hostent()>,
635 C<getnetby*()>.
636 This list is possibly incomplete.
637
638 =item *
639
640 Various C<socket()> related calls are supported, but they may not
641 behave as on Unix platforms.
642
643 =item *
644
645 The four-argument C<select()> call is only supported on sockets.
646
647 =item *
648
649 The C<ioctl()> call is only supported on sockets (where it provides the
650 functionality of ioctlsocket() in the Winsock API).
651
652 =item *
653
654 Failure to spawn() a subprocess is indicated by setting $? to "255 << 8".
655 C<$?> is set in a way compatible with Unix (i.e. the exitstatus of the
656 subprocess is obtained by "$? >> 8", as described in the documentation).
657
658 =item *
659
660 You can expect problems building modules available on CPAN if you
661 build perl itself with -DUSE_THREADS.  These problems should be resolved
662 as we get closer to 5.005.
663
664 =item *
665
666 C<utime()>, C<times()> and process-related functions may not
667 behave as described in the documentation, and some of the
668 returned values or effects may be bogus.
669
670 =item *
671
672 Signal handling may not behave as on Unix platforms (where it
673 doesn't exactly "behave", either :).  For instance, calling C<die()>
674 or C<exit()> from signal handlers will cause an exception, since most
675 implementations of C<signal()> on Win32 are severely crippled.
676 Thus, signals may work only for simple things like setting a flag
677 variable in the handler.  Using signals under this port should
678 currently be considered unsupported.
679
680 =item *
681
682 C<kill()> is implemented, but doesn't have the semantics of
683 C<raise()>, i.e. it doesn't send a signal to the identified process
684 like it does on Unix platforms.  Instead it immediately calls
685 C<TerminateProcess(process,signal)>.  Thus the signal argument is
686 used to set the exit-status of the terminated process.  However,
687 a signal of 0 can be used to safely check if the specified process
688 exists, as on Unix.
689
690 =item *
691
692 File globbing may not behave as on Unix platforms.  In particular,
693 if you don't use perlglob.bat for globbing, it will understand
694 wildcards only in the filename component (and not in the pathname).
695 In other words, something like "print <*/*.pl>" will not print all the
696 perl scripts in all the subdirectories one level under the current one
697 (like it does on UNIX platforms).  perlglob.exe is also dependent on
698 the particular implementation of wildcard expansion in the vendor
699 libraries used to build it (which varies wildly at the present time).
700 Using perlglob.bat (or File::DosGlob) avoids these limitations, but
701 still only provides DOS semantics (read "warts") for globbing.
702
703 =back
704
705 Please send detailed descriptions of any problems and solutions that 
706 you may find to <F<perlbug@perl.com>>, along with the output produced
707 by C<perl -V>.
708
709 =head1 AUTHORS
710
711 =over 4
712
713 Gary Ng E<lt>71564.1743@CompuServe.COME<gt>
714
715 Gurusamy Sarathy E<lt>gsar@activestate.comE<gt>
716
717 Nick Ing-Simmons E<lt>nick@ni-s.u-net.comE<gt>
718
719 =back
720
721 This document is maintained by Gurusamy Sarathy.
722
723 =head1 SEE ALSO
724
725 L<perl>
726
727 =head1 HISTORY
728
729 This port was originally contributed by Gary Ng around 5.003_24,
730 and borrowed from the Hip Communications port that was available
731 at the time.  Various people have made numerous and sundry hacks
732 since then.
733
734 Borland support was added in 5.004_01 (Gurusamy Sarathy).
735
736 GCC/mingw32 support was added in 5.005 (Nick Ing-Simmons).
737
738 Support for PERL_OBJECT was added in 5.005 (ActiveState Tool Corp).
739
740 Support for fork() emulation was added in 5.6 (ActiveState Tool Corp).
741
742 Win9x support was added in 5.6 (Benjamin Stuhl).
743
744 Last updated: 28 December 1999
745
746 =cut