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