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 | |
7bac28a0 |
11 | These are instructions for building Perl under Windows NT (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 | |
7bac28a0 |
34 | You may also want to look at two other options for building |
35 | a perl that will work on Windows NT: the README.cygwin32 and |
36 | README.os2 files, which give a different set of rules to build a |
37 | Perl that will work on Win32 platforms. Those two methods will |
38 | probably enable you to build a more Unix-compatible perl, but you |
39 | will also need to download and use various other build-time and |
40 | run-time support software described in those files. |
68dc0745 |
41 | |
42 | This set of instructions is meant to describe a so-called "native" |
43 | port of Perl to Win32 platforms. The resulting Perl requires no |
44 | additional software to run (other than what came with your operating |
45 | system). Currently, this port is only capable of using Microsoft's |
46 | Visual C++ compiler. The ultimate goal is to support the other major |
7bac28a0 |
47 | compilers that can generally be used to build Win32 applications. |
5aabfad6 |
48 | |
49 | This port currently supports MakeMaker (the set of modules that |
50 | is used to build extensions to perl). Therefore, you should be |
51 | able to build and install most extensions found in the CPAN sites. |
7bac28a0 |
52 | See the L<Usage Hints> section for general hints about this. |
68dc0745 |
53 | |
54 | =head2 Setting Up |
55 | |
56 | =over 4 |
57 | |
58 | =item * |
59 | |
60 | Use the default "cmd" shell that comes with NT. In particular, do |
61 | *not* use the 4DOS/NT shell. The Makefile has commands that are not |
5aabfad6 |
62 | compatible with that shell. You are mostly on your own if you can |
63 | muster the temerity to attempt this with Windows95. |
68dc0745 |
64 | |
65 | =item * |
66 | |
7bac28a0 |
67 | If you did not choose to always initialize the Visual C++ compilation |
68 | environment variables when you installed Visual C++ on your system, you |
69 | will need to run the VCVARS32.BAT file usually found somewhere like |
70 | C:\MSDEV4.2\BIN. This will set your build environment. |
68dc0745 |
71 | |
72 | =item * |
73 | |
74 | Depending on how you extracted the distribution, you have to make sure |
7bac28a0 |
75 | some of the files are writable by you. The easiest way to make sure of |
68dc0745 |
76 | this is to execute: |
77 | |
78 | attrib -R *.* /S |
79 | |
80 | from the perl toplevel directory. You don't I<have> to do this if you |
81 | used the right tools to extract the files in the standard distribution, |
82 | but it doesn't hurt to do so. |
83 | |
84 | =back |
85 | |
137443ea |
86 | =head2 Building |
68dc0745 |
87 | |
88 | =over 4 |
89 | |
90 | =item * |
91 | |
68dc0745 |
92 | Make sure you are in the "win32" subdirectory under the perl toplevel. |
137443ea |
93 | This directory contains a "Makefile" that will work with |
94 | versions of NMAKE that come with Visual C++ ver. 2.0 and above. |
68dc0745 |
95 | |
96 | =item * |
97 | |
137443ea |
98 | Edit the Makefile and change the values of INST_DRV and INST_TOP |
99 | if you want perl to be installed in a location other than "C:\PERL". |
68dc0745 |
100 | |
101 | =item * |
102 | |
137443ea |
103 | If you are using Visual C++ ver. 4.0 and above: type "nmake". |
104 | If you are using a Visual C++ ver. 2.0: type "nmake CCTYPE=MSVC20". |
68dc0745 |
105 | |
137443ea |
106 | This should build everything. Specifically, it will create perl.exe, |
107 | perl.dll, and perlglob.exe at the perl toplevel, and various other |
7bac28a0 |
108 | extension dll's under the lib\auto directory. If the build fails for |
137443ea |
109 | any reason, make sure you have done the previous steps correctly. |
68dc0745 |
110 | |
111 | =back |
112 | |
113 | =head2 Testing |
114 | |
115 | Type "nmake test". This will run most of the tests from the |
8b88ae92 |
116 | testsuite (many tests will be skipped, and but no test should fail). |
68dc0745 |
117 | |
8b88ae92 |
118 | If some tests do fail, it may be because you are using a different command |
137443ea |
119 | shell than the native "cmd.exe". |
68dc0745 |
120 | |
8b88ae92 |
121 | Please report any failures as described under L<BUGS AND CAVEATS>. |
68dc0745 |
122 | |
137443ea |
123 | =head2 Installation |
124 | |
125 | Type "nmake install". This will put the newly built perl and the |
7bac28a0 |
126 | libraries under "C:\perl" (actually whatever you set C<INST_TOP> to |
127 | in the Makefile). It will also install the pod documentation under |
128 | C<$INST_TOP\lib\pod> and HTML versions of the same under |
129 | C<$INST_TOP\lib\pod\html>. To use the Perl you just installed, set your |
130 | PATH environment variable to "C:\perl\bin" (or C<$INST_TOP\bin>, if you |
137443ea |
131 | changed the default as above). |
132 | |
7bac28a0 |
133 | =head2 Usage Hints |
134 | |
135 | =over 4 |
136 | |
137 | =item Environment Variables |
138 | |
139 | The installation paths that you set during the build get compiled |
140 | into perl, so you don't have to do anything additional to start |
141 | using that perl (except add its location to your PATH variable). |
142 | |
143 | If you put extensions in unusual places, you can set PERL5LIB |
144 | to a list of paths separated by semicolons where you want perl |
145 | to look for libraries. Look for descriptions of other environment |
146 | variables you can set in the perlrun podpage. |
147 | |
148 | Sometime in the future, some of the configuration information |
149 | for perl will be moved into the Windows registry. |
150 | |
151 | =item Using perl from the command line |
152 | |
153 | If you are accustomed to using perl from various command-line |
154 | shells found in UNIX environments, you will be less than pleased |
155 | with what Windows NT offers by way of a command shell. |
156 | |
157 | The crucial thing to understand about the "cmd" shell (which is |
158 | the default on Windows NT) is that it does not do any wildcard |
159 | expansions of command-line arguments (so wildcards need not be |
160 | quoted). It also provides only rudimentary quoting. The only |
161 | (useful) quote character is the double quote ("). It can be used to |
162 | protect spaces in arguments and other special characters. The |
163 | Windows NT documentation has almost no description of how the |
164 | quoting rules are implemented, but here are some general observations |
165 | based on experiments: The shell breaks arguments at spaces and |
166 | passes them to programs in argc/argv. Doublequotes can be used |
167 | to prevent arguments with spaces in them from being split up. |
168 | You can put a double quote in an argument by escaping it with |
169 | a backslash and enclosing the whole argument within double quotes. |
170 | The backslash and the pair of double quotes surrounding the |
171 | argument will be stripped by the shell. |
172 | |
173 | The file redirection characters "<", ">", and "|" cannot be quoted |
174 | by double quotes (there are probably more such). Single quotes |
175 | will protect those three file redirection characters, but the |
176 | single quotes don't get stripped by the shell (just to make this |
177 | type of quoting completely useless). The caret "^" has also |
178 | been observed to behave as a quoting character (and doesn't get |
179 | stripped by the shell also). |
180 | |
181 | Here are some examples of usage of the "cmd" shell: |
182 | |
183 | This prints two doublequotes: |
184 | |
185 | perl -e "print '\"\"' " |
186 | |
187 | This does the same: |
188 | |
189 | perl -e "print \"\\\"\\\"\" " |
190 | |
191 | This prints "bar" and writes "foo" to the file "blurch": |
192 | |
193 | perl -e "print 'foo'; print STDERR 'bar'" > blurch |
194 | |
195 | This prints "foo" ("bar" disappears into nowhereland): |
196 | |
197 | perl -e "print 'foo'; print STDERR 'bar'" 2> nul |
198 | |
199 | This prints "bar" and writes "foo" into the file "blurch": |
200 | |
201 | perl -e "print 'foo'; print STDERR 'bar'" 1> blurch |
202 | |
203 | This prints "foo" and writes "bar" to the file "blurch": |
204 | |
205 | perl -e "print 'foo'; print STDERR 'bar'" 2> blurch |
206 | |
207 | This pipes "foo" to the "less" pager and prints "bar" on the console: |
208 | |
209 | perl -e "print 'foo'; print STDERR 'bar'" | less |
210 | |
211 | This pipes "foo\nbar\n" to the less pager: |
212 | |
213 | perl -le "print 'foo'; print STDERR 'bar'" |& less |
214 | |
215 | This does the same thing as the above: |
216 | |
217 | perl -le "print 'foo'; print STDERR 'bar'" 2>&1 | less |
218 | |
219 | This pipes "foo" to the pager and writes "bar" in the file "blurch": |
220 | |
221 | perl -e "print 'foo'; print STDERR 'bar'" 2> blurch | less |
222 | |
223 | |
224 | Discovering the usage of the "command.com" shell on Windows 95 |
225 | is left as an exercise to the reader :) |
226 | |
227 | =item Building Extensions |
228 | |
229 | The Comprehensive Perl Archive Network (CPAN) offers a wealth |
230 | of extensions, some of which require a C compiler to build. |
231 | Look in http://www.perl.com/ for more information on CPAN. |
232 | |
233 | Most extensions (whether they require a C compiler or not) can |
234 | be built, tested and installed with the standard mantra: |
235 | |
236 | perl Makefile.PL |
237 | nmake |
238 | nmake test |
239 | nmake install |
240 | |
241 | Note the NMAKE that comes with Visual C++ is required. Some |
242 | extensions may not provide a testsuite (so "nmake test" |
243 | may not do anything, or fail), but most serious ones do. |
244 | |
245 | If a module implements XSUBs, you will need a C compiler (Visual C++ |
246 | versions 2.0 and above are currently supported). You must make sure |
247 | you have set up the environment for the compiler for command-line |
248 | compilation. |
249 | |
250 | If a module does not build for some reason, carefully look at |
251 | why it failed, and report problems to the module author. If |
252 | it looks like the extension building support is at fault, report |
253 | that with full details of how the build failed using the perlbug |
254 | utility. |
255 | |
256 | =item Miscellaneous Things |
257 | |
258 | A full set of HTML documentation is installed, so you should be |
259 | able to use it if you have a web browser installed on your |
260 | system. |
261 | |
262 | C<perldoc> is also a useful tool for browsing information contained |
263 | in the documentation, especially in conjunction with a pager |
264 | like C<less> (recent versions of which have Win32 support). You may |
265 | have to set the PAGER environment variable to use a specific pager. |
266 | "perldoc -f foo" will print information about the perl operator |
267 | "foo". |
268 | |
269 | If you find bugs in perl, you can run C<perlbug> to create a |
270 | bug report (you may have to send it manually if C<perlbug> cannot |
271 | find a mailer on your system). |
272 | |
273 | =back |
274 | |
68dc0745 |
275 | =head1 BUGS AND CAVEATS |
276 | |
7bac28a0 |
277 | This port has not been tested as extensively as we'd like, and |
278 | therefore should be considered beta quality software. You should |
279 | expect changes in virtually all of these areas: build process, |
280 | installation structure, supported utilities/modules, and supported |
281 | perl functionality. In particular, functionality specific to the |
282 | Win32 environment may ultimately be supported as either core modules |
283 | or extensions. This means that you should be prepared to recompile |
284 | extensions when binary incompatibilites arise due to changes in the |
285 | internal structure of the code. |
68dc0745 |
286 | |
8b88ae92 |
287 | If you have had prior exposure to Perl on Unix platforms, you will notice |
288 | this port exhibits behavior different from what is documented. Most of the |
7bac28a0 |
289 | differences fall under one of these categories. We do not consider |
290 | any of them to be serious limitations (especially when compared to the |
291 | limited nature of some of the Win32 OSes themselves :) |
68dc0745 |
292 | |
293 | =over 8 |
294 | |
295 | =item * |
296 | |
297 | C<stat()> and C<lstat()> functions may not behave as documented. They |
298 | may return values that bear no resemblance to those reported on Unix |
7bac28a0 |
299 | platforms, and some fields (like the the one for inode) may be completely |
300 | bogus. |
68dc0745 |
301 | |
302 | =item * |
303 | |
304 | The following functions are currently unavailable: C<fork()>, C<exec()>, |
5aabfad6 |
305 | C<dump()>, C<chown()>, C<link()>, C<symlink()>, C<chroot()>, |
68dc0745 |
306 | C<setpgrp()>, C<getpgrp()>, C<setpriority()>, C<getpriority()>, |
5aabfad6 |
307 | C<syscall()>, C<fcntl()>, C<flock()>. This list is possibly very |
308 | incomplete. |
68dc0745 |
309 | |
310 | =item * |
311 | |
312 | Various C<socket()> related calls are supported, but they may not |
313 | behave as on Unix platforms. |
314 | |
315 | =item * |
316 | |
317 | The four-argument C<select()> call is only supported on sockets. |
318 | |
319 | =item * |
320 | |
5aabfad6 |
321 | C<$?> ends up with the exitstatus of the subprocess (this is different |
322 | from Unix, where the exitstatus is actually given by "$? >> 8"). |
323 | Failure to spawn() the subprocess is indicated by setting $? to |
324 | "255<<8". This is subject to change. |
68dc0745 |
325 | |
326 | =item * |
327 | |
328 | Building modules available on CPAN is mostly supported, but this |
329 | hasn't been tested much yet. Expect strange problems, and be |
330 | prepared to deal with the consequences. |
331 | |
332 | =item * |
333 | |
334 | C<utime()>, C<times()> and process-related functions may not |
335 | behave as described in the documentation, and some of the |
336 | returned values or effects may be bogus. |
337 | |
338 | =item * |
339 | |
340 | Signal handling may not behave as on Unix platforms. |
341 | |
342 | =item * |
343 | |
7bac28a0 |
344 | File globbing may not behave as on Unix platforms. In particular, |
345 | globbing does not understand wildcards in the pathname component, |
346 | but only in the filename component. In other words, something like |
347 | "print <*/*.pl>" will not print all the perl scripts in all the |
348 | subdirectories one level under the current one (like it does on |
349 | UNIX platforms). |
68dc0745 |
350 | |
351 | =back |
352 | |
353 | Please send detailed descriptions of any problems and solutions that |
354 | you may find to <F<perlbug@perl.com>>, along with the output produced |
355 | by C<perl -V>. |
356 | |
357 | =head1 AUTHORS |
358 | |
359 | =over 4 |
360 | |
361 | =item Gary Ng <F<71564.1743@CompuServe.COM>> |
362 | |
363 | =item Gurusamy Sarathy <F<gsar@umich.edu>> |
364 | |
365 | =item Nick Ing-Simmons <F<nick@ni-s.u-net.com>> |
366 | |
367 | =back |
368 | |
369 | =head1 SEE ALSO |
370 | |
371 | L<perl> |
372 | |
373 | =head1 HISTORY |
374 | |
375 | This port was originally contributed by Gary Ng around 5.003_24, |
376 | and borrowed from the Hip Communications port that was available |
377 | at the time. |
378 | |
379 | Nick Ing-Simmons and Gurusamy Sarathy have made numerous and |
380 | sundry hacks since then. |
381 | |
137443ea |
382 | Last updated: 13 April 1997 |
68dc0745 |
383 | |
384 | =cut |