README.win32

   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
   7 perlwin32 - Perl under Win32
   8
   9 =head1 SYNOPSIS
  10
  11 These are instructions for building Perl under WindowsNT (versions
  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).
  18
  19 =head1 DESCRIPTION
  20
  21 Before you start, you should glance through the README file
  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
  26 Also make sure you read the L<BUGS AND CAVEATS> section below for the
  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
  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.
  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
  59 compatible with that shell.  You are mostly on your own if you can
  60 muster the temerity to attempt this with Windows95.
  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
  81 =head2 Building and Installation
  82
  83 =over 4
  84
  85 =item *
  86
  87 The "win32" directory contains *.mak files for use with the NMAKE that
  88 comes with Visual C++ ver. 4.0 and above.  If you wish to build perl
  89 using Visual C++ versions between 2.0 and 4.0, do the following two
  90 additional steps (these steps are not required if you are
  91 using Visual C++ versions 4.0 and above):
  92
  93 =over 8
  94
  95 =item 1.
  96
  97 Overwrite the *.mak files in the win32 subdirectory with the versions
  98 in the win32\VC-2.0 directory.
  99
 100 =item 2.
 101
 102 Reset your INCLUDE environment variable to the MSVC include directory.
 103 For example:
 104
 105         set INCLUDE=E:\MSVC20\INCLUDE
 106
 107 This must have only one directory (a list of directories will not work).
 108 VCVARS32.BAT may put multiple locations in there, which is why this step
 109 is required.
 110
 111 =back
 112
 113 =item *
 114
 115 Make sure you are in the "win32" subdirectory under the perl toplevel.
 116
 117 =item *
 118
 119 Type "nmake" while in the "win32" subdirectory.  This should build
 120 everything.  Specifically, it will create perl.exe, perl.dll, and
 121 perlglob.exe at the perl toplevel, and various other extension dll's
 122 under the lib\auto directory.  If the make fails for any reason, make
 123 sure you have done the previous steps correctly.
 124
 125 =item *
 126
 127 Type "nmake install".  This will put the newly built perl and the
 128 libraries under C:\PERL.  If you want to alter this location, to say,
 129 D:\FOO\PERL, you will have to say:
 130
 131         nmake install INST_TOP=D:\FOO\PERL
 132
 133 instead.  To use the Perl you just installed, make sure you set your
 134 PATH environment variable to C:\PERL\BIN (or D:\FOO\PERL\BIN).
 135
 136 =back
 137
 138 =head2 Testing
 139
 140 Type "nmake test".  This will run most of the tests from the
 141 testsuite (many tests will be skipped, and but no test should fail).
 142
 143 If some tests do fail, it may be because you are using a different command
 144 shell than the native "cmd.exe".  To get a more detailed breakdown of the
 145 tests that failed, you may want to say:
 146
 147        cd ..\t
 148        .\perl harness
 149
 150 Please report any failures as described under L<BUGS AND CAVEATS>.
 151
 152 =head1 BUGS AND CAVEATS
 153
 154 This is still very much an experimental port, and should be considered
 155 alpha quality software.  You can expect changes in virtually all of
 156 these areas: build process, installation structure, supported
 157 utilities/modules, and supported perl functionality.  Specifically,
 158 functionality specific to the Win32 environment may ultimately
 159 be supported as either core modules or extensions.
 160
 161 If you have had prior exposure to Perl on Unix platforms, you will notice
 162 this port exhibits behavior different from what is documented.  Most of the
 163 differences fall under one of these categories.
 164
 165 =over 8
 166
 167 =item *
 168
 169 C<stat()> and C<lstat()> functions may not behave as documented.  They
 170 may return values that bear no resemblance to those reported on Unix
 171 platforms, and some fields may be completely bogus.
 172
 173 =item *
 174
 175 The following functions are currently unavailable: C<fork()>, C<exec()>,
 176 C<dump()>, C<chown()>, C<link()>, C<symlink()>, C<chroot()>,
 177 C<setpgrp()>, C<getpgrp()>, C<setpriority()>, C<getpriority()>,
 178 C<syscall()>, C<fcntl()>, C<flock()>.  This list is possibly very
 179 incomplete.
 180
 181 =item *
 182
 183 Various C<socket()> related calls are supported, but they may not
 184 behave as on Unix platforms.
 185
 186 =item *
 187
 188 The four-argument C<select()> call is only supported on sockets.
 189
 190 =item *
 191
 192 The behavior of C<system()> or the C<qx[]> operator (a.k.a. "backticks"),
 193 when used to call interactive commands, is ill-defined.
 194
 195 =item *
 196
 197 C<$?> ends up with the exitstatus of the subprocess (this is different
 198 from Unix, where the exitstatus is actually given by "$? >> 8").
 199 Failure to spawn() the subprocess is indicated by setting $? to
 200 "255<<8".  This is subject to change.
 201
 202 =item *
 203
 204 Building modules available on CPAN is mostly supported, but this
 205 hasn't been tested much yet.  Expect strange problems, and be
 206 prepared to deal with the consequences.
 207
 208 =item *
 209
 210 C<utime()>, C<times()> and process-related functions may not
 211 behave as described in the documentation, and some of the
 212 returned values or effects may be bogus.
 213
 214 =item *
 215
 216 Signal handling may not behave as on Unix platforms.
 217
 218 =item *
 219
 220 File globbing may not behave as on Unix platforms.
 221
 222 =item *
 223
 224 Not all of the utilities that come with the Perl distribution
 225 are supported yet.
 226
 227 =back
 228
 229 Please send detailed descriptions of any problems and solutions that
 230 you may find to <F<perlbug@perl.com>>, along with the output produced
 231 by C<perl -V>.
 232
 233 =head1 AUTHORS
 234
 235 =over 4
 236
 237 =item Gary Ng <F<71564.1743@CompuServe.COM>>
 238
 239 =item Gurusamy Sarathy <F<gsar@umich.edu>>
 240
 241 =item Nick Ing-Simmons <F<nick@ni-s.u-net.com>>
 242
 243 =back
 244
 245 =head1 SEE ALSO
 246
 247 L<perl>
 248
 249 =head1 HISTORY
 250
 251 This port was originally contributed by Gary Ng around 5.003_24,
 252 and borrowed from the Hip Communications port that was available
 253 at the time.
 254
 255 Nick Ing-Simmons and Gurusamy Sarathy have made numerous and
 256 sundry hacks since then.
 257
 258 Last updated: 05 April 1997
 259
 260 =cut