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