RE: [PATCH] compress 2.018
[p5sagit/p5-mst-13.2.git] / README.win32
CommitLineData
9baed986 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
7241fd28 44 Borland C++ version 5.02 or later
a7d225ec 45 Microsoft Visual C++ version 2.0 or later
7241fd28 46 MinGW with gcc gcc version 2.95.2 or later
9baed986 47
e2736246 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 50
758e4bce 51The Borland C++ and Microsoft Visual C++ compilers are also now being given
52away free. The Borland compiler is available as "Borland C++ Compiler Free
53Command Line Tools" and is the same compiler that ships with the full
54"Borland C++ Builder" product. The Microsoft compiler is available as
4a3cf07b 55"Visual C++ Toolkit 2003" or "Visual C++ 2005/2008 Express Edition" (and also
56as part of the ".NET Framework SDK") and is the same compiler that ships with
57"Visual C++ .NET 2003 Professional" or "Visual C++ 2005/2008 Professional"
a7d225ec 58respectively.
7241fd28 59
9baed986 60This port can also be built on the Intel IA64 using:
61
62 Microsoft Platform SDK Nov 2001 (64-bit compiler and tools)
63
64The MS Platform SDK can be downloaded from http://www.microsoft.com/.
65
66This port fully supports MakeMaker (the set of modules that
67is used to build extensions to perl). Therefore, you should be
68able to build and install most extensions found in the CPAN sites.
69See L<Usage Hints for Perl on Win32> below for general hints about this.
70
71=head2 Setting Up Perl on Win32
72
73=over 4
74
75=item Make
76
77You need a "make" program to build the sources. If you are using
78Visual C++ or the Platform SDK tools under Windows NT/2000/XP, nmake
79will work. All other builds need dmake.
80
81dmake is a freely available make that has very nice macro features
82and parallelability.
83
84A port of dmake for Windows is available from:
85
13e18e90 86 http://search.cpan.org/dist/dmake/
9baed986 87
13e18e90 88Fetch and install dmake somewhere on your path.
9baed986 89
90There exists a minor coexistence problem with dmake and Borland C++
91compilers. Namely, if a distribution has C files named with mixed
92case letters, they will be compiled into appropriate .obj-files named
93with all lowercase letters, and every time dmake is invoked
94to bring files up to date, it will try to recompile such files again.
95For example, Tk distribution has a lot of such files, resulting in
96needless recompiles every time dmake is invoked. To avoid this, you
97may use the script "sync_ext.pl" after a successful build. It is
98available in the win32 subdirectory of the Perl source distribution.
99
100=item Command Shell
101
102Use the default "cmd" shell that comes with NT. Some versions of the
103popular 4DOS/NT shell have incompatibilities that may cause you trouble.
104If the build fails under that shell, try building again with the cmd
105shell.
106
107The nmake Makefile also has known incompatibilities with the
108"command.com" shell that comes with Windows 9x. You will need to
109use dmake and makefile.mk to build under Windows 9x.
110
111The surest way to build it is on Windows NT/2000/XP, using the cmd shell.
112
113Make sure the path to the build directory does not contain spaces. The
114build usually works in this circumstance, but some tests will fail.
115
116=item Borland C++
117
118If you are using the Borland compiler, you will need dmake.
119(The make that Borland supplies is seriously crippled and will not
120work for MakeMaker builds.)
121
122See L</"Make"> above.
123
124=item Microsoft Visual C++
125
126The nmake that comes with Visual C++ will suffice for building.
127You will need to run the VCVARS32.BAT file, usually found somewhere
00808b83 128like C:\MSDEV4.2\BIN or C:\Program Files\Microsoft Visual Studio\VC98\Bin.
129This will set your build environment.
9baed986 130
131You can also use dmake to build using Visual C++; provided, however,
132you set OSRELEASE to "microsft" (or whatever the directory name
133under which the Visual C dmake configuration lives) in your environment
134and edit win32/config.vc to change "make=nmake" into "make=dmake". The
135latter step is only essential if you want to use dmake as your default
136make for building extensions using MakeMaker.
137
cb644b64 138=item Microsoft Visual C++ 2008 Express Edition
4a3cf07b 139
140This free version of Visual C++ 2008 Professional contains the same compiler
141and linker that ship with the full version, and also contains everything
142necessary to build Perl, rather than requiring a separate download of the
143Platform SDK like previous versions did.
144
cb644b64 145This package can be downloaded by searching for "Visual Studio 2008 Express
146Edition" in the Download Center at
147http://www.microsoft.com/downloads/search.aspx?displaylang=en. (Providing exact
148links to these packages has proven a pointless task because the links keep on
149changing so often.)
4a3cf07b 150
151Install Visual C++ 2008, then setup your environment using
152
153 C:\Program Files\Microsoft Visual Studio 9.0\Common7\Tools\vsvars32.bat
154
155(assuming the default installation location was chosen).
156
157Perl should now build using the win32/Makefile. You will need to edit that
158file to set
159
160 CCTYPE = MSVC90FREE
161
162first.
163
1c847d4b 164=item Microsoft Visual C++ 2005 Express Edition
165
1c847d4b 166This free version of Visual C++ 2005 Professional contains the same compiler
167and linker that ship with the full version, but doesn't contain everything
168necessary to build Perl.
169
170You will also need to download the "Platform SDK" (the "Core SDK" and "MDAC
171SDK" components are required) for more header files and libraries.
172
173These packages can both be downloaded by searching in the Download Center at
174http://www.microsoft.com/downloads/search.aspx?displaylang=en. (Providing exact
175links to these packages has proven a pointless task because the links keep on
176changing so often.)
177
178Try to obtain the latest version of the Platform SDK. Sometimes these packages
179contain a particular Windows OS version in their name, but actually work on
180other OS versions too. For example, the "Windows Server 2003 R2 Platform SDK"
181also runs on Windows XP SP2 and Windows 2000.
182
183According to the download pages these packages are only supported on Windows
1842000/XP/2003, so trying to use these tools on Windows 95/98/ME and even Windows
185NT probably won't work.
186
187Install Visual C++ 2005 first, then the Platform SDK. Setup your environment
188as follows (assuming default installation locations were chosen):
189
4246aec1 190 SET PlatformSDKDir=C:\Program Files\Microsoft Platform SDK
1c847d4b 191
4246aec1 192 SET PATH=%SystemRoot%\system32;%SystemRoot%;C:\Program Files\Microsoft Visual Studio 8\Common7\IDE;C:\Program Files\Microsoft Visual Studio 8\VC\BIN;C:\Program Files\Microsoft Visual Studio 8\Common7\Tools;C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\bin;C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727;C:\Program Files\Microsoft Visual Studio 8\VC\VCPackages;%PlatformSDKDir%\Bin
1c847d4b 193
4246aec1 194 SET INCLUDE=C:\Program Files\Microsoft Visual Studio 8\VC\INCLUDE;%PlatformSDKDir%\include
195
196 SET LIB=C:\Program Files\Microsoft Visual Studio 8\VC\LIB;C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\lib;%PlatformSDKDir%\lib
1c847d4b 197
198 SET LIBPATH=C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727
199
4246aec1 200(The PlatformSDKDir might need to be set differently depending on which version
201you are using. Earlier versions installed into "C:\Program Files\Microsoft SDK",
202while the latest versions install into version-specific locations such as
203"C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2".)
204
1c847d4b 205Perl should now build using the win32/Makefile. You will need to edit that
206file to set
207
208 CCTYPE = MSVC80FREE
209
210and to set CCHOME, CCINCDIR and CCLIBDIR as per the environment setup above.
211
7241fd28 212=item Microsoft Visual C++ Toolkit 2003
213
214This free toolkit contains the same compiler and linker that ship with
1c847d4b 215Visual C++ .NET 2003 Professional, but doesn't contain everything
7241fd28 216necessary to build Perl.
217
218You will also need to download the "Platform SDK" (the "Core SDK" and "MDAC
219SDK" components are required) for header files, libraries and rc.exe, and
220".NET Framework SDK" for more libraries and nmake.exe. Note that the latter
221(which also includes the free compiler and linker) requires the ".NET
222Framework Redistributable" to be installed first. This can be downloaded and
223installed separately, but is included in the "Visual C++ Toolkit 2003" anyway.
224
225These packages can all be downloaded by searching in the Download Center at
1b4f0359 226http://www.microsoft.com/downloads/search.aspx?displaylang=en. (Providing exact
227links to these packages has proven a pointless task because the links keep on
228changing so often.)
229
230Try to obtain the latest version of the Platform SDK. Sometimes these packages
231contain a particular Windows OS version in their name, but actually work on
1c847d4b 232other OS versions too. For example, the "Windows Server 2003 R2 Platform SDK"
1b4f0359 233also runs on Windows XP SP2 and Windows 2000.
7241fd28 234
1c847d4b 235According to the download pages these packages are only supported on Windows
2362000/XP/2003, so trying to use these tools on Windows 95/98/ME and even Windows
237NT probably won't work.
7241fd28 238
239Install the Toolkit first, then the Platform SDK, then the .NET Framework SDK.
240Setup your environment as follows (assuming default installation locations
241were chosen):
242
4246aec1 243 SET PlatformSDKDir=C:\Program Files\Microsoft Platform SDK
244
245 SET PATH=%SystemRoot%\system32;%SystemRoot%;C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin;%PlatformSDKDir%\Bin;C:\Program Files\Microsoft.NET\SDK\v1.1\Bin
246
247 SET INCLUDE=C:\Program Files\Microsoft Visual C++ Toolkit 2003\include;%PlatformSDKDir%\include;C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\include
1c847d4b 248
4246aec1 249 SET LIB=C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib;%PlatformSDKDir%\lib;C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\lib
1c847d4b 250
4246aec1 251(The PlatformSDKDir might need to be set differently depending on which version
252you are using. Earlier versions installed into "C:\Program Files\Microsoft SDK",
253while the latest versions install into version-specific locations such as
254"C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2".)
7241fd28 255
256Several required files will still be missing:
257
258=over 4
259
260=item *
261
262cvtres.exe is required by link.exe when using a .res file. It is actually
263installed by the .NET Framework SDK, but into a location such as the
264following:
265
266 C:\WINDOWS\Microsoft.NET\Framework\v1.1.4322
267
4246aec1 268Copy it from there to %PlatformSDKDir%\Bin
7241fd28 269
270=item *
271
272lib.exe is normally used to build libraries, but link.exe with the /lib
f21bc467 273option also works, so change win32/config.vc to use it instead:
274
275Change the line reading:
276
277 ar='lib'
278
279to:
280
281 ar='link /lib'
282
283It may also be useful to create a batch file called lib.bat in
7241fd28 284C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin containing:
285
286 @echo off
287 link /lib %*
288
f21bc467 289for the benefit of any naughty C extension modules that you might want to build
290later which explicitly reference "lib" rather than taking their value from
291$Config{ar}.
7241fd28 292
293=item *
294
295setargv.obj is required to build perlglob.exe (and perl.exe if the USE_SETARGV
296option is enabled). The Platform SDK supplies this object file in source form
4246aec1 297in %PlatformSDKDir%\src\crt. Copy setargv.c, cruntime.h and
7241fd28 298internal.h from there to some temporary location and build setargv.obj using
299
300 cl.exe /c /I. /D_CRTBLD setargv.c
301
4246aec1 302Then copy setargv.obj to %PlatformSDKDir%\lib
7241fd28 303
f21bc467 304Alternatively, if you don't need perlglob.exe and don't need to enable the
305USE_SETARGV option then you can safely just remove all mention of $(GLOBEXE)
306from win32/Makefile and setargv.obj won't be required anyway.
307
7241fd28 308=back
309
310Perl should now build using the win32/Makefile. You will need to edit that
da2c7419 311file to set
312
313 CCTYPE = MSVC70FREE
314
315and to set CCHOME, CCINCDIR and CCLIBDIR as per the environment setup above.
7241fd28 316
9baed986 317=item Microsoft Platform SDK 64-bit Compiler
318
319The nmake that comes with the Platform SDK will suffice for building
320Perl. Make sure you are building within one of the "Build Environment"
321shells available after you install the Platform SDK from the Start Menu.
322
e2736246 323=item MinGW release 3 with gcc
9baed986 324
dbd54a9f 325The latest release of MinGW at the time of writing is 3.1.0, which contains
7241fd28 326gcc-3.2.3. It can be downloaded here:
9baed986 327
e2736246 328 http://www.mingw.org/
7c5b6093 329
e2736246 330Perl also compiles with earlier releases of gcc (2.95.2 and up). See below
331for notes about using earlier versions of MinGW/gcc.
9baed986 332
333You also need dmake. See L</"Make"> above on how to get it.
334
e2736246 335=item MinGW release 1 with gcc
7c5b6093 336
4a7adf4c 337The MinGW-1.1 bundle contains gcc-2.95.3.
9baed986 338
339Make sure you install the binaries that work with MSVCRT.DLL as indicated
340in the README for the GCC bundle. You may need to set up a few environment
341variables (usually ran from a batch file).
342
343There are a couple of problems with the version of gcc-2.95.2-msvcrt.exe
344released 7 November 1999:
345
346=over
347
348=item *
349
350It left out a fix for certain command line quotes. To fix this, be sure
351to download and install the file fixes/quote-fix-msvcrt.exe from the above
352ftp location.
353
354=item *
355
356The definition of the fpos_t type in stdio.h may be wrong. If your
357stdio.h has this problem, you will see an exception when running the
358test t/lib/io_xs.t. To fix this, change the typedef for fpos_t from
359"long" to "long long" in the file i386-mingw32msvc/include/stdio.h,
360and rebuild.
361
362=back
363
364A potentially simpler to install (but probably soon-to-be-outdated) bundle
365of the above package with the mentioned fixes already applied is available
366here:
367
368 http://downloads.ActiveState.com/pub/staff/gsar/gcc-2.95.2-msvcrt.zip
369 ftp://ftp.ActiveState.com/pub/staff/gsar/gcc-2.95.2-msvcrt.zip
370
371=back
372
373=head2 Building
374
375=over 4
376
377=item *
378
379Make sure you are in the "win32" subdirectory under the perl toplevel.
380This directory contains a "Makefile" that will work with
381versions of nmake that come with Visual C++ or the Platform SDK, and
382a dmake "makefile.mk" that will work for all supported compilers. The
00808b83 383defaults in the dmake makefile are setup to build using MinGW/gcc.
9baed986 384
385=item *
386
dbd54a9f 387Edit the makefile.mk (or Makefile, if you're using nmake) and change
9baed986 388the values of INST_DRV and INST_TOP. You can also enable various
389build flags. These are explained in the makefiles.
390
2b1846f4 391Note that it is generally not a good idea to try to build a perl with
392INST_DRV and INST_TOP set to a path that already exists from a previous
393build. In particular, this may cause problems with the
394lib/ExtUtils/t/Embed.t test, which attempts to build a test program and
395may end up building against the installed perl's lib/CORE directory rather
396than the one being tested.
397
dbd54a9f 398You will have to make sure that CCTYPE is set correctly and that
9baed986 399CCHOME points to wherever you installed your compiler.
400
401The default value for CCHOME in the makefiles for Visual C++
402may not be correct for some versions. Make sure the default exists
403and is valid.
404
da2c7419 405You may also need to comment out the C<DELAYLOAD = ...> line in the
406Makefile if you're using VC++ 6.0 without the latest service pack and
407the linker reports an internal error.
dbd54a9f 408
a7d225ec 409If you are using VC++ 4.2 or earlier then you'll have to change the /EHsc
410option in the CXX_FLAG macro to the equivalent /GX option.
411
9baed986 412If you have either the source or a library that contains des_fcrypt(),
4ace4afb 413enable the appropriate option in the makefile. A ready-to-use version
414of fcrypt.c, based on the version originally written by Eric Young at
415ftp://ftp.funet.fi/pub/crypt/mirrors/dsi/libdes/, is bundled with the
00808b83 416distribution and CRYPT_SRC is set to use it.
4ace4afb 417Alternatively, if you have built a library that contains des_fcrypt(),
418you can set CRYPT_LIB to point to the library name.
9baed986 419Perl will also build without des_fcrypt(), but the crypt() builtin will
420fail at run time.
421
dbd54a9f 422If you want build some core extensions statically into perl's dll, specify
423them in the STATIC_EXT macro.
424
9baed986 425Be sure to read the instructions near the top of the makefiles carefully.
426
427=item *
428
429Type "dmake" (or "nmake" if you are using that make).
430
431This should build everything. Specifically, it will create perl.exe,
abf0ed0d 432perl511.dll at the perl toplevel, and various other extension dll's
9baed986 433under the lib\auto directory. If the build fails for any reason, make
434sure you have done the previous steps correctly.
435
436=back
437
438=head2 Testing Perl on Win32
439
440Type "dmake test" (or "nmake test"). This will run most of the tests from
441the testsuite (many tests will be skipped).
442
443There should be no test failures when running under Windows NT/2000/XP.
444Many tests I<will> fail under Windows 9x due to the inferior command shell.
445
446Some test failures may occur if you use a command shell other than the
447native "cmd.exe", or if you are building from a path that contains
448spaces. So don't do that.
449
450If you are running the tests from a emacs shell window, you may see
451failures in op/stat.t. Run "dmake test-notty" in that case.
452
453If you're using the Borland compiler, you may see a failure in op/taint.t
454arising from the inability to find the Borland Runtime DLLs on the system
455default path. You will need to copy the DLLs reported by the messages
456from where Borland chose to install it, into the Windows system directory
457(usually somewhere like C:\WINNT\SYSTEM32) and rerun the test.
458
459If you're using Borland compiler versions 5.2 and below, you may run into
460problems finding the correct header files when building extensions. For
461example, building the "Tk" extension may fail because both perl and Tk
462contain a header file called "patchlevel.h". The latest Borland compiler
463(v5.5) is free of this misbehaviour, and it even supports an
464option -VI- for backward (bugward) compatibility for using the old Borland
465search algorithm to locate header files.
466
a6a21311 467If you run the tests on a FAT partition, you may see some failures for
468C<link()> related tests (I<op/write.t>, I<op/stat.t> ...). Testing on
469NTFS avoids these errors.
470
471Furthermore, you should make sure that during C<make test> you do not
472have any GNU tool packages in your path: some toolkits like Unixutils
473include some tools (C<type> for instance) which override the Windows
474ones and makes tests fail. Remove them from your path while testing to
475avoid these errors.
476
9baed986 477Please report any other failures as described under L<BUGS AND CAVEATS>.
478
479=head2 Installation of Perl on Win32
480
481Type "dmake install" (or "nmake install"). This will put the newly
482built perl and the libraries under whatever C<INST_TOP> points to in the
483Makefile. It will also install the pod documentation under
00808b83 484C<$INST_TOP\$INST_VER\lib\pod> and HTML versions of the same under
485C<$INST_TOP\$INST_VER\lib\pod\html>.
9baed986 486
00808b83 487To use the Perl you just installed you will need to add a new entry to
488your PATH environment variable: C<$INST_TOP\bin>, e.g.
9baed986 489
00808b83 490 set PATH=c:\perl\bin;%PATH%
9baed986 491
00808b83 492If you opted to uncomment C<INST_VER> and C<INST_ARCH> in the makefile
493then the installation structure is a little more complicated and you will
494need to add two new PATH components instead: C<$INST_TOP\$INST_VER\bin> and
495C<$INST_TOP\$INST_VER\bin\$ARCHNAME>, e.g.
496
497 set PATH=c:\perl\5.6.0\bin;c:\perl\5.6.0\bin\MSWin32-x86;%PATH%
9baed986 498
499=head2 Usage Hints for Perl on Win32
500
501=over 4
502
503=item Environment Variables
504
505The installation paths that you set during the build get compiled
506into perl, so you don't have to do anything additional to start
507using that perl (except add its location to your PATH variable).
508
509If you put extensions in unusual places, you can set PERL5LIB
510to a list of paths separated by semicolons where you want perl
511to look for libraries. Look for descriptions of other environment
512variables you can set in L<perlrun>.
513
514You can also control the shell that perl uses to run system() and
515backtick commands via PERL5SHELL. See L<perlrun>.
516
517Perl does not depend on the registry, but it can look up certain default
518values if you choose to put them there. Perl attempts to read entries from
519C<HKEY_CURRENT_USER\Software\Perl> and C<HKEY_LOCAL_MACHINE\Software\Perl>.
520Entries in the former override entries in the latter. One or more of the
521following entries (of type REG_SZ or REG_EXPAND_SZ) may be set:
522
523 lib-$] version-specific standard library path to add to @INC
524 lib standard library path to add to @INC
525 sitelib-$] version-specific site library path to add to @INC
526 sitelib site library path to add to @INC
527 vendorlib-$] version-specific vendor library path to add to @INC
528 vendorlib vendor library path to add to @INC
529 PERL* fallback for all %ENV lookups that begin with "PERL"
530
531Note the C<$]> in the above is not literal. Substitute whatever version
532of perl you want to honor that entry, e.g. C<5.6.0>. Paths must be
533separated with semicolons, as usual on win32.
534
535=item File Globbing
536
537By default, perl handles file globbing using the File::Glob extension,
538which provides portable globbing.
539
540If you want perl to use globbing that emulates the quirks of DOS
541filename conventions, you might want to consider using File::DosGlob
542to override the internal glob() implementation. See L<File::DosGlob> for
543details.
544
545=item Using perl from the command line
546
547If you are accustomed to using perl from various command-line
548shells found in UNIX environments, you will be less than pleased
549with what Windows offers by way of a command shell.
550
551The crucial thing to understand about the Windows environment is that
552the command line you type in is processed twice before Perl sees it.
553First, your command shell (usually CMD.EXE on Windows NT, and
554COMMAND.COM on Windows 9x) preprocesses the command line, to handle
555redirection, environment variable expansion, and location of the
556executable to run. Then, the perl executable splits the remaining
557command line into individual arguments, using the C runtime library
558upon which Perl was built.
559
560It is particularly important to note that neither the shell nor the C
561runtime do any wildcard expansions of command-line arguments (so
562wildcards need not be quoted). Also, the quoting behaviours of the
563shell and the C runtime are rudimentary at best (and may, if you are
564using a non-standard shell, be inconsistent). The only (useful) quote
565character is the double quote ("). It can be used to protect spaces
566and other special characters in arguments.
567
568The Windows NT documentation has almost no description of how the
569quoting rules are implemented, but here are some general observations
570based on experiments: The C runtime breaks arguments at spaces and
571passes them to programs in argc/argv. Double quotes can be used to
572prevent arguments with spaces in them from being split up. You can
573put a double quote in an argument by escaping it with a backslash and
574enclosing the whole argument within double quotes. The backslash and
575the pair of double quotes surrounding the argument will be stripped by
576the C runtime.
577
00808b83 578The file redirection characters "E<lt>", "E<gt>", and "|" can be quoted by
9baed986 579double quotes (although there are suggestions that this may not always
580be true). Single quotes are not treated as quotes by the shell or
581the C runtime, they don't get stripped by the shell (just to make
582this type of quoting completely useless). The caret "^" has also
583been observed to behave as a quoting character, but this appears
584to be a shell feature, and the caret is not stripped from the command
585line, so Perl still sees it (and the C runtime phase does not treat
586the caret as a quote character).
587
588Here are some examples of usage of the "cmd" shell:
589
590This prints two doublequotes:
591
592 perl -e "print '\"\"' "
593
594This does the same:
595
596 perl -e "print \"\\\"\\\"\" "
597
598This prints "bar" and writes "foo" to the file "blurch":
599
600 perl -e "print 'foo'; print STDERR 'bar'" > blurch
601
602This prints "foo" ("bar" disappears into nowhereland):
603
604 perl -e "print 'foo'; print STDERR 'bar'" 2> nul
605
606This prints "bar" and writes "foo" into the file "blurch":
607
608 perl -e "print 'foo'; print STDERR 'bar'" 1> blurch
609
610This pipes "foo" to the "less" pager and prints "bar" on the console:
611
612 perl -e "print 'foo'; print STDERR 'bar'" | less
613
614This pipes "foo\nbar\n" to the less pager:
615
616 perl -le "print 'foo'; print STDERR 'bar'" 2>&1 | less
617
618This pipes "foo" to the pager and writes "bar" in the file "blurch":
619
620 perl -e "print 'foo'; print STDERR 'bar'" 2> blurch | less
621
622
623Discovering the usefulness of the "command.com" shell on Windows 9x
624is left as an exercise to the reader :)
625
626One particularly pernicious problem with the 4NT command shell for
627Windows NT is that it (nearly) always treats a % character as indicating
628that environment variable expansion is needed. Under this shell, it is
629therefore important to always double any % characters which you want
630Perl to see (for example, for hash variables), even when they are
631quoted.
632
633=item Building Extensions
634
635The Comprehensive Perl Archive Network (CPAN) offers a wealth
636of extensions, some of which require a C compiler to build.
637Look in http://www.cpan.org/ for more information on CPAN.
638
639Note that not all of the extensions available from CPAN may work
640in the Win32 environment; you should check the information at
641http://testers.cpan.org/ before investing too much effort into
642porting modules that don't readily build.
643
644Most extensions (whether they require a C compiler or not) can
645be built, tested and installed with the standard mantra:
646
647 perl Makefile.PL
648 $MAKE
649 $MAKE test
650 $MAKE install
651
652where $MAKE is whatever 'make' program you have configured perl to
653use. Use "perl -V:make" to find out what this is. Some extensions
654may not provide a testsuite (so "$MAKE test" may not do anything or
655fail), but most serious ones do.
656
657It is important that you use a supported 'make' program, and
658ensure Config.pm knows about it. If you don't have nmake, you can
659either get dmake from the location mentioned earlier or get an
660old version of nmake reportedly available from:
661
cb9857f1 662 http://download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/nmake15.exe
9baed986 663
664Another option is to use the make written in Perl, available from
665CPAN.
666
667 http://www.cpan.org/modules/by-module/Make/
668
669You may also use dmake. See L</"Make"> above on how to get it.
670
671Note that MakeMaker actually emits makefiles with different syntax
672depending on what 'make' it thinks you are using. Therefore, it is
673important that one of the following values appears in Config.pm:
674
675 make='nmake' # MakeMaker emits nmake syntax
676 make='dmake' # MakeMaker emits dmake syntax
677 any other value # MakeMaker emits generic make syntax
678 (e.g GNU make, or Perl make)
679
680If the value doesn't match the 'make' program you want to use,
681edit Config.pm to fix it.
682
683If a module implements XSUBs, you will need one of the supported
684C compilers. You must make sure you have set up the environment for
685the compiler for command-line compilation.
686
687If a module does not build for some reason, look carefully for
688why it failed, and report problems to the module author. If
689it looks like the extension building support is at fault, report
690that with full details of how the build failed using the perlbug
691utility.
692
693=item Command-line Wildcard Expansion
694
695The default command shells on DOS descendant operating systems (such
696as they are) usually do not expand wildcard arguments supplied to
697programs. They consider it the application's job to handle that.
698This is commonly achieved by linking the application (in our case,
699perl) with startup code that the C runtime libraries usually provide.
700However, doing that results in incompatible perl versions (since the
701behavior of the argv expansion code differs depending on the
702compiler, and it is even buggy on some compilers). Besides, it may
703be a source of frustration if you use such a perl binary with an
704alternate shell that *does* expand wildcards.
705
706Instead, the following solution works rather well. The nice things
dbd54a9f 707about it are 1) you can start using it right away; 2) it is more
9baed986 708powerful, because it will do the right thing with a pattern like
709*/*/*.c; 3) you can decide whether you do/don't want to use it; and
dbd54a9f 7104) you can extend the method to add any customizations (or even
9baed986 711entirely different kinds of wildcard expansion).
712
713 C:\> copy con c:\perl\lib\Wild.pm
714 # Wild.pm - emulate shell @ARGV expansion on shells that don't
715 use File::DosGlob;
716 @ARGV = map {
717 my @g = File::DosGlob::glob($_) if /[*?]/;
718 @g ? @g : $_;
719 } @ARGV;
720 1;
721 ^Z
722 C:\> set PERL5OPT=-MWild
723 C:\> perl -le "for (@ARGV) { print }" */*/perl*.c
724 p4view/perl/perl.c
725 p4view/perl/perlio.c
726 p4view/perl/perly.c
727 perl5.005/win32/perlglob.c
728 perl5.005/win32/perllib.c
729 perl5.005/win32/perlglob.c
730 perl5.005/win32/perllib.c
731 perl5.005/win32/perlglob.c
732 perl5.005/win32/perllib.c
733
734Note there are two distinct steps there: 1) You'll have to create
735Wild.pm and put it in your perl lib directory. 2) You'll need to
736set the PERL5OPT environment variable. If you want argv expansion
737to be the default, just set PERL5OPT in your default startup
738environment.
739
740If you are using the Visual C compiler, you can get the C runtime's
741command line wildcard expansion built into perl binary. The resulting
742binary will always expand unquoted command lines, which may not be
743what you want if you use a shell that does that for you. The expansion
744done is also somewhat less powerful than the approach suggested above.
745
746=item Win32 Specific Extensions
747
748A number of extensions specific to the Win32 platform are available
749from CPAN. You may find that many of these extensions are meant to
750be used under the Activeware port of Perl, which used to be the only
751native port for the Win32 platform. Since the Activeware port does not
752have adequate support for Perl's extension building tools, these
753extensions typically do not support those tools either and, therefore,
754cannot be built using the generic steps shown in the previous section.
755
756To ensure smooth transitioning of existing code that uses the
757ActiveState port, there is a bundle of Win32 extensions that contains
00808b83 758all of the ActiveState extensions and several other Win32 extensions from
9baed986 759CPAN in source form, along with many added bugfixes, and with MakeMaker
758e4bce 760support. The latest version of this bundle is available at:
9baed986 761
758e4bce 762 http://search.cpan.org/dist/libwin32/
9baed986 763
764See the README in that distribution for building and installation
758e4bce 765instructions.
9baed986 766
767=item Notes on 64-bit Windows
768
769Windows .NET Server supports the LLP64 data model on the Intel Itanium
770architecture.
771
772The LLP64 data model is different from the LP64 data model that is the
773norm on 64-bit Unix platforms. In the former, C<int> and C<long> are
774both 32-bit data types, while pointers are 64 bits wide. In addition,
775there is a separate 64-bit wide integral type, C<__int64>. In contrast,
776the LP64 data model that is pervasive on Unix platforms provides C<int>
777as the 32-bit type, while both the C<long> type and pointers are of
77864-bit precision. Note that both models provide for 64-bits of
779addressability.
780
78164-bit Windows running on Itanium is capable of running 32-bit x86
782binaries transparently. This means that you could use a 32-bit build
783of Perl on a 64-bit system. Given this, why would one want to build
784a 64-bit build of Perl? Here are some reasons why you would bother:
785
00808b83 786=over
787
9baed986 788=item *
789
790A 64-bit native application will run much more efficiently on
791Itanium hardware.
792
793=item *
794
795There is no 2GB limit on process size.
796
797=item *
798
799Perl automatically provides large file support when built under
80064-bit Windows.
801
802=item *
803
804Embedding Perl inside a 64-bit application.
805
806=back
807
00808b83 808=back
809
9baed986 810=head2 Running Perl Scripts
811
812Perl scripts on UNIX use the "#!" (a.k.a "shebang") line to
813indicate to the OS that it should execute the file using perl.
814Win32 has no comparable means to indicate arbitrary files are
815executables.
816
817Instead, all available methods to execute plain text files on
818Win32 rely on the file "extension". There are three methods
819to use this to execute perl scripts:
820
821=over 8
822
823=item 1
824
825There is a facility called "file extension associations" that will
826work in Windows NT 4.0. This can be manipulated via the two
827commands "assoc" and "ftype" that come standard with Windows NT
8284.0. Type "ftype /?" for a complete example of how to set this
829up for perl scripts (Say what? You thought Windows NT wasn't
830perl-ready? :).
831
832=item 2
833
834Since file associations don't work everywhere, and there are
835reportedly bugs with file associations where it does work, the
836old method of wrapping the perl script to make it look like a
837regular batch file to the OS, may be used. The install process
838makes available the "pl2bat.bat" script which can be used to wrap
839perl scripts into batch files. For example:
840
841 pl2bat foo.pl
842
843will create the file "FOO.BAT". Note "pl2bat" strips any
844.pl suffix and adds a .bat suffix to the generated file.
845
846If you use the 4DOS/NT or similar command shell, note that
847"pl2bat" uses the "%*" variable in the generated batch file to
848refer to all the command line arguments, so you may need to make
849sure that construct works in batch files. As of this writing,
8504DOS/NT users will need a "ParameterChar = *" statement in their
8514NT.INI file or will need to execute "setdos /p*" in the 4DOS/NT
852startup file to enable this to work.
853
854=item 3
855
856Using "pl2bat" has a few problems: the file name gets changed,
857so scripts that rely on C<$0> to find what they must do may not
858run properly; running "pl2bat" replicates the contents of the
859original script, and so this process can be maintenance intensive
860if the originals get updated often. A different approach that
861avoids both problems is possible.
862
863A script called "runperl.bat" is available that can be copied
864to any filename (along with the .bat suffix). For example,
865if you call it "foo.bat", it will run the file "foo" when it is
866executed. Since you can run batch files on Win32 platforms simply
867by typing the name (without the extension), this effectively
868runs the file "foo", when you type either "foo" or "foo.bat".
869With this method, "foo.bat" can even be in a different location
870than the file "foo", as long as "foo" is available somewhere on
871the PATH. If your scripts are on a filesystem that allows symbolic
872links, you can even avoid copying "runperl.bat".
873
874Here's a diversion: copy "runperl.bat" to "runperl", and type
875"runperl". Explain the observed behavior, or lack thereof. :)
876Hint: .gnidnats llits er'uoy fi ,"lrepnur" eteled :tniH
877
00808b83 878=back
879
880=head2 Miscellaneous Things
9baed986 881
882A full set of HTML documentation is installed, so you should be
883able to use it if you have a web browser installed on your
884system.
885
886C<perldoc> is also a useful tool for browsing information contained
887in the documentation, especially in conjunction with a pager
888like C<less> (recent versions of which have Win32 support). You may
889have to set the PAGER environment variable to use a specific pager.
890"perldoc -f foo" will print information about the perl operator
891"foo".
892
13ee867e 893One common mistake when using this port with a GUI library like C<Tk>
894is assuming that Perl's normal behavior of opening a command-line
895window will go away. This isn't the case. If you want to start a copy
896of C<perl> without opening a command-line window, use the C<wperl>
897executable built during the installation process. Usage is exactly
898the same as normal C<perl> on Win32, except that options like C<-h>
899don't work (since they need a command-line window to print to).
900
9baed986 901If you find bugs in perl, you can run C<perlbug> to create a
902bug report (you may have to send it manually if C<perlbug> cannot
903find a mailer on your system).
904
9baed986 905=head1 BUGS AND CAVEATS
906
dbd54a9f 907Norton AntiVirus interferes with the build process, particularly if
908set to "AutoProtect, All Files, when Opened". Unlike large applications
909the perl build process opens and modifies a lot of files. Having the
9baed986 910the AntiVirus scan each and every one slows build the process significantly.
911Worse, with PERLIO=stdio the build process fails with peculiar messages
dbd54a9f 912as the virus checker interacts badly with miniperl.exe writing configure
9baed986 913files (it seems to either catch file part written and treat it as suspicious,
914or virus checker may have it "locked" in a way which inhibits miniperl
dbd54a9f 915updating it). The build does complete with
9baed986 916
917 set PERLIO=perlio
918
919but that may be just luck. Other AntiVirus software may have similar issues.
920
921Some of the built-in functions do not act exactly as documented in
922L<perlfunc>, and a few are not implemented at all. To avoid
923surprises, particularly if you have had prior exposure to Perl
924in other operating environments or if you intend to write code
00808b83 925that will be portable to other environments, see L<perlport>
9baed986 926for a reasonably definitive list of these differences.
927
928Not all extensions available from CPAN may build or work properly
929in the Win32 environment. See L</"Building Extensions">.
930
931Most C<socket()> related calls are supported, but they may not
932behave as on Unix platforms. See L<perlport> for the full list.
036c1c1e 933Perl requires Winsock2 to be installed on the system. If you're
934running Win95, you can download Winsock upgrade from here:
935
936http://www.microsoft.com/windows95/downloads/contents/WUAdminTools/S_WUNetworkingTools/W95Sockets2/Default.asp
937
938Later OS versions already include Winsock2 support.
9baed986 939
940Signal handling may not behave as on Unix platforms (where it
941doesn't exactly "behave", either :). For instance, calling C<die()>
942or C<exit()> from signal handlers will cause an exception, since most
943implementations of C<signal()> on Win32 are severely crippled.
944Thus, signals may work only for simple things like setting a flag
945variable in the handler. Using signals under this port should
946currently be considered unsupported.
947
dbd54a9f 948Please send detailed descriptions of any problems and solutions that
00808b83 949you may find to E<lt>F<perlbug@perl.org>E<gt>, along with the output
950produced by C<perl -V>.
9baed986 951
e84ac4e2 952=head1 ACKNOWLEDGEMENTS
953
954The use of a camel with the topic of Perl is a trademark
955of O'Reilly and Associates, Inc. Used with permission.
956
9baed986 957=head1 AUTHORS
958
959=over 4
960
961=item Gary Ng E<lt>71564.1743@CompuServe.COME<gt>
962
963=item Gurusamy Sarathy E<lt>gsar@activestate.comE<gt>
964
965=item Nick Ing-Simmons E<lt>nick@ing-simmons.netE<gt>
966
2bfd3252 967=item Jan Dubois E<lt>jand@activestate.comE<gt>
968
969=item Steve Hay E<lt>steve.hay@uk.radan.comE<gt>
970
9baed986 971=back
972
2bfd3252 973This document is maintained by Jan Dubois.
9baed986 974
975=head1 SEE ALSO
976
977L<perl>
978
979=head1 HISTORY
980
981This port was originally contributed by Gary Ng around 5.003_24,
982and borrowed from the Hip Communications port that was available
983at the time. Various people have made numerous and sundry hacks
984since then.
985
986Borland support was added in 5.004_01 (Gurusamy Sarathy).
987
988GCC/mingw32 support was added in 5.005 (Nick Ing-Simmons).
989
990Support for PERL_OBJECT was added in 5.005 (ActiveState Tool Corp).
991
992Support for fork() emulation was added in 5.6 (ActiveState Tool Corp).
993
994Win9x support was added in 5.6 (Benjamin Stuhl).
995
996Support for 64-bit Windows added in 5.8 (ActiveState Corp).
997
4a3cf07b 998Last updated: 29 August 2007
9baed986 999
1000=cut