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