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