|Home / Documentation / 1.0 / OS-specific Info / Win32 /|
|mod_perl 1.0 Win32 Installation Instructions|
mod_perl2 User's Guide
By Stas Bekman, Jim Brandt
By Stas Bekman, Eric Cholet
This document discusses how to install mod_perl 1.0 under Win32, both in building from sources and in installing pre-compiled binary packages.
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,
cmd, as appropriate.
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
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.
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.
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
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++]"
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).
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
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.
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).
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.
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.
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.
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.
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
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
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.
For ActivePerl users (or compatible), there are also
mod_perl packages available. For this, if you
don't already have it, get and install the latest Win32 Apache binary
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.
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
while for for 8xx builds it is
After this, you can, within the ppm shell, use the
command to either install
mod_perl, for 6xx, or
mod_perl-1, for 8xx. For
ppm2, use the
set save command to save
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
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
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
for EAPI support,
mod_perl-eapi-1.so. You should then
copy this file to your Apache modules directory and rename
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
variable, or try adding the Apache directive
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.
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.
Maintainer is the person(s) you should contact with updates, corrections and patches.
Randy Kobes <firstname.lastname@example.org>
Randy Kobes <email@example.com>
Only the major authors are listed above. For contributors see the Changes file.