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