1PERLWIN32(1)           Perl Programmers Reference Guide           PERLWIN32(1)
2
3
4

NAME

6       perlwin32 - Perl under Windows
7

SYNOPSIS

9       These are instructions for building Perl under Windows 2000 and later.
10

DESCRIPTION

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

BUGS AND CAVEATS

840       Norton AntiVirus interferes with the build process, particularly if set
841       to "AutoProtect, All Files, when Opened". Unlike large applications the
842       perl build process opens and modifies a lot of files. Having the
843       AntiVirus scan each and every one slows build the process
844       significantly.  Worse, with PERLIO=stdio the build process fails with
845       peculiar messages as the virus checker interacts badly with
846       miniperl.exe writing configure files (it seems to either catch file
847       part written and treat it as suspicious, or virus checker may have it
848       "locked" in a way which inhibits miniperl updating it). The build does
849       complete with
850
851          set PERLIO=perlio
852
853       but that may be just luck. Other AntiVirus software may have similar
854       issues.
855
856       A git GUI shell extension for Windows such as TortoiseGit will cause
857       the build and later "make test" to run much slower since every file is
858       checked for its git status as soon as it is created and/or modified.
859       TortoiseGit doesn't cause any test failures or build problems unlike
860       the antivirus software described above, but it does cause similar
861       slowness. It is suggested to use Task Manager to look for background
862       processes which use high CPU amounts during the building process.
863
864       Some of the built-in functions do not act exactly as documented in
865       perlfunc, and a few are not implemented at all.  To avoid surprises,
866       particularly if you have had prior exposure to Perl in other operating
867       environments or if you intend to write code that will be portable to
868       other environments, see perlport for a reasonably definitive list of
869       these differences.
870
871       Not all extensions available from CPAN may build or work properly in
872       the Windows environment.  See "Building Extensions".
873
874       Most "socket()" related calls are supported, but they may not behave as
875       on Unix platforms.  See perlport for the full list.
876
877       Signal handling may not behave as on Unix platforms (where it doesn't
878       exactly "behave", either :).  For instance, calling "die()" or "exit()"
879       from signal handlers will cause an exception, since most
880       implementations of "signal()" on Windows are severely crippled.  Thus,
881       signals may work only for simple things like setting a flag variable in
882       the handler.  Using signals under this port should currently be
883       considered unsupported.
884
885       Please report detailed descriptions of any problems and solutions that
886       you may find at <<https://github.com/Perl/perl5/issues>>, along with
887       the output produced by "perl -V".
888

ACKNOWLEDGEMENTS

890       The use of a camel with the topic of Perl is a trademark of O'Reilly
891       and Associates, Inc. Used with permission.
892

AUTHORS

894       Gary Ng <71564.1743@CompuServe.COM>
895       Gurusamy Sarathy <gsar@activestate.com>
896       Nick Ing-Simmons <nick@ing-simmons.net>
897       Jan Dubois <jand@activestate.com>
898       Steve Hay <steve.m.hay@googlemail.com>
899
900       This document is maintained by Jan Dubois.
901

SEE ALSO

903       perl
904

HISTORY

906       This port was originally contributed by Gary Ng around 5.003_24, and
907       borrowed from the Hip Communications port that was available at the
908       time.  Various people have made numerous and sundry hacks since then.
909
910       GCC/mingw32 support was added in 5.005 (Nick Ing-Simmons).
911
912       Support for PERL_OBJECT was added in 5.005 (ActiveState Tool Corp).
913
914       Support for fork() emulation was added in 5.6 (ActiveState Tool Corp).
915
916       Win9x support was added in 5.6 (Benjamin Stuhl).
917
918       Support for 64-bit Windows added in 5.8 (ActiveState Corp).
919
920       Last updated: 30 April 2019
921
922
923
924perl v5.32.1                      2021-03-31                      PERLWIN32(1)
Impressum