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