revise README.win32 for currentness, point to function

list in perlport.pod (from a patch suggested by Dominic Dunlop)

p4raw-id: //depot/perl@5731

1 files changed, 79 insertions, 192 deletions

diff --git a/README.win32 b/README.win32
index b39961b625..bca4921c2f 100644
--- a/README.win32
+++ b/README.win32
@@ -8,13 +8,8 @@ perlwin32 - Perl under Win32
 
 =head1 SYNOPSIS
 
-These are instructions for building Perl under Windows NT (versions
-3.51 or 4.0).  Currently, this port is reported to build under
-Windows95 using the 4DOS shell--the default shell that infests
-Windows95 may not work fully (but see below).  Note that this caveat
-is only about B<building> perl.  Once built, you should be able to
-B<use> it on either Win32 platform (modulo the problems arising from
-the inferior command shell).
+These are instructions for building Perl under Windows (9x, NT and
+2000).
 
 =head1 DESCRIPTION
 
@@ -62,19 +57,37 @@ See L<Usage Hints> below for general hints about this.
 
 =over 4
 
+=item Make
+
+You need a "make" program to build the sources.  If you are using
+Visual C++ under Windows NT or 2000, nmake will work.  All other
+builds need dmake.
+
+dmake is a freely available make that has very nice macro features
+and parallelability.
+
+A port of dmake for Windows is available from:
+
+    http://www.cpan.org/authors/id/GSAR/dmake-4.1pl1-win32.zip
+
+(This is a fixed version of original dmake sources obtained from
+http://www.wticorp.com/dmake/.  As of version 4.1PL1, the original
+sources did not build as shipped, and had various other problems.
+A patch is included in the above fixed version.)
+
+Fetch and install dmake somewhere on your path (follow the instructions
+in the README.NOW file).
+
 =item Command Shell
 
 Use the default "cmd" shell that comes with NT.  Some versions of the
 popular 4DOS/NT shell have incompatibilities that may cause you trouble.
 If the build fails under that shell, try building again with the cmd
-shell.  The nmake Makefile also has known incompatibilites with the
-"command.com" shell that comes with Windows95.
+shell.
 
-However, there have been reports of successful build attempts using
-4DOS/NT version 6.01 under Windows95, using dmake, but your mileage
-may vary.  There is also some basic support for building using dmake
-under command.com.  Nevertheless, if building under command.com
-doesn't work, try 4DOS/NT.
+The nmake Makefile also has known incompatibilites with the
+"command.com" shell that comes with Windows 9x.  You will need to
+use dmake and makefile.mk to build under Windows 9x.
 
 The surest way to build it is on Windows NT, using the cmd shell.
 
@@ -83,22 +96,11 @@ build usually works in this circumstance, but some tests will fail.
 
 =item Borland C++
 
-If you are using the Borland compiler, you will need dmake, a freely
-available make that has very nice macro features and parallelability.
+If you are using the Borland compiler, you will need dmake.
 (The make that Borland supplies is seriously crippled, and will not
 work for MakeMaker builds.)
 
-A port of dmake for win32 platforms is available from:
-
-    http://cpan.perl.org/authors/id/GSAR/dmake-4.1pl1-win32.zip
-
-(This is a fixed version of original dmake sources obtained from
-http://www.wticorp.com/dmake/.  As of version 4.1PL1, the original
-sources did not build as shipped, and had various other problems.
-A patch is included in the above fixed version.)
-
-Fetch and install dmake somewhere on your path (follow the instructions
-in the README.NOW file).
+See L/"Make"> above.
 
 =item Microsoft Visual C++
 
@@ -125,7 +127,7 @@ Make sure you install the binaries that work with MSVCRT.DLL as indicated
 in the README for the GCC bundle.  You may need to set up a few environment
 variables (usually run from a batch file).
 
-You also need dmake.  See L</"Borland C++"> above on how to get it.
+You also need dmake.  See L</"Make"> above on how to get it.
 
 =back
 
@@ -139,39 +141,20 @@ Make sure you are in the "win32" subdirectory under the perl toplevel.
 This directory contains a "Makefile" that will work with
 versions of nmake that come with Visual C++, and a dmake "makefile.mk"
 that will work for all supported compilers.  The defaults in the dmake
-makefile are setup to build using the Borland compiler.
+makefile are setup to build using the GCC compiler.
 
 =item *
 
 Edit the makefile.mk (or Makefile, if using nmake) and change the values
 of INST_DRV and INST_TOP.   You can also enable various build
-flags.
-
-Beginning with version 5.005, there is experimental support for building
-a perl interpreter that supports the Perl Object abstraction (courtesy
-ActiveState Tool Corp.)  PERL_OBJECT uses C++, and the binaries are
-therefore incompatible with the regular C build.  However, the
-PERL_OBJECT build does provide something called the C-API, for linking
-it with extensions that won't compile under PERL_OBJECT. Using the C_API
-is typically requested through:
-
-    perl Makefile.PL CAPI=TRUE
-
-PERL_OBJECT requires VC++ 5.0 (Service Pack 3 recommended) or later. It
-is not yet supported under GCC.  WARNING:  Binaries built with
-PERL_OBJECT enabled are B<not> compatible with binaries built without.
-Perl installs PERL_OBJECT binaries under a distinct architecture name,
-so they B<can> coexist, though.
-
-Beginning with version 5.005, there is experimental support for building
-a perl interpreter that is capable of native threading.  Binaries built
-with thread support enabled are also incompatible with the vanilla C
-build.  WARNING:  Binaries built with threads enabled are B<not> compatible
-with binaries built without.  Perl installs threads enabled binaries under
-a distinct architecture name, so they B<can> coexist, though.
-
-At the present time, you cannot enable both threading and PERL_OBJECT.
-You can get only one of them in a Perl interpreter.
+flags.  These are explained in the makefiles.
+
+You will have to make sure CCTYPE is set correctly, and CCHOME points
+to wherever you installed your compiler.
+
+The default value for CCHOME in the makefiles for Visual C++
+may not be correct for some versions.  Make sure the default exists
+and is valid.
 
 If you have either the source or a library that contains des_fcrypt(),
 enable the appropriate option in the makefile.  des_fcrypt() is not
@@ -192,35 +175,24 @@ in des_fcrypt.patch.
 Perl will also build without des_fcrypt(), but the crypt() builtin will
 fail at run time.
 
-You will also have to make sure CCHOME points to wherever you installed
-your compiler.
-
-The default value for CCHOME in the makefiles for Visual C++
-may not be correct for some versions.  Make sure the default exists
-and is valid.
-
-Other options are explained in the makefiles.  Be sure to read the
-instructions carefully.
+Be sure to read the instructions near the top of the makefiles carefully.
 
 =item *
 
 Type "dmake" (or "nmake" if you are using that make).
 
 This should build everything.  Specifically, it will create perl.exe,
-perl.dll (or perl56.dll), and perlglob.exe at the perl toplevel, and
-various other extension dll's under the lib\auto directory.  If the build
-fails for any reason, make sure you have done the previous steps correctly.
-
-The build process may produce "harmless" compiler warnings (more or
-less copiously, depending on how picky your compiler gets).  The
-maintainers are aware of these warnings, thankyouverymuch. :)
+perl56.dll at the perl toplevel, and various other extension dll's
+under the lib\auto directory.  If the build fails for any reason, make
+sure you have done the previous steps correctly.
 
 =back
 
 =head2 Testing
 
 Type "dmake test" (or "nmake test").  This will run most of the tests from
-the testsuite (many tests will be skipped, and but no test should fail).
+the testsuite (many tests will be skipped, but no tests should typically
+fail).
 
 If some tests do fail, it may be because you are using a different command
 shell than the native "cmd.exe", or because you are building from a path
@@ -248,8 +220,13 @@ you will need to add two components to your PATH environment variable,
 C<$INST_TOP\$VERSION\bin>, and C<$INST_TOP\$VERSION\bin\$ARCHNAME>.
 For example:
 
-    set PATH c:\perl\5.005\bin;c:\perl\5.005\bin\MSWin32-x86;%PATH%
+    set PATH c:\perl\5.6.0\bin;c:\perl\5.6.0\bin\MSWin32-x86;%PATH%
 
+If you opt to comment out INST_VER and INST_ARCH in the makefiles, the
+installation structure is much simpler.  In that case, it will be
+sufficient to add a single entry to the path, for instance:
+
+    set PATH c:\perl\bin;%PATH%
 
 =head2 Usage Hints
 
@@ -289,32 +266,19 @@ separated with semicolons, as usual on win32.
 
 =item File Globbing
 
-By default, perl spawns an external program to do file globbing.
-The install process installs both a perlglob.exe and a perlglob.bat
-that perl can use for this purpose.  Note that with the default
-installation, perlglob.exe will be found by the system before
-perlglob.bat.
-
-perlglob.exe relies on the argv expansion done by the C Runtime of
-the particular compiler you used, and therefore behaves very
-differently depending on the Runtime used to build it.  To preserve
-compatiblity, perlglob.bat (a perl script that can be used portably)
-is installed.  Besides being portable, perlglob.bat also offers
-enhanced globbing functionality.
-
-If you want perl to use perlglob.bat instead of perlglob.exe, just
-delete perlglob.exe from the install location (or move it somewhere
-perl cannot find).  Using File::DosGlob.pm (which implements the core
-functionality of perlglob.bat) to override the internal CORE::glob()
-works about 10 times faster than spawing perlglob.exe, and you should
-take this approach when writing new modules.  See File::DosGlob for
+By default, perl handles file globbing using the File::Glob extension,
+which provides portable globbing.
+
+If you want perl to use globbing that emulates the quirks of DOS
+filename conventions, you might want to consider using File::DosGlob
+to override the internal glob() implementation.  See L<File::DosGlob> for
 details.
 
 =item Using perl from the command line
 
 If you are accustomed to using perl from various command-line
 shells found in UNIX environments, you will be less than pleased
-with what Windows NT offers by way of a command shell.
+with what Windows offers by way of a command shell.
 
 The crucial thing to understand about the "cmd" shell (which is
 the default on Windows NT) is that it does not do any wildcard
@@ -375,14 +339,19 @@ This pipes "foo" to the pager and writes "bar" in the file "blurch":
     perl -e "print 'foo'; print STDERR 'bar'" 2> blurch | less
 
 
-Discovering the usefulness of the "command.com" shell on Windows95
+Discovering the usefulness of the "command.com" shell on Windows 9x
 is left as an exercise to the reader :)
 
 =item Building Extensions
 
 The Comprehensive Perl Archive Network (CPAN) offers a wealth
 of extensions, some of which require a C compiler to build.
-Look in http://www.perl.com/ for more information on CPAN.
+Look in http://www.cpan.org/ for more information on CPAN.
+
+Note that not all of the extensions available from CPAN may work
+in the Win32 environment; you should check the information at
+http://testers.cpan.org/ before investing too much effort into
+porting modules that don't readily build.
 
 Most extensions (whether they require a C compiler or not) can
 be built, tested and installed with the standard mantra:
@@ -407,9 +376,9 @@ old version of nmake reportedly available from:
 Another option is to use the make written in Perl, available from
 CPAN:
 
-    http://www.perl.com/CPAN/authors/id/NI-S/Make-0.03.tar.gz
+    http://www.cpan.org/authors/id/NI-S/Make-0.03.tar.gz
 
-You may also use dmake.  See L</"Borland C++"> above on how to get it.
+You may also use dmake.  See L</"Make"> above on how to get it.
 
 Note that MakeMaker actually emits makefiles with different syntax
 depending on what 'make' it thinks you are using.  Therefore, it is
@@ -502,7 +471,7 @@ all of the ActiveState extensions and most other Win32 extensions from
 CPAN in source form, along with many added bugfixes, and with MakeMaker
 support.  This bundle is available at:
 
-   http://www.perl.com/CPAN/authors/id/GSAR/libwin32-0.14.zip
+   http://www.cpan.org/authors/id/GSAR/libwin32-0.151.zip
 
 See the README in that distribution for building and installation
 instructions.  Look for later versions that may be available at the
@@ -599,75 +568,18 @@ find a mailer on your system).
 
 =head1 BUGS AND CAVEATS
 
-An effort has been made to ensure that the DLLs produced by the two
-supported compilers are compatible with each other (despite the
-best efforts of the compiler vendors).  Extension binaries produced
-by one compiler should also coexist with a perl binary built by
-a different compiler.  In order to accomplish this, PERL.DLL provides
-a layer of runtime code that uses the C Runtime that perl was compiled
-with.  Extensions which include "perl.h" will transparently access
-the functions in this layer, thereby ensuring that both perl and
-extensions use the same runtime functions.
-
-If you have had prior exposure to Perl on Unix platforms, you will notice
-this port exhibits behavior different from what is documented.  Most of the
-differences fall under one of these categories.  We do not consider
-any of them to be serious limitations (especially when compared to the
-limited nature of some of the Win32 OSes themselves :)
-
-=over 8
-
-=item *
-
-C<stat()> and C<lstat()> functions may not behave as documented.  They
-may return values that bear no resemblance to those reported on Unix
-platforms, and some fields (like the the one for inode) may be completely
-bogus.
-
-=item *
-
-The following functions are currently unavailable: C<fork()>,
-C<dump()>, C<chown()>, C<link()>, C<symlink()>, C<chroot()>,
-C<setpgrp()> and related security functions, C<setpriority()>,
-C<getpriority()>, C<syscall()>, C<fcntl()>, C<getpw*()>,
-C<msg*()>, C<shm*()>, C<sem*()>, C<alarm()>, C<socketpair()>,
-C<*netent()>, C<*protoent()>, C<*servent()>, C<*hostent()>,
-C<getnetby*()>.
-This list is possibly incomplete.
+Some of the built-in functions do not act exactly as documented in
+L<perlfunc>, and a few are not implemented at all.  To avoid
+surprises, particularly if you have had prior exposure to Perl
+in other operating environments or if you intend to write code
+that will be portable to other environments, see L<perlport>
+for a reasonably definitive list of these differences.
 
-=item *
-
-Various C<socket()> related calls are supported, but they may not
-behave as on Unix platforms.
-
-=item *
-
-The four-argument C<select()> call is only supported on sockets.
+Not all extensions available from CPAN may build or work properly
+in the Win32 environment.  See L</"Building Extensions">.
 
-=item *
-
-The C<ioctl()> call is only supported on sockets (where it provides the
-functionality of ioctlsocket() in the Winsock API).
-
-=item *
-
-Failure to spawn() a subprocess is indicated by setting $? to "255 << 8".
-C<$?> is set in a way compatible with Unix (i.e. the exitstatus of the
-subprocess is obtained by "$? >> 8", as described in the documentation).
-
-=item *
-
-You can expect problems building modules available on CPAN if you
-build perl itself with -DUSE_THREADS.  These problems should be resolved
-as we get closer to 5.005.
-
-=item *
-
-C<utime()>, C<times()> and process-related functions may not
-behave as described in the documentation, and some of the
-returned values or effects may be bogus.
-
-=item *
+Most C<socket()> related calls are supported, but they may not
+behave as on Unix platforms.  See L<perlport> for the full list.
 
 Signal handling may not behave as on Unix platforms (where it
 doesn't exactly "behave", either :).  For instance, calling C<die()>
@@ -677,31 +589,6 @@ Thus, signals may work only for simple things like setting a flag
 variable in the handler.  Using signals under this port should
 currently be considered unsupported.
 
-=item *
-
-C<kill()> is implemented, but doesn't have the semantics of
-C<raise()>, i.e. it doesn't send a signal to the identified process
-like it does on Unix platforms.  Instead it immediately calls
-C<TerminateProcess(process,signal)>.  Thus the signal argument is
-used to set the exit-status of the terminated process.  However,
-a signal of 0 can be used to safely check if the specified process
-exists, as on Unix.
-
-=item *
-
-File globbing may not behave as on Unix platforms.  In particular,
-if you don't use perlglob.bat for globbing, it will understand
-wildcards only in the filename component (and not in the pathname).
-In other words, something like "print <*/*.pl>" will not print all the
-perl scripts in all the subdirectories one level under the current one
-(like it does on UNIX platforms).  perlglob.exe is also dependent on
-the particular implementation of wildcard expansion in the vendor
-libraries used to build it (which varies wildly at the present time).
-Using perlglob.bat (or File::DosGlob) avoids these limitations, but
-still only provides DOS semantics (read "warts") for globbing.
-
-=back
-
 Please send detailed descriptions of any problems and solutions that 
 you may find to <F<perlbug@perl.com>>, along with the output produced
 by C<perl -V>.
@@ -741,6 +628,6 @@ Support for fork() emulation was added in 5.6 (ActiveState Tool Corp).
 
 Win9x support was added in 5.6 (Benjamin Stuhl).
 
-Last updated: 28 December 1999
+Last updated: 13 March 2000
 
 =cut