This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
OS/2 doc patch for _99
[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
137443ea 81=head2 Building
68dc0745
PP
82
83=over 4
84
85=item *
86
68dc0745 87Make sure you are in the "win32" subdirectory under the perl toplevel.
137443ea
PP
88This directory contains a "Makefile" that will work with
89versions of NMAKE that come with Visual C++ ver. 2.0 and above.
68dc0745
PP
90
91=item *
92
137443ea
PP
93Edit the Makefile and change the values of INST_DRV and INST_TOP
94if you want perl to be installed in a location other than "C:\PERL".
68dc0745
PP
95
96=item *
97
137443ea
PP
98If you are using Visual C++ ver. 4.0 and above: type "nmake".
99If you are using a Visual C++ ver. 2.0: type "nmake CCTYPE=MSVC20".
68dc0745 100
137443ea
PP
101This should build everything. Specifically, it will create perl.exe,
102perl.dll, and perlglob.exe at the perl toplevel, and various other
103extension dll's under the lib\auto directory. If the make fails for
104any reason, make sure you have done the previous steps correctly.
68dc0745
PP
105
106=back
107
108=head2 Testing
109
110Type "nmake test". This will run most of the tests from the
8b88ae92 111testsuite (many tests will be skipped, and but no test should fail).
68dc0745 112
8b88ae92 113If some tests do fail, it may be because you are using a different command
137443ea 114shell than the native "cmd.exe".
68dc0745 115
8b88ae92 116Please report any failures as described under L<BUGS AND CAVEATS>.
68dc0745 117
137443ea
PP
118=head2 Installation
119
120Type "nmake install". This will put the newly built perl and the
121libraries under "C:\PERL" (actually whatever you set INST_TOP to
122in the Makefile). To use the Perl you just installed, set your
123PATH environment variable to "C:\PERL\BIN" (or $(INST_TOP)\BIN, if you
124changed the default as above).
125
68dc0745
PP
126=head1 BUGS AND CAVEATS
127
128This is still very much an experimental port, and should be considered
129alpha quality software. You can expect changes in virtually all of
130these areas: build process, installation structure, supported
131utilities/modules, and supported perl functionality. Specifically,
8b88ae92 132functionality specific to the Win32 environment may ultimately
68dc0745
PP
133be supported as either core modules or extensions.
134
8b88ae92
NIS
135If you have had prior exposure to Perl on Unix platforms, you will notice
136this port exhibits behavior different from what is documented. Most of the
5aabfad6 137differences fall under one of these categories.
68dc0745
PP
138
139=over 8
140
141=item *
142
143C<stat()> and C<lstat()> functions may not behave as documented. They
144may return values that bear no resemblance to those reported on Unix
145platforms, and some fields may be completely bogus.
146
147=item *
148
149The following functions are currently unavailable: C<fork()>, C<exec()>,
5aabfad6 150C<dump()>, C<chown()>, C<link()>, C<symlink()>, C<chroot()>,
68dc0745 151C<setpgrp()>, C<getpgrp()>, C<setpriority()>, C<getpriority()>,
5aabfad6
PP
152C<syscall()>, C<fcntl()>, C<flock()>. This list is possibly very
153incomplete.
68dc0745
PP
154
155=item *
156
157Various C<socket()> related calls are supported, but they may not
158behave as on Unix platforms.
159
160=item *
161
162The four-argument C<select()> call is only supported on sockets.
163
164=item *
165
166The behavior of C<system()> or the C<qx[]> operator (a.k.a. "backticks"),
167when used to call interactive commands, is ill-defined.
168
169=item *
170
5aabfad6
PP
171C<$?> ends up with the exitstatus of the subprocess (this is different
172from Unix, where the exitstatus is actually given by "$? >> 8").
173Failure to spawn() the subprocess is indicated by setting $? to
174"255<<8". This is subject to change.
68dc0745
PP
175
176=item *
177
178Building modules available on CPAN is mostly supported, but this
179hasn't been tested much yet. Expect strange problems, and be
180prepared to deal with the consequences.
181
182=item *
183
184C<utime()>, C<times()> and process-related functions may not
185behave as described in the documentation, and some of the
186returned values or effects may be bogus.
187
188=item *
189
190Signal handling may not behave as on Unix platforms.
191
192=item *
193
194File globbing may not behave as on Unix platforms.
195
196=item *
197
198Not all of the utilities that come with the Perl distribution
199are supported yet.
200
201=back
202
203Please send detailed descriptions of any problems and solutions that
204you may find to <F<perlbug@perl.com>>, along with the output produced
205by C<perl -V>.
206
207=head1 AUTHORS
208
209=over 4
210
211=item Gary Ng <F<71564.1743@CompuServe.COM>>
212
213=item Gurusamy Sarathy <F<gsar@umich.edu>>
214
215=item Nick Ing-Simmons <F<nick@ni-s.u-net.com>>
216
217=back
218
219=head1 SEE ALSO
220
221L<perl>
222
223=head1 HISTORY
224
225This port was originally contributed by Gary Ng around 5.003_24,
226and borrowed from the Hip Communications port that was available
227at the time.
228
229Nick Ing-Simmons and Gurusamy Sarathy have made numerous and
230sundry hacks since then.
231
137443ea 232Last updated: 13 April 1997
68dc0745
PP
233
234=cut