Installing mod_perl for Windows (Practical mod

2.4. Installing mod_perl for Windows

Apache runs on many flavors of Unix and Unix-like operating systems. Version 1.3 introduced a port to the Windows family of operating systems, often named Win32 after the name of the common API. Because of the many differences between Unix and Windows, the Win32 port of Apache is still branded as beta quality—it hasn't yet reached the stability and performance levels of the native Unix counterpart.

Another hindrance to using mod_perl on Windows is that current versions of Perl are not thread-safe on Win32. As a consequence, mod_perl calls to the embedded Perl interpreter must be serialized (i.e., executed one at a time). For these reasons, we recommend that mod_perl on Windows be used only for testing purposes, not in production.

Building mod_perl from source on Windows is a bit of a challenge. Development tools such as a C compiler are not bundled with the operating system, and most users expect a point-and-click installation, as with most Windows software. Additionally, all software packages need to be built with the same compiler and compile options. This means building Perl, Apache, and mod_perl from source, which is quite a daunting task.

Fortunately, Randy Kobes maintains a Windows distribution of mod_perl that includes all the necessary tools, including Perl, Apache, and a host of useful CPAN modules. Using this distribution provides an out-of-the-box Apache + mod_perl combo in minutes.

The distribution comes with extensive documentation. Take the time to read it, particularly if you want to install the software in a location different from the default. In the following installation, we'll use the default locations and options.

Here are the steps for installing mod_perl:

Download the Windows distribution. Download perl-win32-bin-x.x.exe from https://perl.apache.org/download/binaries.html. This self-extracting archive yields four directories: Apache/, Perl/, openssl/, and readmes/.
Install the software. Move the Apache/ and Perl/ directories to C:\. Edit C:\AUTOEXEC.BAT to install the Perl executable directories in your system's search path:
```
SET PATH=C:\Perl\5.6.1\bin;C:\Perl\5.6.1\bin\MSWin32-x86;"%PATH%"
```
Then restart Windows for this change to take effect.
Test the Perl installation. Open a DOS prompt window to verify that Perl is installed correctly and learn the version number:
```
C:\> perl -v

This is perl, v5.6.1 built for MSWin32-x86

Copyright 1987-2000, Larry Wall
```
Start Apache. The distribution comes with a ready-made configuration file for mod_perl, which we'll use to start Apache. From the C:\Apache directory, start Apache:
```
C:\Apache> apache.exe -f conf\httpd.conf
```
Now, issuing a request for https://localhost/ displays the usual Apache "It Worked!" page.
Test mod_perl. The distribution comes with a preconfigured mod_perl handler and Apache::Registry directory. We can test our mod_perl-enabled server by issuing the following requests:
```
https://localhost/hello
https://localhost/mod_perl/printenv
```

We now have a fully functional mod_perl server. The example scripts described in the rest of this chapter can be used with minor modifications to file paths and URIs. In particular, change all instances of /home/stas to C:\Apache\, and change all instances of https://localhost/perl to https://localhost/mod_perl.

2.4.1. Installing mod_perl with the Perl Package Manager

If you are already a Perl developer on Windows, it is likely that you have ActivePerl (see https://www.activestate.com/) installed. In that case, you can get a mod_perl distribution that takes advantage of your existing Perl installation.

First of all, you will need to get the latest Apache distribution. Go to https://www.apache.org/dist/httpd/binaries/win32/ and get the latest version of apache_1.3.xx-win32-no_src.msi, which is a graphical installer. Read the notes on that page about the MSI Binary distribution carefully if you are using Windows NT 4.0 or Windows 9x, as there may be some prerequisites.

There is a lot of documentation at https://httpd.apache.org/ about installing Apache on Windows, so we won't repeat it here. But for the purposes of this example, let's suppose that your Apache directory is C:\Apache, which means you chose C:\ as the installation directory during the installation of Apache, and it created a subdirectory named Apache there.

Once Apache is installed, we can install mod_perl. mod_perl is distributed as a PPM file, which is the format used by the ActivePerl ppm command-line utility. mod_perl isn't available from ActiveState, but it has been made available from a separate archive, maintained by Randy Kobes.[12] To install mod_perl, do the following from a DOS prompt:

[12]See the Preface for more information about PPM installation.

C:\> ppm
PPM> install mod_perl
PPM> quit
C:\>

When install mod_perl completes, a post-installation script will run, asking you where to install mod_perl.so, the mod_perl dynamic link library (DLL) that's used by Apache. Look over the suggested path and correct it if necessary, or press Enter if it's correct; it should be the C:\Apache\modules directory if you used C:\Apache as an installation directory.

Please note that the version of mod_perl provided in that archive is always the latest version of mod_perl compiled against the latest version of Apache, so you will need to make sure you have the latest Apache (of the 1.3.x series) installed before proceeding. Furthermore, you will need an ActivePerl installation from the 6xx series, based on Perl 5.6.x, or mod_perl won't work.

The next step is to enable mod_perl in your httpd.conf file. If you installed Apache in C:\Apache, this will be C:\Apache\conf\httpd.conf.

Add this line together with any other LoadModule directives:

LoadModule perl_module modules/mod_perl.so

Furthermore, if you have a ClearModuleList directive in the same file, add the following line with the other AddModule directives:

AddModule mod_perl.c

For more information, see the Apache documentation for these two directives, and see Chapter 3 for more information on using mod_perl as a dynamic shared object (DSO).

With this installation, you can start Apache as described in its documentation, and try out the examples in this book. However, the mod_perl test scripts cited above aren't provided, and you will have to configure mod_perl yourself. See Chapter 4 for more information about configuring mod_perl. For example:

Alias /perl/ C:/Apache/perl/

PerlModule Apache::Registry
<Location /perl/>
    SetHandler perl-script
    PerlHandler Apache::Registry
    Options +ExecCGI
    PerlSendHeader On
    Allow from all
</Location>

This will allow you to run Apache::Registry scripts placed in the directory C:\Apache\perl. As you may have noticed, we use forward slashes instead of the backslashes that are used on Windows (i.e., C:/Apache/perl/ instead of C:\Apache\perl\), to be compatible with Unix notation.