This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
getenv() after my_setenv() gets old entry on Win32
[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
3e3baf6d
TB
123.51 or 4.0), using Visual C++ (versions 2.0 through 5.0) or Borland
13C++ (version 5.x). Currently, this port may also build under Windows95,
14but you can expect problems stemming from the unmentionable command
15shell that infests that platform. Note this caveat is only about
16B<building> perl. Once built, you should be able to B<use> it on
17either Win32 platform (modulo the problems arising from the inferior
18command shell).
68dc0745
PP
19
20=head1 DESCRIPTION
21
3fe9a6f1 22Before you start, you should glance through the README file
68dc0745
PP
23found in the top-level directory where the Perl distribution
24was extracted. Make sure you read and understand the terms under
25which this software is being distributed.
26
3fe9a6f1 27Also make sure you read the L<BUGS AND CAVEATS> section below for the
68dc0745
PP
28known limitations of this port.
29
30The INSTALL file in the perl top-level has much information that is
31only relevant to people building Perl on Unix-like systems. In
32particular, you can safely ignore any information that talks about
33"Configure".
34
7bac28a0
PP
35You may also want to look at two other options for building
36a perl that will work on Windows NT: the README.cygwin32 and
3e3baf6d
TB
37README.os2 files, which each give a different set of rules to build
38a Perl that will work on Win32 platforms. Those two methods will
7bac28a0
PP
39probably enable you to build a more Unix-compatible perl, but you
40will also need to download and use various other build-time and
41run-time support software described in those files.
68dc0745
PP
42
43This set of instructions is meant to describe a so-called "native"
44port of Perl to Win32 platforms. The resulting Perl requires no
45additional software to run (other than what came with your operating
3e3baf6d
TB
46system). Currently, this port is capable of using either the
47Microsoft Visual C++ compiler, or the Borland C++ compiler. The
48ultimate goal is to support the other major compilers that can
49generally be used to build Win32 applications.
5aabfad6
PP
50
51This port currently supports MakeMaker (the set of modules that
52is used to build extensions to perl). Therefore, you should be
53able to build and install most extensions found in the CPAN sites.
c90c0ff4 54See L<Usage Hints> below for general hints about this.
68dc0745
PP
55
56=head2 Setting Up
57
58=over 4
59
3e3baf6d 60=item Command Shell
68dc0745
PP
61
62Use the default "cmd" shell that comes with NT. In particular, do
63*not* use the 4DOS/NT shell. The Makefile has commands that are not
c90c0ff4
PP
64compatible with that shell. The Makefile also has known
65incompatibilites with the default shell that comes with Windows95,
66so building under Windows95 should be considered "unsupported".
68dc0745 67
3e3baf6d
TB
68=item Borland C++
69
70If you are using the Borland compiler, you will need dmake, a freely
71available make that has very nice macro features and parallelability.
72(The make that Borland supplies is seriously crippled, and will not
73work for MakeMaker builds--if you *have* to bug someone about this,
74I suggest you bug Borland to fix their make :)
75
76A port of dmake for win32 platforms is available from
77"http://www-personal.umich.edu/~gsar/dmake-4.0-win32.tar.gz".
78Fetch and install dmake somewhere on your path. Also make sure you
79copy the Borland dmake.ini file to some location where you keep
80*.ini files. If you use the binary that comes with the above port, you
81will need to set INIT in your environment to the directory where you
82put the dmake.ini file.
83
84=item Microsoft Visual C++
68dc0745 85
3e3baf6d 86The NMAKE that comes with Visual C++ will suffice for building.
7bac28a0
PP
87If you did not choose to always initialize the Visual C++ compilation
88environment variables when you installed Visual C++ on your system, you
89will need to run the VCVARS32.BAT file usually found somewhere like
90C:\MSDEV4.2\BIN. This will set your build environment.
68dc0745 91
3e3baf6d
TB
92You can also use dmake to build using Visual C++, provided: you
93copied the dmake.ini for Visual C++; set INIT to point to the
94directory where you put it, as above; and edit win32/config.vc
95and change "make=nmake" to "make=dmake". The last step is only
96essential if you want to use dmake to be your default make for
97building extensions using MakeMaker.
98
99=item Permissions
68dc0745
PP
100
101Depending on how you extracted the distribution, you have to make sure
7bac28a0 102some of the files are writable by you. The easiest way to make sure of
68dc0745
PP
103this is to execute:
104
105 attrib -R *.* /S
106
107from the perl toplevel directory. You don't I<have> to do this if you
108used the right tools to extract the files in the standard distribution,
109but it doesn't hurt to do so.
110
111=back
112
137443ea 113=head2 Building
68dc0745
PP
114
115=over 4
116
117=item *
118
68dc0745 119Make sure you are in the "win32" subdirectory under the perl toplevel.
137443ea 120This directory contains a "Makefile" that will work with
3e3baf6d
TB
121versions of NMAKE that come with Visual C++ ver. 2.0 and above, and
122a dmake "makefile.mk" that will work for both Borland and Visual C++
123builds. The defaults in the dmake makefile are setup to build using the
124Borland compiler.
68dc0745
PP
125
126=item *
127
3e3baf6d
TB
128Edit the Makefile (or makefile.mk, if using dmake) and change the values
129of INST_DRV and INST_TOP if you want perl to be installed in a location
130other than "C:\PERL". If you are using Visual C++ ver. 2.0, uncomment
131the line that sets "CCTYPE=MSVC20".
c90c0ff4 132
3e3baf6d
TB
133You will also have to make sure CCHOME points to wherever you installed
134your compiler.
c90c0ff4 135
68dc0745
PP
136=item *
137
3e3baf6d 138Type "nmake" (or "dmake" if you are using that make).
68dc0745 139
137443ea
PP
140This should build everything. Specifically, it will create perl.exe,
141perl.dll, and perlglob.exe at the perl toplevel, and various other
7bac28a0 142extension dll's under the lib\auto directory. If the build fails for
137443ea 143any reason, make sure you have done the previous steps correctly.
68dc0745 144
3e3baf6d
TB
145When building using Visual C++, a perl95.exe will also get built. This
146executable is only needed on Windows95, and should be used instead of
147perl.exe, and then only if you want sockets to work properly on Windows95.
148This is necessitated by a bug in the Microsoft C Runtime that cannot be
149worked around in the "normal" perl.exe. Again, if this bugs you, please
150bug Microsoft :). perl95.exe gets built with its own private copy of the
151C Runtime that is not accessible to extensions (which see the DLL version
152of the CRT). Be aware, therefore, that this perl95.exe will have
153esoteric problems with extensions like perl/Tk that themselves use the C
154Runtime heavily, or want to free() pointers malloc()-ed by perl.
155
156You can avoid the perl95.exe problems completely if you use Borland
157C++ for building perl (perl95.exe is not needed and will not be built
158in that case).
159
68dc0745
PP
160=back
161
162=head2 Testing
163
3e3baf6d
TB
164Type "nmake test" (or "dmake test"). This will run most of the tests from
165the testsuite (many tests will be skipped, and but no test should fail).
68dc0745 166
8b88ae92 167If some tests do fail, it may be because you are using a different command
137443ea 168shell than the native "cmd.exe".
68dc0745 169
3e3baf6d
TB
170If you used the Borland compiler, you may see a failure in op/taint.t
171arising from the inability to find the Borland Runtime DLLs on the system
172default path. You will need to copy the DLLs reported by the messages
173from where Borland chose to install it, into the Windows system directory
174(usually somewhere like C:\WINNT\SYSTEM32), and rerun the test.
175
176Please report any other failures as described under L<BUGS AND CAVEATS>.
68dc0745 177
137443ea
PP
178=head2 Installation
179
3e3baf6d
TB
180Type "nmake install" (or "dmake install"). This will put the newly
181built perl and the libraries under "C:\perl" (actually whatever you set
182C<INST_TOP> to in the Makefile). It will also install the pod
183documentation under C<$INST_TOP\lib\pod> and HTML versions of the same
184under C<$INST_TOP\lib\pod\html>. To use the Perl you just installed,
185set your PATH environment variable to "C:\perl\bin" (or C<$INST_TOP\bin>,
186if you changed the default as above).
137443ea 187
7bac28a0
PP
188=head2 Usage Hints
189
190=over 4
191
192=item Environment Variables
193
194The installation paths that you set during the build get compiled
195into perl, so you don't have to do anything additional to start
196using that perl (except add its location to your PATH variable).
197
198If you put extensions in unusual places, you can set PERL5LIB
199to a list of paths separated by semicolons where you want perl
200to look for libraries. Look for descriptions of other environment
201variables you can set in the perlrun podpage.
202
203Sometime in the future, some of the configuration information
204for perl will be moved into the Windows registry.
205
3e3baf6d
TB
206=item File Globbing
207
208By default, perl spawns an external program to do file globbing.
209The install process installs both a perlglob.exe and a perlglob.bat
210that perl can use for this purpose. Note that with the default
211installation, perlglob.exe will be found by the system before
212perlglob.bat.
213
214perlglob.exe relies on the argv expansion done by the C Runtime of
215the particular compiler you used, and therefore behaves very
216differently depending on the Runtime used to build it. To preserve
217compatiblity, perlglob.bat (a perl script/module that can be
218used portably) is installed. Besides being portable, perlglob.bat
219also offers enhanced globbing functionality.
220
221If you want perl to use perlglob.bat instead of perlglob.exe, just
222delete perlglob.exe from the install location (or move it somewhere
223perl cannot find). Using File::DosGlob.pm (which is the same
224as perlglob.bat) to override the internal CORE::glob() works about 10
225times faster than spawing perlglob.exe, and you should take this
226approach when writing new modules. See File::DosGlob for details.
227
7bac28a0
PP
228=item Using perl from the command line
229
230If you are accustomed to using perl from various command-line
231shells found in UNIX environments, you will be less than pleased
232with what Windows NT offers by way of a command shell.
233
234The crucial thing to understand about the "cmd" shell (which is
235the default on Windows NT) is that it does not do any wildcard
236expansions of command-line arguments (so wildcards need not be
237quoted). It also provides only rudimentary quoting. The only
238(useful) quote character is the double quote ("). It can be used to
239protect spaces in arguments and other special characters. The
240Windows NT documentation has almost no description of how the
241quoting rules are implemented, but here are some general observations
242based on experiments: The shell breaks arguments at spaces and
243passes them to programs in argc/argv. Doublequotes can be used
244to prevent arguments with spaces in them from being split up.
245You can put a double quote in an argument by escaping it with
246a backslash and enclosing the whole argument within double quotes.
247The backslash and the pair of double quotes surrounding the
248argument will be stripped by the shell.
249
250The file redirection characters "<", ">", and "|" cannot be quoted
251by double quotes (there are probably more such). Single quotes
252will protect those three file redirection characters, but the
253single quotes don't get stripped by the shell (just to make this
254type of quoting completely useless). The caret "^" has also
255been observed to behave as a quoting character (and doesn't get
256stripped by the shell also).
257
258Here are some examples of usage of the "cmd" shell:
259
260This prints two doublequotes:
261
262 perl -e "print '\"\"' "
263
264This does the same:
265
266 perl -e "print \"\\\"\\\"\" "
267
268This prints "bar" and writes "foo" to the file "blurch":
269
270 perl -e "print 'foo'; print STDERR 'bar'" > blurch
271
272This prints "foo" ("bar" disappears into nowhereland):
273
274 perl -e "print 'foo'; print STDERR 'bar'" 2> nul
275
276This prints "bar" and writes "foo" into the file "blurch":
277
278 perl -e "print 'foo'; print STDERR 'bar'" 1> blurch
279
7bac28a0
PP
280This pipes "foo" to the "less" pager and prints "bar" on the console:
281
282 perl -e "print 'foo'; print STDERR 'bar'" | less
283
284This pipes "foo\nbar\n" to the less pager:
285
7bac28a0
PP
286 perl -le "print 'foo'; print STDERR 'bar'" 2>&1 | less
287
288This pipes "foo" to the pager and writes "bar" in the file "blurch":
289
290 perl -e "print 'foo'; print STDERR 'bar'" 2> blurch | less
291
292
c90c0ff4 293Discovering the usage of the "command.com" shell on Windows95
7bac28a0
PP
294is left as an exercise to the reader :)
295
296=item Building Extensions
297
298The Comprehensive Perl Archive Network (CPAN) offers a wealth
299of extensions, some of which require a C compiler to build.
300Look in http://www.perl.com/ for more information on CPAN.
301
302Most extensions (whether they require a C compiler or not) can
303be built, tested and installed with the standard mantra:
304
305 perl Makefile.PL
3e3baf6d
TB
306 $MAKE
307 $MAKE test
308 $MAKE install
7bac28a0 309
3e3baf6d
TB
310where $MAKE stands for NMAKE or DMAKE. Some extensions may not
311provide a testsuite (so "$MAKE test" may not do anything, or fail),
312but most serious ones do.
7bac28a0 313
3e3baf6d
TB
314If a module implements XSUBs, you will need one of the supported
315C compilers. You must make sure you have set up the environment for
316the compiler for command-line compilation.
7bac28a0 317
3e3baf6d 318If a module does not build for some reason, look carefully for
7bac28a0
PP
319why it failed, and report problems to the module author. If
320it looks like the extension building support is at fault, report
321that with full details of how the build failed using the perlbug
322utility.
323
c90c0ff4
PP
324=item Win32 Specific Extensions
325
326A number of extensions specific to the Win32 platform are available
327from CPAN. You may find that many of these extensions are meant to
328be used under the Activeware port of Perl, which used to be the only
329native port for the Win32 platform. Since the Activeware port does not
330have adequate support for Perl's extension building tools, these
331extensions typically do not support those tools either, and therefore
332cannot be built using the generic steps shown in the previous section.
333
334To ensure smooth transitioning of existing code that uses the
335Activeware port, there is a bundle of Win32 extensions that contains
336all of the Activeware extensions and most other Win32 extensions from
337CPAN in source form, along with many added bugfixes, and with MakeMaker
338support. This bundle is available at:
339
6890e559 340 http://www.perl.com/CPAN/authors/id/GSAR/libwin32-0.07.tar.gz
c90c0ff4
PP
341
342See the README in that distribution for building and installation
343instructions. Look for later versions that may be available at the
344same location.
345
346It is expected that authors of Win32 specific extensions will begin
347distributing their work in MakeMaker compatible form subsequent to
348the 5.004 release of perl, at which point the need for a dedicated
349bundle such as the above should diminish.
350
7bac28a0
PP
351=item Miscellaneous Things
352
353A full set of HTML documentation is installed, so you should be
354able to use it if you have a web browser installed on your
355system.
356
357C<perldoc> is also a useful tool for browsing information contained
358in the documentation, especially in conjunction with a pager
359like C<less> (recent versions of which have Win32 support). You may
360have to set the PAGER environment variable to use a specific pager.
361"perldoc -f foo" will print information about the perl operator
362"foo".
363
364If you find bugs in perl, you can run C<perlbug> to create a
365bug report (you may have to send it manually if C<perlbug> cannot
366find a mailer on your system).
367
368=back
369
68dc0745
PP
370=head1 BUGS AND CAVEATS
371
3e3baf6d
TB
372This port should be considered beta quality software at the present
373time because some details are still in flux and there may be
374changes in any of these areas: build process, installation structure,
375supported utilities/modules, and supported perl functionality.
376In particular, functionality specific to the Win32 environment may
377ultimately be supported as either core modules or extensions. This
378means that you should be prepared to recompile extensions when binary
379incompatibilites arise due to changes in the internal structure of
380the code.
381
382The DLLs produced by the two supported compilers are incompatible
383with each other due to the conventions they use to export symbols,
384and due to differences in the Runtime libraries that they provide.
385This means that extension binaries built under either compiler will
386only work with the perl binaries built under the same compiler.
387If you know of a robust, freely available C Runtime that can
388be used under win32, let us know.
68dc0745 389
8b88ae92
NIS
390If you have had prior exposure to Perl on Unix platforms, you will notice
391this port exhibits behavior different from what is documented. Most of the
7bac28a0
PP
392differences fall under one of these categories. We do not consider
393any of them to be serious limitations (especially when compared to the
394limited nature of some of the Win32 OSes themselves :)
68dc0745
PP
395
396=over 8
397
398=item *
399
400C<stat()> and C<lstat()> functions may not behave as documented. They
401may return values that bear no resemblance to those reported on Unix
7bac28a0
PP
402platforms, and some fields (like the the one for inode) may be completely
403bogus.
68dc0745
PP
404
405=item *
406
6890e559 407The following functions are currently unavailable: C<fork()>,
5aabfad6 408C<dump()>, C<chown()>, C<link()>, C<symlink()>, C<chroot()>,
68dc0745 409C<setpgrp()>, C<getpgrp()>, C<setpriority()>, C<getpriority()>,
3e3baf6d 410C<syscall()>, C<fcntl()>. This list is possibly very incomplete.
68dc0745
PP
411
412=item *
413
6890e559
GS
414crypt() is not available due to silly export restrictions. It may
415become available when the laws change. Meanwhile, look in CPAN for
416extensions that provide it.
417
418=item *
419
68dc0745
PP
420Various C<socket()> related calls are supported, but they may not
421behave as on Unix platforms.
422
423=item *
424
425The four-argument C<select()> call is only supported on sockets.
426
427=item *
428
5aabfad6
PP
429C<$?> ends up with the exitstatus of the subprocess (this is different
430from Unix, where the exitstatus is actually given by "$? >> 8").
431Failure to spawn() the subprocess is indicated by setting $? to
432"255<<8". This is subject to change.
68dc0745
PP
433
434=item *
435
436Building modules available on CPAN is mostly supported, but this
437hasn't been tested much yet. Expect strange problems, and be
438prepared to deal with the consequences.
439
440=item *
441
442C<utime()>, C<times()> and process-related functions may not
443behave as described in the documentation, and some of the
444returned values or effects may be bogus.
445
446=item *
447
3e3baf6d
TB
448Signal handling may not behave as on Unix platforms (where it
449doesn't exactly "behave", either :).
68dc0745
PP
450
451=item *
452
7bac28a0 453File globbing may not behave as on Unix platforms. In particular,
3e3baf6d
TB
454if you don't use perlglob.bat for globbing, it will understand
455wildcards only in the filename component (and not in the pathname).
456In other words, something like "print <*/*.pl>" will not print all the
457perl scripts in all the subdirectories one level under the current one
458(like it does on UNIX platforms). perlglob.exe is also dependent on
459the particular implementation of wildcard expansion in the vendor
460libraries used to build it (which varies wildly at the present time).
461Using perlglob.bat (or File::DosGlob) avoids these limitations, but
462still only provides DOS semantics (read "warts") for globbing.
68dc0745
PP
463
464=back
465
466Please send detailed descriptions of any problems and solutions that
467you may find to <F<perlbug@perl.com>>, along with the output produced
468by C<perl -V>.
469
470=head1 AUTHORS
471
472=over 4
473
3e3baf6d 474Gary Ng E<lt>71564.1743@CompuServe.COME<gt>
68dc0745 475
3e3baf6d 476Gurusamy Sarathy E<lt>gsar@umich.eduE<gt>
68dc0745 477
3e3baf6d 478Nick Ing-Simmons E<lt>nick@ni-s.u-net.comE<gt>
68dc0745
PP
479
480=back
481
482=head1 SEE ALSO
483
484L<perl>
485
486=head1 HISTORY
487
488This port was originally contributed by Gary Ng around 5.003_24,
489and borrowed from the Hip Communications port that was available
490at the time.
491
492Nick Ing-Simmons and Gurusamy Sarathy have made numerous and
493sundry hacks since then.
494
3e3baf6d
TB
495Borland support was added in 5.004_01 (Gurusamy Sarathy).
496
6890e559 497Last updated: 15 June 1997
68dc0745
PP
498
499=cut
3e3baf6d 500