This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
[win32] tweak op.c to avoid warning
[perl5.git] / README.win32
CommitLineData
68dc0745
PP
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
5aabfad6 7perlwin32 - Perl under Win32
68dc0745
PP
8
9=head1 SYNOPSIS
10
7bac28a0 11These are instructions for building Perl under Windows NT (versions
3e3baf6d
TB
123.51 or 4.0), using Visual C++ (versions 2.0 through 5.0) or Borland
13C++ (version 5.x). Currently, this port may also build under Windows95,
14but you can expect problems stemming from the unmentionable command
15shell that infests that platform. Note this caveat is only about
16B<building> perl. Once built, you should be able to B<use> it on
17either Win32 platform (modulo the problems arising from the inferior
18command shell).
68dc0745
PP
19
20=head1 DESCRIPTION
21
3fe9a6f1 22Before you start, you should glance through the README file
68dc0745
PP
23found in the top-level directory where the Perl distribution
24was extracted. Make sure you read and understand the terms under
25which this software is being distributed.
26
f7c603cb 27Also make sure you read L<BUGS AND CAVEATS> below for the
68dc0745
PP
28known limitations of this port.
29
30The INSTALL file in the perl top-level has much information that is
31only relevant to people building Perl on Unix-like systems. In
32particular, you can safely ignore any information that talks about
33"Configure".
34
7bac28a0
PP
35You may also want to look at two other options for building
36a perl that will work on Windows NT: the README.cygwin32 and
3e3baf6d
TB
37README.os2 files, which each give a different set of rules to build
38a Perl that will work on Win32 platforms. Those two methods will
7bac28a0
PP
39probably enable you to build a more Unix-compatible perl, but you
40will also need to download and use various other build-time and
41run-time support software described in those files.
68dc0745
PP
42
43This set of instructions is meant to describe a so-called "native"
44port of Perl to Win32 platforms. The resulting Perl requires no
45additional software to run (other than what came with your operating
3e3baf6d
TB
46system). Currently, this port is capable of using either the
47Microsoft Visual C++ compiler, or the Borland C++ compiler. The
48ultimate goal is to support the other major compilers that can
49generally be used to build Win32 applications.
5aabfad6
PP
50
51This port currently supports MakeMaker (the set of modules that
52is used to build extensions to perl). Therefore, you should be
53able to build and install most extensions found in the CPAN sites.
c90c0ff4 54See L<Usage Hints> below for general hints about this.
68dc0745
PP
55
56=head2 Setting Up
57
58=over 4
59
3e3baf6d 60=item Command Shell
68dc0745
PP
61
62Use the default "cmd" shell that comes with NT. In particular, do
63*not* use the 4DOS/NT shell. The Makefile has commands that are not
c90c0ff4
PP
64compatible with that shell. The Makefile also has known
65incompatibilites with the default shell that comes with Windows95,
66so building under Windows95 should be considered "unsupported".
68dc0745 67
3e3baf6d
TB
68=item Borland C++
69
70If you are using the Borland compiler, you will need dmake, a freely
71available make that has very nice macro features and parallelability.
72(The make that Borland supplies is seriously crippled, and will not
73work for MakeMaker builds--if you *have* to bug someone about this,
74I suggest you bug Borland to fix their make :)
75
76A port of dmake for win32 platforms is available from
77"http://www-personal.umich.edu/~gsar/dmake-4.0-win32.tar.gz".
78Fetch and install dmake somewhere on your path. Also make sure you
79copy the Borland dmake.ini file to some location where you keep
80*.ini files. If you use the binary that comes with the above port, you
81will need to set INIT in your environment to the directory where you
82put the dmake.ini file.
83
84=item Microsoft Visual C++
68dc0745 85
3e3baf6d 86The NMAKE that comes with Visual C++ will suffice for building.
7bac28a0
PP
87If you did not choose to always initialize the Visual C++ compilation
88environment variables when you installed Visual C++ on your system, you
89will need to run the VCVARS32.BAT file usually found somewhere like
90C:\MSDEV4.2\BIN. This will set your build environment.
68dc0745 91
3e3baf6d
TB
92You can also use dmake to build using Visual C++, provided: you
93copied the dmake.ini for Visual C++; set INIT to point to the
94directory where you put it, as above; and edit win32/config.vc
95and change "make=nmake" to "make=dmake". The last step is only
96essential if you want to use dmake to be your default make for
97building extensions using MakeMaker.
98
99=item Permissions
68dc0745
PP
100
101Depending on how you extracted the distribution, you have to make sure
7bac28a0 102some of the files are writable by you. The easiest way to make sure of
68dc0745
PP
103this is to execute:
104
105 attrib -R *.* /S
106
107from the perl toplevel directory. You don't I<have> to do this if you
108used the right tools to extract the files in the standard distribution,
109but it doesn't hurt to do so.
110
111=back
112
137443ea 113=head2 Building
68dc0745
PP
114
115=over 4
116
117=item *
118
68dc0745 119Make sure you are in the "win32" subdirectory under the perl toplevel.
137443ea 120This directory contains a "Makefile" that will work with
3e3baf6d
TB
121versions of NMAKE that come with Visual C++ ver. 2.0 and above, and
122a dmake "makefile.mk" that will work for both Borland and Visual C++
123builds. The defaults in the dmake makefile are setup to build using the
124Borland compiler.
68dc0745
PP
125
126=item *
127
3e3baf6d
TB
128Edit the Makefile (or makefile.mk, if using dmake) and change the values
129of INST_DRV and INST_TOP if you want perl to be installed in a location
130other than "C:\PERL". If you are using Visual C++ ver. 2.0, uncomment
131the line that sets "CCTYPE=MSVC20".
c90c0ff4 132
3e3baf6d
TB
133You will also have to make sure CCHOME points to wherever you installed
134your compiler.
c90c0ff4 135
68dc0745
PP
136=item *
137
3e3baf6d 138Type "nmake" (or "dmake" if you are using that make).
68dc0745 139
137443ea
PP
140This should build everything. Specifically, it will create perl.exe,
141perl.dll, and perlglob.exe at the perl toplevel, and various other
7bac28a0 142extension dll's under the lib\auto directory. If the build fails for
137443ea 143any reason, make sure you have done the previous steps correctly.
68dc0745 144
156a3eb7
GS
145The build process may produce "harmless" compiler warnings (more or
146less copiously, depending on how picky your compiler gets). The
147maintainers are aware of these warnings, thankyouverymuch. :)
148
3e3baf6d
TB
149When building using Visual C++, a perl95.exe will also get built. This
150executable is only needed on Windows95, and should be used instead of
151perl.exe, and then only if you want sockets to work properly on Windows95.
152This is necessitated by a bug in the Microsoft C Runtime that cannot be
153worked around in the "normal" perl.exe. Again, if this bugs you, please
154bug Microsoft :). perl95.exe gets built with its own private copy of the
155C Runtime that is not accessible to extensions (which see the DLL version
156of the CRT). Be aware, therefore, that this perl95.exe will have
157esoteric problems with extensions like perl/Tk that themselves use the C
158Runtime heavily, or want to free() pointers malloc()-ed by perl.
159
160You can avoid the perl95.exe problems completely if you use Borland
161C++ for building perl (perl95.exe is not needed and will not be built
162in that case).
163
68dc0745
PP
164=back
165
166=head2 Testing
167
3e3baf6d
TB
168Type "nmake test" (or "dmake test"). This will run most of the tests from
169the testsuite (many tests will be skipped, and but no test should fail).
68dc0745 170
8b88ae92 171If some tests do fail, it may be because you are using a different command
137443ea 172shell than the native "cmd.exe".
68dc0745 173
3e3baf6d
TB
174If you used the Borland compiler, you may see a failure in op/taint.t
175arising from the inability to find the Borland Runtime DLLs on the system
176default path. You will need to copy the DLLs reported by the messages
177from where Borland chose to install it, into the Windows system directory
178(usually somewhere like C:\WINNT\SYSTEM32), and rerun the test.
179
180Please report any other failures as described under L<BUGS AND CAVEATS>.
68dc0745 181
137443ea
PP
182=head2 Installation
183
3e3baf6d
TB
184Type "nmake install" (or "dmake install"). This will put the newly
185built perl and the libraries under "C:\perl" (actually whatever you set
186C<INST_TOP> to in the Makefile). It will also install the pod
187documentation under C<$INST_TOP\lib\pod> and HTML versions of the same
188under C<$INST_TOP\lib\pod\html>. To use the Perl you just installed,
189set your PATH environment variable to "C:\perl\bin" (or C<$INST_TOP\bin>,
190if you changed the default as above).
137443ea 191
7bac28a0
PP
192=head2 Usage Hints
193
194=over 4
195
196=item Environment Variables
197
198The installation paths that you set during the build get compiled
199into perl, so you don't have to do anything additional to start
200using that perl (except add its location to your PATH variable).
201
202If you put extensions in unusual places, you can set PERL5LIB
203to a list of paths separated by semicolons where you want perl
204to look for libraries. Look for descriptions of other environment
205variables you can set in the perlrun podpage.
206
207Sometime in the future, some of the configuration information
208for perl will be moved into the Windows registry.
209
3e3baf6d
TB
210=item File Globbing
211
212By default, perl spawns an external program to do file globbing.
213The install process installs both a perlglob.exe and a perlglob.bat
214that perl can use for this purpose. Note that with the default
215installation, perlglob.exe will be found by the system before
216perlglob.bat.
217
218perlglob.exe relies on the argv expansion done by the C Runtime of
219the particular compiler you used, and therefore behaves very
220differently depending on the Runtime used to build it. To preserve
221compatiblity, perlglob.bat (a perl script/module that can be
222used portably) is installed. Besides being portable, perlglob.bat
223also offers enhanced globbing functionality.
224
225If you want perl to use perlglob.bat instead of perlglob.exe, just
226delete perlglob.exe from the install location (or move it somewhere
227perl cannot find). Using File::DosGlob.pm (which is the same
228as perlglob.bat) to override the internal CORE::glob() works about 10
229times faster than spawing perlglob.exe, and you should take this
230approach when writing new modules. See File::DosGlob for details.
231
7bac28a0
PP
232=item Using perl from the command line
233
234If you are accustomed to using perl from various command-line
235shells found in UNIX environments, you will be less than pleased
236with what Windows NT offers by way of a command shell.
237
238The crucial thing to understand about the "cmd" shell (which is
239the default on Windows NT) is that it does not do any wildcard
240expansions of command-line arguments (so wildcards need not be
241quoted). It also provides only rudimentary quoting. The only
242(useful) quote character is the double quote ("). It can be used to
243protect spaces in arguments and other special characters. The
244Windows NT documentation has almost no description of how the
245quoting rules are implemented, but here are some general observations
246based on experiments: The shell breaks arguments at spaces and
247passes them to programs in argc/argv. Doublequotes can be used
248to prevent arguments with spaces in them from being split up.
249You can put a double quote in an argument by escaping it with
250a backslash and enclosing the whole argument within double quotes.
251The backslash and the pair of double quotes surrounding the
252argument will be stripped by the shell.
253
254The file redirection characters "<", ">", and "|" cannot be quoted
255by double quotes (there are probably more such). Single quotes
256will protect those three file redirection characters, but the
257single quotes don't get stripped by the shell (just to make this
258type of quoting completely useless). The caret "^" has also
259been observed to behave as a quoting character (and doesn't get
260stripped by the shell also).
261
262Here are some examples of usage of the "cmd" shell:
263
264This prints two doublequotes:
265
266 perl -e "print '\"\"' "
267
268This does the same:
269
270 perl -e "print \"\\\"\\\"\" "
271
272This prints "bar" and writes "foo" to the file "blurch":
273
274 perl -e "print 'foo'; print STDERR 'bar'" > blurch
275
276This prints "foo" ("bar" disappears into nowhereland):
277
278 perl -e "print 'foo'; print STDERR 'bar'" 2> nul
279
280This prints "bar" and writes "foo" into the file "blurch":
281
282 perl -e "print 'foo'; print STDERR 'bar'" 1> blurch
283
7bac28a0
PP
284This pipes "foo" to the "less" pager and prints "bar" on the console:
285
286 perl -e "print 'foo'; print STDERR 'bar'" | less
287
288This pipes "foo\nbar\n" to the less pager:
289
7bac28a0
PP
290 perl -le "print 'foo'; print STDERR 'bar'" 2>&1 | less
291
292This pipes "foo" to the pager and writes "bar" in the file "blurch":
293
294 perl -e "print 'foo'; print STDERR 'bar'" 2> blurch | less
295
296
84902520 297Discovering the usefulness of the "command.com" shell on Windows95
7bac28a0
PP
298is left as an exercise to the reader :)
299
300=item Building Extensions
301
302The Comprehensive Perl Archive Network (CPAN) offers a wealth
303of extensions, some of which require a C compiler to build.
304Look in http://www.perl.com/ for more information on CPAN.
305
306Most extensions (whether they require a C compiler or not) can
307be built, tested and installed with the standard mantra:
308
309 perl Makefile.PL
3e3baf6d
TB
310 $MAKE
311 $MAKE test
312 $MAKE install
7bac28a0 313
3e3baf6d
TB
314where $MAKE stands for NMAKE or DMAKE. Some extensions may not
315provide a testsuite (so "$MAKE test" may not do anything, or fail),
316but most serious ones do.
7bac28a0 317
3e3baf6d
TB
318If a module implements XSUBs, you will need one of the supported
319C compilers. You must make sure you have set up the environment for
320the compiler for command-line compilation.
7bac28a0 321
3e3baf6d 322If a module does not build for some reason, look carefully for
7bac28a0
PP
323why it failed, and report problems to the module author. If
324it looks like the extension building support is at fault, report
325that with full details of how the build failed using the perlbug
326utility.
327
c90c0ff4
PP
328=item Win32 Specific Extensions
329
330A number of extensions specific to the Win32 platform are available
331from CPAN. You may find that many of these extensions are meant to
332be used under the Activeware port of Perl, which used to be the only
333native port for the Win32 platform. Since the Activeware port does not
334have adequate support for Perl's extension building tools, these
335extensions typically do not support those tools either, and therefore
336cannot be built using the generic steps shown in the previous section.
337
338To ensure smooth transitioning of existing code that uses the
339Activeware port, there is a bundle of Win32 extensions that contains
340all of the Activeware extensions and most other Win32 extensions from
341CPAN in source form, along with many added bugfixes, and with MakeMaker
342support. This bundle is available at:
343
f7c603cb 344 http://www.perl.com/CPAN/authors/id/GSAR/libwin32-0.08.tar.gz
c90c0ff4
PP
345
346See the README in that distribution for building and installation
347instructions. Look for later versions that may be available at the
348same location.
349
350It is expected that authors of Win32 specific extensions will begin
351distributing their work in MakeMaker compatible form subsequent to
352the 5.004 release of perl, at which point the need for a dedicated
353bundle such as the above should diminish.
354
156a3eb7
GS
355=item Running Perl Scripts
356
357Perl scripts on UNIX use the "#!" (a.k.a "shebang") line to
358indicate to the OS that it should execute the file using perl.
359Win32 has no comparable means to indicate arbitrary files are
360executables.
361
362Instead, all available methods to execute plain text files on
363Win32 rely on the file "extension". There are three methods
364to use this to execute perl scripts:
365
366=over 8
367
368=item 1
369
370There is a facility called "file extension associations" that will
371work in Windows NT 4.0. This can be manipulated via the two
372commands "assoc" and "ftype" that come standard with Windows NT
3734.0. Type "ftype /?" for a complete example of how to set this
374up for perl scripts (Say what? You thought Windows NT wasn't
375perl-ready? :).
376
377=item 2
378
379Since file associations don't work everywhere, and there are
380reportedly bugs with file associations where it does work, the
381old method of wrapping the perl script to make it look like a
382regular batch file to the OS, may be used. The install process
383makes available the "pl2bat.bat" script which can be used to wrap
384perl scripts into batch files. For example:
385
386 pl2bat foo.pl
387
388will create the file "FOO.BAT". Note "pl2bat" strips any
389.pl suffix and adds a .bat suffix to the generated file.
390
391If you use the 4DOS/NT or similar command shell, note that
392"pl2bat" uses the "%*" variable in the generated batch file to
393refer to all the command line arguments, so you may need to make
394sure that construct works in batch files. As of this writing,
3954DOS/NT users will need a "ParameterChar = *" statement in their
3964NT.INI file, or will need to execute "setdos /p*" in the 4DOS/NT
397startup file to enable this to work.
398
399=item 3
400
401Using "pl2bat" has a few problems: the file name gets changed,
402so scripts that rely on C<$0> to find what they must do may not
403run properly; running "pl2bat" replicates the contents of the
404original script, and so this process can be maintenance intensive
405if the originals get updated often. A different approach that
406avoids both problems is possible.
407
408A script called "runperl.bat" is available that can be copied
409to any filename (along with the .bat suffix). For example,
410if you call it "foo.bat", it will run the file "foo" when it is
411executed. Since you can run batch files on Win32 platforms simply
412by typing the name (without the extension), this effectively
413runs the file "foo", when you type either "foo" or "foo.bat".
414With this method, "foo.bat" can even be in a different location
415than the file "foo", as long as "foo" is available somewhere on
416the PATH. If your scripts are on a filesystem that allows symbolic
417links, you can even avoid copying "runperl.bat".
418
419Here's a diversion: copy "runperl.bat" to "runperl", and type
420"runperl". Explain the observed behavior, or lack thereof. :)
421Hint: .gnidnats llits er'uoy fi ,"lrepnur" eteled :tniH
422
423=back
424
7bac28a0
PP
425=item Miscellaneous Things
426
427A full set of HTML documentation is installed, so you should be
428able to use it if you have a web browser installed on your
429system.
430
431C<perldoc> is also a useful tool for browsing information contained
432in the documentation, especially in conjunction with a pager
433like C<less> (recent versions of which have Win32 support). You may
434have to set the PAGER environment variable to use a specific pager.
435"perldoc -f foo" will print information about the perl operator
436"foo".
437
438If you find bugs in perl, you can run C<perlbug> to create a
439bug report (you may have to send it manually if C<perlbug> cannot
440find a mailer on your system).
441
442=back
443
68dc0745
PP
444=head1 BUGS AND CAVEATS
445
3e3baf6d
TB
446This port should be considered beta quality software at the present
447time because some details are still in flux and there may be
448changes in any of these areas: build process, installation structure,
449supported utilities/modules, and supported perl functionality.
450In particular, functionality specific to the Win32 environment may
f7c603cb
GS
451ultimately be supported as either core modules or extensions. The
452beta status implies, among other things, that you should be prepared
453to recompile extensions when binary incompatibilites arise due to
454changes in the internal structure of the code.
455
456An effort has been made to ensure that the DLLs produced by the two
457supported compilers are compatible with each other (despite the
458best efforts of the compiler vendors). Extension binaries produced
459by one compiler should also coexist with a perl binary built by
460a different compiler. In order to accomplish this, PERL.DLL provides
461a layer of runtime code that uses the C Runtime that perl was compiled
462with. Extensions which include "perl.h" will transparently access
463the functions in this layer, thereby ensuring that both perl and
464extensions use the same runtime functions.
68dc0745 465
8b88ae92
NIS
466If you have had prior exposure to Perl on Unix platforms, you will notice
467this port exhibits behavior different from what is documented. Most of the
7bac28a0
PP
468differences fall under one of these categories. We do not consider
469any of them to be serious limitations (especially when compared to the
470limited nature of some of the Win32 OSes themselves :)
68dc0745
PP
471
472=over 8
473
474=item *
475
476C<stat()> and C<lstat()> functions may not behave as documented. They
477may return values that bear no resemblance to those reported on Unix
7bac28a0
PP
478platforms, and some fields (like the the one for inode) may be completely
479bogus.
68dc0745
PP
480
481=item *
482
6890e559 483The following functions are currently unavailable: C<fork()>,
5aabfad6 484C<dump()>, C<chown()>, C<link()>, C<symlink()>, C<chroot()>,
68dc0745 485C<setpgrp()>, C<getpgrp()>, C<setpriority()>, C<getpriority()>,
3e3baf6d 486C<syscall()>, C<fcntl()>. This list is possibly very incomplete.
68dc0745
PP
487
488=item *
489
6890e559
GS
490crypt() is not available due to silly export restrictions. It may
491become available when the laws change. Meanwhile, look in CPAN for
492extensions that provide it.
493
494=item *
495
68dc0745
PP
496Various C<socket()> related calls are supported, but they may not
497behave as on Unix platforms.
498
499=item *
500
501The four-argument C<select()> call is only supported on sockets.
502
503=item *
504
5aabfad6
PP
505C<$?> ends up with the exitstatus of the subprocess (this is different
506from Unix, where the exitstatus is actually given by "$? >> 8").
507Failure to spawn() the subprocess is indicated by setting $? to
508"255<<8". This is subject to change.
68dc0745
PP
509
510=item *
511
512Building modules available on CPAN is mostly supported, but this
513hasn't been tested much yet. Expect strange problems, and be
514prepared to deal with the consequences.
515
516=item *
517
518C<utime()>, C<times()> and process-related functions may not
519behave as described in the documentation, and some of the
520returned values or effects may be bogus.
521
522=item *
523
3e3baf6d 524Signal handling may not behave as on Unix platforms (where it
f7c603cb
GS
525doesn't exactly "behave", either :). For instance, calling C<die()>
526or C<exit()> from signal handlers will cause an exception, since most
527implementations of C<signal()> on Win32 are severely crippled.
528Thus, signals may work only for simple things like setting a flag
529variable in the handler. Using signals under this port should
530currently be considered unsupported.
68dc0745
PP
531
532=item *
533
7bac28a0 534File globbing may not behave as on Unix platforms. In particular,
3e3baf6d
TB
535if you don't use perlglob.bat for globbing, it will understand
536wildcards only in the filename component (and not in the pathname).
537In other words, something like "print <*/*.pl>" will not print all the
538perl scripts in all the subdirectories one level under the current one
539(like it does on UNIX platforms). perlglob.exe is also dependent on
540the particular implementation of wildcard expansion in the vendor
541libraries used to build it (which varies wildly at the present time).
542Using perlglob.bat (or File::DosGlob) avoids these limitations, but
543still only provides DOS semantics (read "warts") for globbing.
68dc0745
PP
544
545=back
546
547Please send detailed descriptions of any problems and solutions that
548you may find to <F<perlbug@perl.com>>, along with the output produced
549by C<perl -V>.
550
551=head1 AUTHORS
552
553=over 4
554
3e3baf6d 555Gary Ng E<lt>71564.1743@CompuServe.COME<gt>
68dc0745 556
3e3baf6d 557Gurusamy Sarathy E<lt>gsar@umich.eduE<gt>
68dc0745 558
3e3baf6d 559Nick Ing-Simmons E<lt>nick@ni-s.u-net.comE<gt>
68dc0745
PP
560
561=back
562
f7c603cb
GS
563This document is maintained by Gurusamy Sarathy.
564
68dc0745
PP
565=head1 SEE ALSO
566
567L<perl>
568
569=head1 HISTORY
570
571This port was originally contributed by Gary Ng around 5.003_24,
572and borrowed from the Hip Communications port that was available
573at the time.
574
575Nick Ing-Simmons and Gurusamy Sarathy have made numerous and
576sundry hacks since then.
577
3e3baf6d
TB
578Borland support was added in 5.004_01 (Gurusamy Sarathy).
579
f7c603cb 580Last updated: 25 July 1997
68dc0745
PP
581
582=cut
3e3baf6d 583