This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
gcc -Wall nit noticed by NI-S.
[perl5.git] / README.win32
CommitLineData
9fba2765
JH
1If you read this file _as_is_, just ignore the funny characters you\r
2see. It is written in the POD format (see pod/perlpod.pod) which is\r
3specially designed to be readable as is.\r
4\r
5=head1 NAME\r
6\r
7perlwin32 - Perl under Windows\r
8\r
9=head1 SYNOPSIS\r
10\r
11These are instructions for building Perl under Windows 9x/NT/2000/XP\r
12on the Intel x86 and Itanium architectures.\r
13\r
14=head1 DESCRIPTION\r
15\r
16Before you start, you should glance through the README file\r
17found in the top-level directory to which the Perl distribution\r
18was extracted. Make sure you read and understand the terms under\r
19which this software is being distributed.\r
20\r
21Also make sure you read L<BUGS AND CAVEATS> below for the\r
22known limitations of this port.\r
23\r
24The INSTALL file in the perl top-level has much information that is\r
25only relevant to people building Perl on Unix-like systems. In\r
26particular, you can safely ignore any information that talks about\r
27"Configure".\r
28\r
29You may also want to look at two other options for building\r
30a perl that will work on Windows NT: the README.cygwin and\r
31README.os2 files, each of which give a different set of rules to\r
32build a Perl that will work on Win32 platforms. Those two methods\r
33will probably enable you to build a more Unix-compatible perl, but\r
34you will also need to download and use various other build-time and\r
35run-time support software described in those files.\r
36\r
37This set of instructions is meant to describe a so-called "native"\r
38port of Perl to Win32 platforms. This includes both 32-bit and\r
3964-bit Windows operating systems. The resulting Perl requires no\r
40additional software to run (other than what came with your operating\r
41system). Currently, this port is capable of using one of the\r
42following compilers on the Intel x86 architecture:\r
43\r
44 Borland C++ version 5.02 or later\r
45 Microsoft Visual C++ version 4.2 or later\r
46 Mingw32 with GCC version 2.95.2 or better\r
47\r
48The last of these is a high quality freeware compiler. Support\r
49for it is still experimental. (Older versions of GCC are known\r
50not to work.)\r
51\r
52This port can also be built on the Intel IA64 using:\r
53\r
54 Microsoft Platform SDK Nov 2001 (64-bit compiler and tools)\r
55\r
56The MS Platform SDK can be downloaded from http://www.microsoft.com/.\r
57\r
58This port fully supports MakeMaker (the set of modules that\r
59is used to build extensions to perl). Therefore, you should be\r
60able to build and install most extensions found in the CPAN sites.\r
61See L<Usage Hints for Perl on Win32> below for general hints about this.\r
62\r
63=head2 Setting Up Perl on Win32\r
64\r
65=over 4\r
66\r
67=item Make\r
68\r
69You need a "make" program to build the sources. If you are using\r
70Visual C++ or the Platform SDK tools under Windows NT/2000/XP, nmake\r
71will work. All other builds need dmake.\r
72\r
73dmake is a freely available make that has very nice macro features\r
74and parallelability.\r
75\r
76A port of dmake for Windows is available from:\r
77\r
78 http://www.cpan.org/authors/id/GSAR/dmake-4.1pl1-win32.zip\r
79\r
80(This is a fixed version of the original dmake sources obtained from\r
81http://www.wticorp.com/ As of version 4.1PL1, the original\r
82sources did not build as shipped and had various other problems.\r
83A patch is included in the above fixed version.)\r
84\r
85Fetch and install dmake somewhere on your path (follow the instructions\r
86in the README.NOW file).\r
87\r
88There exists a minor coexistence problem with dmake and Borland C++\r
89compilers. Namely, if a distribution has C files named with mixed\r
90case letters, they will be compiled into appropriate .obj-files named\r
91with all lowercase letters, and every time dmake is invoked\r
92to bring files up to date, it will try to recompile such files again.\r
93For example, Tk distribution has a lot of such files, resulting in\r
94needless recompiles every time dmake is invoked. To avoid this, you\r
95may use the script "sync_ext.pl" after a successful build. It is\r
96available in the win32 subdirectory of the Perl source distribution.\r
97\r
98=item Command Shell\r
99\r
100Use the default "cmd" shell that comes with NT. Some versions of the\r
101popular 4DOS/NT shell have incompatibilities that may cause you trouble.\r
102If the build fails under that shell, try building again with the cmd\r
103shell.\r
104\r
105The nmake Makefile also has known incompatibilities with the\r
106"command.com" shell that comes with Windows 9x. You will need to\r
107use dmake and makefile.mk to build under Windows 9x.\r
108\r
109The surest way to build it is on Windows NT/2000/XP, using the cmd shell.\r
110\r
111Make sure the path to the build directory does not contain spaces. The\r
112build usually works in this circumstance, but some tests will fail.\r
113\r
114=item Borland C++\r
115\r
116If you are using the Borland compiler, you will need dmake.\r
117(The make that Borland supplies is seriously crippled and will not\r
118work for MakeMaker builds.)\r
119\r
120See L</"Make"> above.\r
121\r
122=item Microsoft Visual C++\r
123\r
124The nmake that comes with Visual C++ will suffice for building.\r
125You will need to run the VCVARS32.BAT file, usually found somewhere\r
126like C:\MSDEV4.2\BIN. This will set your build environment.\r
127\r
128You can also use dmake to build using Visual C++; provided, however,\r
129you set OSRELEASE to "microsft" (or whatever the directory name\r
130under which the Visual C dmake configuration lives) in your environment\r
131and edit win32/config.vc to change "make=nmake" into "make=dmake". The\r
132latter step is only essential if you want to use dmake as your default\r
133make for building extensions using MakeMaker.\r
134\r
135=item Microsoft Platform SDK 64-bit Compiler\r
136\r
137The nmake that comes with the Platform SDK will suffice for building\r
138Perl. Make sure you are building within one of the "Build Environment"\r
139shells available after you install the Platform SDK from the Start Menu.\r
140\r
141=item Mingw32 with GCC\r
142\r
143GCC-2.95.2 binaries can be downloaded from:\r
144\r
145 ftp://ftp.xraylith.wisc.edu/pub/khan/gnu-win32/mingw32/\r
146\r
147You also need dmake. See L</"Make"> above on how to get it.\r
148\r
149The GCC-2.95.2 bundle comes with Mingw32 libraries and headers.\r
150\r
151Make sure you install the binaries that work with MSVCRT.DLL as indicated\r
152in the README for the GCC bundle. You may need to set up a few environment\r
153variables (usually ran from a batch file).\r
154\r
155There are a couple of problems with the version of gcc-2.95.2-msvcrt.exe\r
156released 7 November 1999:\r
157\r
158=over\r
159\r
160=item *\r
161\r
162It left out a fix for certain command line quotes. To fix this, be sure\r
163to download and install the file fixes/quote-fix-msvcrt.exe from the above\r
164ftp location.\r
165\r
166=item *\r
167\r
168The definition of the fpos_t type in stdio.h may be wrong. If your\r
169stdio.h has this problem, you will see an exception when running the\r
170test t/lib/io_xs.t. To fix this, change the typedef for fpos_t from\r
171"long" to "long long" in the file i386-mingw32msvc/include/stdio.h,\r
172and rebuild.\r
173\r
174=back\r
175\r
176A potentially simpler to install (but probably soon-to-be-outdated) bundle\r
177of the above package with the mentioned fixes already applied is available\r
178here:\r
179\r
180 http://downloads.ActiveState.com/pub/staff/gsar/gcc-2.95.2-msvcrt.zip\r
181 ftp://ftp.ActiveState.com/pub/staff/gsar/gcc-2.95.2-msvcrt.zip\r
182\r
183=back\r
184\r
185=head2 Building\r
186\r
187=over 4\r
188\r
189=item *\r
190\r
191Make sure you are in the "win32" subdirectory under the perl toplevel.\r
192This directory contains a "Makefile" that will work with\r
193versions of nmake that come with Visual C++ or the Platform SDK, and\r
194a dmake "makefile.mk" that will work for all supported compilers. The\r
195defaults in the dmake makefile are setup to build using the GCC compiler.\r
196\r
197=item *\r
198\r
199Edit the makefile.mk (or Makefile, if you're using nmake) and change \r
200the values of INST_DRV and INST_TOP. You can also enable various\r
201build flags. These are explained in the makefiles.\r
202\r
203You will have to make sure that CCTYPE is set correctly and that \r
204CCHOME points to wherever you installed your compiler.\r
205\r
206The default value for CCHOME in the makefiles for Visual C++\r
207may not be correct for some versions. Make sure the default exists\r
208and is valid.\r
209\r
210If you have either the source or a library that contains des_fcrypt(),\r
211enable the appropriate option in the makefile. des_fcrypt() is not\r
212bundled with the distribution due to US Government restrictions\r
213on the export of cryptographic software. Nevertheless, this routine\r
214is part of the "libdes" library (written by Eric Young) which is widely\r
215available worldwide, usually along with SSLeay ( for example, \r
216ftp://ftp.funet.fi/pub/crypt/mirrors/dsi/libdes/ ). Set CRYPT_SRC to the\r
217name of the file that implements des_fcrypt(). Alternatively, if\r
218you have built a library that contains des_fcrypt(), you can set\r
219CRYPT_LIB to point to the library name. The location above contains\r
220many versions of the "libdes" library, all with slightly different\r
221implementations of des_fcrypt(). Older versions have a single,\r
222self-contained file (fcrypt.c) that implements crypt(), so they may be\r
223easier to use. A patch against the fcrypt.c found in libdes-3.06 is\r
224in des_fcrypt.patch.\r
225\r
226An easier alternative may be to get the pre-patched and ready-to-use\r
227fcrypt.c that can be found here:\r
228\r
229 http://downloads.ActiveState.com/pub/staff/gsar/fcrypt.c\r
230 ftp://ftp.ActiveState.com/pub/staff/gsar/fcrypt.c\r
231\r
232Perl will also build without des_fcrypt(), but the crypt() builtin will\r
233fail at run time.\r
234\r
235Be sure to read the instructions near the top of the makefiles carefully.\r
236\r
237=item *\r
238\r
239Type "dmake" (or "nmake" if you are using that make).\r
240\r
241This should build everything. Specifically, it will create perl.exe,\r
242perl58.dll at the perl toplevel, and various other extension dll's\r
243under the lib\auto directory. If the build fails for any reason, make\r
244sure you have done the previous steps correctly.\r
245\r
246=back\r
247\r
248=head2 Testing Perl on Win32\r
249\r
250Type "dmake test" (or "nmake test"). This will run most of the tests from\r
251the testsuite (many tests will be skipped).\r
252\r
253There should be no test failures when running under Windows NT/2000/XP.\r
254Many tests I<will> fail under Windows 9x due to the inferior command shell.\r
255\r
256Some test failures may occur if you use a command shell other than the\r
257native "cmd.exe", or if you are building from a path that contains\r
258spaces. So don't do that.\r
259\r
260If you are running the tests from a emacs shell window, you may see\r
261failures in op/stat.t. Run "dmake test-notty" in that case.\r
262\r
263If you're using the Borland compiler, you may see a failure in op/taint.t\r
264arising from the inability to find the Borland Runtime DLLs on the system\r
265default path. You will need to copy the DLLs reported by the messages\r
266from where Borland chose to install it, into the Windows system directory\r
267(usually somewhere like C:\WINNT\SYSTEM32) and rerun the test.\r
268\r
269If you're using Borland compiler versions 5.2 and below, you may run into\r
270problems finding the correct header files when building extensions. For\r
271example, building the "Tk" extension may fail because both perl and Tk\r
272contain a header file called "patchlevel.h". The latest Borland compiler\r
273(v5.5) is free of this misbehaviour, and it even supports an\r
274option -VI- for backward (bugward) compatibility for using the old Borland\r
275search algorithm to locate header files.\r
276\r
277Please report any other failures as described under L<BUGS AND CAVEATS>.\r
278\r
279=head2 Installation of Perl on Win32\r
280\r
281Type "dmake install" (or "nmake install"). This will put the newly\r
282built perl and the libraries under whatever C<INST_TOP> points to in the\r
283Makefile. It will also install the pod documentation under\r
284C<$INST_TOP\$VERSION\lib\pod> and HTML versions of the same under\r
285C<$INST_TOP\$VERSION\lib\pod\html>. To use the Perl you just installed,\r
286you will need to add two components to your PATH environment variable,\r
287C<$INST_TOP\$VERSION\bin> and C<$INST_TOP\$VERSION\bin\$ARCHNAME>.\r
288For example:\r
289\r
290 set PATH c:\perl\5.6.0\bin;c:\perl\5.6.0\bin\MSWin32-x86;%PATH%\r
291\r
292If you opt to comment out INST_VER and INST_ARCH in the makefiles, the\r
293installation structure is much simpler. In that case, it will be\r
294sufficient to add a single entry to the path, for instance:\r
295\r
296 set PATH c:\perl\bin;%PATH%\r
297\r
298=head2 Usage Hints for Perl on Win32\r
299\r
300=over 4\r
301\r
302=item Environment Variables\r
303\r
304The installation paths that you set during the build get compiled\r
305into perl, so you don't have to do anything additional to start\r
306using that perl (except add its location to your PATH variable).\r
307\r
308If you put extensions in unusual places, you can set PERL5LIB\r
309to a list of paths separated by semicolons where you want perl\r
310to look for libraries. Look for descriptions of other environment\r
311variables you can set in L<perlrun>.\r
312\r
313You can also control the shell that perl uses to run system() and\r
314backtick commands via PERL5SHELL. See L<perlrun>.\r
315\r
316Perl does not depend on the registry, but it can look up certain default\r
317values if you choose to put them there. Perl attempts to read entries from\r
318C<HKEY_CURRENT_USER\Software\Perl> and C<HKEY_LOCAL_MACHINE\Software\Perl>.\r
319Entries in the former override entries in the latter. One or more of the\r
320following entries (of type REG_SZ or REG_EXPAND_SZ) may be set:\r
321\r
322 lib-$] version-specific standard library path to add to @INC\r
323 lib standard library path to add to @INC\r
324 sitelib-$] version-specific site library path to add to @INC\r
325 sitelib site library path to add to @INC\r
326 vendorlib-$] version-specific vendor library path to add to @INC\r
327 vendorlib vendor library path to add to @INC\r
328 PERL* fallback for all %ENV lookups that begin with "PERL"\r
329\r
330Note the C<$]> in the above is not literal. Substitute whatever version\r
331of perl you want to honor that entry, e.g. C<5.6.0>. Paths must be\r
332separated with semicolons, as usual on win32.\r
333\r
334=item File Globbing\r
335\r
336By default, perl handles file globbing using the File::Glob extension,\r
337which provides portable globbing.\r
338\r
339If you want perl to use globbing that emulates the quirks of DOS\r
340filename conventions, you might want to consider using File::DosGlob\r
341to override the internal glob() implementation. See L<File::DosGlob> for\r
342details.\r
343\r
344=item Using perl from the command line\r
345\r
346If you are accustomed to using perl from various command-line\r
347shells found in UNIX environments, you will be less than pleased\r
348with what Windows offers by way of a command shell.\r
349\r
350The crucial thing to understand about the Windows environment is that\r
351the command line you type in is processed twice before Perl sees it.\r
352First, your command shell (usually CMD.EXE on Windows NT, and\r
353COMMAND.COM on Windows 9x) preprocesses the command line, to handle\r
354redirection, environment variable expansion, and location of the\r
355executable to run. Then, the perl executable splits the remaining\r
356command line into individual arguments, using the C runtime library\r
357upon which Perl was built.\r
358\r
359It is particularly important to note that neither the shell nor the C\r
360runtime do any wildcard expansions of command-line arguments (so\r
361wildcards need not be quoted). Also, the quoting behaviours of the\r
362shell and the C runtime are rudimentary at best (and may, if you are\r
363using a non-standard shell, be inconsistent). The only (useful) quote\r
364character is the double quote ("). It can be used to protect spaces\r
365and other special characters in arguments.\r
366\r
367The Windows NT documentation has almost no description of how the\r
368quoting rules are implemented, but here are some general observations\r
369based on experiments: The C runtime breaks arguments at spaces and\r
370passes them to programs in argc/argv. Double quotes can be used to\r
371prevent arguments with spaces in them from being split up. You can\r
372put a double quote in an argument by escaping it with a backslash and\r
373enclosing the whole argument within double quotes. The backslash and\r
374the pair of double quotes surrounding the argument will be stripped by\r
375the C runtime.\r
376\r
377The file redirection characters "<", ">", and "|" can be quoted by\r
378double quotes (although there are suggestions that this may not always\r
379be true). Single quotes are not treated as quotes by the shell or\r
380the C runtime, they don't get stripped by the shell (just to make\r
381this type of quoting completely useless). The caret "^" has also\r
382been observed to behave as a quoting character, but this appears\r
383to be a shell feature, and the caret is not stripped from the command\r
384line, so Perl still sees it (and the C runtime phase does not treat\r
385the caret as a quote character).\r
386\r
387Here are some examples of usage of the "cmd" shell:\r
388\r
389This prints two doublequotes:\r
390\r
391 perl -e "print '\"\"' "\r
392\r
393This does the same:\r
394\r
395 perl -e "print \"\\\"\\\"\" "\r
396\r
397This prints "bar" and writes "foo" to the file "blurch":\r
398\r
399 perl -e "print 'foo'; print STDERR 'bar'" > blurch\r
400\r
401This prints "foo" ("bar" disappears into nowhereland):\r
402\r
403 perl -e "print 'foo'; print STDERR 'bar'" 2> nul\r
404\r
405This prints "bar" and writes "foo" into the file "blurch":\r
406\r
407 perl -e "print 'foo'; print STDERR 'bar'" 1> blurch\r
408\r
409This pipes "foo" to the "less" pager and prints "bar" on the console:\r
410\r
411 perl -e "print 'foo'; print STDERR 'bar'" | less\r
412\r
413This pipes "foo\nbar\n" to the less pager:\r
414\r
415 perl -le "print 'foo'; print STDERR 'bar'" 2>&1 | less\r
416\r
417This pipes "foo" to the pager and writes "bar" in the file "blurch":\r
418\r
419 perl -e "print 'foo'; print STDERR 'bar'" 2> blurch | less\r
420\r
421\r
422Discovering the usefulness of the "command.com" shell on Windows 9x\r
423is left as an exercise to the reader :)\r
424\r
425One particularly pernicious problem with the 4NT command shell for\r
426Windows NT is that it (nearly) always treats a % character as indicating\r
427that environment variable expansion is needed. Under this shell, it is\r
428therefore important to always double any % characters which you want\r
429Perl to see (for example, for hash variables), even when they are\r
430quoted.\r
431\r
432=item Building Extensions\r
433\r
434The Comprehensive Perl Archive Network (CPAN) offers a wealth\r
435of extensions, some of which require a C compiler to build.\r
436Look in http://www.cpan.org/ for more information on CPAN.\r
437\r
438Note that not all of the extensions available from CPAN may work\r
439in the Win32 environment; you should check the information at\r
440http://testers.cpan.org/ before investing too much effort into\r
441porting modules that don't readily build.\r
442\r
443Most extensions (whether they require a C compiler or not) can\r
444be built, tested and installed with the standard mantra:\r
445\r
446 perl Makefile.PL\r
447 $MAKE\r
448 $MAKE test\r
449 $MAKE install\r
450\r
451where $MAKE is whatever 'make' program you have configured perl to\r
452use. Use "perl -V:make" to find out what this is. Some extensions\r
453may not provide a testsuite (so "$MAKE test" may not do anything or\r
454fail), but most serious ones do.\r
455\r
456It is important that you use a supported 'make' program, and\r
457ensure Config.pm knows about it. If you don't have nmake, you can\r
458either get dmake from the location mentioned earlier or get an\r
459old version of nmake reportedly available from:\r
460\r
461 ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe\r
462\r
463Another option is to use the make written in Perl, available from\r
464CPAN.\r
465\r
466 http://www.cpan.org/modules/by-module/Make/\r
467\r
468You may also use dmake. See L</"Make"> above on how to get it.\r
469\r
470Note that MakeMaker actually emits makefiles with different syntax\r
471depending on what 'make' it thinks you are using. Therefore, it is\r
472important that one of the following values appears in Config.pm:\r
473\r
474 make='nmake' # MakeMaker emits nmake syntax\r
475 make='dmake' # MakeMaker emits dmake syntax\r
476 any other value # MakeMaker emits generic make syntax\r
477 (e.g GNU make, or Perl make)\r
478\r
479If the value doesn't match the 'make' program you want to use,\r
480edit Config.pm to fix it.\r
481\r
482If a module implements XSUBs, you will need one of the supported\r
483C compilers. You must make sure you have set up the environment for\r
484the compiler for command-line compilation.\r
485\r
486If a module does not build for some reason, look carefully for\r
487why it failed, and report problems to the module author. If\r
488it looks like the extension building support is at fault, report\r
489that with full details of how the build failed using the perlbug\r
490utility.\r
491\r
492=item Command-line Wildcard Expansion\r
493\r
494The default command shells on DOS descendant operating systems (such\r
495as they are) usually do not expand wildcard arguments supplied to\r
496programs. They consider it the application's job to handle that.\r
497This is commonly achieved by linking the application (in our case,\r
498perl) with startup code that the C runtime libraries usually provide.\r
499However, doing that results in incompatible perl versions (since the\r
500behavior of the argv expansion code differs depending on the\r
501compiler, and it is even buggy on some compilers). Besides, it may\r
502be a source of frustration if you use such a perl binary with an\r
503alternate shell that *does* expand wildcards.\r
504\r
505Instead, the following solution works rather well. The nice things\r
506about it are 1) you can start using it right away; 2) it is more \r
507powerful, because it will do the right thing with a pattern like\r
508*/*/*.c; 3) you can decide whether you do/don't want to use it; and\r
5094) you can extend the method to add any customizations (or even \r
510entirely different kinds of wildcard expansion).\r
511\r
512 C:\> copy con c:\perl\lib\Wild.pm\r
513 # Wild.pm - emulate shell @ARGV expansion on shells that don't\r
514 use File::DosGlob;\r
515 @ARGV = map {\r
516 my @g = File::DosGlob::glob($_) if /[*?]/;\r
517 @g ? @g : $_;\r
518 } @ARGV;\r
519 1;\r
520 ^Z\r
521 C:\> set PERL5OPT=-MWild\r
522 C:\> perl -le "for (@ARGV) { print }" */*/perl*.c\r
523 p4view/perl/perl.c\r
524 p4view/perl/perlio.c\r
525 p4view/perl/perly.c\r
526 perl5.005/win32/perlglob.c\r
527 perl5.005/win32/perllib.c\r
528 perl5.005/win32/perlglob.c\r
529 perl5.005/win32/perllib.c\r
530 perl5.005/win32/perlglob.c\r
531 perl5.005/win32/perllib.c\r
532\r
533Note there are two distinct steps there: 1) You'll have to create\r
534Wild.pm and put it in your perl lib directory. 2) You'll need to\r
535set the PERL5OPT environment variable. If you want argv expansion\r
536to be the default, just set PERL5OPT in your default startup\r
537environment.\r
538\r
539If you are using the Visual C compiler, you can get the C runtime's\r
540command line wildcard expansion built into perl binary. The resulting\r
541binary will always expand unquoted command lines, which may not be\r
542what you want if you use a shell that does that for you. The expansion\r
543done is also somewhat less powerful than the approach suggested above.\r
544\r
545=item Win32 Specific Extensions\r
546\r
547A number of extensions specific to the Win32 platform are available\r
548from CPAN. You may find that many of these extensions are meant to\r
549be used under the Activeware port of Perl, which used to be the only\r
550native port for the Win32 platform. Since the Activeware port does not\r
551have adequate support for Perl's extension building tools, these\r
552extensions typically do not support those tools either and, therefore,\r
553cannot be built using the generic steps shown in the previous section.\r
554\r
555To ensure smooth transitioning of existing code that uses the\r
556ActiveState port, there is a bundle of Win32 extensions that contains\r
557all of the ActiveState extensions and most other Win32 extensions from\r
558CPAN in source form, along with many added bugfixes, and with MakeMaker\r
559support. This bundle is available at:\r
560\r
561 http://www.cpan.org/authors/id/GSAR/libwin32-0.18.zip\r
562\r
563See the README in that distribution for building and installation\r
564instructions. Look for later versions that may be available at the\r
565same location.\r
566\r
567=item Notes on 64-bit Windows\r
568\r
569Windows .NET Server supports the LLP64 data model on the Intel Itanium\r
570architecture.\r
571\r
572The LLP64 data model is different from the LP64 data model that is the\r
573norm on 64-bit Unix platforms. In the former, C<int> and C<long> are\r
574both 32-bit data types, while pointers are 64 bits wide. In addition,\r
575there is a separate 64-bit wide integral type, C<__int64>. In contrast,\r
576the LP64 data model that is pervasive on Unix platforms provides C<int>\r
577as the 32-bit type, while both the C<long> type and pointers are of\r
57864-bit precision. Note that both models provide for 64-bits of\r
579addressability.\r
580\r
58164-bit Windows running on Itanium is capable of running 32-bit x86\r
582binaries transparently. This means that you could use a 32-bit build\r
583of Perl on a 64-bit system. Given this, why would one want to build\r
584a 64-bit build of Perl? Here are some reasons why you would bother:\r
585\r
586=item *\r
587\r
588A 64-bit native application will run much more efficiently on\r
589Itanium hardware.\r
590\r
591=item *\r
592\r
593There is no 2GB limit on process size.\r
594\r
595=item *\r
596\r
597Perl automatically provides large file support when built under\r
59864-bit Windows.\r
599\r
600=item *\r
601\r
602Embedding Perl inside a 64-bit application.\r
603\r
604=back\r
605\r
606=head2 Running Perl Scripts\r
607\r
608Perl scripts on UNIX use the "#!" (a.k.a "shebang") line to\r
609indicate to the OS that it should execute the file using perl.\r
610Win32 has no comparable means to indicate arbitrary files are\r
611executables.\r
612\r
613Instead, all available methods to execute plain text files on\r
614Win32 rely on the file "extension". There are three methods\r
615to use this to execute perl scripts:\r
616\r
617=over 8\r
618\r
619=item 1\r
620\r
621There is a facility called "file extension associations" that will\r
622work in Windows NT 4.0. This can be manipulated via the two\r
623commands "assoc" and "ftype" that come standard with Windows NT\r
6244.0. Type "ftype /?" for a complete example of how to set this\r
625up for perl scripts (Say what? You thought Windows NT wasn't\r
626perl-ready? :).\r
627\r
628=item 2\r
629\r
630Since file associations don't work everywhere, and there are\r
631reportedly bugs with file associations where it does work, the\r
632old method of wrapping the perl script to make it look like a\r
633regular batch file to the OS, may be used. The install process\r
634makes available the "pl2bat.bat" script which can be used to wrap\r
635perl scripts into batch files. For example:\r
636\r
637 pl2bat foo.pl\r
638\r
639will create the file "FOO.BAT". Note "pl2bat" strips any\r
640.pl suffix and adds a .bat suffix to the generated file.\r
641\r
642If you use the 4DOS/NT or similar command shell, note that\r
643"pl2bat" uses the "%*" variable in the generated batch file to\r
644refer to all the command line arguments, so you may need to make\r
645sure that construct works in batch files. As of this writing,\r
6464DOS/NT users will need a "ParameterChar = *" statement in their\r
6474NT.INI file or will need to execute "setdos /p*" in the 4DOS/NT\r
648startup file to enable this to work.\r
649\r
650=item 3\r
651\r
652Using "pl2bat" has a few problems: the file name gets changed,\r
653so scripts that rely on C<$0> to find what they must do may not\r
654run properly; running "pl2bat" replicates the contents of the\r
655original script, and so this process can be maintenance intensive\r
656if the originals get updated often. A different approach that\r
657avoids both problems is possible.\r
658\r
659A script called "runperl.bat" is available that can be copied\r
660to any filename (along with the .bat suffix). For example,\r
661if you call it "foo.bat", it will run the file "foo" when it is\r
662executed. Since you can run batch files on Win32 platforms simply\r
663by typing the name (without the extension), this effectively\r
664runs the file "foo", when you type either "foo" or "foo.bat".\r
665With this method, "foo.bat" can even be in a different location\r
666than the file "foo", as long as "foo" is available somewhere on\r
667the PATH. If your scripts are on a filesystem that allows symbolic\r
668links, you can even avoid copying "runperl.bat".\r
669\r
670Here's a diversion: copy "runperl.bat" to "runperl", and type\r
671"runperl". Explain the observed behavior, or lack thereof. :)\r
672Hint: .gnidnats llits er'uoy fi ,"lrepnur" eteled :tniH\r
673\r
674=item Miscellaneous Things\r
675\r
676A full set of HTML documentation is installed, so you should be\r
677able to use it if you have a web browser installed on your\r
678system.\r
679\r
680C<perldoc> is also a useful tool for browsing information contained\r
681in the documentation, especially in conjunction with a pager\r
682like C<less> (recent versions of which have Win32 support). You may\r
683have to set the PAGER environment variable to use a specific pager.\r
684"perldoc -f foo" will print information about the perl operator\r
685"foo".\r
686\r
687If you find bugs in perl, you can run C<perlbug> to create a\r
688bug report (you may have to send it manually if C<perlbug> cannot\r
689find a mailer on your system).\r
690\r
691=back\r
692\r
693=head1 BUGS AND CAVEATS\r
694\r
695Norton AntiVirus interferes with the build process, particularly if \r
696set to "AutoProtect, All Files, when Opened". Unlike large applications \r
697the perl build process opens and modifies a lot of files. Having the \r
698the AntiVirus scan each and every one slows build the process significantly.\r
699Worse, with PERLIO=stdio the build process fails with peculiar messages\r
700as the virus checker interacts badly with miniperl.exe writing configure \r
701files (it seems to either catch file part written and treat it as suspicious,\r
702or virus checker may have it "locked" in a way which inhibits miniperl\r
703updating it). The build does complete with \r
704\r
705 set PERLIO=perlio\r
706\r
707but that may be just luck. Other AntiVirus software may have similar issues.\r
708\r
709Some of the built-in functions do not act exactly as documented in\r
710L<perlfunc>, and a few are not implemented at all. To avoid\r
711surprises, particularly if you have had prior exposure to Perl\r
712in other operating environments or if you intend to write code\r
713that will be portable to other environments. See L<perlport>\r
714for a reasonably definitive list of these differences.\r
715\r
716Not all extensions available from CPAN may build or work properly\r
717in the Win32 environment. See L</"Building Extensions">.\r
718\r
719Most C<socket()> related calls are supported, but they may not\r
720behave as on Unix platforms. See L<perlport> for the full list.\r
721\r
722Signal handling may not behave as on Unix platforms (where it\r
723doesn't exactly "behave", either :). For instance, calling C<die()>\r
724or C<exit()> from signal handlers will cause an exception, since most\r
725implementations of C<signal()> on Win32 are severely crippled.\r
726Thus, signals may work only for simple things like setting a flag\r
727variable in the handler. Using signals under this port should\r
728currently be considered unsupported.\r
729\r
730Please send detailed descriptions of any problems and solutions that \r
731you may find to <F<perlbug@perl.com>>, along with the output produced\r
732by C<perl -V>.\r
733\r
734=head1 AUTHORS\r
735\r
736=over 4\r
737\r
738=item Gary Ng E<lt>71564.1743@CompuServe.COME<gt>\r
739\r
740=item Gurusamy Sarathy E<lt>gsar@activestate.comE<gt>\r
741\r
742=item Nick Ing-Simmons E<lt>nick@ing-simmons.netE<gt>\r
743\r
744=back\r
745\r
746This document is maintained by Gurusamy Sarathy.\r
747\r
748=head1 SEE ALSO\r
749\r
750L<perl>\r
751\r
752=head1 HISTORY\r
753\r
754This port was originally contributed by Gary Ng around 5.003_24,\r
755and borrowed from the Hip Communications port that was available\r
756at the time. Various people have made numerous and sundry hacks\r
757since then.\r
758\r
759Borland support was added in 5.004_01 (Gurusamy Sarathy).\r
760\r
761GCC/mingw32 support was added in 5.005 (Nick Ing-Simmons).\r
762\r
763Support for PERL_OBJECT was added in 5.005 (ActiveState Tool Corp).\r
764\r
765Support for fork() emulation was added in 5.6 (ActiveState Tool Corp).\r
766\r
767Win9x support was added in 5.6 (Benjamin Stuhl).\r
768\r
769Support for 64-bit Windows added in 5.8 (ActiveState Corp).\r
770\r
771Last updated: 20 April 2002\r
772\r
773=cut\r