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