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