perlwin32 - Perl under Win32


SYNOPSIS

       These are instructions for building Perl under Windows
       (9x, NT and 2000).


DESCRIPTION

       Before you start, you should glance through the README
       file found in the top-level directory where the Perl dis­
       tribution was extracted.  Make sure you read and under­
       stand the terms under which this software is being dis­
       tributed.

       Also make sure you read the BUGS AND CAVEATS entry else­
       where in this document below for the known limitations of
       this port.

       The INSTALL file in the perl top-level has much informa­
       tion that is only relevant to people building Perl on
       Unix-like systems.  In particular, you can safely ignore
       any information that talks about "Configure".

       You may also want to look at two other options for build­
       ing a perl that will work on Windows NT:  the README.cyg­
       win and README.os2 files, which each give a different set
       of rules to build a Perl that will work on Win32 plat­
       forms.  Those two methods will probably enable you to
       build a more Unix-compatible perl, but you will also need
       to download and use various other build-time and run-time
       support software described in those files.

       This set of instructions is meant to describe a so-called
       "native" port of Perl to Win32 platforms.  The resulting
       Perl requires no additional software to run (other than
       what came with your operating system).  Currently, this
       port is capable of using one of the following compilers:

             Borland C++               version 5.02 or later
             Microsoft Visual C++      version 4.2 or later
             Mingw32 with GCC          version 2.95.2 or better

       The last of these is a high quality freeware compiler.
       Support for it is still experimental.  (Older versions of
       GCC are known not to work.)

       This port currently supports MakeMaker (the set of modules
       that is used to build extensions to perl).  Therefore, you
       should be able to build and install most extensions found
       in the CPAN sites.  See the Usage Hints entry elsewhere in
       this document below for general hints about this.


       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).

       Command Shell
           Use the default "cmd" shell that comes with NT.  Some
           versions of the popular 4DOS/NT shell have incompati­
           bilities 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 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.

           Make sure the path to the build directory does not
           contain spaces.  The build usually works in this cir­
           cumstance, but some tests will fail.

       Borland C++
           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.)

           See L/"Make"> above.

       Microsoft Visual C++
           The nmake that comes with Visual C++ will suffice for
           building.  You will need to run the VCVARS32.BAT file
           usually found somewhere like C:\MSDEV4.2\BIN.  This


           You can also use dmake to build using Visual C++, pro­
           vided: you set OSRELEASE to "microsft" (or whatever
           the directory name under which the Visual C dmake con­
           figuration lives) in your environment, and edit
           win32/config.vc to change "make=nmake" into
           "make=dmake".  The latter step is only essential if
           you want to use dmake as your default make for build­
           ing extensions using MakeMaker.

       Mingw32 with GCC
           GCC-2.95.2 binaries can be downloaded from:

               ftp://ftp.xraylith.wisc.edu/pub/khan/gnu-win32/mingw32/

           The GCC-2.95.2 bundle comes with Mingw32 libraries and
           headers.

           Make sure you install the binaries that work with
           MSVCRT.DLL as indicated in the README for the GCC bun­
           dle.  You may need to set up a few environment vari­
           ables (usually run from a batch file).

           You also need dmake.  See the Make entry elsewhere in
           this document above on how to get it.

       Building

       ·   Make sure you are in the "win32" subdirectory under
           the perl toplevel.  This directory contains a "Make­
           file" 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 GCC com­
           piler.

       ·   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.  These are explained
           in the makefiles.

           You will have to make sure CCTYPE is set correctly,
           and CCHOME points to wherever you installed your com­
           piler.

           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 con­
           tains des_fcrypt(), enable the appropriate option in
           the makefile.  des_fcrypt() is not bundled with the

           export of cryptographic software.  Nevertheless, this
           routine is part of the "libdes" library (written by
           Eric Young) which is widely available worldwide, usu­
           ally along with SSLeay (for example: "ftp://frac­
           tal.mta.ca/pub/crypto/SSLeay/DES/").  Set CRYPT_SRC to
           the name of the file that implements des_fcrypt().
           Alternatively, if you have built a library that con­
           tains des_fcrypt(), you can set CRYPT_LIB to point to
           the library name.  The location above contains many
           versions of the "libdes" library, all with slightly
           different implementations of des_fcrypt().  Older ver­
           sions have a single, self-contained file (fcrypt.c)
           that implements crypt(), so they may be easier to use.
           A patch against the fcrypt.c found in libdes-3.06 is
           in des_fcrypt.patch.

           Perl will also build without des_fcrypt(), but the
           crypt() builtin will fail at run time.

           Be sure to read the instructions near the top of the
           makefiles carefully.

       ·   Type "dmake" (or "nmake" if you are using that make).

           This should build everything.  Specifically, it will
           create perl.exe, 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.

       Testing

       Type "dmake test" (or "nmake test").  This will run most
       of the tests from the testsuite (many tests will be
       skipped).

       No tests should typically fail when running Windows NT
       4.0.  Under Windows 2000, test 22 in lib/open3.t is known
       to fail (cause still unknown).  Many tests will fail under
       Windows 9x due to the inferior command shell.

       Some test failures may occur if you use a command shell
       other than the native "cmd.exe", or if you are building
       from a path that contains spaces.  So don't do that.

       If you are running the tests from a emacs shell window,
       you may see failures in op/stat.t.  Run "dmake test-notty"
       in that case.

       If you're using the Borland compiler, you may see a fail­
       ure in op/taint.t arising from the inability to find the
       Borland Runtime DLLs on the system default path.  You will
       need to copy the DLLs reported by the messages from where

       directory (usually somewhere like C:\WINNT\SYSTEM32), and
       rerun the test.

       Please report any other failures as described under the
       BUGS AND CAVEATS entry elsewhere in this document.

       Installation

       Type "dmake install" (or "nmake install").  This will put
       the newly built perl and the libraries under whatever
       `INST_TOP' points to in the Makefile.  It will also
       install the pod documentation under `$INST_TOP\$VER­
       SION\lib\pod' and HTML versions of the same under
       `$INST_TOP\$VERSION\lib\pod\html'.  To use the Perl you
       just installed, you will need to add two components to
       your PATH environment variable, `$INST_TOP\$VERSION\bin',
       and `$INST_TOP\$VERSION\bin\$ARCHNAME'.  For example:

           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%

       Usage Hints

       Environment Variables
           The installation paths that you set during the build
           get compiled into perl, so you don't have to do any­
           thing additional to start using that perl (except add
           its location to your PATH variable).

           If you put extensions in unusual places, you can set
           PERL5LIB to a list of paths separated by semicolons
           where you want perl to look for libraries.  Look for
           descriptions of other environment variables you can
           set in the perlrun manpage.

           You can also control the shell that perl uses to run
           system() and backtick commands via PERL5SHELL.  See
           the perlrun manpage.

           Perl does not depend on the registry, but it can look
           up certain default values if you choose to put them
           there.  Perl attempts to read entries from `HKEY_CUR­
           RENT_USER\Software\Perl' and `HKEY_LOCAL_MACHINE\Soft­
           ware\Perl'.  Entries in the former override entries in
           the latter.  One or more of the following entries (of


               lib-$]              version-specific standard library path to add to @INC
               lib                 standard library path to add to @INC
               sitelib-$]          version-specific site library path to add to @INC
               sitelib             site library path to add to @INC
               vendorlib-$]        version-specific vendor library path to add to @INC
               vendorlib           vendor library path to add to @INC
               PERL*               fallback for all %ENV lookups that begin with "PERL"

           Note the `$]' in the above is not literal.  Substitute
           whatever version of perl you want to honor that entry,
           e.g. `5.6.0'.  Paths must be separated with semi­
           colons, as usual on win32.

       File Globbing
           By default, perl handles file globbing using the
           File::Glob extension, which provides portable glob­
           bing.

           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 the File::DosGlob manpage
           for details.

       Using perl from the command line
           If you are accustomed to using perl from various com­
           mand-line shells found in UNIX environments, you will
           be less than pleased 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 expansions of command-line argu­
           ments (so wildcards need not be quoted).  It also pro­
           vides only rudimentary quoting.  The only (useful)
           quote character is the double quote (").  It can be
           used to protect spaces in arguments and other special
           characters.  The Windows NT documentation has almost
           no description of how the quoting rules are imple­
           mented, but here are some general observations based
           on experiments:  The shell breaks arguments at spaces
           and passes them to programs in argc/argv.  Double­
           quotes can be used to prevent arguments with spaces in
           them from being split up.  You can put a double quote
           in an argument by escaping it with a backslash and
           enclosing the whole argument within double quotes.
           The backslash and the pair of double quotes surround­
           ing the argument will be stripped by the shell.

           The file redirection characters "<", ">", and "|" can­
           not be quoted by double quotes (there are probably
           more such).  Single quotes will protect those three

           don't get stripped by the shell (just to make this
           type of quoting completely useless).  The caret "^"
           has also been observed to behave as a quoting charac­
           ter (and doesn't get stripped by the shell also).

           Here are some examples of usage of the "cmd" shell:

           This prints two doublequotes:

               perl -e "print '\"\"' "

           This does the same:

               perl -e "print \"\\\"\\\"\" "

           This prints "bar" and writes "foo" to the file
           "blurch":

               perl -e "print 'foo'; print STDERR 'bar'" > blurch

           This prints "foo" ("bar" disappears into nowhereland):

               perl -e "print 'foo'; print STDERR 'bar'" 2> nul

           This prints "bar" and writes "foo" into the file
           "blurch":

               perl -e "print 'foo'; print STDERR 'bar'" 1> blurch

           This pipes "foo" to the "less" pager and prints "bar"
           on the console:

               perl -e "print 'foo'; print STDERR 'bar'" | less

           This pipes "foo\nbar\n" to the less pager:

               perl -le "print 'foo'; print STDERR 'bar'" 2>&1 | less

           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 Windows 9x is left as an exercise to the reader :)

       Building Extensions
           The Comprehensive Perl Archive Network (CPAN) offers a
           wealth of extensions, some of which require a C com­
           piler to build.  Look in http://www.cpan.org/ for more
           information on CPAN.

           Note that not all of the extensions available from

           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 stan­
           dard mantra:

               perl Makefile.PL
               $MAKE
               $MAKE test
               $MAKE install

           where $MAKE is whatever 'make' program you have con­
           figured perl to use.  Use "perl -V:make" to find out
           what this is.  Some extensions may not provide a test­
           suite (so "$MAKE test" may not do anything, or fail),
           but most serious ones do.

           It is important that you use a supported 'make' pro­
           gram, and ensure Config.pm knows about it.  If you
           don't have nmake, you can either get dmake from the
           location mentioned earlier, or get an old version of
           nmake reportedly available from:

               ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe

           Another option is to use the make written in Perl,
           available from CPAN:

               http://www.cpan.org/authors/id/NI-S/Make-0.03.tar.gz

           You may also use dmake.  See the Make entry elsewhere
           in this document above on how to get it.

           Note that MakeMaker actually emits makefiles with dif­
           ferent syntax depending on what 'make' it thinks you
           are using.  Therefore, it is important that one of the
           following values appears in Config.pm:

               make='nmake'        # MakeMaker emits nmake syntax
               make='dmake'        # MakeMaker emits dmake syntax
               any other value     # MakeMaker emits generic make syntax
                                       (e.g GNU make, or Perl make)

           If the value doesn't match the 'make' program you want
           to use, edit Config.pm to fix it.

           If a module implements XSUBs, you will need one of the
           supported C compilers.  You must make sure you have
           set up the environment for the compiler for command-
           line compilation.

           fully for why it failed, and report problems to the
           module author.  If it looks like the extension build­
           ing support is at fault, report that with full details
           of how the build failed using the perlbug utility.

       Command-line Wildcard Expansion
           The default command shells on DOS descendant operating
           systems (such as they are) usually do not expand wild­
           card arguments supplied to programs.  They consider it
           the application's job to handle that.  This is com­
           monly achieved by linking the application (in our
           case, perl) with startup code that the C runtime
           libraries usually provide.  However, doing that
           results in incompatible perl versions (since the
           behavior of the argv expansion code differs depending
           on the compiler, and it is even buggy on some compil­
           ers).  Besides, it may be a source of frustration if
           you use such a perl binary with an alternate shell
           that *does* expand wildcards.

           Instead, the following solution works rather well. The
           nice things about it: 1) you can start using it right
           away 2) it is more powerful, because it will do the
           right thing with a pattern like */*/*.c 3) you can
           decide whether you do/don't want to use it 4) you can
           extend the method to add any customizations (or even
           entirely different kinds of wildcard expansion).

                   C:\> copy con c:\perl\lib\Wild.pm
                   # Wild.pm - emulate shell @ARGV expansion on shells that don't
                   use File::DosGlob;
                   @ARGV = map {
                                 my @g = File::DosGlob::glob($_) if /[*?]/;
                                 @g ? @g : $_;
                               } @ARGV;
                   1;
                   ^Z
                   C:\> set PERL5OPT=-MWild
                   C:\> perl -le "for (@ARGV) { print }" */*/perl*.c
                   p4view/perl/perl.c
                   p4view/perl/perlio.c
                   p4view/perl/perly.c
                   perl5.005/win32/perlglob.c
                   perl5.005/win32/perllib.c
                   perl5.005/win32/perlglob.c
                   perl5.005/win32/perllib.c
                   perl5.005/win32/perlglob.c
                   perl5.005/win32/perllib.c

           Note there are two distinct steps there: 1) You'll
           have to create Wild.pm and put it in your perl lib
           directory. 2) You'll need to set the PERL5OPT environ­
           ment variable.  If you want argv expansion to be the

           environment.

           If you are using the Visual C compiler, you can get
           the C runtime's command line wildcard expansion built
           into perl binary.  The resulting binary will always
           expand unquoted command lines, which may not be what
           you want if you use a shell that does that for you.
           The expansion done is also somewhat less powerful than
           the approach suggested above.

       Win32 Specific Extensions
           A number of extensions specific to the Win32 platform
           are available from CPAN.  You may find that many of
           these extensions are meant to be used under the
           Activeware port of Perl, which used to be the only
           native port for the Win32 platform.  Since the Active­
           ware port does not have adequate support for Perl's
           extension building tools, these extensions typically
           do not support those tools either, and therefore can­
           not be built using the generic steps shown in the pre­
           vious section.

           To ensure smooth transitioning of existing code that
           uses the ActiveState port, there is a bundle of Win32
           extensions that contains all of the ActiveState exten­
           sions 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.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 same location.

       Running Perl Scripts
           Perl scripts on UNIX use the "#!" (a.k.a "shebang")
           line to indicate to the OS that it should execute the
           file using perl.  Win32 has no comparable means to
           indicate arbitrary files are executables.

           Instead, all available methods to execute plain text
           files on Win32 rely on the file "extension".  There
           are three methods to use this to execute perl scripts:

           1       There is a facility called "file extension
                   associations" that will work in Windows NT
                   4.0.  This can be manipulated via the two com­
                   mands "assoc" and "ftype" that come standard
                   with Windows NT 4.0.  Type "ftype /?" for a
                   complete example of how to set this up for
                   perl scripts (Say what?  You thought Windows
                   NT wasn't perl-ready? :).

                   and there are reportedly bugs with file asso­
                   ciations where it does work, the old method of
                   wrapping the perl script to make it look like
                   a regular batch file to the OS, may be used.
                   The install process makes available the
                   "pl2bat.bat" script which can be used to wrap
                   perl scripts into batch files.  For example:

                           pl2bat foo.pl

                   will create the file "FOO.BAT".  Note "pl2bat"
                   strips any .pl suffix and adds a .bat suffix
                   to the generated file.

                   If you use the 4DOS/NT or similar command
                   shell, note that "pl2bat" uses the "%*" vari­
                   able in the generated batch file to refer to
                   all the command line arguments, so you may
                   need to make sure that construct works in
                   batch files.  As of this writing, 4DOS/NT
                   users will need a "ParameterChar = *" state­
                   ment in their 4NT.INI file, or will need to
                   execute "setdos /p*" in the 4DOS/NT startup
                   file to enable this to work.

           3       Using "pl2bat" has a few problems:  the file
                   name gets changed, so scripts that rely on
                   `$0' to find what they must do may not run
                   properly; running "pl2bat" replicates the con­
                   tents of the original script, and so this pro­
                   cess can be maintenance intensive if the orig­
                   inals get updated often.  A different approach
                   that avoids both problems is possible.

                   A script called "runperl.bat" is available
                   that can be copied to any filename (along with
                   the .bat suffix).  For example, if you call it
                   "foo.bat", it will run the file "foo" when it
                   is executed.  Since you can run batch files on
                   Win32 platforms simply by typing the name
                   (without the extension), this effectively runs
                   the file "foo", when you type either "foo" or
                   "foo.bat".  With this method, "foo.bat" can
                   even be in a different location than the file
                   "foo", as long as "foo" is available somewhere
                   on the PATH.  If your scripts are on a
                   filesystem that allows symbolic links, you can
                   even avoid copying "runperl.bat".

                   Here's a diversion:  copy "runperl.bat" to
                   "runperl", and type "runperl".  Explain the
                   observed behavior, or lack thereof. :) Hint:
                   .gnidnats llits er'uoy fi ,"lrepnur" eteled


       Miscellaneous Things
           A full set of HTML documentation is installed, so you
           should be able to use it if you have a web browser
           installed on your system.

           `perldoc' is also a useful tool for browsing informa­
           tion contained in the documentation, especially in
           conjunction with a pager like `less' (recent versions
           of which have Win32 support).  You may have to set the
           PAGER environment variable to use a specific pager.
           "perldoc -f foo" will print information about the perl
           operator "foo".

           If you find bugs in perl, you can run `perlbug' to
           create a bug report (you may have to send it manually
           if `perlbug' cannot find a mailer on your system).


BUGS AND CAVEATS

       Some of the built-in functions do not act exactly as docu­
       mented in the perlfunc manpage, and a few are not imple­
       mented at all.  To avoid surprises, particularly if you
       have had prior exposure to Perl in other operating envi­
       ronments or if you intend to write code that will be
       portable to other environments, see the perlport manpage
       for a reasonably definitive list of these differences.

       Not all extensions available from CPAN may build or work
       properly in the Win32 environment.  See the Building
       Extensions entry elsewhere in this document.

       Most `socket()' related calls are supported, but they may
       not behave as on Unix platforms.  See the perlport manpage
       for the full list.

       Signal handling may not behave as on Unix platforms (where
       it doesn't exactly "behave", either :).  For instance,
       calling `die()' or `exit()' from signal handlers will
       cause an exception, since most implementations of `sig­
       nal()' on Win32 are severely crippled.  Thus, signals may
       work only for simple things like setting a flag variable
       in the handler.  Using signals under this port should cur­
       rently be considered unsupported.

       Please send detailed descriptions of any problems and
       solutions that you may find to <perlbug@perl.com>, along
       with the output produced by `perl -V'.


AUTHORS

       Gary Ng <71564.1743@CompuServe.COM>

       Gurusamy Sarathy <gsar@activestate.com>


       This document is maintained by Gurusamy Sarathy.


SEE ALSO

       the perl manpage


HISTORY

       This port was originally contributed by Gary Ng around
       5.003_24, and borrowed from the Hip Communications port
       that was available at the time.  Various people have made
       numerous and sundry hacks since then.

       Borland support was added in 5.004_01 (Gurusamy Sarathy).

       GCC/mingw32 support was added in 5.005 (Nick Ing-Simmons).

       Support for PERL_OBJECT was added in 5.005 (ActiveState
       Tool Corp).

       Support for fork() emulation was added in 5.6 (ActiveState
       Tool Corp).

       Win9x support was added in 5.6 (Benjamin Stuhl).

       Last updated: 22 March 2000


Man(1) output converted with man2html