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 WindowsNT [XXX and perhaps under Windows95]
   8
   9 =head1 SYNOPSIS
  10
  11 These are instructions for building Perl under WindowsNT (versions
  12 3.51 or 4.0), using Visual C++.
  13
  14 =head1 DESCRIPTION
  15
  16 Before you start, you should glance through the README file
  17 found in the top-level directory where the Perl distribution
  18 was extracted.  Make sure you read and understand the terms under
  19 which this software is being distributed.
  20
  21 Also make sure you read the L<BUGS AND CAVEATS> section below for the
  22 known limitations of this port.
  23
  24 The INSTALL file in the perl top-level has much information that is
  25 only relevant to people building Perl on Unix-like systems.  In
  26 particular, you can safely ignore any information that talks about
  27 "Configure".
  28
  29 You should probably also read the README.os2 file, which gives a
  30 different set of rules to build a Perl that will work on Win32
  31 platforms.  That method will probably enable you to build a more
  32 Unix-compatible perl, but you will also need to download and use
  33 various other support software described in that file.
  34
  35 This set of instructions is meant to describe a so-called "native"
  36 port of Perl to Win32 platforms.  The resulting Perl requires no
  37 additional software to run (other than what came with your operating
  38 system).  Currently, this port is only capable of using Microsoft's
  39 Visual C++ compiler.  The ultimate goal is to support the other major
  40 compilers that can be used on the platforms.
  41
  42 =head2 Setting Up
  43
  44 =over 4
  45
  46 =item *
  47
  48 Use the default "cmd" shell that comes with NT.  In particular, do
  49 *not* use the 4DOS/NT shell.  The Makefile has commands that are not
  50 compatible with that shell.
  51
  52 =item *
  53
  54 Run the VCVARS32.BAT file usually found somewhere like C:\MSDEV4.2\BIN.
  55 This will set your build environment.
  56
  57 =item *
  58
  59 Depending on how you extracted the distribution, you have to make sure
  60 all the files are writable by you.  The easiest way to make sure of
  61 this is to execute:
  62
  63         attrib -R *.* /S
  64
  65 from the perl toplevel directory.  You don't I<have> to do this if you
  66 used the right tools to extract the files in the standard distribution,
  67 but it doesn't hurt to do so.
  68
  69 =back
  70
  71 =head2 Building and Installation
  72
  73 =over 4
  74
  75 =item *
  76
  77 The "win32" directory contains *.mak files for use with the NMAKE that
  78 comes with Visual C++ ver. 4.0 and above.  If you wish to build perl
  79 using Visual C++ versions between 2.0 and 4.0, do the following two
  80 additional steps (these steps are not required if you are
  81 using Visual C++ versions 4.0 and above):
  82
  83 =over 8
  84
  85 =item 1.
  86
  87 Overwrite the *.mak files in the win32 subdirectory with the versions
  88 in the win32\VC-2.0 directory.
  89
  90 =item 2.
  91
  92 Reset your INCLUDE environment variable to the MSVC include directory.
  93 For example:
  94
  95         set INCLUDE=E:\MSVC20\INCLUDE
  96
  97 This must have only one directory (a list of directories will not work).
  98 VCVARS32.BAT may put multiple locations in there, which is why this step
  99 is required.
 100
 101 =back
 102
 103 =item *
 104
 105 Make sure you are in the "win32" subdirectory under the perl toplevel.
 106
 107 =item *
 108
 109 Type "nmake" while in the "win32" subdirectory.  This should build
 110 everything.  Specifically, it will create perl.exe, perl.dll, and
 111 perlglob.exe at the perl toplevel, and various other extension dll's
 112 under the lib\auto directory.  If the make fails for any reason, make
 113 sure you have done the previous steps correctly.
 114
 115 =item *
 116
 117 Type "nmake install".  This will put the newly built perl and the
 118 libraries under C:\PERL.  If you want to alter this location, to say,
 119 D:\FOO\PERL, you will have to say:
 120
 121         nmake install INST_TOP=D:\FOO\PERL
 122
 123 instead.  To use the Perl you just installed, make sure you set your
 124 PATH environment variable to C:\PERL\BIN (or D:\FOO\PERL\BIN).
 125
 126 =back
 127
 128 =head2 Testing
 129
 130 Type "nmake test".  This will run most of the tests from the
 131 testsuite (many tests will be skipped, and some tests will fail).
 132 Most failures are due to UNIXisms in the standard perl testsuite.
 133
 134 To get a more detailed breakdown of the tests that failed, say:
 135
 136        cd ..\t
 137        .\perl harness
 138
 139 This should produce a summary very similar to the following:
 140
 141     Failed Test  Status Wstat Total Fail  Failed  List of failed
 142     ------------------------------------------------------------------------------
 143     io/fs.t                      26   16  61.54%  1-5, 7-11, 16-18, 23-25
 144     lib/anydbm.t                 12    1   8.33%  2
 145     lib/findbin.t                 1    1 100.00%  1
 146     lib/sdbm.t                   12    1   8.33%  2
 147     op/magic.t                   28    1   3.57%  16
 148     op/mkdir.t                    7    2  28.57%  3, 7
 149     op/runlevel.t                 8    1  12.50%  4
 150     op/stat.t                    56    3   5.36%  2-3, 20
 151     op/taint.t                   98   20  20.41%  1-6, 14, 16, 19-21, 24, 26, 35-3
 152     pragma/locale.t              98   40  40.82%  1, 13-14, 21-27, 33, 39, 45-53,
 153     Failed 10/149 test scripts, 93.29% okay. 86/3871 subtests failed, 97.78% okay.
 154
 155
 156 Check if any additional tests other than the ones shown here
 157 failed.  The standard testsuite will ultimately be modified so
 158 that the testsuite avoids running irrelevant tests on Win32.
 159
 160 =head1 BUGS AND CAVEATS
 161
 162 This is still very much an experimental port, and should be considered
 163 alpha quality software.  You can expect changes in virtually all of
 164 these areas: build process, installation structure, supported
 165 utilities/modules, and supported perl functionality.  Specifically,
 166 functionality that supports the Win32 environment may ultimately
 167 be supported as either core modules or extensions.
 168
 169 Many tests from the standard testsuite either fail or produce different
 170 results under this port.  Most of the problems fall under one of these
 171 categories
 172
 173 =over 8
 174
 175 =item *
 176
 177 C<stat()> and C<lstat()> functions may not behave as documented.  They
 178 may return values that bear no resemblance to those reported on Unix
 179 platforms, and some fields may be completely bogus.
 180
 181 =item *
 182
 183 The following functions are currently unavailable: C<fork()>, C<exec()>,
 184 C<dump()>, C<kill()>, C<chown()>, C<link()>, C<symlink()>, C<chroot()>,
 185 C<setpgrp()>, C<getpgrp()>, C<setpriority()>, C<getpriority()>,
 186 C<syscall()>, C<fcntl()>, C<flock()>.  This list is possibly incomplete.
 187
 188 =item *
 189
 190 Various C<socket()> related calls are supported, but they may not
 191 behave as on Unix platforms.
 192
 193 =item *
 194
 195 The four-argument C<select()> call is only supported on sockets.
 196
 197 =item *
 198
 199 The behavior of C<system()> or the C<qx[]> operator (a.k.a. "backticks"),
 200 when used to call interactive commands, is ill-defined.
 201
 202 =item *
 203
 204 C<$!> doesn't work reliably yet.
 205
 206 =item *
 207
 208 Building modules available on CPAN is mostly supported, but this
 209 hasn't been tested much yet.  Expect strange problems, and be
 210 prepared to deal with the consequences.
 211
 212 =item *
 213
 214 C<utime()>, C<times()> and process-related functions may not
 215 behave as described in the documentation, and some of the
 216 returned values or effects may be bogus.
 217
 218 =item *
 219
 220 Signal handling may not behave as on Unix platforms.
 221
 222 =item *
 223
 224 File globbing may not behave as on Unix platforms.
 225
 226 =item *
 227
 228 Not all of the utilities that come with the Perl distribution
 229 are supported yet.
 230
 231 =back
 232
 233 Please send detailed descriptions of any problems and solutions that
 234 you may find to <F<perlbug@perl.com>>, along with the output produced
 235 by C<perl -V>.
 236
 237 =head1 AUTHORS
 238
 239 =over 4
 240
 241 =item Gary Ng <F<71564.1743@CompuServe.COM>>
 242
 243 =item Gurusamy Sarathy <F<gsar@umich.edu>>
 244
 245 =item Nick Ing-Simmons <F<nick@ni-s.u-net.com>>
 246
 247 =back
 248
 249 =head1 SEE ALSO
 250
 251 L<perl>
 252
 253 =head1 HISTORY
 254
 255 This port was originally contributed by Gary Ng around 5.003_24,
 256 and borrowed from the Hip Communications port that was available
 257 at the time.
 258
 259 Nick Ing-Simmons and Gurusamy Sarathy have made numerous and
 260 sundry hacks since then.
 261
 262 Last updated: 19 March 1997
 263
 264 =cut
 265