Writing Apache Modules with Perl and C By:   Lincoln Stein and Doug MacEachern Published:   O'Reilly & Associates, Inc.  - March 1999 Copyright © 1999 by O'Reilly & Associates, Inc.

Appendix B - Building and Installing mod_perl
Other Configuration Methods

In this section...

Introduction Using the .makepl_args.mod_perl File Installing via CPAN.pm Building mod_perl and Apache Separately Building mod_perl as a DSO

Introduction

As with everything having to do with Perl, there are many ways to build and install mod_perl. This section covers several of the alternatives.

Using the .makepl_args.mod_perl File

The various Makefile.PL options can be overwhelming, difficult to remember, and cumbersome to type. One way to save your preferences for posterity is to wrap the Makefile.PL command into a shell script.

Another way to save your preferences is to create a file named .makepl_args.mod_perl, located either in the current directory (.), the parent directory (..), or your home directory. When Makefile.PL runs, it scans these directories for the file, reads it in, and strips out blank lines and comments. Everything else is treated as a command line option. For example:

# File: .makepl_args.mod_perl
# enable all phase callbacks, API modules and misc features
EVERYTHING=1

#tell Makefile.PL where the Apache source tree is
APACHE_SRC=/usr/local/apache/src

#tell Makefile.PL to use the first source found, which will be the
#path specified above by APACHE_SRC
DO_HTTPD=1

#tell Makefile.PL to configure Apache using the apaci interface
USE_APACI=1

#specify the --prefix to give Apache's configure script
APACHE_PREFIX=/usr/local/apache

#add mod_info, mod_status and mod_proxy
ADD_MODULE=info,status,proxy

#additional arguments to give Apache's configure script
#arguments can be delimited by a comma and/or specified with multiple
#APACI_ARGS lines
APACI_ARGS=--enable-shared=mime,--enable-shared=alias
APACI_ARGS=--logfiledir=/usr/local/apache/logs
APACI_ARGS=--runtimedir=/usr/local/apache/logs

Now you can type the command perl Makefile.PL without giving any explicit options and they will be read in from the file. Any options you do supply on the command line will override those in the file.

Installing via CPAN.pm

Once you are familiar with installing mod_perl manually, you might want to install future updates using Andreas Koenig's awesome CPAN shell. This interactive program automatically determines the latest version of mod_perl, downloads it from a CPAN site, and runs the configuration, make, and install steps.

To enter the CPAN shell, type:

% perl -MCPAN -e shell

If this is the first time you're running the shell, you'll be lead through a series of one-time configuration questions. The only question you need to be prepared for is the one that prompts you to type in the name of your favorite CPAN site. Refer back to the preface for instructions on finding a convenient site.

After CPAN is initialized, type:

cpan> install mod_perl

and watch it fly!

Building mod_perl and Apache Separately

If you use a lot of third-party Apache modules, you may want to decouple the process of building mod_perl from the process of building Apache. This is only a little bit harder than the full automatic method described above.

You will first need to configure mod_perl using Makefile.PL in the manner described in the previous sections. However, answer "no" when prompted for whether to build httpd in the Apache source tree. Alternatively, you can disable the prompt completely by providing a configuration option of PREP_HTTPD=1 on the command line.

You will make and make install in the mod_perl source directory as before. This process will build a libperl.a library within the Apache source tree but will not build the server itself. Now go ahead and build any third-party modules you wish to add to Apache. When you are ready to configure and install the server, enter the Apache directory tree and run the configure script with the following option:

--activate-module=src/modules/perl/libperl.a

This option must be in addition to any other options you wish to pass to the configure script; again, it's a good idea to run the configure command from within a shell script that you can edit and run again. The --activate-module option links the precompiled libperl.a library to the Apache server executable but does not otherwise interact with the mod_perl build process.

Building mod_perl as a DSO

If an Apache server installation is already installed, mod_perl can be built as a DSO without the Apache source tree handy. Example:

perl Makefile.PL USE_APXS=1 APACHE_PREFIX=/usr/local/apache EVERYTHING=1 ...

The USE_APXS option tells mod_perl to build itself using the Apache apxs tool. The Makefile.PL will look for apxs under the bin/ and sbin/ directories relative to APACHE_PREFIX. If apxs happens to be installed elsewhere, simply use the full pathname for the value of the USE_APXS attribute:

perl Makefile.PL USE_APXS=/usr/bin/apxs EVERYTHING=1 ...

Provided an APACHE_PREFIX attribute was passed to the Makefile.PL script, running make install will install and configure the mod_perl DSO library along with installing the Perl libraries. If no APACHE_PREFIX attribute was specified, simply copy the new apaci/libperl.so library to anywhere you choose.