Commit | Line | Data |
---|---|---|
68dc0745 | 1 | If you read this file _as_is_, just ignore the funny characters you |
2 | see. It is written in the POD format (see pod/perlpod.pod) which is | |
3 | specially designed to be readable as is. | |
4 | ||
5 | =head1 NAME | |
6 | ||
5aabfad6 | 7 | perlwin32 - Perl under Win32 |
68dc0745 | 8 | |
9 | =head1 SYNOPSIS | |
10 | ||
11 | These are instructions for building Perl under WindowsNT (versions | |
5aabfad6 | 12 | 3.51 or 4.0), using Visual C++ (versions 2.0 through 5.0). Currently, |
13 | this port may also build under Windows95, but you can expect problems | |
14 | stemming from the unmentionable command shell that infests that | |
15 | platform. Note this caveat is only about B<building> perl. Once | |
16 | built, you should be able to B<use> it on either Win32 platform (modulo | |
17 | the problems arising from the inferior command shell). | |
68dc0745 | 18 | |
19 | =head1 DESCRIPTION | |
20 | ||
3fe9a6f1 | 21 | Before you start, you should glance through the README file |
68dc0745 | 22 | found in the top-level directory where the Perl distribution |
23 | was extracted. Make sure you read and understand the terms under | |
24 | which this software is being distributed. | |
25 | ||
3fe9a6f1 | 26 | Also make sure you read the L<BUGS AND CAVEATS> section below for the |
68dc0745 | 27 | known limitations of this port. |
28 | ||
29 | The INSTALL file in the perl top-level has much information that is | |
30 | only relevant to people building Perl on Unix-like systems. In | |
31 | particular, you can safely ignore any information that talks about | |
32 | "Configure". | |
33 | ||
34 | You should probably also read the README.os2 file, which gives a | |
35 | different set of rules to build a Perl that will work on Win32 | |
36 | platforms. That method will probably enable you to build a more | |
37 | Unix-compatible perl, but you will also need to download and use | |
38 | various other support software described in that file. | |
39 | ||
40 | This set of instructions is meant to describe a so-called "native" | |
41 | port of Perl to Win32 platforms. The resulting Perl requires no | |
42 | additional software to run (other than what came with your operating | |
43 | system). Currently, this port is only capable of using Microsoft's | |
44 | Visual C++ compiler. The ultimate goal is to support the other major | |
5aabfad6 | 45 | compilers that can be used to build Win32 applications. |
46 | ||
47 | This port currently supports MakeMaker (the set of modules that | |
48 | is used to build extensions to perl). Therefore, you should be | |
49 | able 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 | ||
57 | Use 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 | 59 | compatible with that shell. You are mostly on your own if you can |
60 | muster the temerity to attempt this with Windows95. | |
68dc0745 | 61 | |
62 | =item * | |
63 | ||
64 | Run the VCVARS32.BAT file usually found somewhere like C:\MSDEV4.2\BIN. | |
65 | This will set your build environment. | |
66 | ||
67 | =item * | |
68 | ||
69 | Depending on how you extracted the distribution, you have to make sure | |
70 | all the files are writable by you. The easiest way to make sure of | |
71 | this is to execute: | |
72 | ||
73 | attrib -R *.* /S | |
74 | ||
75 | from the perl toplevel directory. You don't I<have> to do this if you | |
76 | used the right tools to extract the files in the standard distribution, | |
77 | but it doesn't hurt to do so. | |
78 | ||
79 | =back | |
80 | ||
137443ea | 81 | =head2 Building |
68dc0745 | 82 | |
83 | =over 4 | |
84 | ||
85 | =item * | |
86 | ||
68dc0745 | 87 | Make sure you are in the "win32" subdirectory under the perl toplevel. |
137443ea | 88 | This directory contains a "Makefile" that will work with |
89 | versions of NMAKE that come with Visual C++ ver. 2.0 and above. | |
68dc0745 | 90 | |
91 | =item * | |
92 | ||
137443ea | 93 | Edit the Makefile and change the values of INST_DRV and INST_TOP |
94 | if you want perl to be installed in a location other than "C:\PERL". | |
68dc0745 | 95 | |
96 | =item * | |
97 | ||
137443ea | 98 | If you are using Visual C++ ver. 4.0 and above: type "nmake". |
99 | If you are using a Visual C++ ver. 2.0: type "nmake CCTYPE=MSVC20". | |
68dc0745 | 100 | |
137443ea | 101 | This should build everything. Specifically, it will create perl.exe, |
102 | perl.dll, and perlglob.exe at the perl toplevel, and various other | |
103 | extension dll's under the lib\auto directory. If the make fails for | |
104 | any reason, make sure you have done the previous steps correctly. | |
68dc0745 | 105 | |
106 | =back | |
107 | ||
108 | =head2 Testing | |
109 | ||
110 | Type "nmake test". This will run most of the tests from the | |
8b88ae92 | 111 | testsuite (many tests will be skipped, and but no test should fail). |
68dc0745 | 112 | |
8b88ae92 | 113 | If some tests do fail, it may be because you are using a different command |
137443ea | 114 | shell than the native "cmd.exe". |
68dc0745 | 115 | |
8b88ae92 | 116 | Please report any failures as described under L<BUGS AND CAVEATS>. |
68dc0745 | 117 | |
137443ea | 118 | =head2 Installation |
119 | ||
120 | Type "nmake install". This will put the newly built perl and the | |
121 | libraries under "C:\PERL" (actually whatever you set INST_TOP to | |
122 | in the Makefile). To use the Perl you just installed, set your | |
123 | PATH environment variable to "C:\PERL\BIN" (or $(INST_TOP)\BIN, if you | |
124 | changed the default as above). | |
125 | ||
68dc0745 | 126 | =head1 BUGS AND CAVEATS |
127 | ||
128 | This is still very much an experimental port, and should be considered | |
129 | alpha quality software. You can expect changes in virtually all of | |
130 | these areas: build process, installation structure, supported | |
131 | utilities/modules, and supported perl functionality. Specifically, | |
8b88ae92 | 132 | functionality specific to the Win32 environment may ultimately |
68dc0745 | 133 | be supported as either core modules or extensions. |
134 | ||
8b88ae92 NIS |
135 | If you have had prior exposure to Perl on Unix platforms, you will notice |
136 | this port exhibits behavior different from what is documented. Most of the | |
5aabfad6 | 137 | differences fall under one of these categories. |
68dc0745 | 138 | |
139 | =over 8 | |
140 | ||
141 | =item * | |
142 | ||
143 | C<stat()> and C<lstat()> functions may not behave as documented. They | |
144 | may return values that bear no resemblance to those reported on Unix | |
145 | platforms, and some fields may be completely bogus. | |
146 | ||
147 | =item * | |
148 | ||
149 | The following functions are currently unavailable: C<fork()>, C<exec()>, | |
5aabfad6 | 150 | C<dump()>, C<chown()>, C<link()>, C<symlink()>, C<chroot()>, |
68dc0745 | 151 | C<setpgrp()>, C<getpgrp()>, C<setpriority()>, C<getpriority()>, |
5aabfad6 | 152 | C<syscall()>, C<fcntl()>, C<flock()>. This list is possibly very |
153 | incomplete. | |
68dc0745 | 154 | |
155 | =item * | |
156 | ||
157 | Various C<socket()> related calls are supported, but they may not | |
158 | behave as on Unix platforms. | |
159 | ||
160 | =item * | |
161 | ||
162 | The four-argument C<select()> call is only supported on sockets. | |
163 | ||
164 | =item * | |
165 | ||
166 | The behavior of C<system()> or the C<qx[]> operator (a.k.a. "backticks"), | |
167 | when used to call interactive commands, is ill-defined. | |
168 | ||
169 | =item * | |
170 | ||
5aabfad6 | 171 | C<$?> ends up with the exitstatus of the subprocess (this is different |
172 | from Unix, where the exitstatus is actually given by "$? >> 8"). | |
173 | Failure to spawn() the subprocess is indicated by setting $? to | |
174 | "255<<8". This is subject to change. | |
68dc0745 | 175 | |
176 | =item * | |
177 | ||
178 | Building modules available on CPAN is mostly supported, but this | |
179 | hasn't been tested much yet. Expect strange problems, and be | |
180 | prepared to deal with the consequences. | |
181 | ||
182 | =item * | |
183 | ||
184 | C<utime()>, C<times()> and process-related functions may not | |
185 | behave as described in the documentation, and some of the | |
186 | returned values or effects may be bogus. | |
187 | ||
188 | =item * | |
189 | ||
190 | Signal handling may not behave as on Unix platforms. | |
191 | ||
192 | =item * | |
193 | ||
194 | File globbing may not behave as on Unix platforms. | |
195 | ||
196 | =item * | |
197 | ||
198 | Not all of the utilities that come with the Perl distribution | |
199 | are supported yet. | |
200 | ||
201 | =back | |
202 | ||
203 | Please send detailed descriptions of any problems and solutions that | |
204 | you may find to <F<perlbug@perl.com>>, along with the output produced | |
205 | by 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 | ||
221 | L<perl> | |
222 | ||
223 | =head1 HISTORY | |
224 | ||
225 | This port was originally contributed by Gary Ng around 5.003_24, | |
226 | and borrowed from the Hip Communications port that was available | |
227 | at the time. | |
228 | ||
229 | Nick Ing-Simmons and Gurusamy Sarathy have made numerous and | |
230 | sundry hacks since then. | |
231 | ||
137443ea | 232 | Last updated: 13 April 1997 |
68dc0745 | 233 | |
234 | =cut |