Description

This document discusses how to install mod_perl 1.0 under Win32, both in building from sources and in installing pre-compiled binary packages.

Synopsis

Unless you are using an all-in-one package, you should first install Perl and Apache, either from the sources or as binaries. The Perl sources are available from http://www.cpan.org/src/, with directions for building contained in README.win32. ActiveState also makes the sources available for their binary builds at ftp://ftp.activestate.com/ActivePerl/src/, which may contain, in particular, Win32-specific fixes not in the CPAN Perl sources. As a binary, at present, an ActivePerl-compatible Perl, compiled with Visual C++, is the most common one used in the Win32 mod_perl/Apache environment; you can obtain such a prebuilt Perl binary from http://www.activestate.com/.

mod_perl 1 builds and tests successfully with either an ActivePerl Perl in the 6xx series, based on perl-5.6.1, or with an ActivePerl Perl in the 8xx series, based on perl-5.8.0 (for the latter, this requires mod_perl-1.29 or later). If you are using perl-5.8, you may want to consider mod_perl 2.0, which although still in a development phase offers several significant performance improvements for Win32 - see modperl-2 in Win32 for details.

The Apache sources and binaries are available at http://httpd.apache.org/.

When installing Perl or other related binaries, subtleties may arise in using path names that have spaces in them - you may, for example, have to specify C:\Program Files\ by the DOS 8.3 path name C:\Progra~1\ in certain Apache directives. If you want to avoid this, install, if possible, these packages to locations without spaces in their names (eg, C:\Perl for Perl and C:\Apache for Apache).

In the following, it may be necessary to invoke certain commands through a DOS prompt. A DOS window may be opened either through a Command Prompt option of the Start menu, or by choosing to run, from the Start menu, command or cmd, as appropriate.

Building from sources

You will need

• patience - mod_perl is considered alpha under Win32.

• MSVC++ 5.0+, Apache version 1.3-dev or higher and Perl 5.004_02 or higher.

• As of version 1.24_01, mod_perl will build on Win32 ActivePerls based on Perl-5.6.x (builds 6xx). For ActivePerl builds 8xx, you will need mod_perl-1.29 or later. For binary compatibility you should use the same compiler in building mod_perl that was used to compile your Perl binary; for ActivePerl, this means using VC++ 6.

First obtain the mod_perl 1.0 sources as a tar.gz file - when unpacked, using Winzip or similar tools, a subdirectory mod_perl-1.xx will be created.

There are two ways to build mod_perl - with MS Developer Studio, and through command-line arguments to 'perl Makefile.PL'. In both cases Apache should previously have been built and installed - if you are using a binary build of Apache, make sure that you obtain a binary build that includes the Apache libraries and header files. If you're building Apache yourself from sources, make sure to obtain the win32-src.zip archive, which has the necessary VC++ makefiles.

Building with MS Developer Studio

• Setup the Perl side

  Run, from a DOS window in the top-level directory of the mod_perl sources,

    C:\modperl_src> perl Makefile.PL
    C:\modperl_src> nmake

  This will set up the Perl side of mod_perl for the library build.

• Build mod_perl.so

  Using MS developer studio,

   select "File -> Open Workspace ...", 
   select "Files of type [Projects (*.dsp)]"
   open mod_perl-x.xx/src/modules/win32/mod_perl.dsp

• Settings

   select "Tools -> Options -> [Directories]"
   
   select "Show directories for: [Include files]", and add
   
     C:\Apache\include
     .  (should expand to C:\...\mod_perl-x.xx\src\modules\perl)
     C:\Perl\lib\Core
  
   select "Project -> Add to Project -> Files", adding:
   
     perl.lib (or perl56.lib)   (e.g. C:\perl\lib\Core\perl.lib)
     ApacheCore.lib (e.g. C:\Apache\ApacheCore.lib)
  
   select "Build -> Set Active Configuration -> [mod_perl - Win32 Release]"
  
   select "Build -> Build mod_perl.so"

  You may see some harmless warnings, which can be reduced (along with the size of the DLL), by setting:

   "Project -> Settings -> [C/C++] -> Category: [Code Generation] -> 
    Use runtime library: [Multithreaded DLL]"

  As well, if you are using a mod_ssl enabled Apache, you should add EAPI to the list of preprocessor definitions under

   "Project -> Settings -> [C/C++]"

• Testing

  Once mod_perl.so is built you may test mod_perl with:

     C:\modperl_src> nmake test

  after which, assuming the tests are OK,

     C:\modperl_src> nmake install

  will install the Perl side of mod_perl. The mod_perl.so file built under mod_perl-1.xx/src/modules/win32/Release should be copied to your Apache modules directory (eg, C:\Apache\modules).

Building with Makefile.PL arguments

Generating the Makefile as, for example,

  C:\modperl_src> perl Makefile.PL APACHE_SRC=\Apache

will build mod_perl (including mod_perl.so) entirely from the command line. The arguments accepted include

• APACHE_SRC

  This can be one of two values: either the path to the Apache build directory (eg, ..\apache_1.3.xx), or to the installed Apache location (eg, \Apache). This is used to set the locations of ApacheCore.lib and the Apache header files.

• INSTALL_DLL

  This gives the location of where to install mod_perl.so (eg, \Apache\modules). No default is assumed - if this argument is not given, mod_perl.so must be copied manually (in mod_perl-1.29 or later, INSTALL_DLL, if not supplied, will assume a default of APACHE_SRC/modules, if this directory exists).

• INSTALL_LIB

  This option, which is available only in mod_perl-1.29 or later, gives the location of where to install mod_perl.lib (eg, \Apache\libexec). This library is needed for building certain 3rd party Apache modules. If this is not supplied, a default of APACHE_SRC/libexec will be assumed, if this directory exists.

• DEBUG

  If true (DEBUG=1), a Debug version will be built (this assumes that a Debug Apache has been built). If false, or not given, a Release version will be built.

• EAPI

  If true (EAPI=1), EAPI (Extended API) will be defined when compiling. This is useful when building mod_perl against mod_ssl patched Apache sources. If false, or not given, EAPI will not be defined.

After this, running

   C:\modperl_src> nmake
   C:\modperl_src> nmake test
   C:\modperl_src> nmake install

will complete the installation.

This latter method of building mod_perl will also install the Apache and mod_perl header files, which can then be accessed through the Apache::src module.

If this build fails, you may want to try the sources obtained from svn - see the discussion on the Development Source Distribution for details. Be aware, though, that as well as providing bug fixes, there may be new features being added and tested in the svn versions, so at any given time there are no guarantees that these packages will build and test successfully.

Binaries

There are two major types of binary packages available for Win32 mod_perl - all-in-one Perl/Apache/mod_perl binaries, and mod_perl ppm (Perl Package Manager) packages.

All-in-one packages

There are a number of binary packages for Win32 that contain the necessary Perl and Apache binaries:

• IndigoPerl from http://www.indigostar.com/,

• XAMPP for Windows from http://www.apachefriends.org/en/xampp-windows.html

• DeveloperSide.NET for Windows at http://www.devside.net/web/server/free/software

• zangweb from http://www.arbingersys.com/hostsites/zangweb/

As well, there is a package perl-win32-bin.exe from http://www.apache.org/dyn/closer.cgi/perl/win32-bin/ - see the file perl-win32-bin.readme for a description. If you have trouble fetching the whole file at once, the directory http://www.apache.org/dyn/closer.cgi/perl/win32-bin/perl-win32-bin/ contains this distribution split across multiple files - see README.join for instructions on how to join them. Alternatively, if you have Perl already, you can get the script distinstall which, when invoked as perl distinstall, will fetch and join the files for you.

As well as including a number of non-core modules, both of these packages contain mod_perl. See the documentation on the web sites and that included with the packages for installation instructions. Both of these also include an ActiveState-compatible ppm (Perl Package Manager) utility for adding and upgrading modules.

For the adventuresome who want a taste of things to come, or for those who want to avoid the multithreading limitations of mod_perl 1.0, a mod_perl-2.0/Apache-2.0 binary distribution is available - see the discussion of modperl-2 on Win32 for details. Be aware though that mod_perl 2.0 is still in a development phase, and that a minimum Perl version of 5.8 (ActivePerl 8xx) is required.

PPM Packages

For ActivePerl users (or compatible), there are also PPM mod_perl packages available. For this, if you don't already have it, get and install the latest Win32 Apache binary from http://httpd.apache.org/.

Both ActivePerl and Apache binaries are available as MSI files for use by the Microsoft Installer - as discussed on the ActiveState site, users of Windows 95 and 98 may need to obtain this. In installing these packages, you may find it convenient when transcribing any Unix-oriented documentation to choose installation directories that do not have spaces in their names (eg, C:\Perl and C:\Apache).

After installing Perl and Apache, you can then install mod_perl via the PPM utility. ActiveState does not maintain mod_perl in their ppm repository, so you must get it from a different location other than ActiveState's site. A quick way to do this is to download the script mpinstall and save it as, for example, mpinstall. Invoking this as perl mpinstall on a command line will take you through a dialogue, based on your configuration, which will determine and install, via ppm, the desired mod_perl ppm package.

The direct way to install mod_perl via ppm is simply as (broken over two lines for readability)

  C:\> ppm install
       http://theoryx5.uwinnipeg.ca/ppmpackages/mod_perl.ppd

for Activeperl 6xx builds, and as

  C:\> ppm install
       http://theoryx5.uwinnipeg.ca/ppms/mod_perl-1.ppd

for 8xx builds. Another way, which will be useful if you plan on installing additional Apache modules, is to add the repository where the mod_perl package is kept to the ppm shell utility. For ppm2 this may be done with the set repository alias location command, while for ppm3 (the default with ActivePerl 8xx) the appropriate command is repository add alias location; see the help utility within the ppm shell for details. For 6xx builds, the appropriate location is

  http://theoryx5.uwinnipeg.ca/cgi-bin/ppmserver?urn:/PPMServer

while for for 8xx builds it is

  http://theoryx5.uwinnipeg.ca/cgi-bin/ppmserver?urn:/PPMServer58

After this, you can, within the ppm shell, use the install command to either install mod_perl, for 6xx, or mod_perl-1, for 8xx. For ppm2, use the set save command to save the theoryx5 repository to your PPM configuration file, so that future PPM sessions will search this repository, as well as ActiveState's, for requested packages. If you are running mod_ssl under Apache, then you should obtain the mod_perl-eapi package for 6xx or the mod_perl-eapi-1 package for 8xx instead.

Note that, because of binary incompatibilities, one should not install packages for ActivePerl 8xx from a repository containing packages for ActivePerl 6xx, and vice-versa, particularly if these packages contain XS-based modules.

The mod_perl PPM package also includes the necessary Apache DLL mod_perl.so; a post-installation script should be run which will offer to copy this file to your Apache modules directory (eg, C:\Apache\modules). If this fails, you can grab the appropriate dll and install it manually. For 6xx builds, this is at http://theoryx5.uwinnipeg.ca/ppmpackages/x86/, for which the relevant file is either mod_perl.so or, for EAPI support, mod_perl-eapi.so. For 8xx builds, the location is http://theoryx5.uwinnipeg.ca/ppms/x86/, for which the relevant file is either mod_perl-1.so or, for EAPI support, mod_perl-eapi-1.so. You should then copy this file to your Apache modules directory and rename it as mod_perl.so, if necessary.

The mod_perl package available from this site will always use the latest mod_perl sources compiled against the latest official Apache release; depending on changes made in Apache, you may or may not be able to use an earlier Apache binary. However, in the Apache Win32 world it is particularly a good idea to use the latest version, for bug and security fixes. If you encounter problems in loading mod_perl.so, ensure that the mod_perl version you are using matches that of Apache, make certain Perl is in your PATH environment variable, or try adding the Apache directive

  LoadFile "C:/Path/to/your/Perl/bin/perlxx.dll"

before loading mod_perl.so. If all else fails, a reboot may help.

If the theoryx5.uwinnipeg.ca repository is down, you can access these packages at http://www.apache.org/dyn/closer.cgi/perl/win32-bin/ppms/, for builds 8xx, and http://www.apache.org/dyn/closer.cgi/perl/win32-bin/ppmpackages/, for builds 6xx.

See Also

The directions for configuring mod_perl 1.0 on Win32, the mod_perl documentation, and the FAQs for mod_perl on Win32. Help is also available through the archives of and subscribing to the mod_perl mailing list.

Maintainers

Maintainer is the person(s) you should contact with updates, corrections and patches.

• Randy Kobes <randy@theoryx5.uwinnipeg.ca>

Authors

• Randy Kobes <randy@theoryx5.uwinnipeg.ca>

Only the major authors are listed above. For contributors see the Changes file.