NAME

mod_perl 2.0 Win32 Installation Instructions

Description

This document deals with installation specifics on Win32 platforms.

Synopsis

As described in the discussion of issues in multithreaded win32, a mod_perl 1.0 enabled server based on Apache 1.3 on Win32 is limited to a single thread serving a request at a time. This effectively prevents concurrent processing, which can have serious implications for busy sites. This problem is addressed in the multi-thread/multi-process approach of mod_perl 2.0/Apache 2.0.

Note that there are some threading issues in perl-5.6 (upon which ActivePerl builds 6xx are based) which may cause problems with mod_perl 2.0. Because of this, it is (strongly) recommended that perl-5.8 (ActivePerl builds 8xx) be used with mod_perl 2.0 on Win32.

Installing

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

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

As of this writing, mod_perl 2.0 is known to compile and work with an ActivePerl-compatible Perl, both for builds 6xx, based on perl-5.6.1, and builds 8xx, based on perl-5.8.0. However, because of improved threading support, perl-5.8 is recommended for Win32 mod_perl 2.0. See the section on Apache/mod_perl binaries below for details on a suitable repository containing mod_perl ppm packages, and also how to obtain other Win32 binary packages.

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:\Apache2 for Apache 2.0).

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

If you are building mod_perl 2.0 from sources, it is probably also best to do the same for Apache 2.0. The Apache 2.0 sources can be obtained from http://httpd.apache.org/, which when unpacked will contain at the top-level a Visual Studio project file. Choose the InstallBin - Win32 Release target to build and install Apache 2.0, which by default will be placed in /Apache2.

Having built and installed Apache 2.0, next obtain the mod_perl 2.0 First obtain the mod_perl 2.0 sources as a tar.gz file - when unpacked, using Winzip or similar tools, a subdirectory mod_perl-x.xx will be created. Next, run the command

    C:\modperl_src> perl Makefile.PL MP_AP_PREFIX=\Path\to\Apache2

Then

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

will build and test mod_perl 2.0. mod_perl 2.0 on Win32 is considered at an alpha stage of development, so not all the tests may pass.

The final command,

    C:\modperl_src> nmake install

will install the necessary mod_perl 2.0 files into your Perl directory tree, and also copy src/modules/perl/mod_perl.so into your /Path/to/Apache2/modules/ directory. If you are installing mod_perl 2.0 on a system that also contains mod_perl 1.0, then some mod_perl 1.0 files will be overwritten by this procedure. This can be avoided by preparing the build as

  C:\modperl_src> perl Makefile.PL MP_AP_PREFIX=\Path\to\Apache2 MP_INST_APACHE2=1

which will subsequently lead to the mod_perl 2.0 files being installed under an Apache2 subdirectory in your Perl tree. You will then have to employ either a use Apache2; line in your scripts/packages or else a PerlModule Apache2 directive in Apache's httpd.conf.

If this build fails, or you want features not present in the official releases, you may want to try the sources obtained from cvs - see the discussion on the 2.0 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 cvs versions, so at any given time there are no guarantees that these packages will build and test successfully.

PPM Packages

The first, for ActivePerl users, is through PPM - this assumes you already have ActivePerl (build 8xx is recommended) from http://www.activestate.com/ and a Win32 Apache 2.0 binary from http://httpd.apache.org/. In installing this, you might avoid some future problems by choosing installation directories that do not have spaces in their names (eg, C:/Apache2).

After installing Perl and Apache 2.0, 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-2.ppd

for ActivePerl 6xx builds, and

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

for ActivePerl 8xx builds (at present, this latter repository does not contain a mod_perl-1 package). Another way, which will be useful if you plan on installing additional Apache modules, is to set the repository within the ppm shell utility to

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

for ActivePerl 6xx builds, and to

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

for ActivePerl 8xx builds. The repository may be set using

   ppm> set repository NAME LOCATION

for ppm2 and by

   ppm> rep add NAME LOCATION

for ppm3 - see the help utility within the ppm shell for details. mod_perl 2.0 can then be installed as

   ppm> install mod_perl-2

for builds 6xx and as

   ppm> install mod_perl

for builds 8xx.

This will install the necessary modules under an Apache2 subdirectory in your Perl tree, so as not to disturb an existing Apache directory from mod_perl 1.0. See the section below on configuring mod_perl to add this directory to the @INC path for searching for 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 Apache2 modules directory (eg, C:/Apache2/modules/). If this is not done, get either mod_perl-2.tar.gz from http://theoryx5.uwinnipeg.ca/ppmpackages/x86/, for builds 6xx, or mod_perl.tar.gz from http://theoryx5.uwinnipeg.ca/ppms/x86/, for builds 8xx; when unpacked, this file contains mod_perl.so in the top-level directory.

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.

Note that 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 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.

All in one packages

At http://theoryx5.uwinnipeg.ca/pub/other/ there is a self-extracting archive Perl-5.8-win32-bin.exe containing a binary version of perl-5.8 (compatible with ActivePerl 8xx), together with Apache 2.0 and mod_perl 2.0. See the file Perl-5.8-win32-bin.readme for a description. If you have trouble fetching the whole file at once, the directory http://theoryx5.uwinnipeg.ca/pub/other/Perl-5.8-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.

See Also

The directions for configuring mod_perl 2.0 on Win32, the mod_perl documentation, http://take23.org/, http://httpd.apache.org/, http://www.activestate.com/, 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.

cpanm mod_perl

perl -MCPAN -e shell
install mod_perl