This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
revise README.win32 for currentness, point to function
authorGurusamy Sarathy <gsar@cpan.org>
Tue, 14 Mar 2000 17:15:44 +0000 (17:15 +0000)
committerGurusamy Sarathy <gsar@cpan.org>
Tue, 14 Mar 2000 17:15:44 +0000 (17:15 +0000)
list in perlport.pod (from a patch suggested by Dominic Dunlop)

p4raw-id: //depot/perl@5731

README.win32
pod/perlport.pod

index b39961b..bca4921 100644 (file)
@@ -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
index 2a1bc77..e59b385 100644 (file)
@@ -1223,6 +1223,12 @@ suffixes.  C<-S> is meaningless.  (Win32)
 C<-x> (or C<-X>) determine if a file has an executable file type.
 (S<RISC OS>)
 
+=item alarm SECONDS
+
+=item alarm
+
+Not implemented. (Win32)
+
 =item binmode FILEHANDLE
 
 Meaningless.  (S<Mac OS>, S<RISC OS>)
@@ -1444,14 +1450,8 @@ Not implemented. (S<Mac OS>, Plan9)
 Globbing built-in, but only C<*> and C<?> metacharacters are supported.
 (S<Mac OS>)
 
-Features depend on external perlglob.exe or perlglob.bat.  May be
-overridden with something like File::DosGlob, which is recommended.
-(Win32)
-
-Globbing built-in, but only C<*> and C<?> metacharacters are supported.
-Globbing relies on operating system calls, which may return filenames
-in any order.  As most filesystems are case-insensitive, even "sorted"
-filenames will not be in case-sensitive order. (S<RISC OS>)
+This operator is implemented via the File::Glob extension on most
+platforms.  See L<File::Glob> for portability information.
 
 =item ioctl FILEHANDLE,FUNCTION,SCALAR
 
@@ -1467,9 +1467,12 @@ Available only for socket handles. (S<RISC OS>)
 Not implemented, hence not useful for taint checking. (S<Mac OS>,
 S<RISC OS>)
 
-C<kill($sig, $pid)> makes the process exit immediately with exit
-status $sig.  As in Unix, if $sig is 0 and the specified process exists,
-it returns true without actually terminating it. (Win32)
+C<kill()> 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 C<kill($sig, $pid)> terminates the process identified by $pid,
+and makes it exit immediately with exit status $sig.  As in Unix, if
+$sig is 0 and the specified process exists, it returns true without
+actually terminating it. (Win32)
 
 =item link OLDFILE,NEWFILE
 
@@ -1489,7 +1492,7 @@ under NTFS only.
 
 Not implemented. (VMS, S<RISC OS>)
 
-Return values may be bogus. (Win32)
+Return values (especially for device and inode) may be bogus. (Win32)
 
 =item msgctl ID,CMD,ARG
 
@@ -1531,6 +1534,8 @@ Only implemented on sockets. (Win32)
 
 Only reliable on sockets. (S<RISC OS>)
 
+Note that the C<socket FILEHANDLE> form is generally portable.
+
 =item semctl ID,SEMNUM,CMD,ARG
 
 =item semget KEY,NSEMS,FLAGS
@@ -1612,7 +1617,10 @@ As an optimization, may not call the command shell specified in
 C<$ENV{PERL5SHELL}>.  C<system(1, @args)> spawns an external
 process and immediately returns its process designator, without
 waiting for it to terminate.  Return value may be used subsequently
-in C<wait> or C<waitpid>.  (Win32)
+in C<wait> or C<waitpid>.  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).  (Win32)
 
 There is no shell to process metacharacters, and the native standard is
 to pass a command line terminated by "\n" "\r" or "\0" to the spawned
@@ -1636,9 +1644,10 @@ Does not automatically flush output handles on some platforms.
 
 Only the first entry returned is nonzero. (S<Mac OS>)
 
-"cumulative" times will be bogus.  On anything other than Windows NT,
-"system" time will be bogus, and "user" time is actually the time
-returned by the clock() function in the C runtime library. (Win32)
+"cumulative" times will be bogus.  On anything other than Windows NT
+or Windows 2000, "system" time will be bogus, and "user" time is
+actually the time returned by the clock() function in the C runtime
+library. (Win32)
 
 Not useful. (S<RISC OS>)