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