From: Gurusamy Sarathy Date: Tue, 14 Mar 2000 17:15:44 +0000 (+0000) Subject: revise README.win32 for currentness, point to function X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=63f87e493b935d228b65680cfa65fe182cf034d7;p=p5sagit%2Fp5-mst-13.2.git revise README.win32 for currentness, point to function list in perlport.pod (from a patch suggested by Dominic Dunlop) p4raw-id: //depot/perl@5731 --- diff --git a/README.win32 b/README.win32 index b39961b..bca4921 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 perl. Once built, you should be able to -B 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 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 above on how to get it. +You also need dmake. See L 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 compatible with binaries built without. -Perl installs PERL_OBJECT binaries under a distinct architecture name, -so they B 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 compatible -with binaries built without. Perl installs threads enabled binaries under -a distinct architecture name, so they B 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 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 above on how to get it. +You may also use dmake. See L 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 and C 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, -C, C, C, C, C, -C and related security functions, C, -C, C, C, C, -C, C, C, C, C, -C<*netent()>, C<*protoent()>, C<*servent()>, C<*hostent()>, -C. -This list is possibly incomplete. +Some of the built-in functions do not act exactly as documented in +L, 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 +for a reasonably definitive list of these differences. -=item * - -Various C related calls are supported, but they may not -behave as on Unix platforms. - -=item * - -The four-argument C call is only supported on sockets. +Not all extensions available from CPAN may build or work properly +in the Win32 environment. See L. -=item * - -The C 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, C 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 related calls are supported, but they may not +behave as on Unix platforms. See L for the full list. Signal handling may not behave as on Unix platforms (where it doesn't exactly "behave", either :). For instance, calling C @@ -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 is implemented, but doesn't have the semantics of -C, i.e. it doesn't send a signal to the identified process -like it does on Unix platforms. Instead it immediately calls -C. 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 >, along with the output produced by C. @@ -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 diff --git a/pod/perlport.pod b/pod/perlport.pod index 2a1bc77..e59b385 100644 --- a/pod/perlport.pod +++ b/pod/perlport.pod @@ -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) +=item alarm SECONDS + +=item alarm + +Not implemented. (Win32) + =item binmode FILEHANDLE Meaningless. (S, S) @@ -1444,14 +1450,8 @@ Not implemented. (S, Plan9) Globbing built-in, but only C<*> and C metacharacters are supported. (S) -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) +This operator is implemented via the File::Glob extension on most +platforms. See L for portability information. =item ioctl FILEHANDLE,FUNCTION,SCALAR @@ -1467,9 +1467,12 @@ Available only for socket handles. (S) Not implemented, hence not useful for taint checking. (S, S) -C 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 doesn't have the semantics of C, i.e. it doesn't send +a signal to the identified process like it does on Unix platforms. +Instead C 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) -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) +Note that the C 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 spawns an external process and immediately returns its process designator, without waiting for it to terminate. Return value may be used subsequently -in C or C. (Win32) +in C or C. 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) -"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)