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