The configuration stage of the build is performed by the command perl Makefile.PL, which accepts various parameters. This section covers all of the configuration parameters, grouped by their functionality.

Of course, you should keep in mind that these options are cumulative. We display only one or two options being used at once, but you should use the ones you want to enable all at once, in one call to perl Makefile.PL.

APACHE_SRC, DO_HTTPD, NO_HTTPD, PREP_HTTPD

These four parameters are tightly interconnected, as they control the way in which the Apache source is handled.

Typically, when you want mod_perl to be compiled statically with Apache without adding any extra components, you specify the location of the Apache source tree using the APACHE_SRC parameter and use the DO_HTTPD=1 parameter to tell the installation script to build the httpd executable:

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

If no APACHE_SRC is specified, Makefile.PL makes an intelligent guess by looking at the directories at the same level as the mod_perl sources and suggesting a directory with the highest version of Apache found there.

By default, the configuration process will ask you to confirm whether the location of the source tree is correct before continuing. If you use DO_HTTPD=1 or NO_HTTPD=1, the first Apache source tree found or the one you specified will be used for the rest of the build process.

If you don't use DO_HTTPD=1, you will be prompted by the following question:

Shall I build httpd in ../apache_1.3.xx/src for you?

Note that if you set DO_HTTPD=1 but do not use APACHE_SRC=../apache_1.3.xx/src, the first Apache source tree found will be used to configure and build against. Therefore, you should always use an explicit APACHE_SRC parameter, to avoid confusion.

If you don't want to build the httpd in the Apache source tree because you might need to add extra third-party modules, you should use NO_HTTPD=1 instead of DO_HTTPD=1. This option will install all the files that are needed to build mod_perl in the Apache source tree, but it will not build httpd itself.

PREP_HTTPD=1 is similar to NO_HTTPD=1, but if you set this parameter you will be asked to confirm the location of the Apache source directory even if you have specified the APACHE_SRC parameter.

If you choose not to build the binary, you will have to do that manually. Building an httpd binary is covered in an upcoming section. In any case, you will need to run make install in the mod_perl source tree so the Perl side of mod_perl will be installed. Note that mod_perl's make test won't work until you have built the server.

APACHE_HEADER_INSTALL

When Apache and mod_perl are installed, you may need to build other Perl modules that use Apache C functions, such as HTML::Embperl or Apache::Peek. These modules usually will fail to build if Apache header files aren't installed in the Perl tree. By default, the Apache source header files are installed into the $Config{sitearchexp}/auto/Apache/include directory.[17] If you don't want or need these headers to be installed, you can change this behavior by using the APACHE_HEADER_INSTALL=0 parameter.

[17]%Config is defined in the Config.pm file in your Perl installation.

USE_APACI

The USE_APACI parameter tells mod_perl to configure Apache using the flexible APACI. The alternative is the older system, which required a file named src/Configuration to be edited manually. To enable APACI, use:

panic% perl Makefile.PL USE_APACI=1
APACI_ARGS

When you use the USE_APACI=1 parameter, you can tell Makefile.PL to pass any arguments you want to the Apache ./configure utility. For example:

panic% perl Makefile.PL USE_APACI=1 \
    APACI_ARGS='--sbindir=/home/httpd/httpd_perl/sbin, \
        --sysconfdir=/home/httpd/httpd_perl/etc'

Note that the APACI_ARGS argument must be passed as a single long line if you work with a C-style shell (such as csh or tcsh), as those shells seem to corrupt multi-lined values enclosed inside single quotes.

Of course, if you want the default Apache directory layout but a different root directory (/home/httpd/httpd_perl/, in our case), the following is the simplest way to do so:

panic% perl Makefile.PL USE_APACI=1 \
    APACI_ARGS='--prefix=/home/httpd/httpd_perl'
ADD_MODULE

This parameter enables building of built-in Apache modules. For example, to enable the mod_rewrite and mod_proxy modules, you can do the following:

panic% perl Makefile.PL ADD_MODULE=proxy,rewrite

If you are already using APACI_ARGS, you can add the usual Apache ./configure directives as follows:

panic% perl Makefile.PL USE_APACI=1 \
    APACI_ARGS='--enable-module=proxy --enable-module=rewrite'
APACHE_PREFIX

As an alternative to:

APACI_ARGS='--prefix=/home/httpd/httpd_perl'

you can use the APACHE_PREFIX parameter. When USE_APACI is enabled, this attribute specifies the same —prefix option.

Additionally, the APACHE_PREFIX option automatically executes make install in the Apache source directory, which makes the following commands:

panic% perl Makefile.PL APACHE_SRC=../apache_1.3.xx/src \
    DO_HTTPD=1 USE_APACI=1 EVERYTHING=1 \
    APACI_ARGS='--prefix=/home/httpd/httpd_perl'
panic% make && make test
panic# make install
panic# cd ../apache_1.3.xx
panic# make install

equivalent to these commands:

panic% perl Makefile.PL APACHE_SRC=../apache_1.3.xx/src \
    DO_HTTPD=1 USE_APACI=1 EVERYTHING=1 \
    APACHE_PREFIX=/home/httpd/httpd_perl
panic% make && make test
panic# make install
PERL_STATIC_EXTS

Normally, if a C code extension is statically linked with Perl, it is listed in Config.pm's $Config{static_exts}, in which case mod_perl will also statically link this extension with httpd. However, if an extension is statically linked with Perl after it is installed, it will not be listed in Config.pm. You can either edit Config.pm and add these extensions, or configure mod_perl like this:

panic% perl Makefile.PL "PERL_STATIC_EXTS=DBI DBD::Oracle"
DYNAMIC

This option tells mod_perl to build the Apache::* API extensions as shared libraries. The default is to link these modules statically with the httpd executable. This can save some memory if you use these API features only occasionally. To enable this option, use:

panic% perl Makefile.PL DYNAMIC=1
USE_APXS

If this option is enabled, mod_perl will be built using the APXS tool. This tool is used to build C API modules in a way that is independent of the Apache source tree. mod_perl will look for the apxs executable in the location specified by WITH_APXS; otherwise, it will check the bin and sbin directories relative to APACHE_PREFIX. To enable this option, use:

panic% perl Makefile.PL USE_APXS=1
WITH_APXS

This attribute tells mod_perl the location of the apxs executable. This is necessary if the binary cannot be found in the command path or in the location specified by APACHE_PREFIX. For example:

panic% perl Makefile.PL USE_APXS=1 WITH_APXS=/home/httpd/bin/apxs
USE_DSO

This option tells mod_perl to build itself as a DSO. Although this reduces the apparent size of the httpd executable on disk, it doesn't actually reduce the memory consumed by each httpd process. This is recommended only if you are going to be using the mod_perl API only occasionally, or if you wish to experiment with its features before you start using it in a production environment. To enable this option, use:

panic% perl Makefile.PL USE_DSO=1
SSL_BASE

When building against a mod_ssl-enabled server, this option will tell Apache where to look for the SSL include and lib subdirectories. For example:

panic% perl Makefile.PL SSL_BASE=/usr/share/ssl
PERL_DESTRUCT_LEVEL={1,2}

When the Perl interpreter shuts down, this level enables additional checks during server shutdown to make sure the interpreter has done proper bookkeeping. The default is 0. A value of 1 enables full destruction, and 2 enables full destruction with checks. This value can also be changed at runtime by setting the environment variable PERL_DESTRUCT_LEVEL. We will revisit this parameter in Chapter 5.

PERL_TRACE

To enable mod_perl debug tracing, configure mod_perl with the PERL_TRACE option:

panic% perl Makefile.PL PERL_TRACE=1

To see the diagnostics, you will also need to set the MOD_PERL_TRACE environment variable at runtime.

We will use mod_perl configured with this parameter enabled to show a few debugging techniques in Chapter 21.

PERL_DEBUG

This option builds mod_perl and the Apache server with C source code debugging enabled (the -g switch). It also enables PERL_TRACE, sets PERL_DESTRUCT_LEVEL to 2, and links against the debuggable libperld Perl interpreter if one has been installed. You will be able to debug the Apache executable and each of its modules with a source-level debugger, such as the GNU debugger gdb. To enable this option, use:

panic% perl Makefile.PL PERL_DEBUG=1

We will discuss this option in Chapter 21, as it is extremely useful to track down bugs or report problems.