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