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