1 If you read this file _as_is_, just ignore the funny characters you
2 see. It is written in the POD format (see pod/perlpod.pod) which is
3 specially designed to be readable as is.
7 perlwin32 - Perl under Windows
11 These are instructions for building Perl under Windows 9x/NT/2000/XP
12 on the Intel x86 and Itanium architectures.
16 Before you start, you should glance through the README file
17 found in the top-level directory to which the Perl distribution
18 was extracted. Make sure you read and understand the terms under
19 which this software is being distributed.
21 Also make sure you read L<BUGS AND CAVEATS> below for the
22 known limitations of this port.
24 The INSTALL file in the perl top-level has much information that is
25 only relevant to people building Perl on Unix-like systems. In
26 particular, you can safely ignore any information that talks about
29 You may also want to look at two other options for building
30 a perl that will work on Windows NT: the README.cygwin and
31 README.os2 files, each of which give a different set of rules to
32 build a Perl that will work on Win32 platforms. Those two methods
33 will probably enable you to build a more Unix-compatible perl, but
34 you will also need to download and use various other build-time and
35 run-time support software described in those files.
37 This set of instructions is meant to describe a so-called "native"
38 port of Perl to Win32 platforms. This includes both 32-bit and
39 64-bit Windows operating systems. The resulting Perl requires no
40 additional software to run (other than what came with your operating
41 system). Currently, this port is capable of using one of the
42 following compilers on the Intel x86 architecture:
44 Borland C++ version 5.02 or later
45 Microsoft Visual C++ version 4.2 or later
46 MinGW with gcc gcc version 2.95.2 or later
48 The last of these is a high quality freeware compiler. Use version
49 3.2.x or later for the best results with this compiler.
51 The Microsoft Visual C++ compiler is also now being given away free in
52 the "Visual C++ Toolkit 2003", and also as part of the ".NET Framework
53 SDK". This is the same compiler that ships with "Visual Studio .NET 2003
56 This port can also be built on the Intel IA64 using:
58 Microsoft Platform SDK Nov 2001 (64-bit compiler and tools)
60 The MS Platform SDK can be downloaded from http://www.microsoft.com/.
62 This port fully supports MakeMaker (the set of modules that
63 is used to build extensions to perl). Therefore, you should be
64 able to build and install most extensions found in the CPAN sites.
65 See L<Usage Hints for Perl on Win32> below for general hints about this.
67 =head2 Setting Up Perl on Win32
73 You need a "make" program to build the sources. If you are using
74 Visual C++ or the Platform SDK tools under Windows NT/2000/XP, nmake
75 will work. All other builds need dmake.
77 dmake is a freely available make that has very nice macro features
80 A port of dmake for Windows is available from:
82 http://www.cpan.org/authors/id/GSAR/dmake-4.1pl1-win32.zip
84 (This is a fixed version of the original dmake sources obtained from
85 http://www.wticorp.com/ As of version 4.1PL1, the original
86 sources did not build as shipped and had various other problems.
87 A patch is included in the above fixed version.)
89 Fetch and install dmake somewhere on your path (follow the instructions
90 in the README.NOW file).
92 There exists a minor coexistence problem with dmake and Borland C++
93 compilers. Namely, if a distribution has C files named with mixed
94 case letters, they will be compiled into appropriate .obj-files named
95 with all lowercase letters, and every time dmake is invoked
96 to bring files up to date, it will try to recompile such files again.
97 For example, Tk distribution has a lot of such files, resulting in
98 needless recompiles every time dmake is invoked. To avoid this, you
99 may use the script "sync_ext.pl" after a successful build. It is
100 available in the win32 subdirectory of the Perl source distribution.
104 Use the default "cmd" shell that comes with NT. Some versions of the
105 popular 4DOS/NT shell have incompatibilities that may cause you trouble.
106 If the build fails under that shell, try building again with the cmd
109 The nmake Makefile also has known incompatibilities with the
110 "command.com" shell that comes with Windows 9x. You will need to
111 use dmake and makefile.mk to build under Windows 9x.
113 The surest way to build it is on Windows NT/2000/XP, using the cmd shell.
115 Make sure the path to the build directory does not contain spaces. The
116 build usually works in this circumstance, but some tests will fail.
120 If you are using the Borland compiler, you will need dmake.
121 (The make that Borland supplies is seriously crippled and will not
122 work for MakeMaker builds.)
124 See L</"Make"> above.
126 =item Microsoft Visual C++
128 The nmake that comes with Visual C++ will suffice for building.
129 You will need to run the VCVARS32.BAT file, usually found somewhere
130 like C:\MSDEV4.2\BIN or C:\Program Files\Microsoft Visual Studio\VC98\Bin.
131 This will set your build environment.
133 You can also use dmake to build using Visual C++; provided, however,
134 you set OSRELEASE to "microsft" (or whatever the directory name
135 under which the Visual C dmake configuration lives) in your environment
136 and edit win32/config.vc to change "make=nmake" into "make=dmake". The
137 latter step is only essential if you want to use dmake as your default
138 make for building extensions using MakeMaker.
140 =item Microsoft Visual C++ Toolkit 2003
142 This free toolkit contains the same compiler and linker that ship with
143 Visual Studio .NET 2003 Professional, but doesn't contain everything
144 necessary to build Perl.
146 You will also need to download the "Platform SDK" (the "Core SDK" and "MDAC
147 SDK" components are required) for header files, libraries and rc.exe, and
148 ".NET Framework SDK" for more libraries and nmake.exe. Note that the latter
149 (which also includes the free compiler and linker) requires the ".NET
150 Framework Redistributable" to be installed first. This can be downloaded and
151 installed separately, but is included in the "Visual C++ Toolkit 2003" anyway.
153 These packages can all be downloaded by searching in the Download Center at
154 http://www.microsoft.com/downloads/search.aspx?displaylang=en
156 Note that the "Platform SDK February 2003" download requires Internet Explorer
157 5.0 to function. Alternatively, the very latest version at the time of writing
158 (called "Windows XP Service Pack 2 Platform SDK RC2") is now available as an
159 ISO-9660 CD image file and does not require IE5 to be downloaded but will only
162 According to the download pages the Toolkit and the .NET Framework SDK are only
163 supported on Windows 2000/XP/2003, so trying to use these tools on Windows
164 95/98/ME and even Windows NT probably won't work.
166 Install the Toolkit first, then the Platform SDK, then the .NET Framework SDK.
167 Setup your environment as follows (assuming default installation locations
170 SET PATH=%SystemRoot%\system32;%SystemRoot%;C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin;C:\Program Files\Microsoft SDK\Bin;C:\Program Files\Microsoft.NET\SDK\v1.1\Bin
171 SET INCLUDE=C:\Program Files\Microsoft Visual C++ Toolkit 2003\include;C:\Program Files\Microsoft SDK\include;C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\include
172 SET LIB=C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib;C:\Program Files\Microsoft SDK\lib;C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\lib
174 Several required files will still be missing:
180 cvtres.exe is required by link.exe when using a .res file. It is actually
181 installed by the .NET Framework SDK, but into a location such as the
184 C:\WINDOWS\Microsoft.NET\Framework\v1.1.4322
186 Copy it from there to C:\Program Files\Microsoft SDK\Bin
190 lib.exe is normally used to build libraries, but link.exe with the /lib
191 option also works, so create a batch file called lib.bat in
192 C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin containing:
197 This will work as long as "lib.exe" is invoked simply as "lib" (which it is
198 during the Perl build process).
202 setargv.obj is required to build perlglob.exe (and perl.exe if the USE_SETARGV
203 option is enabled). The Platform SDK supplies this object file in source form
204 in C:\Program Files\Microsoft SDK\src\crt. Copy setargv.c, cruntime.h and
205 internal.h from there to some temporary location and build setargv.obj using
207 cl.exe /c /I. /D_CRTBLD setargv.c
209 Then copy setargv.obj to C:\Program Files\Microsoft SDK\lib
213 Perl should now build using the win32/Makefile. You will need to edit that
214 file to comment-out CCTYPE = MSVC60 (since that enables delay-loading of the
215 Winsock DLL which the free toolkit does not support) and to set CCHOME,
216 CCINCDIR and CCLIBDIR as per the environment setup above.
218 =item Microsoft Platform SDK 64-bit Compiler
220 The nmake that comes with the Platform SDK will suffice for building
221 Perl. Make sure you are building within one of the "Build Environment"
222 shells available after you install the Platform SDK from the Start Menu.
224 =item MinGW release 3 with gcc
226 The latest release of MinGW at the time of writing is 3.1.0, which contains
227 gcc-3.2.3. It can be downloaded here:
229 http://www.mingw.org/
231 Perl also compiles with earlier releases of gcc (2.95.2 and up). See below
232 for notes about using earlier versions of MinGW/gcc.
234 You also need dmake. See L</"Make"> above on how to get it.
236 =item MinGW release 1 with gcc
238 The MinGW-1.1 bundle contains gcc-2.95.3.
240 Make sure you install the binaries that work with MSVCRT.DLL as indicated
241 in the README for the GCC bundle. You may need to set up a few environment
242 variables (usually ran from a batch file).
244 There are a couple of problems with the version of gcc-2.95.2-msvcrt.exe
245 released 7 November 1999:
251 It left out a fix for certain command line quotes. To fix this, be sure
252 to download and install the file fixes/quote-fix-msvcrt.exe from the above
257 The definition of the fpos_t type in stdio.h may be wrong. If your
258 stdio.h has this problem, you will see an exception when running the
259 test t/lib/io_xs.t. To fix this, change the typedef for fpos_t from
260 "long" to "long long" in the file i386-mingw32msvc/include/stdio.h,
265 A potentially simpler to install (but probably soon-to-be-outdated) bundle
266 of the above package with the mentioned fixes already applied is available
269 http://downloads.ActiveState.com/pub/staff/gsar/gcc-2.95.2-msvcrt.zip
270 ftp://ftp.ActiveState.com/pub/staff/gsar/gcc-2.95.2-msvcrt.zip
280 Make sure you are in the "win32" subdirectory under the perl toplevel.
281 This directory contains a "Makefile" that will work with
282 versions of nmake that come with Visual C++ or the Platform SDK, and
283 a dmake "makefile.mk" that will work for all supported compilers. The
284 defaults in the dmake makefile are setup to build using MinGW/gcc.
288 Edit the makefile.mk (or Makefile, if you're using nmake) and change
289 the values of INST_DRV and INST_TOP. You can also enable various
290 build flags. These are explained in the makefiles.
292 Note that it is generally not a good idea to try to build a perl with
293 INST_DRV and INST_TOP set to a path that already exists from a previous
294 build. In particular, this may cause problems with the
295 lib/ExtUtils/t/Embed.t test, which attempts to build a test program and
296 may end up building against the installed perl's lib/CORE directory rather
297 than the one being tested.
299 You will have to make sure that CCTYPE is set correctly and that
300 CCHOME points to wherever you installed your compiler.
302 The default value for CCHOME in the makefiles for Visual C++
303 may not be correct for some versions. Make sure the default exists
306 If you have either the source or a library that contains des_fcrypt(),
307 enable the appropriate option in the makefile. A ready-to-use version
308 of fcrypt.c, based on the version originally written by Eric Young at
309 ftp://ftp.funet.fi/pub/crypt/mirrors/dsi/libdes/, is bundled with the
310 distribution and CRYPT_SRC is set to use it.
311 Alternatively, if you have built a library that contains des_fcrypt(),
312 you can set CRYPT_LIB to point to the library name.
313 Perl will also build without des_fcrypt(), but the crypt() builtin will
316 Be sure to read the instructions near the top of the makefiles carefully.
320 Type "dmake" (or "nmake" if you are using that make).
322 This should build everything. Specifically, it will create perl.exe,
323 perl58.dll at the perl toplevel, and various other extension dll's
324 under the lib\auto directory. If the build fails for any reason, make
325 sure you have done the previous steps correctly.
329 =head2 Testing Perl on Win32
331 Type "dmake test" (or "nmake test"). This will run most of the tests from
332 the testsuite (many tests will be skipped).
334 There should be no test failures when running under Windows NT/2000/XP.
335 Many tests I<will> fail under Windows 9x due to the inferior command shell.
337 Some test failures may occur if you use a command shell other than the
338 native "cmd.exe", or if you are building from a path that contains
339 spaces. So don't do that.
341 If you are running the tests from a emacs shell window, you may see
342 failures in op/stat.t. Run "dmake test-notty" in that case.
344 If you're using the Borland compiler, you may see a failure in op/taint.t
345 arising from the inability to find the Borland Runtime DLLs on the system
346 default path. You will need to copy the DLLs reported by the messages
347 from where Borland chose to install it, into the Windows system directory
348 (usually somewhere like C:\WINNT\SYSTEM32) and rerun the test.
350 If you're using Borland compiler versions 5.2 and below, you may run into
351 problems finding the correct header files when building extensions. For
352 example, building the "Tk" extension may fail because both perl and Tk
353 contain a header file called "patchlevel.h". The latest Borland compiler
354 (v5.5) is free of this misbehaviour, and it even supports an
355 option -VI- for backward (bugward) compatibility for using the old Borland
356 search algorithm to locate header files.
358 If you run the tests on a FAT partition, you may see some failures for
359 C<link()> related tests:
361 Failed Test Stat Wstat Total Fail Failed List
363 ../ext/IO/lib/IO/t/io_dup.t 6 4 66.67% 2-5
364 ../lib/File/Temp/t/mktemp.t 9 1 11.11% 2
365 ../lib/File/Temp/t/posix.t 7 1 14.29% 3
366 ../lib/File/Temp/t/security.t 13 1 7.69% 2
367 ../lib/File/Temp/t/tempfile.t 20 2 10.00% 2 4
368 comp/multiline.t 6 2 33.33% 5-6
369 io/dup.t 8 6 75.00% 2-7
370 op/write.t 47 7 14.89% 1-3 6 9-11
372 Testing on NTFS avoids these errors.
374 Furthermore, you should make sure that during C<make test> you do not
375 have any GNU tool packages in your path: some toolkits like Unixutils
376 include some tools (C<type> for instance) which override the Windows
377 ones and makes tests fail. Remove them from your path while testing to
380 Please report any other failures as described under L<BUGS AND CAVEATS>.
382 =head2 Installation of Perl on Win32
384 Type "dmake install" (or "nmake install"). This will put the newly
385 built perl and the libraries under whatever C<INST_TOP> points to in the
386 Makefile. It will also install the pod documentation under
387 C<$INST_TOP\$INST_VER\lib\pod> and HTML versions of the same under
388 C<$INST_TOP\$INST_VER\lib\pod\html>.
390 To use the Perl you just installed you will need to add a new entry to
391 your PATH environment variable: C<$INST_TOP\bin>, e.g.
393 set PATH=c:\perl\bin;%PATH%
395 If you opted to uncomment C<INST_VER> and C<INST_ARCH> in the makefile
396 then the installation structure is a little more complicated and you will
397 need to add two new PATH components instead: C<$INST_TOP\$INST_VER\bin> and
398 C<$INST_TOP\$INST_VER\bin\$ARCHNAME>, e.g.
400 set PATH=c:\perl\5.6.0\bin;c:\perl\5.6.0\bin\MSWin32-x86;%PATH%
402 =head2 Usage Hints for Perl on Win32
406 =item Environment Variables
408 The installation paths that you set during the build get compiled
409 into perl, so you don't have to do anything additional to start
410 using that perl (except add its location to your PATH variable).
412 If you put extensions in unusual places, you can set PERL5LIB
413 to a list of paths separated by semicolons where you want perl
414 to look for libraries. Look for descriptions of other environment
415 variables you can set in L<perlrun>.
417 You can also control the shell that perl uses to run system() and
418 backtick commands via PERL5SHELL. See L<perlrun>.
420 Perl does not depend on the registry, but it can look up certain default
421 values if you choose to put them there. Perl attempts to read entries from
422 C<HKEY_CURRENT_USER\Software\Perl> and C<HKEY_LOCAL_MACHINE\Software\Perl>.
423 Entries in the former override entries in the latter. One or more of the
424 following entries (of type REG_SZ or REG_EXPAND_SZ) may be set:
426 lib-$] version-specific standard library path to add to @INC
427 lib standard library path to add to @INC
428 sitelib-$] version-specific site library path to add to @INC
429 sitelib site library path to add to @INC
430 vendorlib-$] version-specific vendor library path to add to @INC
431 vendorlib vendor library path to add to @INC
432 PERL* fallback for all %ENV lookups that begin with "PERL"
434 Note the C<$]> in the above is not literal. Substitute whatever version
435 of perl you want to honor that entry, e.g. C<5.6.0>. Paths must be
436 separated with semicolons, as usual on win32.
440 By default, perl handles file globbing using the File::Glob extension,
441 which provides portable globbing.
443 If you want perl to use globbing that emulates the quirks of DOS
444 filename conventions, you might want to consider using File::DosGlob
445 to override the internal glob() implementation. See L<File::DosGlob> for
448 =item Using perl from the command line
450 If you are accustomed to using perl from various command-line
451 shells found in UNIX environments, you will be less than pleased
452 with what Windows offers by way of a command shell.
454 The crucial thing to understand about the Windows environment is that
455 the command line you type in is processed twice before Perl sees it.
456 First, your command shell (usually CMD.EXE on Windows NT, and
457 COMMAND.COM on Windows 9x) preprocesses the command line, to handle
458 redirection, environment variable expansion, and location of the
459 executable to run. Then, the perl executable splits the remaining
460 command line into individual arguments, using the C runtime library
461 upon which Perl was built.
463 It is particularly important to note that neither the shell nor the C
464 runtime do any wildcard expansions of command-line arguments (so
465 wildcards need not be quoted). Also, the quoting behaviours of the
466 shell and the C runtime are rudimentary at best (and may, if you are
467 using a non-standard shell, be inconsistent). The only (useful) quote
468 character is the double quote ("). It can be used to protect spaces
469 and other special characters in arguments.
471 The Windows NT documentation has almost no description of how the
472 quoting rules are implemented, but here are some general observations
473 based on experiments: The C runtime breaks arguments at spaces and
474 passes them to programs in argc/argv. Double quotes can be used to
475 prevent arguments with spaces in them from being split up. You can
476 put a double quote in an argument by escaping it with a backslash and
477 enclosing the whole argument within double quotes. The backslash and
478 the pair of double quotes surrounding the argument will be stripped by
481 The file redirection characters "E<lt>", "E<gt>", and "|" can be quoted by
482 double quotes (although there are suggestions that this may not always
483 be true). Single quotes are not treated as quotes by the shell or
484 the C runtime, they don't get stripped by the shell (just to make
485 this type of quoting completely useless). The caret "^" has also
486 been observed to behave as a quoting character, but this appears
487 to be a shell feature, and the caret is not stripped from the command
488 line, so Perl still sees it (and the C runtime phase does not treat
489 the caret as a quote character).
491 Here are some examples of usage of the "cmd" shell:
493 This prints two doublequotes:
495 perl -e "print '\"\"' "
499 perl -e "print \"\\\"\\\"\" "
501 This prints "bar" and writes "foo" to the file "blurch":
503 perl -e "print 'foo'; print STDERR 'bar'" > blurch
505 This prints "foo" ("bar" disappears into nowhereland):
507 perl -e "print 'foo'; print STDERR 'bar'" 2> nul
509 This prints "bar" and writes "foo" into the file "blurch":
511 perl -e "print 'foo'; print STDERR 'bar'" 1> blurch
513 This pipes "foo" to the "less" pager and prints "bar" on the console:
515 perl -e "print 'foo'; print STDERR 'bar'" | less
517 This pipes "foo\nbar\n" to the less pager:
519 perl -le "print 'foo'; print STDERR 'bar'" 2>&1 | less
521 This pipes "foo" to the pager and writes "bar" in the file "blurch":
523 perl -e "print 'foo'; print STDERR 'bar'" 2> blurch | less
526 Discovering the usefulness of the "command.com" shell on Windows 9x
527 is left as an exercise to the reader :)
529 One particularly pernicious problem with the 4NT command shell for
530 Windows NT is that it (nearly) always treats a % character as indicating
531 that environment variable expansion is needed. Under this shell, it is
532 therefore important to always double any % characters which you want
533 Perl to see (for example, for hash variables), even when they are
536 =item Building Extensions
538 The Comprehensive Perl Archive Network (CPAN) offers a wealth
539 of extensions, some of which require a C compiler to build.
540 Look in http://www.cpan.org/ for more information on CPAN.
542 Note that not all of the extensions available from CPAN may work
543 in the Win32 environment; you should check the information at
544 http://testers.cpan.org/ before investing too much effort into
545 porting modules that don't readily build.
547 Most extensions (whether they require a C compiler or not) can
548 be built, tested and installed with the standard mantra:
555 where $MAKE is whatever 'make' program you have configured perl to
556 use. Use "perl -V:make" to find out what this is. Some extensions
557 may not provide a testsuite (so "$MAKE test" may not do anything or
558 fail), but most serious ones do.
560 It is important that you use a supported 'make' program, and
561 ensure Config.pm knows about it. If you don't have nmake, you can
562 either get dmake from the location mentioned earlier or get an
563 old version of nmake reportedly available from:
565 http://download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/nmake15.exe
567 Another option is to use the make written in Perl, available from
570 http://www.cpan.org/modules/by-module/Make/
572 You may also use dmake. See L</"Make"> above on how to get it.
574 Note that MakeMaker actually emits makefiles with different syntax
575 depending on what 'make' it thinks you are using. Therefore, it is
576 important that one of the following values appears in Config.pm:
578 make='nmake' # MakeMaker emits nmake syntax
579 make='dmake' # MakeMaker emits dmake syntax
580 any other value # MakeMaker emits generic make syntax
581 (e.g GNU make, or Perl make)
583 If the value doesn't match the 'make' program you want to use,
584 edit Config.pm to fix it.
586 If a module implements XSUBs, you will need one of the supported
587 C compilers. You must make sure you have set up the environment for
588 the compiler for command-line compilation.
590 If a module does not build for some reason, look carefully for
591 why it failed, and report problems to the module author. If
592 it looks like the extension building support is at fault, report
593 that with full details of how the build failed using the perlbug
596 =item Command-line Wildcard Expansion
598 The default command shells on DOS descendant operating systems (such
599 as they are) usually do not expand wildcard arguments supplied to
600 programs. They consider it the application's job to handle that.
601 This is commonly achieved by linking the application (in our case,
602 perl) with startup code that the C runtime libraries usually provide.
603 However, doing that results in incompatible perl versions (since the
604 behavior of the argv expansion code differs depending on the
605 compiler, and it is even buggy on some compilers). Besides, it may
606 be a source of frustration if you use such a perl binary with an
607 alternate shell that *does* expand wildcards.
609 Instead, the following solution works rather well. The nice things
610 about it are 1) you can start using it right away; 2) it is more
611 powerful, because it will do the right thing with a pattern like
612 */*/*.c; 3) you can decide whether you do/don't want to use it; and
613 4) you can extend the method to add any customizations (or even
614 entirely different kinds of wildcard expansion).
616 C:\> copy con c:\perl\lib\Wild.pm
617 # Wild.pm - emulate shell @ARGV expansion on shells that don't
620 my @g = File::DosGlob::glob($_) if /[*?]/;
625 C:\> set PERL5OPT=-MWild
626 C:\> perl -le "for (@ARGV) { print }" */*/perl*.c
630 perl5.005/win32/perlglob.c
631 perl5.005/win32/perllib.c
632 perl5.005/win32/perlglob.c
633 perl5.005/win32/perllib.c
634 perl5.005/win32/perlglob.c
635 perl5.005/win32/perllib.c
637 Note there are two distinct steps there: 1) You'll have to create
638 Wild.pm and put it in your perl lib directory. 2) You'll need to
639 set the PERL5OPT environment variable. If you want argv expansion
640 to be the default, just set PERL5OPT in your default startup
643 If you are using the Visual C compiler, you can get the C runtime's
644 command line wildcard expansion built into perl binary. The resulting
645 binary will always expand unquoted command lines, which may not be
646 what you want if you use a shell that does that for you. The expansion
647 done is also somewhat less powerful than the approach suggested above.
649 =item Win32 Specific Extensions
651 A number of extensions specific to the Win32 platform are available
652 from CPAN. You may find that many of these extensions are meant to
653 be used under the Activeware port of Perl, which used to be the only
654 native port for the Win32 platform. Since the Activeware port does not
655 have adequate support for Perl's extension building tools, these
656 extensions typically do not support those tools either and, therefore,
657 cannot be built using the generic steps shown in the previous section.
659 To ensure smooth transitioning of existing code that uses the
660 ActiveState port, there is a bundle of Win32 extensions that contains
661 all of the ActiveState extensions and several other Win32 extensions from
662 CPAN in source form, along with many added bugfixes, and with MakeMaker
663 support. This bundle is available at:
665 http://www.cpan.org/modules/by-module/Win32/libwin32-0.191.zip
667 See the README in that distribution for building and installation
668 instructions. Look for later versions that may be available at the
671 =item Notes on 64-bit Windows
673 Windows .NET Server supports the LLP64 data model on the Intel Itanium
676 The LLP64 data model is different from the LP64 data model that is the
677 norm on 64-bit Unix platforms. In the former, C<int> and C<long> are
678 both 32-bit data types, while pointers are 64 bits wide. In addition,
679 there is a separate 64-bit wide integral type, C<__int64>. In contrast,
680 the LP64 data model that is pervasive on Unix platforms provides C<int>
681 as the 32-bit type, while both the C<long> type and pointers are of
682 64-bit precision. Note that both models provide for 64-bits of
685 64-bit Windows running on Itanium is capable of running 32-bit x86
686 binaries transparently. This means that you could use a 32-bit build
687 of Perl on a 64-bit system. Given this, why would one want to build
688 a 64-bit build of Perl? Here are some reasons why you would bother:
694 A 64-bit native application will run much more efficiently on
699 There is no 2GB limit on process size.
703 Perl automatically provides large file support when built under
708 Embedding Perl inside a 64-bit application.
714 =head2 Running Perl Scripts
716 Perl scripts on UNIX use the "#!" (a.k.a "shebang") line to
717 indicate to the OS that it should execute the file using perl.
718 Win32 has no comparable means to indicate arbitrary files are
721 Instead, all available methods to execute plain text files on
722 Win32 rely on the file "extension". There are three methods
723 to use this to execute perl scripts:
729 There is a facility called "file extension associations" that will
730 work in Windows NT 4.0. This can be manipulated via the two
731 commands "assoc" and "ftype" that come standard with Windows NT
732 4.0. Type "ftype /?" for a complete example of how to set this
733 up for perl scripts (Say what? You thought Windows NT wasn't
738 Since file associations don't work everywhere, and there are
739 reportedly bugs with file associations where it does work, the
740 old method of wrapping the perl script to make it look like a
741 regular batch file to the OS, may be used. The install process
742 makes available the "pl2bat.bat" script which can be used to wrap
743 perl scripts into batch files. For example:
747 will create the file "FOO.BAT". Note "pl2bat" strips any
748 .pl suffix and adds a .bat suffix to the generated file.
750 If you use the 4DOS/NT or similar command shell, note that
751 "pl2bat" uses the "%*" variable in the generated batch file to
752 refer to all the command line arguments, so you may need to make
753 sure that construct works in batch files. As of this writing,
754 4DOS/NT users will need a "ParameterChar = *" statement in their
755 4NT.INI file or will need to execute "setdos /p*" in the 4DOS/NT
756 startup file to enable this to work.
760 Using "pl2bat" has a few problems: the file name gets changed,
761 so scripts that rely on C<$0> to find what they must do may not
762 run properly; running "pl2bat" replicates the contents of the
763 original script, and so this process can be maintenance intensive
764 if the originals get updated often. A different approach that
765 avoids both problems is possible.
767 A script called "runperl.bat" is available that can be copied
768 to any filename (along with the .bat suffix). For example,
769 if you call it "foo.bat", it will run the file "foo" when it is
770 executed. Since you can run batch files on Win32 platforms simply
771 by typing the name (without the extension), this effectively
772 runs the file "foo", when you type either "foo" or "foo.bat".
773 With this method, "foo.bat" can even be in a different location
774 than the file "foo", as long as "foo" is available somewhere on
775 the PATH. If your scripts are on a filesystem that allows symbolic
776 links, you can even avoid copying "runperl.bat".
778 Here's a diversion: copy "runperl.bat" to "runperl", and type
779 "runperl". Explain the observed behavior, or lack thereof. :)
780 Hint: .gnidnats llits er'uoy fi ,"lrepnur" eteled :tniH
784 =head2 Miscellaneous Things
786 A full set of HTML documentation is installed, so you should be
787 able to use it if you have a web browser installed on your
790 C<perldoc> is also a useful tool for browsing information contained
791 in the documentation, especially in conjunction with a pager
792 like C<less> (recent versions of which have Win32 support). You may
793 have to set the PAGER environment variable to use a specific pager.
794 "perldoc -f foo" will print information about the perl operator
797 One common mistake when using this port with a GUI library like C<Tk>
798 is assuming that Perl's normal behavior of opening a command-line
799 window will go away. This isn't the case. If you want to start a copy
800 of C<perl> without opening a command-line window, use the C<wperl>
801 executable built during the installation process. Usage is exactly
802 the same as normal C<perl> on Win32, except that options like C<-h>
803 don't work (since they need a command-line window to print to).
805 If you find bugs in perl, you can run C<perlbug> to create a
806 bug report (you may have to send it manually if C<perlbug> cannot
807 find a mailer on your system).
809 =head1 BUGS AND CAVEATS
811 Norton AntiVirus interferes with the build process, particularly if
812 set to "AutoProtect, All Files, when Opened". Unlike large applications
813 the perl build process opens and modifies a lot of files. Having the
814 the AntiVirus scan each and every one slows build the process significantly.
815 Worse, with PERLIO=stdio the build process fails with peculiar messages
816 as the virus checker interacts badly with miniperl.exe writing configure
817 files (it seems to either catch file part written and treat it as suspicious,
818 or virus checker may have it "locked" in a way which inhibits miniperl
819 updating it). The build does complete with
823 but that may be just luck. Other AntiVirus software may have similar issues.
825 Some of the built-in functions do not act exactly as documented in
826 L<perlfunc>, and a few are not implemented at all. To avoid
827 surprises, particularly if you have had prior exposure to Perl
828 in other operating environments or if you intend to write code
829 that will be portable to other environments, see L<perlport>
830 for a reasonably definitive list of these differences.
832 Not all extensions available from CPAN may build or work properly
833 in the Win32 environment. See L</"Building Extensions">.
835 Most C<socket()> related calls are supported, but they may not
836 behave as on Unix platforms. See L<perlport> for the full list.
837 Perl requires Winsock2 to be installed on the system. If you're
838 running Win95, you can download Winsock upgrade from here:
840 http://www.microsoft.com/windows95/downloads/contents/WUAdminTools/S_WUNetworkingTools/W95Sockets2/Default.asp
842 Later OS versions already include Winsock2 support.
844 Signal handling may not behave as on Unix platforms (where it
845 doesn't exactly "behave", either :). For instance, calling C<die()>
846 or C<exit()> from signal handlers will cause an exception, since most
847 implementations of C<signal()> on Win32 are severely crippled.
848 Thus, signals may work only for simple things like setting a flag
849 variable in the handler. Using signals under this port should
850 currently be considered unsupported.
852 Please send detailed descriptions of any problems and solutions that
853 you may find to E<lt>F<perlbug@perl.org>E<gt>, along with the output
854 produced by C<perl -V>.
856 =head1 ACKNOWLEDGEMENTS
858 The use of a camel with the topic of Perl is a trademark
859 of O'Reilly and Associates, Inc. Used with permission.
865 =item Gary Ng E<lt>71564.1743@CompuServe.COME<gt>
867 =item Gurusamy Sarathy E<lt>gsar@activestate.comE<gt>
869 =item Nick Ing-Simmons E<lt>nick@ing-simmons.netE<gt>
873 This document is maintained by Gurusamy Sarathy.
881 This port was originally contributed by Gary Ng around 5.003_24,
882 and borrowed from the Hip Communications port that was available
883 at the time. Various people have made numerous and sundry hacks
886 Borland support was added in 5.004_01 (Gurusamy Sarathy).
888 GCC/mingw32 support was added in 5.005 (Nick Ing-Simmons).
890 Support for PERL_OBJECT was added in 5.005 (ActiveState Tool Corp).
892 Support for fork() emulation was added in 5.6 (ActiveState Tool Corp).
894 Win9x support was added in 5.6 (Benjamin Stuhl).
896 Support for 64-bit Windows added in 5.8 (ActiveState Corp).
898 Last updated: 30 July 2004