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 found
  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 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 three
  80 additional steps (these three 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.  (The only difference in those makefiles
  89 is in how the $(INCLUDE) variable is handled--VC 2.0 NMAKE does not
  90 grok a path list in $(INCLUDE)).
  91
  92 =item 2.
  93
  94 Reset your INCLUDE environment variable to the MSVC include directory.
  95 For example:
  96
  97         set INCLUDE=E:\MSVC20\INCLUDE
  98
  99 This must have only one directory (a list of directories will not work).
 100 VCVARS32.BAT may put multiple locations in there, which is why this step
 101 is required.
 102
 103 =item 3.
 104
 105 Apply the patch found in win32\VC-2.0\vc2.patch, like so:
 106
 107         cd win32
 108         patch -p2 -N < VC-2.0\vc2.patch
 109
 110 You may have to edit win32\win32.c manually if you don't have GNU patch.
 111
 112 =back
 113
 114 =item *
 115
 116 Make sure you are in the "win32" subdirectory under the perl toplevel.
 117
 118 =item *
 119
 120 Type "nmake" while in the "win32" subdirectory.  This should build
 121 everything.  Specifically, it will create perl.exe, perl.dll, and
 122 perlglob.exe at the perl toplevel, and various other extension dll's
 123 under the lib\auto directory.  If the make fails for any reason, make
 124 sure you have done the previous steps correctly.
 125
 126 =item *
 127
 128 Type "nmake install".  This will put the newly built perl and the
 129 libraries under C:\PERL.  If you want to alter this location, to say,
 130 D:\FOO\PERL, you will have to say:
 131
 132         nmake install INST_TOP=D:\FOO\PERL
 133
 134 instead.  To use the Perl you just installed, make sure you set your
 135 PATH environment variable to C:\PERL\BIN (or D:\FOO\PERL\BIN).
 136
 137 =back
 138
 139 =head2 Testing
 140
 141 Type "nmake test".  This will run most of the tests from the
 142 testsuite (many tests will be skipped, and some tests will fail).
 143 Most failures are due to UNIXisms in the standard perl testsuite.
 144
 145 To get a more detailed breakdown of the tests that failed, say:
 146
 147        cd ..\t
 148        .\perl harness
 149
 150 This should produce a summary very similar to the following:
 151
 152     Failed Test  Status Wstat Total Fail  Failed  List of failed
 153     ------------------------------------------------------------------------------
 154     io/fs.t                      26   16  61.54%  1-5, 7-11, 16-18, 23-25
 155     io/tell.t                    13    1   7.69%  10
 156     lib/anydbm.t                 12    1   8.33%  2
 157     lib/findbin.t                 1    1 100.00%  1
 158     lib/sdbm.t                   12    1   8.33%  2
 159     op/mkdir.t                    7    2  28.57%  3, 7
 160     op/runlevel.t                 8    1  12.50%  4
 161     op/stat.t                    56    3   5.36%  3-4, 20
 162     op/taint.t                   98   20  20.41%  1-6, 14, 16, 19-21, 24, 26, 35-3
 163     pragma/locale.t              98   40  40.82%  1, 13-14, 21-27, 33, 39, 45-53,
 164     Failed 10/149 test scripts, 93.29% okay. 86/3506 subtests failed, 97.55% okay.
 165
 166 Check if any additional tests other than the ones shown here
 167 failed.  The standard testsuite will ultimately be modified so
 168 that the testsuite avoids running irrelevant tests on Win32.
 169
 170 =head1 BUGS AND CAVEATS
 171
 172 This is still very much an experimental port, and should be considered
 173 alpha quality software.  You can expect changes in virtually all of
 174 these areas: build process, installation structure, supported
 175 utilities/modules, and supported perl functionality.  Specifically,
 176 functionality that supports the Win32 environment may be ultimately
 177 be supported as either core modules or extensions.
 178
 179 Many tests from the standard testsuite either fail or produce different
 180 results under this port.  Most of the problems fall under one of these
 181 categories
 182
 183 =over 8
 184
 185 =item *
 186
 187 C<stat()> and C<lstat()> functions may not behave as documented.  They
 188 may return values that bear no resemblance to those reported on Unix
 189 platforms, and some fields may be completely bogus.
 190
 191 =item *
 192
 193 The following functions are currently unavailable: C<fork()>, C<exec()>,
 194 C<dump()>, C<kill()>, C<chown()>, C<link()>, C<symlink()>, C<chroot()>,
 195 C<setpgrp()>, C<getpgrp()>, C<setpriority()>, C<getpriority()>,
 196 C<syscall()>, C<fcntl()>, C<flock()>.  This list is possibly incomplete.
 197
 198 =item *
 199
 200 Various C<socket()> related calls are supported, but they may not
 201 behave as on Unix platforms.
 202
 203 =item *
 204
 205 The four-argument C<select()> call is only supported on sockets.
 206
 207 =item *
 208
 209 The behavior of C<system()> or the C<qx[]> operator (a.k.a. "backticks"),
 210 when used to call interactive commands, is ill-defined.
 211
 212 =item *
 213
 214 C<$!> doesn't work reliably yet.
 215
 216 =item *
 217
 218 Building modules available on CPAN is mostly supported, but this
 219 hasn't been tested much yet.  Expect strange problems, and be
 220 prepared to deal with the consequences.
 221
 222 =item *
 223
 224 C<utime()>, C<times()> and process-related functions may not
 225 behave as described in the documentation, and some of the
 226 returned values or effects may be bogus.
 227
 228 =item *
 229
 230 Signal handling may not behave as on Unix platforms.
 231
 232 =item *
 233
 234 File globbing may not behave as on Unix platforms.
 235
 236 =item *
 237
 238 Not all of the utilities that come with the Perl distribution
 239 are supported yet.
 240
 241 =back
 242
 243 Please send detailed descriptions of any problems and solutions that
 244 you may find to <F<perlbug@perl.com>>, along with the output produced
 245 by C<perl -V>.
 246
 247 =head1 AUTHORS
 248
 249 =over 4
 250
 251 =item Gary Ng <F<71564.1743@CompuServe.COM>>
 252
 253 =item Gurusamy Sarathy <F<gsar@umich.edu>>
 254
 255 =item Nick Ing-Simmons <F<nick@ni-s.u-net.com>>
 256
 257 =back
 258
 259 =head1 SEE ALSO
 260
 261 L<perl>
 262
 263 =head1 HISTORY
 264
 265 This port was originally contributed by Gary Ng around 5.003_24,
 266 and borrowed from the Hip Communications port that was available
 267 at the time.
 268
 269 Nick Ing-Simmons and Gurusamy Sarathy have made numerous and
 270 sundry hacks since then.
 271
 272 Last updated: 19 March 1997
 273
 274 =cut
 275