This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
[inseparable changes from match from perl-5.003_97 to perl-5.003_97a]
[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
11These are instructions for building Perl under WindowsNT (versions
5aabfad6
PP
123.51 or 4.0), using Visual C++ (versions 2.0 through 5.0). Currently,
13this port may also build under Windows95, but you can expect problems
14stemming from the unmentionable command shell that infests that
15platform. Note this caveat is only about B<building> perl. Once
16built, you should be able to B<use> it on either Win32 platform (modulo
17the problems arising from the inferior command shell).
68dc0745
PP
18
19=head1 DESCRIPTION
20
3fe9a6f1 21Before you start, you should glance through the README file
68dc0745
PP
22found in the top-level directory where the Perl distribution
23was extracted. Make sure you read and understand the terms under
24which this software is being distributed.
25
3fe9a6f1 26Also make sure you read the L<BUGS AND CAVEATS> section below for the
68dc0745
PP
27known limitations of this port.
28
29The INSTALL file in the perl top-level has much information that is
30only relevant to people building Perl on Unix-like systems. In
31particular, you can safely ignore any information that talks about
32"Configure".
33
34You should probably also read the README.os2 file, which gives a
35different set of rules to build a Perl that will work on Win32
36platforms. That method will probably enable you to build a more
37Unix-compatible perl, but you will also need to download and use
38various other support software described in that file.
39
40This set of instructions is meant to describe a so-called "native"
41port of Perl to Win32 platforms. The resulting Perl requires no
42additional software to run (other than what came with your operating
43system). Currently, this port is only capable of using Microsoft's
44Visual C++ compiler. The ultimate goal is to support the other major
5aabfad6
PP
45compilers that can be used to build Win32 applications.
46
47This port currently supports MakeMaker (the set of modules that
48is used to build extensions to perl). Therefore, you should be
49able to build and install most extensions found in the CPAN sites.
68dc0745
PP
50
51=head2 Setting Up
52
53=over 4
54
55=item *
56
57Use the default "cmd" shell that comes with NT. In particular, do
58*not* use the 4DOS/NT shell. The Makefile has commands that are not
5aabfad6
PP
59compatible with that shell. You are mostly on your own if you can
60muster the temerity to attempt this with Windows95.
68dc0745
PP
61
62=item *
63
64Run the VCVARS32.BAT file usually found somewhere like C:\MSDEV4.2\BIN.
65This will set your build environment.
66
67=item *
68
69Depending on how you extracted the distribution, you have to make sure
70all the files are writable by you. The easiest way to make sure of
71this is to execute:
72
73 attrib -R *.* /S
74
75from the perl toplevel directory. You don't I<have> to do this if you
76used the right tools to extract the files in the standard distribution,
77but it doesn't hurt to do so.
78
79=back
80
81=head2 Building and Installation
82
83=over 4
84
85=item *
86
87The "win32" directory contains *.mak files for use with the NMAKE that
88comes with Visual C++ ver. 4.0 and above. If you wish to build perl
3fe9a6f1
PP
89using Visual C++ versions between 2.0 and 4.0, do the following two
90additional steps (these steps are not required if you are
68dc0745
PP
91using Visual C++ versions 4.0 and above):
92
93=over 8
94
95=item 1.
96
97Overwrite the *.mak files in the win32 subdirectory with the versions
3fe9a6f1 98in the win32\VC-2.0 directory.
68dc0745
PP
99
100=item 2.
101
102Reset your INCLUDE environment variable to the MSVC include directory.
103For example:
104
105 set INCLUDE=E:\MSVC20\INCLUDE
106
107This must have only one directory (a list of directories will not work).
108VCVARS32.BAT may put multiple locations in there, which is why this step
109is required.
110
68dc0745
PP
111=back
112
113=item *
114
115Make sure you are in the "win32" subdirectory under the perl toplevel.
116
117=item *
118
119Type "nmake" while in the "win32" subdirectory. This should build
120everything. Specifically, it will create perl.exe, perl.dll, and
121perlglob.exe at the perl toplevel, and various other extension dll's
122under the lib\auto directory. If the make fails for any reason, make
123sure you have done the previous steps correctly.
124
125=item *
126
127Type "nmake install". This will put the newly built perl and the
128libraries under C:\PERL. If you want to alter this location, to say,
129D:\FOO\PERL, you will have to say:
130
131 nmake install INST_TOP=D:\FOO\PERL
132
133instead. To use the Perl you just installed, make sure you set your
134PATH environment variable to C:\PERL\BIN (or D:\FOO\PERL\BIN).
135
136=back
137
138=head2 Testing
139
140Type "nmake test". This will run most of the tests from the
5aabfad6 141testsuite (many tests will be skipped, and a few tests may fail).
68dc0745 142
5aabfad6
PP
143To get a more detailed breakdown of the tests that failed,
144you may want to say:
68dc0745
PP
145
146 cd ..\t
147 .\perl harness
148
5aabfad6
PP
149This should produce a summary of the failed tests. Currently, the
150only known failure is lib\findbin.t:
68dc0745
PP
151
152 Failed Test Status Wstat Total Fail Failed List of failed
153 ------------------------------------------------------------------------------
68dc0745 154 lib/findbin.t 1 1 100.00% 1
5aabfad6 155 Failed 1/151 test scripts, 99.34% okay. 1/3902 subtests failed, 99.97% okay.
3fe9a6f1 156
68dc0745
PP
157
158Check if any additional tests other than the ones shown here
5aabfad6 159failed, and report them as described under L<BUGS AND CAVEATS>.
68dc0745
PP
160
161=head1 BUGS AND CAVEATS
162
163This is still very much an experimental port, and should be considered
164alpha quality software. You can expect changes in virtually all of
165these areas: build process, installation structure, supported
166utilities/modules, and supported perl functionality. Specifically,
3fe9a6f1 167functionality that supports the Win32 environment may ultimately
68dc0745
PP
168be supported as either core modules or extensions.
169
5aabfad6
PP
170If you have had prior exposure to Perl on Unix platforms, this port
171may exhibit behavior different from what is documented. Most of the
172differences fall under one of these categories.
68dc0745
PP
173
174=over 8
175
176=item *
177
178C<stat()> and C<lstat()> functions may not behave as documented. They
179may return values that bear no resemblance to those reported on Unix
180platforms, and some fields may be completely bogus.
181
182=item *
183
184The following functions are currently unavailable: C<fork()>, C<exec()>,
5aabfad6 185C<dump()>, C<chown()>, C<link()>, C<symlink()>, C<chroot()>,
68dc0745 186C<setpgrp()>, C<getpgrp()>, C<setpriority()>, C<getpriority()>,
5aabfad6
PP
187C<syscall()>, C<fcntl()>, C<flock()>. This list is possibly very
188incomplete.
68dc0745
PP
189
190=item *
191
192Various C<socket()> related calls are supported, but they may not
193behave as on Unix platforms.
194
195=item *
196
197The four-argument C<select()> call is only supported on sockets.
198
199=item *
200
201The behavior of C<system()> or the C<qx[]> operator (a.k.a. "backticks"),
202when used to call interactive commands, is ill-defined.
203
204=item *
205
5aabfad6
PP
206C<$?> ends up with the exitstatus of the subprocess (this is different
207from Unix, where the exitstatus is actually given by "$? >> 8").
208Failure to spawn() the subprocess is indicated by setting $? to
209"255<<8". This is subject to change.
68dc0745
PP
210
211=item *
212
213Building modules available on CPAN is mostly supported, but this
214hasn't been tested much yet. Expect strange problems, and be
215prepared to deal with the consequences.
216
217=item *
218
219C<utime()>, C<times()> and process-related functions may not
220behave as described in the documentation, and some of the
221returned values or effects may be bogus.
222
223=item *
224
225Signal handling may not behave as on Unix platforms.
226
227=item *
228
229File globbing may not behave as on Unix platforms.
230
231=item *
232
233Not all of the utilities that come with the Perl distribution
234are supported yet.
235
236=back
237
238Please send detailed descriptions of any problems and solutions that
239you may find to <F<perlbug@perl.com>>, along with the output produced
240by C<perl -V>.
241
242=head1 AUTHORS
243
244=over 4
245
246=item Gary Ng <F<71564.1743@CompuServe.COM>>
247
248=item Gurusamy Sarathy <F<gsar@umich.edu>>
249
250=item Nick Ing-Simmons <F<nick@ni-s.u-net.com>>
251
252=back
253
254=head1 SEE ALSO
255
256L<perl>
257
258=head1 HISTORY
259
260This port was originally contributed by Gary Ng around 5.003_24,
261and borrowed from the Hip Communications port that was available
262at the time.
263
264Nick Ing-Simmons and Gurusamy Sarathy have made numerous and
265sundry hacks since then.
266
5aabfad6 267Last updated: 04 April 1997
68dc0745
PP
268
269=cut
270