This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
xsubpp incorrectly handles 'class::newthing()'
[perl5.git] / README.win32
CommitLineData
68dc0745 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 8
9=head1 SYNOPSIS
10
11These are instructions for building Perl under WindowsNT (versions
5aabfad6 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 18
19=head1 DESCRIPTION
20
3fe9a6f1 21Before you start, you should glance through the README file
68dc0745 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 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 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 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 59compatible with that shell. You are mostly on your own if you can
60muster the temerity to attempt this with Windows95.
68dc0745 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 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 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 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 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
8b88ae92 141testsuite (many tests will be skipped, and but no test should fail).
68dc0745 142
8b88ae92
NIS
143If some tests do fail, it may be because you are using a different command
144shell than the native "cmd.exe". To get a more detailed breakdown of the
145tests that failed, you may want to say:
68dc0745 146
147 cd ..\t
148 .\perl harness
149
8b88ae92 150Please report any failures as described under L<BUGS AND CAVEATS>.
68dc0745 151
152=head1 BUGS AND CAVEATS
153
154This is still very much an experimental port, and should be considered
155alpha quality software. You can expect changes in virtually all of
156these areas: build process, installation structure, supported
157utilities/modules, and supported perl functionality. Specifically,
8b88ae92 158functionality specific to the Win32 environment may ultimately
68dc0745 159be supported as either core modules or extensions.
160
8b88ae92
NIS
161If you have had prior exposure to Perl on Unix platforms, you will notice
162this port exhibits behavior different from what is documented. Most of the
5aabfad6 163differences fall under one of these categories.
68dc0745 164
165=over 8
166
167=item *
168
169C<stat()> and C<lstat()> functions may not behave as documented. They
170may return values that bear no resemblance to those reported on Unix
171platforms, and some fields may be completely bogus.
172
173=item *
174
175The following functions are currently unavailable: C<fork()>, C<exec()>,
5aabfad6 176C<dump()>, C<chown()>, C<link()>, C<symlink()>, C<chroot()>,
68dc0745 177C<setpgrp()>, C<getpgrp()>, C<setpriority()>, C<getpriority()>,
5aabfad6 178C<syscall()>, C<fcntl()>, C<flock()>. This list is possibly very
179incomplete.
68dc0745 180
181=item *
182
183Various C<socket()> related calls are supported, but they may not
184behave as on Unix platforms.
185
186=item *
187
188The four-argument C<select()> call is only supported on sockets.
189
190=item *
191
192The behavior of C<system()> or the C<qx[]> operator (a.k.a. "backticks"),
193when used to call interactive commands, is ill-defined.
194
195=item *
196
5aabfad6 197C<$?> ends up with the exitstatus of the subprocess (this is different
198from Unix, where the exitstatus is actually given by "$? >> 8").
199Failure to spawn() the subprocess is indicated by setting $? to
200"255<<8". This is subject to change.
68dc0745 201
202=item *
203
204Building modules available on CPAN is mostly supported, but this
205hasn't been tested much yet. Expect strange problems, and be
206prepared to deal with the consequences.
207
208=item *
209
210C<utime()>, C<times()> and process-related functions may not
211behave as described in the documentation, and some of the
212returned values or effects may be bogus.
213
214=item *
215
216Signal handling may not behave as on Unix platforms.
217
218=item *
219
220File globbing may not behave as on Unix platforms.
221
222=item *
223
224Not all of the utilities that come with the Perl distribution
225are supported yet.
226
227=back
228
229Please send detailed descriptions of any problems and solutions that
230you may find to <F<perlbug@perl.com>>, along with the output produced
231by C<perl -V>.
232
233=head1 AUTHORS
234
235=over 4
236
237=item Gary Ng <F<71564.1743@CompuServe.COM>>
238
239=item Gurusamy Sarathy <F<gsar@umich.edu>>
240
241=item Nick Ing-Simmons <F<nick@ni-s.u-net.com>>
242
243=back
244
245=head1 SEE ALSO
246
247L<perl>
248
249=head1 HISTORY
250
251This port was originally contributed by Gary Ng around 5.003_24,
252and borrowed from the Hip Communications port that was available
253at the time.
254
255Nick Ing-Simmons and Gurusamy Sarathy have made numerous and
256sundry hacks since then.
257
8b88ae92 258Last updated: 05 April 1997
68dc0745 259
260=cut