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 / Standard Installation
Makefile.PL Options for mod_perl

In this section...

Introduction Options for controlling the build process Options for activating phase callback hooks Options for activating standard API features Options for activating miscellaneous features

Introduction

There are several reasons for mod_perl's bewildering number of configuration options. Many of the options came to be during the early days of mod_perl, when new options were frequently added in an "experimental" state. As these features matured and stabilized, their activation switches remained for those site administrators who do not want to expose certain areas of the API to programmers. By turning off unwanted features, sites can also reduce the size of the Apache executable somewhat, although this overhead is small compared to the size of the Perl runtime itself.

Most first-time users of the Perl API will want to configure mod_perl with the EVERYTHING=1 option in order to turn on all features. Later, when you've experimented with the API, you may decide to dispense with some features, and you can reconfigure the server with a more select set of options. Other recommended options are USE_APACI=1, to use the Apache AutoConf-style Interface (APACI), and APACHE_PREFIX=//, to specify the location of the server root in which to install the mod_perl-enabled server and support files.

Options for controlling the build process

These options control the configuration and build process. Among other things, these options allow you to specify parameters that are passed through to Apache's configuration system.

USE_APACI=1

Tells mod_perl to configure Apache using the flexible Apache AutoConf-style Interface (APACI), rather than the older system, which required a file named src/Configuration to be edited. This option is recommended.

APACHE_PREFIX=/usr/local/apache

When USE_APACI is enabled, this attribute will specify the --prefix option for Apache's configure script, specifying the installation path for Apache. When this option is used, mod_perl's make install will also make install on the Apache side, installing the httpd binary and support tools, along with the configuration, log, and document trees.

APACI_ARGS="--option=val,--other-option=val"

Passes additional arguments to Apache's configure script. The argument list should be contained within single or double quotes and delimited by commas. Example:

% set runpath=/var/run/apache
% set logpath=/var/logs/apache
% perl Makefile.PL APACI_ARGS="--runtimedir=$runpath,--logfiledir=$logpath"

WITH_APXS=~www/bin/apxs

Tells mod_perl the location of the APache eXtenSion tool (apxs); see Chapter 2 under "Building a Dynamically Loadable Module" and Appendix C, Building Multifile C API Modules. This is necessary if the binary cannot be found in the command path or in the location specified by APACHE_PREFIX.

USE_APXS=1

Tells mod_perl to build itself using the APache eXtenSion (apxs) tool. As described in Chapter 2, 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 apxs in the location specified by USE_APXS. If USE_APXS is not specified, mod_perl will check the bin and sbin directories relative to APACHE_PREFIX.

USE_DSO=1

Tells mod_perl to build itself as a dynamic shared object (DSO). Although this reduces the apparent size of the httpd executable on disk, it doesn't actually reduce its memory consumption. This is recommended only if you are going to be using the Perl API occasionally or if you wish to experiment with its features before you start using it in a production environment.

This feature was considered experimental at the time this book was written. Consult the mod_perl INSTALL.apaci file for details on using this option.

APACHE_SRC=///apache_/src

Tells mod_perl where the Apache source tree is located. You may need this if the Apache source tree is not in the immediate vicinity of the mod_perl directory.

SSL_BASE=///ssl

When building against a mod_ssl enabled server, this option tells Apache where to look for SSL include and lib subdirectories.

DO_HTTPD=1

Tells mod_perl to build the Apache server for you, skipping the interactive prompt. If APACHE_SRC is also specified, mod_perl will use its value. Otherwise, it will search the immediate vicinity of the mod_perl directory and use the first Apache source tree it finds.

ADD_MODULE=info,status,proxy

Specifies a list of optional Apache modules to configure into the server, delimited by a comma. For example, this command will enable the mod_info, mod_status, and mod_proxy modules:

% perl Makefile.PL ADD_MODULE=info,status,proxy

PREP_HTTPD=1

Tells mod_perl only to prepare Apache for building. Running the make command after this option is used will only build the Perl side of mod_perl. You will have to build httpd manually.

DYNAMIC=1

Tells mod_perl to build the Apache::* API extensions as shared libraries. The default action is to link these modules statically with the httpd executable. This can save some memory if you only occasionally use these API features. They are described briefly in this appendix and in more detail in Chapter 9, Perl API Reference Guide.

PERL_TRACE=1

This option enables runtime diagnostics for mod_perl. You will also need to set the MOD_PERL_TRACE environment variable at runtime in order to see the diagnostics.

PERL_DESTRUCT_LEVEL={1,2}

When the Perl interpreter is shutting down during server shutdown, this level enables additional checks 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.

PERL_DEBUG=1

This options 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.

Options for activating phase callback hooks

PERL_DISPATCH=1

Enables the PerlDispatchHandler directive.

PERL_CHILD_INIT=1

Enables the PerlChildInitHandler directive.

PERL_CHILD_EXIT=1

Enables the PerlChildExitHandler directive.

PERL_INIT=1

Enables the PerlInitHandler directive.

PERL_POST_READ_REQUEST=1

Enables the PerlPostReadRequestHandler directive.

PERL_TRANS=1

Enables the PerlTransHandler directive.

PERL_HEADER_PARSER=1

Enables the PerlHeaderParserHandler directive.

PERL_ACCESS=1 s

Enables the PerlAccessHandler directive.

PERL_AUTHEN=1

Enables the PerlAuthenHandler directive.

PERL_AUTHZ=1

Enables the PerlAuthzHandler directive.

PERL_TYPE=1

Enables the PerlTypeHandler directive.

PERL_FIXUP=1

Enables the PerlFixupHandler directive.

PERL_HANDLER=1

Enables the PerlHandler directive. (This directive is enabled by default.)

PERL_LOG=1

Enables the PerlLogHandler directive.

PERL_CLEANUP=1

Enables the PerlCleanupHandler directive.

Options for activating standard API features

PERL_FILE_API=1

Enables the Apache::File class.

PERL_TABLE_API=1

Enables the Apache::Table class.

PERL_LOG_API=1

Enables the Apache::Log class.

PERL_URI_API=1

Enables the Apache::URI class.

PERL_UTIL_API=1

Enables the Apache::Util class.

PERL_CONNECTION_API=1

Enables the Apache::Connection class. This class is enabled by default. Set the option to 0 to disable it.

PERL_SERVER_API=1

Enables the Apache::Server class. This class is enabled by default. Set the option to 0 to disable it.

APACHE_HEADER_INSTALL=1

Disables the installation of Apache header files. This option is enabled by default. Set the option to 0 to disable it.

Options for activating miscellaneous features

PERL_SECTIONS=1

Enables <Perl> configuration sections.

PERL_SSI=1

Enables the perl directive in the mod_include module.

PERL_DIRECTIVE_HANDLERS=1

Enables the Perl configuration directive API, including the Apache::ModuleConfig and Apache::CmdParms classes. This API is described in Chapter 8, Customizing the Apache Configuration Process.

PERL_STACKED_HANDLERS=1

Enables the "Stacked Handlers" feature.

PERL_METHOD_HANDLERS=1

Enables the "Method Handlers" feature.

EVERYTHING=1

This attribute enables all phase callback handlers, all API modules, and all miscellaneous features.

EXPERIMENTAL=1

This attribute enables all "experimental" features, which are usually under development and discussion on the modperl mailing list.