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