This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Have win32/makefile.mk default to gcc, and update docs
[perl5.git] / README.win32
CommitLineData
9baed986
LC
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
7perlwin32 - Perl under Windows
8
9=head1 SYNOPSIS
10
11These are instructions for building Perl under Windows 9x/NT/2000/XP
12on the Intel x86 and Itanium architectures.
13
14=head1 DESCRIPTION
15
16Before you start, you should glance through the README file
17found in the top-level directory to which the Perl distribution
18was extracted. Make sure you read and understand the terms under
19which this software is being distributed.
20
21Also make sure you read L<BUGS AND CAVEATS> below for the
22known limitations of this port.
23
24The INSTALL file in the perl top-level has much information that is
25only relevant to people building Perl on Unix-like systems. In
26particular, you can safely ignore any information that talks about
27"Configure".
28
29You may also want to look at two other options for building
30a perl that will work on Windows NT: the README.cygwin and
31README.os2 files, each of which give a different set of rules to
32build a Perl that will work on Win32 platforms. Those two methods
33will probably enable you to build a more Unix-compatible perl, but
34you will also need to download and use various other build-time and
35run-time support software described in those files.
36
37This set of instructions is meant to describe a so-called "native"
38port of Perl to Win32 platforms. This includes both 32-bit and
3964-bit Windows operating systems. The resulting Perl requires no
40additional software to run (other than what came with your operating
41system). Currently, this port is capable of using one of the
42following compilers on the Intel x86 architecture:
43
44 Borland C++ version 5.02 or later
45 Microsoft Visual C++ version 4.2 or later
e2736246 46 MinGW with gcc gcc version 2.95.2 or later
9baed986 47
e2736246
SH
48The last of these is a high quality freeware compiler. Use version
493.2.x or later for the best results with this compiler.
9baed986
LC
50
51This port can also be built on the Intel IA64 using:
52
53 Microsoft Platform SDK Nov 2001 (64-bit compiler and tools)
54
55The MS Platform SDK can be downloaded from http://www.microsoft.com/.
56
57This port fully supports MakeMaker (the set of modules that
58is used to build extensions to perl). Therefore, you should be
59able to build and install most extensions found in the CPAN sites.
60See L<Usage Hints for Perl on Win32> below for general hints about this.
61
62=head2 Setting Up Perl on Win32
63
64=over 4
65
66=item Make
67
68You need a "make" program to build the sources. If you are using
69Visual C++ or the Platform SDK tools under Windows NT/2000/XP, nmake
70will work. All other builds need dmake.
71
72dmake is a freely available make that has very nice macro features
73and parallelability.
74
75A port of dmake for Windows is available from:
76
77 http://www.cpan.org/authors/id/GSAR/dmake-4.1pl1-win32.zip
78
79(This is a fixed version of the original dmake sources obtained from
80http://www.wticorp.com/ As of version 4.1PL1, the original
81sources did not build as shipped and had various other problems.
82A patch is included in the above fixed version.)
83
84Fetch and install dmake somewhere on your path (follow the instructions
85in the README.NOW file).
86
87There exists a minor coexistence problem with dmake and Borland C++
88compilers. Namely, if a distribution has C files named with mixed
89case letters, they will be compiled into appropriate .obj-files named
90with all lowercase letters, and every time dmake is invoked
91to bring files up to date, it will try to recompile such files again.
92For example, Tk distribution has a lot of such files, resulting in
93needless recompiles every time dmake is invoked. To avoid this, you
94may use the script "sync_ext.pl" after a successful build. It is
95available in the win32 subdirectory of the Perl source distribution.
96
97=item Command Shell
98
99Use the default "cmd" shell that comes with NT. Some versions of the
100popular 4DOS/NT shell have incompatibilities that may cause you trouble.
101If the build fails under that shell, try building again with the cmd
102shell.
103
104The nmake Makefile also has known incompatibilities with the
105"command.com" shell that comes with Windows 9x. You will need to
106use dmake and makefile.mk to build under Windows 9x.
107
108The surest way to build it is on Windows NT/2000/XP, using the cmd shell.
109
110Make sure the path to the build directory does not contain spaces. The
111build usually works in this circumstance, but some tests will fail.
112
113=item Borland C++
114
115If you are using the Borland compiler, you will need dmake.
116(The make that Borland supplies is seriously crippled and will not
117work for MakeMaker builds.)
118
119See L</"Make"> above.
120
121=item Microsoft Visual C++
122
123The nmake that comes with Visual C++ will suffice for building.
124You will need to run the VCVARS32.BAT file, usually found somewhere
125like C:\MSDEV4.2\BIN. This will set your build environment.
126
127You can also use dmake to build using Visual C++; provided, however,
128you set OSRELEASE to "microsft" (or whatever the directory name
129under which the Visual C dmake configuration lives) in your environment
130and edit win32/config.vc to change "make=nmake" into "make=dmake". The
131latter step is only essential if you want to use dmake as your default
132make for building extensions using MakeMaker.
133
134=item Microsoft Platform SDK 64-bit Compiler
135
136The nmake that comes with the Platform SDK will suffice for building
137Perl. Make sure you are building within one of the "Build Environment"
138shells available after you install the Platform SDK from the Start Menu.
139
e2736246 140=item MinGW release 3 with gcc
9baed986 141
e2736246
SH
142The latest release of MinGW at the time of writing is 3.1.0, which comes
143with gcc-3.2.3, and can be downloaded here:
9baed986 144
e2736246 145 http://www.mingw.org/
7c5b6093 146
e2736246
SH
147Perl also compiles with earlier releases of gcc (2.95.2 and up). See below
148for notes about using earlier versions of MinGW/gcc.
9baed986
LC
149
150You also need dmake. See L</"Make"> above on how to get it.
151
e2736246 152=item MinGW release 1 with gcc
7c5b6093
AB
153
154The MinGW-1.1 bundle comes with gcc-2.95.3.
9baed986
LC
155
156Make sure you install the binaries that work with MSVCRT.DLL as indicated
157in the README for the GCC bundle. You may need to set up a few environment
158variables (usually ran from a batch file).
159
160There are a couple of problems with the version of gcc-2.95.2-msvcrt.exe
161released 7 November 1999:
162
163=over
164
165=item *
166
167It left out a fix for certain command line quotes. To fix this, be sure
168to download and install the file fixes/quote-fix-msvcrt.exe from the above
169ftp location.
170
171=item *
172
173The definition of the fpos_t type in stdio.h may be wrong. If your
174stdio.h has this problem, you will see an exception when running the
175test t/lib/io_xs.t. To fix this, change the typedef for fpos_t from
176"long" to "long long" in the file i386-mingw32msvc/include/stdio.h,
177and rebuild.
178
179=back
180
181A potentially simpler to install (but probably soon-to-be-outdated) bundle
182of the above package with the mentioned fixes already applied is available
183here:
184
185 http://downloads.ActiveState.com/pub/staff/gsar/gcc-2.95.2-msvcrt.zip
186 ftp://ftp.ActiveState.com/pub/staff/gsar/gcc-2.95.2-msvcrt.zip
187
188=back
189
190=head2 Building
191
192=over 4
193
194=item *
195
196Make sure you are in the "win32" subdirectory under the perl toplevel.
197This directory contains a "Makefile" that will work with
198versions of nmake that come with Visual C++ or the Platform SDK, and
199a dmake "makefile.mk" that will work for all supported compilers. The
200defaults in the dmake makefile are setup to build using Microsoft Visual
201C++ 6.0 or newer.
202
203=item *
204
205Edit the makefile.mk (or Makefile, if you're using nmake) and change
206the values of INST_DRV and INST_TOP. You can also enable various
207build flags. These are explained in the makefiles.
208
2b1846f4
SH
209Note that it is generally not a good idea to try to build a perl with
210INST_DRV and INST_TOP set to a path that already exists from a previous
211build. In particular, this may cause problems with the
212lib/ExtUtils/t/Embed.t test, which attempts to build a test program and
213may end up building against the installed perl's lib/CORE directory rather
214than the one being tested.
215
9baed986
LC
216You will have to make sure that CCTYPE is set correctly and that
217CCHOME points to wherever you installed your compiler.
218
219The default value for CCHOME in the makefiles for Visual C++
220may not be correct for some versions. Make sure the default exists
221and is valid.
222
223If you have either the source or a library that contains des_fcrypt(),
4ace4afb
SH
224enable the appropriate option in the makefile. A ready-to-use version
225of fcrypt.c, based on the version originally written by Eric Young at
226ftp://ftp.funet.fi/pub/crypt/mirrors/dsi/libdes/, is bundled with the
227distribution. Set CRYPT_SRC to fcrypt.c to use this version.
228Alternatively, if you have built a library that contains des_fcrypt(),
229you can set CRYPT_LIB to point to the library name.
9baed986
LC
230Perl will also build without des_fcrypt(), but the crypt() builtin will
231fail at run time.
232
233Be sure to read the instructions near the top of the makefiles carefully.
234
235=item *
236
237Type "dmake" (or "nmake" if you are using that make).
238
239This should build everything. Specifically, it will create perl.exe,
78a7c709 240perl59.dll at the perl toplevel, and various other extension dll's
9baed986
LC
241under the lib\auto directory. If the build fails for any reason, make
242sure you have done the previous steps correctly.
243
244=back
245
246=head2 Testing Perl on Win32
247
248Type "dmake test" (or "nmake test"). This will run most of the tests from
249the testsuite (many tests will be skipped).
250
251There should be no test failures when running under Windows NT/2000/XP.
252Many tests I<will> fail under Windows 9x due to the inferior command shell.
253
254Some test failures may occur if you use a command shell other than the
255native "cmd.exe", or if you are building from a path that contains
256spaces. So don't do that.
257
258If you are running the tests from a emacs shell window, you may see
259failures in op/stat.t. Run "dmake test-notty" in that case.
260
261If you're using the Borland compiler, you may see a failure in op/taint.t
262arising from the inability to find the Borland Runtime DLLs on the system
263default path. You will need to copy the DLLs reported by the messages
264from where Borland chose to install it, into the Windows system directory
265(usually somewhere like C:\WINNT\SYSTEM32) and rerun the test.
266
267If you're using Borland compiler versions 5.2 and below, you may run into
268problems finding the correct header files when building extensions. For
269example, building the "Tk" extension may fail because both perl and Tk
270contain a header file called "patchlevel.h". The latest Borland compiler
271(v5.5) is free of this misbehaviour, and it even supports an
272option -VI- for backward (bugward) compatibility for using the old Borland
273search algorithm to locate header files.
274
a6a21311
PEE
275If you run the tests on a FAT partition, you may see some failures for
276C<link()> related tests (I<op/write.t>, I<op/stat.t> ...). Testing on
277NTFS avoids these errors.
278
279Furthermore, you should make sure that during C<make test> you do not
280have any GNU tool packages in your path: some toolkits like Unixutils
281include some tools (C<type> for instance) which override the Windows
282ones and makes tests fail. Remove them from your path while testing to
283avoid these errors.
284
9baed986
LC
285Please report any other failures as described under L<BUGS AND CAVEATS>.
286
287=head2 Installation of Perl on Win32
288
289Type "dmake install" (or "nmake install"). This will put the newly
290built perl and the libraries under whatever C<INST_TOP> points to in the
291Makefile. It will also install the pod documentation under
292C<$INST_TOP\$VERSION\lib\pod> and HTML versions of the same under
293C<$INST_TOP\$VERSION\lib\pod\html>. To use the Perl you just installed,
294you will need to add two components to your PATH environment variable,
295C<$INST_TOP\$VERSION\bin> and C<$INST_TOP\$VERSION\bin\$ARCHNAME>.
296For example:
297
298 set PATH c:\perl\5.6.0\bin;c:\perl\5.6.0\bin\MSWin32-x86;%PATH%
299
300If you opt to comment out INST_VER and INST_ARCH in the makefiles, the
301installation structure is much simpler. In that case, it will be
302sufficient to add a single entry to the path, for instance:
303
304 set PATH c:\perl\bin;%PATH%
305
306=head2 Usage Hints for Perl on Win32
307
308=over 4
309
310=item Environment Variables
311
312The installation paths that you set during the build get compiled
313into perl, so you don't have to do anything additional to start
314using that perl (except add its location to your PATH variable).
315
316If you put extensions in unusual places, you can set PERL5LIB
317to a list of paths separated by semicolons where you want perl
318to look for libraries. Look for descriptions of other environment
319variables you can set in L<perlrun>.
320
321You can also control the shell that perl uses to run system() and
322backtick commands via PERL5SHELL. See L<perlrun>.
323
324Perl does not depend on the registry, but it can look up certain default
325values if you choose to put them there. Perl attempts to read entries from
326C<HKEY_CURRENT_USER\Software\Perl> and C<HKEY_LOCAL_MACHINE\Software\Perl>.
327Entries in the former override entries in the latter. One or more of the
328following entries (of type REG_SZ or REG_EXPAND_SZ) may be set:
329
330 lib-$] version-specific standard library path to add to @INC
331 lib standard library path to add to @INC
332 sitelib-$] version-specific site library path to add to @INC
333 sitelib site library path to add to @INC
334 vendorlib-$] version-specific vendor library path to add to @INC
335 vendorlib vendor library path to add to @INC
336 PERL* fallback for all %ENV lookups that begin with "PERL"
337
338Note the C<$]> in the above is not literal. Substitute whatever version
339of perl you want to honor that entry, e.g. C<5.6.0>. Paths must be
340separated with semicolons, as usual on win32.
341
342=item File Globbing
343
344By default, perl handles file globbing using the File::Glob extension,
345which provides portable globbing.
346
347If you want perl to use globbing that emulates the quirks of DOS
348filename conventions, you might want to consider using File::DosGlob
349to override the internal glob() implementation. See L<File::DosGlob> for
350details.
351
352=item Using perl from the command line
353
354If you are accustomed to using perl from various command-line
355shells found in UNIX environments, you will be less than pleased
356with what Windows offers by way of a command shell.
357
358The crucial thing to understand about the Windows environment is that
359the command line you type in is processed twice before Perl sees it.
360First, your command shell (usually CMD.EXE on Windows NT, and
361COMMAND.COM on Windows 9x) preprocesses the command line, to handle
362redirection, environment variable expansion, and location of the
363executable to run. Then, the perl executable splits the remaining
364command line into individual arguments, using the C runtime library
365upon which Perl was built.
366
367It is particularly important to note that neither the shell nor the C
368runtime do any wildcard expansions of command-line arguments (so
369wildcards need not be quoted). Also, the quoting behaviours of the
370shell and the C runtime are rudimentary at best (and may, if you are
371using a non-standard shell, be inconsistent). The only (useful) quote
372character is the double quote ("). It can be used to protect spaces
373and other special characters in arguments.
374
375The Windows NT documentation has almost no description of how the
376quoting rules are implemented, but here are some general observations
377based on experiments: The C runtime breaks arguments at spaces and
378passes them to programs in argc/argv. Double quotes can be used to
379prevent arguments with spaces in them from being split up. You can
380put a double quote in an argument by escaping it with a backslash and
381enclosing the whole argument within double quotes. The backslash and
382the pair of double quotes surrounding the argument will be stripped by
383the C runtime.
384
385The file redirection characters "<", ">", and "|" can be quoted by
386double quotes (although there are suggestions that this may not always
387be true). Single quotes are not treated as quotes by the shell or
388the C runtime, they don't get stripped by the shell (just to make
389this type of quoting completely useless). The caret "^" has also
390been observed to behave as a quoting character, but this appears
391to be a shell feature, and the caret is not stripped from the command
392line, so Perl still sees it (and the C runtime phase does not treat
393the caret as a quote character).
394
395Here are some examples of usage of the "cmd" shell:
396
397This prints two doublequotes:
398
399 perl -e "print '\"\"' "
400
401This does the same:
402
403 perl -e "print \"\\\"\\\"\" "
404
405This prints "bar" and writes "foo" to the file "blurch":
406
407 perl -e "print 'foo'; print STDERR 'bar'" > blurch
408
409This prints "foo" ("bar" disappears into nowhereland):
410
411 perl -e "print 'foo'; print STDERR 'bar'" 2> nul
412
413This prints "bar" and writes "foo" into the file "blurch":
414
415 perl -e "print 'foo'; print STDERR 'bar'" 1> blurch
416
417This pipes "foo" to the "less" pager and prints "bar" on the console:
418
419 perl -e "print 'foo'; print STDERR 'bar'" | less
420
421This pipes "foo\nbar\n" to the less pager:
422
423 perl -le "print 'foo'; print STDERR 'bar'" 2>&1 | less
424
425This pipes "foo" to the pager and writes "bar" in the file "blurch":
426
427 perl -e "print 'foo'; print STDERR 'bar'" 2> blurch | less
428
429
430Discovering the usefulness of the "command.com" shell on Windows 9x
431is left as an exercise to the reader :)
432
433One particularly pernicious problem with the 4NT command shell for
434Windows NT is that it (nearly) always treats a % character as indicating
435that environment variable expansion is needed. Under this shell, it is
436therefore important to always double any % characters which you want
437Perl to see (for example, for hash variables), even when they are
438quoted.
439
440=item Building Extensions
441
442The Comprehensive Perl Archive Network (CPAN) offers a wealth
443of extensions, some of which require a C compiler to build.
444Look in http://www.cpan.org/ for more information on CPAN.
445
446Note that not all of the extensions available from CPAN may work
447in the Win32 environment; you should check the information at
448http://testers.cpan.org/ before investing too much effort into
449porting modules that don't readily build.
450
451Most extensions (whether they require a C compiler or not) can
452be built, tested and installed with the standard mantra:
453
454 perl Makefile.PL
455 $MAKE
456 $MAKE test
457 $MAKE install
458
459where $MAKE is whatever 'make' program you have configured perl to
460use. Use "perl -V:make" to find out what this is. Some extensions
461may not provide a testsuite (so "$MAKE test" may not do anything or
462fail), but most serious ones do.
463
464It is important that you use a supported 'make' program, and
465ensure Config.pm knows about it. If you don't have nmake, you can
466either get dmake from the location mentioned earlier or get an
467old version of nmake reportedly available from:
468
cb9857f1 469 http://download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/nmake15.exe
9baed986
LC
470
471Another option is to use the make written in Perl, available from
472CPAN.
473
474 http://www.cpan.org/modules/by-module/Make/
475
476You may also use dmake. See L</"Make"> above on how to get it.
477
478Note that MakeMaker actually emits makefiles with different syntax
479depending on what 'make' it thinks you are using. Therefore, it is
480important that one of the following values appears in Config.pm:
481
482 make='nmake' # MakeMaker emits nmake syntax
483 make='dmake' # MakeMaker emits dmake syntax
484 any other value # MakeMaker emits generic make syntax
485 (e.g GNU make, or Perl make)
486
487If the value doesn't match the 'make' program you want to use,
488edit Config.pm to fix it.
489
490If a module implements XSUBs, you will need one of the supported
491C compilers. You must make sure you have set up the environment for
492the compiler for command-line compilation.
493
494If a module does not build for some reason, look carefully for
495why it failed, and report problems to the module author. If
496it looks like the extension building support is at fault, report
497that with full details of how the build failed using the perlbug
498utility.
499
500=item Command-line Wildcard Expansion
501
502The default command shells on DOS descendant operating systems (such
503as they are) usually do not expand wildcard arguments supplied to
504programs. They consider it the application's job to handle that.
505This is commonly achieved by linking the application (in our case,
506perl) with startup code that the C runtime libraries usually provide.
507However, doing that results in incompatible perl versions (since the
508behavior of the argv expansion code differs depending on the
509compiler, and it is even buggy on some compilers). Besides, it may
510be a source of frustration if you use such a perl binary with an
511alternate shell that *does* expand wildcards.
512
513Instead, the following solution works rather well. The nice things
514about it are 1) you can start using it right away; 2) it is more
515powerful, because it will do the right thing with a pattern like
516*/*/*.c; 3) you can decide whether you do/don't want to use it; and
5174) you can extend the method to add any customizations (or even
518entirely different kinds of wildcard expansion).
519
520 C:\> copy con c:\perl\lib\Wild.pm
521 # Wild.pm - emulate shell @ARGV expansion on shells that don't
522 use File::DosGlob;
523 @ARGV = map {
524 my @g = File::DosGlob::glob($_) if /[*?]/;
525 @g ? @g : $_;
526 } @ARGV;
527 1;
528 ^Z
529 C:\> set PERL5OPT=-MWild
530 C:\> perl -le "for (@ARGV) { print }" */*/perl*.c
531 p4view/perl/perl.c
532 p4view/perl/perlio.c
533 p4view/perl/perly.c
534 perl5.005/win32/perlglob.c
535 perl5.005/win32/perllib.c
536 perl5.005/win32/perlglob.c
537 perl5.005/win32/perllib.c
538 perl5.005/win32/perlglob.c
539 perl5.005/win32/perllib.c
540
541Note there are two distinct steps there: 1) You'll have to create
542Wild.pm and put it in your perl lib directory. 2) You'll need to
543set the PERL5OPT environment variable. If you want argv expansion
544to be the default, just set PERL5OPT in your default startup
545environment.
546
547If you are using the Visual C compiler, you can get the C runtime's
548command line wildcard expansion built into perl binary. The resulting
549binary will always expand unquoted command lines, which may not be
550what you want if you use a shell that does that for you. The expansion
551done is also somewhat less powerful than the approach suggested above.
552
553=item Win32 Specific Extensions
554
555A number of extensions specific to the Win32 platform are available
556from CPAN. You may find that many of these extensions are meant to
557be used under the Activeware port of Perl, which used to be the only
558native port for the Win32 platform. Since the Activeware port does not
559have adequate support for Perl's extension building tools, these
560extensions typically do not support those tools either and, therefore,
561cannot be built using the generic steps shown in the previous section.
562
563To ensure smooth transitioning of existing code that uses the
564ActiveState port, there is a bundle of Win32 extensions that contains
565all of the ActiveState extensions and most other Win32 extensions from
566CPAN in source form, along with many added bugfixes, and with MakeMaker
567support. This bundle is available at:
568
569 http://www.cpan.org/authors/id/GSAR/libwin32-0.18.zip
570
571See the README in that distribution for building and installation
572instructions. Look for later versions that may be available at the
573same location.
574
575=item Notes on 64-bit Windows
576
577Windows .NET Server supports the LLP64 data model on the Intel Itanium
578architecture.
579
580The LLP64 data model is different from the LP64 data model that is the
581norm on 64-bit Unix platforms. In the former, C<int> and C<long> are
582both 32-bit data types, while pointers are 64 bits wide. In addition,
583there is a separate 64-bit wide integral type, C<__int64>. In contrast,
584the LP64 data model that is pervasive on Unix platforms provides C<int>
585as the 32-bit type, while both the C<long> type and pointers are of
58664-bit precision. Note that both models provide for 64-bits of
587addressability.
588
58964-bit Windows running on Itanium is capable of running 32-bit x86
590binaries transparently. This means that you could use a 32-bit build
591of Perl on a 64-bit system. Given this, why would one want to build
592a 64-bit build of Perl? Here are some reasons why you would bother:
593
594=item *
595
596A 64-bit native application will run much more efficiently on
597Itanium hardware.
598
599=item *
600
601There is no 2GB limit on process size.
602
603=item *
604
605Perl automatically provides large file support when built under
60664-bit Windows.
607
608=item *
609
610Embedding Perl inside a 64-bit application.
611
612=back
613
614=head2 Running Perl Scripts
615
616Perl scripts on UNIX use the "#!" (a.k.a "shebang") line to
617indicate to the OS that it should execute the file using perl.
618Win32 has no comparable means to indicate arbitrary files are
619executables.
620
621Instead, all available methods to execute plain text files on
622Win32 rely on the file "extension". There are three methods
623to use this to execute perl scripts:
624
625=over 8
626
627=item 1
628
629There is a facility called "file extension associations" that will
630work in Windows NT 4.0. This can be manipulated via the two
631commands "assoc" and "ftype" that come standard with Windows NT
6324.0. Type "ftype /?" for a complete example of how to set this
633up for perl scripts (Say what? You thought Windows NT wasn't
634perl-ready? :).
635
636=item 2
637
638Since file associations don't work everywhere, and there are
639reportedly bugs with file associations where it does work, the
640old method of wrapping the perl script to make it look like a
641regular batch file to the OS, may be used. The install process
642makes available the "pl2bat.bat" script which can be used to wrap
643perl scripts into batch files. For example:
644
645 pl2bat foo.pl
646
647will create the file "FOO.BAT". Note "pl2bat" strips any
648.pl suffix and adds a .bat suffix to the generated file.
649
650If you use the 4DOS/NT or similar command shell, note that
651"pl2bat" uses the "%*" variable in the generated batch file to
652refer to all the command line arguments, so you may need to make
653sure that construct works in batch files. As of this writing,
6544DOS/NT users will need a "ParameterChar = *" statement in their
6554NT.INI file or will need to execute "setdos /p*" in the 4DOS/NT
656startup file to enable this to work.
657
658=item 3
659
660Using "pl2bat" has a few problems: the file name gets changed,
661so scripts that rely on C<$0> to find what they must do may not
662run properly; running "pl2bat" replicates the contents of the
663original script, and so this process can be maintenance intensive
664if the originals get updated often. A different approach that
665avoids both problems is possible.
666
667A script called "runperl.bat" is available that can be copied
668to any filename (along with the .bat suffix). For example,
669if you call it "foo.bat", it will run the file "foo" when it is
670executed. Since you can run batch files on Win32 platforms simply
671by typing the name (without the extension), this effectively
672runs the file "foo", when you type either "foo" or "foo.bat".
673With this method, "foo.bat" can even be in a different location
674than the file "foo", as long as "foo" is available somewhere on
675the PATH. If your scripts are on a filesystem that allows symbolic
676links, you can even avoid copying "runperl.bat".
677
678Here's a diversion: copy "runperl.bat" to "runperl", and type
679"runperl". Explain the observed behavior, or lack thereof. :)
680Hint: .gnidnats llits er'uoy fi ,"lrepnur" eteled :tniH
681
682=item Miscellaneous Things
683
684A full set of HTML documentation is installed, so you should be
685able to use it if you have a web browser installed on your
686system.
687
688C<perldoc> is also a useful tool for browsing information contained
689in the documentation, especially in conjunction with a pager
690like C<less> (recent versions of which have Win32 support). You may
691have to set the PAGER environment variable to use a specific pager.
692"perldoc -f foo" will print information about the perl operator
693"foo".
694
13ee867e
BD
695One common mistake when using this port with a GUI library like C<Tk>
696is assuming that Perl's normal behavior of opening a command-line
697window will go away. This isn't the case. If you want to start a copy
698of C<perl> without opening a command-line window, use the C<wperl>
699executable built during the installation process. Usage is exactly
700the same as normal C<perl> on Win32, except that options like C<-h>
701don't work (since they need a command-line window to print to).
702
9baed986
LC
703If you find bugs in perl, you can run C<perlbug> to create a
704bug report (you may have to send it manually if C<perlbug> cannot
705find a mailer on your system).
706
707=back
708
709=head1 BUGS AND CAVEATS
710
711Norton AntiVirus interferes with the build process, particularly if
712set to "AutoProtect, All Files, when Opened". Unlike large applications
713the perl build process opens and modifies a lot of files. Having the
714the AntiVirus scan each and every one slows build the process significantly.
715Worse, with PERLIO=stdio the build process fails with peculiar messages
716as the virus checker interacts badly with miniperl.exe writing configure
717files (it seems to either catch file part written and treat it as suspicious,
718or virus checker may have it "locked" in a way which inhibits miniperl
719updating it). The build does complete with
720
721 set PERLIO=perlio
722
723but that may be just luck. Other AntiVirus software may have similar issues.
724
725Some of the built-in functions do not act exactly as documented in
726L<perlfunc>, and a few are not implemented at all. To avoid
727surprises, particularly if you have had prior exposure to Perl
728in other operating environments or if you intend to write code
729that will be portable to other environments. See L<perlport>
730for a reasonably definitive list of these differences.
731
732Not all extensions available from CPAN may build or work properly
733in the Win32 environment. See L</"Building Extensions">.
734
735Most C<socket()> related calls are supported, but they may not
736behave as on Unix platforms. See L<perlport> for the full list.
737
738Signal handling may not behave as on Unix platforms (where it
739doesn't exactly "behave", either :). For instance, calling C<die()>
740or C<exit()> from signal handlers will cause an exception, since most
741implementations of C<signal()> on Win32 are severely crippled.
742Thus, signals may work only for simple things like setting a flag
743variable in the handler. Using signals under this port should
744currently be considered unsupported.
745
746Please send detailed descriptions of any problems and solutions that
747you may find to <F<perlbug@perl.com>>, along with the output produced
748by C<perl -V>.
749
e84ac4e2
SH
750=head1 ACKNOWLEDGEMENTS
751
752The use of a camel with the topic of Perl is a trademark
753of O'Reilly and Associates, Inc. Used with permission.
754
9baed986
LC
755=head1 AUTHORS
756
757=over 4
758
759=item Gary Ng E<lt>71564.1743@CompuServe.COME<gt>
760
761=item Gurusamy Sarathy E<lt>gsar@activestate.comE<gt>
762
763=item Nick Ing-Simmons E<lt>nick@ing-simmons.netE<gt>
764
765=back
766
767This document is maintained by Gurusamy Sarathy.
768
769=head1 SEE ALSO
770
771L<perl>
772
773=head1 HISTORY
774
775This port was originally contributed by Gary Ng around 5.003_24,
776and borrowed from the Hip Communications port that was available
777at the time. Various people have made numerous and sundry hacks
778since then.
779
780Borland support was added in 5.004_01 (Gurusamy Sarathy).
781
782GCC/mingw32 support was added in 5.005 (Nick Ing-Simmons).
783
784Support for PERL_OBJECT was added in 5.005 (ActiveState Tool Corp).
785
786Support for fork() emulation was added in 5.6 (ActiveState Tool Corp).
787
788Win9x support was added in 5.6 (Benjamin Stuhl).
789
790Support for 64-bit Windows added in 5.8 (ActiveState Corp).
791
792Last updated: 20 April 2002
793
794=cut