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