2.2 Installing mod_perl on Unix Platforms

Now let's go over the installation again, this time with each step explained in detail and with some troubleshooting advice. If the build worked and you are in a hurry to boot your new httpd, you may skip to Section 2.4.

Before installing Apache and mod_perl, you usually have to become root so that the files can be installed in a protected area. However, users without root access can still install all files under their home directories by building Apache in an unprivileged location; you need root access only to install it. We will talk about the nuances of this approach in Chapter 3.

2.2.1 Obtaining and Unpacking the Source Code

The first step is to obtain the source code distributions of Apache and mod_perl. These distributions can be retrieved from http://www.apache.org/dist/httpd/ and http://perl.apache.org/dist/ and are also available from mirror sites. Even if you have the Apache server running on your machine, you'll need its source distribution to rebuild it from scratch with mod_perl.

The source distributions of Apache and mod_perl should be downloaded into a directory of your choice. For the sake of consistency, we assume throughout the book that all builds are being done in the /home/stas/src directory. Just remember to substitute /home/stas/src in the examples with the actual path being used.

The next step is to move to the directory containing the source archives:

panic% cd /home/stas/src

Uncompress and untar both sources. GNU tar allows this using a single command per file:

panic% tar -zvxf apache_1.3.xx.tar.gz
panic% tar -zvxf mod_perl-1.xx.tar.gz

For non-GNU tars, you may need to do this with two steps (which you can combine via a pipe):

panic% gzip -dc apache_1.3.xx.tar.gz | tar -xvf -
panic% gzip -dc mod_perl-1.xx.tar.gz | tar -xvf -

Linux distributions supply tar and gzip and install them by default. If your machine doesn't have these utilities already installed, you can get tar and gzip from http://www.gnu.org/, among other sources. The GNU versions are available for every platform that Apache supports.

2.2.2 Building mod_perl

Move into the /home/stas/src/mod_perl-1.xx/ source distribution directory:

panic% cd mod_perl-1.xx

The next step is to create the Makefile. This is no different in principle from the creation of the Makefile for any other Perl module.

panic% perl Makefile.PL APACHE_SRC=../apache_1.3.xx/src \
  DO_HTTPD=1 USE_APACI=1 EVERYTHING=1

mod_perl accepts a variety of parameters. The options specified above will enable almost every feature that mod_perl offers. There are many other options for fine-tuning mod_perl to suit particular circumstances; these are explained in detail in Chapter 3.

Running Makefile.PL will cause Perl to check for prerequisites and identify any required software packages that are missing. If it reports missing Perl packages, they will have to be installed before proceeding. Perl modules are available from CPAN (http://cpan.org/) and can easily be downloaded and installed.

An advantage of installing mod_perl with the help of the CPAN.pm module is that all the missing modules will be installed with the Bundle::Apache bundle:

panic% perl -MCPAN -e 'install("Bundle::Apache")'

We will talk in depth about using CPAN.pm in Chapter 3.

Running Makefile.PL also transparently executes the ./configure script from Apache's source distribution directory, which prepares the Apache build configuration files. If parameters must be passed to Apache's ./configure script, they can be passed as options to Makefile.PL. Chapter 3 covers all this in detail.

The httpd executable can now be built by using the make utility (note that the current working directory is still /home/stas/src/mod_perl-1.xx/):

panic% make

This command prepares the mod_perl extension files, installs them in the Apache source tree, and builds the httpd executable (the web server itself) by compiling all the required files. Upon completion of the make process, the working directory is restored to /home/stas/src/mod_perl-1.xx/.

Running make test will execute various mod_perl tests on the newly built httpd executable:

panic% make test

This command starts the server on a nonstandard port (8529) and tests whether all parts of the built server function correctly. The process will report anything that does not work properly.

2.2.3 Installing mod_perl

Running make install completes the installation process by installing all the Perl files required for mod_perl to run. It also installs the mod_perl documentation (manpages). Typically, you need to be root to have permission to do this, but another user account can be used if the appropriate options are set on the perl Makefile.PL command line (see Chapter 3). To become root, use the su command.

panic% su
panic# make install

If you have the proper permissions, you can also chain all three make commands into a single command line:

panic# make && make test && make install

The single-line version simplifies the installation, since there is no need to wait for each command to complete before starting the next one. Of course, if you need to become root in order to run make install, you'll either need to run make install as a separate command or become root before running the single-line version.

If you choose the all-in-one approach and any of the make commands fail, execution will stop at that point. For example, if make alone fails, then make test and make install will not be attempted. Similarly, if make test fails, then make install will not be attempted.

Finally, change to the Apache source distribution directory and run make install to create the Apache directory tree and install Apache's header files (*.h), default configuration files (*.conf), the httpd executable, and a few other programs:

panic# cd ../apache_1.3.xx
panic# make install

Note that, as with a plain Apache installation, any configuration files left from a previous installation will not be overwritten by this process. Although backing up is never unwise, it's not actually necessary to back up the previously working configuration files before the installation.

At the end of the make install process, the installation program will list the path to the apachectl utility, which you can use to start and stop the server, and the path to the installed configuration files. It is important to write down these pathnames, as they will be needed frequently when maintaining and configuring Apache. On our machines, these two important paths are:

/usr/local/apache/bin/apachectl
/usr/local/apache/conf/httpd.conf

The mod_perl Apache server is now built and installed. All that needs to be done before it can be run is to edit the configuration file httpd.conf and write a test script.