home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam  

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.


   Show Contents   Previous Page   Next Page

Appendix B - Building and Installing mod_perl / Standard Installation
Makefile.PL Options for mod_perl

In this section...

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


   Show Contents   Go to Top   Previous Page   Next Page

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

   Show Contents   Go to Top   Previous Page   Next Page

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.

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.
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.
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"
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.
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.
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.

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.
When building against a mod_ssl enabled server, this option tells Apache where to look for SSL include and lib subdirectories.
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.
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
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.
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.
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.
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.
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

   Show Contents   Go to Top   Previous Page   Next Page

The following Makefile.PL options enable handling of the various phases of the Apache request cycle. The significance of these phases is explained in previous chapters. Unless specified otherwise, these options are all disabled by default. Specifying EVERYTHING=1 will enable them en masse.
Enables the PerlDispatchHandler directive.
Enables the PerlChildInitHandler directive.
Enables the PerlChildExitHandler directive.
Enables the PerlInitHandler directive.
Enables the PerlPostReadRequestHandler directive.
Enables the PerlTransHandler directive.
Enables the PerlHeaderParserHandler directive.
Enables the PerlAccessHandler directive.
Enables the PerlAuthenHandler directive.
Enables the PerlAuthzHandler directive.
Enables the PerlTypeHandler directive.
Enables the PerlFixupHandler directive.
Enables the PerlHandler directive. (This directive is enabled by default.)
Enables the PerlLogHandler directive.
Enables the PerlCleanupHandler directive.

Options for activating standard API features

   Show Contents   Go to Top   Previous Page   Next Page

These options enable various standard features of the API, which are described in Chapter 9. While not absolutely needed, they're very handy and there's little penalty for including them. Unless specified otherwise, these options are all disabled by default. The EVERYTHING=1 or DYNAMIC=1 options will enable them all.
Enables the Apache::File class.
Enables the Apache::Table class.
Enables the Apache::Log class.
Enables the Apache::URI class.
Enables the Apache::Util class.
Enables the Apache::Connection class. This class is enabled by default. Set the option to 0 to disable it.
Enables the Apache::Server class. This class is enabled by default. Set the option to 0 to disable it.
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

   Show Contents   Go to Top   Previous Page   Next Page

These options enable or disable a variety of features that you may or may not need. They are disabled by default unless EVERYTHING=1 is specified.
Enables <Perl> configuration sections.
Enables the perl directive in the mod_include module.
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.
Enables the "Stacked Handlers" feature.
Enables the "Method Handlers" feature.
This attribute enables all phase callback handlers, all API modules, and all miscellaneous features.
This attribute enables all "experimental" features, which are usually under development and discussion on the modperl mailing list.
   Show Contents   Go to Top   Previous Page   Next Page
Copyright 1999 by O'Reilly & Associates, Inc.