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