Chapter 3. Installing mod_perl
In Chapter 2, we presented a basic mod_perl
installation. In this chapter, we will talk about various ways in
which mod_perl can be installed (using a variety of installation
parameters), as well as prepackaged binary installations, and more. Chapter 2 showed you the following
commands to
build and install a basic mod_perl-enabled Apache server on almost
any standard flavor of Unix. First, download
http://www.apache.org/dist/httpd/apache_1.3.xx.tar.gz
and
http://perl.apache.org/dist/mod_perl-1.xx.tar.gz.
Then, issue the following commands: panic% cd /home/stas/src
panic% tar xzvf apache_1.3.xx.tar.gz
panic% tar xzvf mod_perl-1.xx.tar.gz
panic% cd mod_perl-1.xx
panic% perl Makefile.PL APACHE_SRC=../apache_1.3.xx/src \
DO_HTTPD=1 USE_APACI=1 EVERYTHING=1
panic% make && make test
panic# make install
panic# cd ../apache_1.3.xx
panic# make install
As usual, replace 1.xx and
1.3.xx with the real version numbers of mod_perl
and Apache, respectively. You can then add a few configuration lines to
httpd.conf (the Apache configuration file),
start the server, and enjoy mod_perl. This should work just fine.
Why, then, are you now reading a 50-page chapter on installing
mod_perl? You're reading this chapter for the same reason you
bought this book. Sure, the instructions above will get you a working
version of mod_perl. But the average reader of this book
won't want to stop there. If you're
using mod_perl, it's because you want to improve the
performance of your web server. And when you're
concerned with performance, you're always looking
for ways to eke a little bit more out of your server. In essence,
that's what this book is about: getting the most out
of your mod_perl-enabled Apache server. And it all starts at the
beginning, with the installation of the software. In the basic mod_perl installation, the
parameter
EVERYTHING=1 enables a lot of options for you,
whether you actually need them or not. You may want to enable only
the required options, to squeeze even more juice out of mod_perl. You
may want to build mod_perl as a loadable object instead of compiling
it into Apache, so that it can be upgraded without rebuilding Apache
itself. You may also want to install other Apache components, such as
PHP or mod_ssl, alongside mod_perl. To accomplish any of these tasks, you will need to understand various
techniques for mod_perl configuration and building. You need to know
what configuration parameters are available to you and when and how
to use them. As with Perl, in mod_perl simple things are simple. But when you need
to accomplish more complicated tasks, you may have to invest some
time to gain a deeper understanding of the process. In this chapter,
we will take the following route. We'll start with a
detailed explanation of the four stages of the mod_perl installation
process, then continue on with the different paths each installation
might take according to your goal, followed by a few copy-and-paste
real-world installation scenarios. Toward the end of the chapter we
will show you various approaches that might make the installation
easier, by automating most of the steps. Finally,
we'll cover some of the general issues that new
users might stumble on while installing mod_perl.
3.1. Configuring the Source
Before building and installing mod_perl you
will have to configure it, as you would configure any other Perl
module:
panic% perl Makefile.PL [parameters].
Perl Installation Requirements
Make sure you have Perl installed! Use the latest stable
version, if possible. To determine
your version of Perl, run the following command on the command line:
panic% perl -v
You will need at least Perl Version 5.004. If you
don't have it, install it. Follow the instructions
in the distribution's INSTALL
file. The only thing to watch for is that during the configuration
stage (while running ./Configure) you make sure
you can dynamically load Perl module extensions. That is, answer
YES to the following question:
Do you wish to use dynamic loading? [y]
|
In this section, we will explain each of the parameters accepted by
the Makefile.PL file for mod_perl First,
however, lets talk about how the mod_perl configuration dovetails
with Apache's configuration. The source
configuration mechanism in Apache 1.3 provides four major features
(which of course are available to mod_perl):
-
Apache
modules can use per-module
configuration scripts to link themselves into
the Apache configuration process. This feature lets you automatically
adjust the configuration and build parameters from the Apache module
sources. It is triggered by
ConfigStart/ConfigEnd sections inside
modulename.module files (e.g., see the file
libperl.module in the mod_perl distribution).
-
The APache AutoConf-style
Interface (APACI)
is the top-level
configure script from Apache 1.3; it provides a
GNU Autoconf-style interface to the
Apache configuration process. APACI is useful for configuring the
source tree without manually editing any
src/Configuration files. Any parameterization
can be done via command-line options to the
configure script. Internally, this is just a
nifty wrapper over the old src/Configure script.
Since Apache 1.3, APACI is the best way to install mod_perl as
cleanly as possible. However, the complete Apache 1.3 source
configuration mechanism is available only under Unix at this
writing—it doesn't work on Win32.
-
Dynamic shared object (DSO)
support is one of the most
interesting features in Apache 1.3. It allows Apache
modules to be built as so-called DSOs
(usually named modulename.so), which can be
loaded via the
LoadModule
directive in Apache's
httpd.conf file. The benefit is that the modules
become part of the httpd executable only on
demand; they aren't loaded into the address space of
the httpd executable until the user asks for
them to be. The benefits of DSO support are most evident in relation
to memory consumption and added flexibility (in that you
won't have to recompile your
httpd each time you want to add, remove, or
upgrade a module).
The DSO mechanism is provided by Apache's
mod_so
module, which needs to be compiled into the
httpd binary with:
panic% ./configure --enable-module=so
The usage of any —enable-shared option
automatically implies an —enable-module=so
option, because the bootstrapping module mod_so is
always needed for DSO support. So if, for example, you want the
module mod_dir to be built as a DSO, you can
write:
panic% ./configure --enable-shared=dir
and the DSO support will be added automatically.
-
The APache eXtension
Support tool (APXS)
is a tool from Apache 1.3 that can be used to build an Apache module
as a DSO even outside the Apache source tree. APXS
is to Apache what
MakeMaker
and XS are to Perl.[16] It knows the
platform-dependent build parameters for making DSO files and provides
an easy way to run the build commands with them.
[16]MakeMaker allows easy, automatic
configuration, building, testing, and installation of Perl modules,
while XS allows you to call functions implemented
in C/C++ from Perl code.
Pros and Cons of Building mod_perl as a DSO
As of Apache 1.3, the configuration system
supports two optional features for taking advantage of the modular
DSO approach: compilation of the Apache core program into a DSO
library for shared usage, and compilation of the Apache modules into
DSO files for explicit loading at runtime.
Should you build mod_perl as a DSO? Let's study the
pros and cons of this installation method, so you can decide for
yourself.
Pros:
-
The server package is
more flexible because the actual
server executable can be assembled at runtime via
LoadModule configuration commands in
httpd.conf instead of via
AddModule commands in the
Configuration file at build time. This allows
you to run different server instances (e.g., standard and SSL
servers, or servers with and without mod_perl) with only one Apache
installation; the only thing you need is different configuration
files (or, by judicious use of IfDefine, different
startup scripts).
-
The server package can
easily be extended with
third-party
modules even
after installation. This is especially helpful for vendor package
maintainers who can create an Apache core package and additional
packages containing extensions such as PHP, mod_perl, mod_fastcgi,
etc.
-
DSO support allows easier Apache
module prototyping, because with the
DSO/APXS pair you can work outside the Apache
source tree and need only an apxs -i command
followed by an apachectl restart to bring a new
version of your currently developed module into the running Apache
server.
Cons:
-
The DSO mechanism cannot be used on every platform,
because not all operating systems support shared libraries.
-
The server starts up
approximately 20% slower because of the
overhead of the symbol-resolving the Unix loader now has to do.
-
The server runs approximately 5% slower on some platforms, because
position-independent code (PIC) sometimes needs complicated assembler
tricks for relative addressing, which are not necessarily as fast as
those for absolute addressing.
-
Because DSO modules cannot be linked against other DSO-based
libraries (ld -lfoo) on all platforms (for
instance, a.out-based platforms usually
don't provide this functionality, while ELF-based
platforms do), you cannot use the DSO mechanism for all types of
modules. In other words, modules compiled as DSO files are restricted
to use symbols only from the Apache core, from the C library
(libc) and from any other dynamic or static
libraries used by the Apache core, or from static library archives
(libfoo.a) containing position-independent code.
The only way you can use other code is to either make sure the Apache
core itself already contains a reference to it, load the code
yourself via dlopen( ), or enable the
SHARED_CHAIN rule while building Apache (if your
platform supports linking DSO files against DSO libraries). This,
however, won't be of much significance to you if
you're writing modules only in Perl.
-
Under some platforms (e.g., many SVR4 systems), there is no way to
force the linker to export all global symbols for use in DSOs when
linking the Apache httpd executable program. But
without the visibility of the Apache core symbols, no standard Apache
module could be used as a DSO. The only workaround here is to use the
SHARED_CORE feature, because in this way the
global symbols are forced to be exported. As a consequence, the
Apache src/Configure script automatically
enforces SHARED_CORE on these platforms when DSO
features are used in the Configuration file or
on the configure command line.
|
Together, these four features provide a way to integrate mod_perl
into Apache in a very clean and smooth way. No patching of the Apache
source tree is usually required, and for APXS
support, not even the Apache source tree is needed.
To benefit from the above features, a hybrid build environment was
created for the Apache side of mod_perl. See Section 3.5, later in this chapter, for details.
Once the overview of the four building steps is complete, we will
return to each of the above configuration mechanisms when describing
different installation passes.
3.1.1. Controlling the Build Process
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.
3.1.2. Activating Callback Hooks
A callback hook (also known simply as a
callback) is a reference to a subroutine. In
Perl, we create subroutine references with
the following syntax:
$callback = \&subroutine;
In this example, $callback contains a reference to
the subroutine called subroutine. Another way to
create a callback is to use an anonymous subroutine:
$callback = sub { 'some code' };
Here, $callback contains a reference to the
anonymous subroutine. Callbacks are used when we want some action
(subroutine call) to occur when some event takes place. Since we
don't know exactly when the event will take place,
we give the event
handler
a reference to the subroutine we want to be executed. The handler
will call our subroutine at the right time, effectively
calling back that subroutine.
By default, most of the callback hooks except for
PerlHandler,
PerlChildInitHandler,
PerlChildExitHandler,
PerlConnectionApi, and
PerlServerApi are turned off. You may enable them
via options to Makefile.PL.
Here is the list of available hooks and the
parameters that enable them. The
Apache request prcessing phases were explained in Chapter 1.
Directive/Hook Configuration Option
--------------------------------------------------------
PerlPostReadRequestHandler PERL_POST_READ_REQUEST
PerlTransHandler PERL_TRANS
PerlInitHandler PERL_INIT
PerlHeaderParserHandler PERL_HEADER_PARSER
PerlAuthenHandler PERL_AUTHEN
PerlAuthzHandler PERL_AUTHZ
PerlAccessHandler PERL_ACCESS
PerlTypeHandler PERL_TYPE
PerlFixupHandler PERL_FIXUP
PerlHandler PERL_HANDLER
PerlLogHandler PERL_LOG
PerlCleanupHandler PERL_CLEANUP
PerlChildInitHandler PERL_CHILD_INIT
PerlChildExitHandler PERL_CHILD_EXIT
PerlDispatchHandler PERL_DISPATCH
As with any parameters that are either defined or not, use
OPTION_FOO=1 to enable them (e.g.,
PERL_AUTHEN=1).
To enable all callback hooks, use:
ALL_HOOKS=1
There are a few more hooks that won't be enabled by
default, because they are experimental.
If you are using:
panic% perl Makefile.PL EVERYTHING=1 ...
it already includes the ALL_HOOKS=1 option.
3.1.3. Activating Standard API Features
The following options enable
various standard features
of the mod_perl API. While not absolutely needed,
they're very handy and there's
little penalty in including them. Unless specified otherwise, these
options are all disabled by default. The
EVERYTHING=1 or DYNAMIC=1
options will enable them en masse. If in doubt, include these.
- PERL_FILE_API=1
Enables the Apache::File class, which helps with
the handling of files under mod_perl.
- PERL_TABLE_API=1
Enables the Apache::Table class, which provides
tied access to the Apache Table structure (used for HTTP headers,
among others).
- PERL_LOG_API=1
Enables the Apache::Log class. This class allows
you to access Apache's more advanced logging
features.
- PERL_URI_API=1
Enables the Apache::URI class, which deals with
the parsing of URIs in a similar way to the Perl
URI::URL module, but much faster.
- PERL_UTIL_API=1
Enables the Apache::Util class, allowing you to
use various functions such as HTML escaping or date parsing, but
implemented in C.
- 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.
Please refer to Lincoln Stein and Doug MacEachern's
Writing Apache Modules with Perl and C
(O'Reilly) for more information about the Apache
API.
3.1.4. Enabling Extra Features
mod_perl
comes with a number of other
features. Most of them are disabled by default. This is the list of
features and options to enable them:
-
<Perl>sections give you a way to configure
Apache using Perl code in the httpd.conf file
itself. See Chapter 4 for more information.
panic% perl Makefile.PL PERL_SECTIONS=1 ...
-
With the PERL_SSI option, the mod_include module can be
extended to include a #perl directive.
panic% perl Makefile.PL PERL_SSI=1
By enabling PERL_SSI, a new
#perl element is added to the standard mod_include
functionality. This element allows server-side includes to call Perl
subroutines directly. This feature works only when mod_perl is not
built as a DSO (i.e., when it's built statically).
-
If you develop an Apache module in Perl and you want to create custom
configuration directives[18] to be recognized in
httpd.conf, you need to use
Apache::ModuleConfig and
Apache::CmdParms. For these modules to work, you
will need to enable this option: [18]See Chapters 8 and 9 of
Writing Apache Modules with Perl and C
(O'Reilly).
panic% perl Makefile.PL PERL_DIRECTIVE_HANDLERS=1
-
The stacked handlers feature explained in Chapter 4 requires this parameter to be enabled:
panic% perl Makefile.PL PERL_STACKED_HANDLERS=1
-
The method handlers feature discussed in Chapter 4
requires this parameter to be enabled:
panic% perl Makefile.PL PERL_METHOD_HANDLERS=1
-
To enable all phase callback handlers, all API modules, and all
miscellaneous features, use the
"catch-all" option we used when we
first compiled mod_perl:
panic% perl Makefile.PL EVERYTHING=1
3.1.5. Reusing Configuration Parameters
When you have to
upgrade the server,
it's sometimes hard to remember what parameters you
used in the previous mod_perl build. So it's a good
idea to save them in a file.
One way to save parameters is to create
a file (e.g.,
~/.mod_perl_build_options) with the following
contents:
APACHE_SRC=../apache_1.3.xx/src DO_HTTPD=1 USE_APACI=1 \
EVERYTHING=1
Then build the server with the following command:
panic% perl Makefile.PL `cat ~/.mod_perl_build_options`
panic% make && make test
panic# make install
But mod_perl has a standard method to perform this trick. If a file
named
makepl_args.mod_perl is found in the same
directory as the mod_perl build location, it will
be read in by Makefile.PL. Parameters supplied
at the command line will override the parameters given in this file.
The makepl_args.mod_perl file can also be
located in your home directory or in the ../
directory relative to the mod_perl distribution directory. The
filename can also start with a dot
(.makepl_args.mod_perl), so you can keep
it
nicely hidden along with the rest of the dot files in your home
directory. So, Makefile.PL will look for the
following files (in this order), using the first one it comes across:
./makepl_args.mod_perl
../makepl_args.mod_perl
./.makepl_args.mod_perl
../.makepl_args.mod_perl
$ENV{HOME}/.makepl_args.mod_perl
For example:
panic% ls -1 /home/stas/src
apache_1.3.xx/
makepl_args.mod_perl
mod_perl-1.xx/
panic% cat makepl_args.mod_perl
APACHE_SRC=../apache_1.3.xx/src
DO_HTTPD=1
USE_APACI=1
EVERYTHING=1
panic% cd mod_perl-1.xx
panic% perl Makefile.PL
panic% make && make test
panic# make install
Now the parameters from the makepl_args.mod_perl
file will be used automatically, as if they were entered directly.
In the sample makepl_args.mod_perl file in the
eg/ directory of the mod_perl distribution
package, you might find a few options enabling some experimental
features for you to play with, too!
If you are faced with a compiled Apache and no trace of the
parameters used to build it, you can usually still find them if
make clean was not run on the sources. You will
find the Apache-specific parameters in
apache_1.3.xx/config.status and the mod_perl
parameters in
mod_perl-1.xx/apaci/mod_perl.config.
3.1.6. Discovering Whether a Feature Was Enabled
mod_perl Version 1.25
introduced
Apache::MyConfig, which provides access to the various
hooks and features set when mod_perl was built. This circumvents the
need to set up a live server just to find out if a certain callback
hook is available.
To see whether some feature was built in or not, check the
%Apache::MyConfig::Setup hash. For example,
suppose we install mod_perl with the following options:
panic% perl Makefile.PL EVERYTHING=1
but the next day we can't remember which callback
hooks were enabled. We want to know whether the
PERL_LOG callback hook is available. One of the
ways to find an answer is to run the following code:
panic% perl -MApache::MyConfig -e 'print $Apache::MyConfig::Setup{PERL_LOG}'
If it prints 1, that means the
PERL_LOG callback hook is enabled (which it should
be, as EVERYTHING=1 enables them all).
Another approach is to configure
Apache::Status (see Chapter 9) and
run http://localhost/perl-status?hooks to check
for enabled hooks.
If you want to check for the existence of
various hooks within your handlers, you
can use the script shown in Example 3-1.
Example 3-1. test_hooks.pl
use mod_perl_hooks;
for my $hook (mod_perl::hooks( )) {
if (mod_perl::hook($hook)) {
print "$hook is enabled\n";
}
else {
print "$hook is not enabled\n";
}
}
You can also try to look at the symbols inside the
httpd executable with the help of
nm(1) or a similar utility. For example, if you
want to see whether you enabled PERL_LOG=1 while
building mod_perl, you can search for a symbol with the same name but
in lowercase:
panic% nm httpd | grep perl_log
08071724 T perl_logger
This shows that PERL_LOG=1 was enabled. But this
approach will work only if you have an unstripped
httpd binary. By default, make
install strips the binary before installing it, thus
removing the symbol names to save space. Use the
—without-execstrip ./configure option to
prevent stripping during the make install phase.
[19] [19]You might need the unstripped version for debugging
reasons too.
Yet another approach that will work in most cases is to try to use
the feature in question. If it wasn't configured,
Apache will give an error message.
3.1.7. Using an Alternative Configuration File
By default,
mod_perl provides its own
copy of the Configuration file to
Apache's configure utility. If
you want to pass it your own version, do this:
panic% perl Makefile.PL CONFIG=Configuration.custom
where
Configuration.custom is the pathname of the file
relative to the Apache source tree you build
against.
3.1.8. perl Makefile.PL Troubleshooting
During the configuration (perl
Makefile.PL) stage, you may encounter some of
these problems. To help you avoid them, let's study
them, find out why they happened, and discuss how to fix them.
3.1.8.1. A test compilation with your Makefile configuration failed...
When you see the
following error during the
perl Makefile.PL stage:
** A test compilation with your Makefile configuration
** failed. This is most likely because your C compiler
** is not ANSI. Apache requires an ANSI C Compiler, such
** as gcc. The above error message from your compiler
** will also provide a clue.
Aborting!
it's possible that you have a problem with a
compiler. It may be improperly installed or not installed at all.
Sometimes the reason is that your Perl executable was built on a
different machine, and the software installed on your machine is not
the same. Generally this happens when you install prebuilt packages,
such as rpm or deb. You may
find that the dependencies weren't properly defined
in the Perl binary package and you were allowed to install it even
though some essential packages were not installed.
The most frequent pitfall is a missing gdbm
library (see the next section).
But why guess, when we can actually see the real error message and
understand what the real problem is? To get a real error message,
edit the Apache src/Configure script. Around
line 2140, you should see a line like this:
if ./helpers/TestCompile sanity; then
Add the -v option, as follows:
if ./helpers/TestCompile -v sanity; then
and try again. Now you should get a useful error message.
3.1.8.2. Missing or misconfigured libgdbm.so
On some Red Hat Linux systems, you might
encounter a problem during the perl Makefile.PL
stage, when Perl was installed from an rpm
package built with the gdbm
library, but libgdbm
isn't actually installed. If this happens to you,
make sure you install it before proceeding with the build process.
You can check how Perl was built by running the perl
-V command:
panic% perl -V | grep libs
You should see output similar to this:
libs=-lnsl -lndbm -lgdbm -ldb -ldl -lm -lc -lposix -lcrypt
Sometimes the problem is even more obscure: you do have
libgdbm installed, but it's not
installed properly. Do this:
panic% ls /usr/lib/libgdbm.so*
If you get at least three lines, like we do:
lrwxrwxrwx /usr/lib/libgdbm.so -> libgdbm.so.2.0.0
lrwxrwxrwx /usr/lib/libgdbm.so.2 -> libgdbm.so.2.0.0
-rw-r--r-- /usr/lib/libgdbm.so.2.0.0
you are all set. On some installations, the
libgdbm.so symbolic link is missing, so you get
only:
lrwxrwxrwx /usr/lib/libgdbm.so.2 -> libgdbm.so.2.0.0
-rw-r--r-- /usr/lib/libgdbm.so.2.0.0
To fix this problem, add the missing symbolic link:
panic% cd /usr/lib
panic% ln -s libgdbm.so.2.0.0 libgdbm.so
Now you should be able to build mod_perl without any problems.
Note that you might need to prepare this symbolic link as well:
lrwxrwxrwx /usr/lib/libgdbm.so.2 -> libgdbm.so.2.0.0
with the command:
panic% ln -s libgdbm.so.2.0.0 libgdbm.so.2
Of course, if a new version of the libgdbm library
was released between the moment we wrote this sentence and the moment
you're reading it, you will have to adjust the
version numbers. We didn't use the usual
xx.xx version replacement here, to make it
easier to understand how the symbolic links should be set.
About the gdbm, db, and ndbm Libraries
If you need to have the dbm library linked in, you should know
that both the gdbm and db
libraries offer ndbm emulation, which is the
interface that Apache actually uses. So when you build mod_perl, you
end up using whichever library was linked first by the Perl
compilation. If you build Apache without mod_perl, you end up with
whatever appears to be be your ndbm library, which
will vary between systems, and especially Linux distributions. So you
may have to work a bit to get both Apache and Perl to use the same
library, and you are likely to have trouble copying the
dbm file from one system to another or even
using it after an upgrade.
|
3.1.8.3. Undefined reference to `PL_perl_destruct_level'
When manually building mod_perl using the shared library:
panic% cd mod_perl-1.xx
panic% perl Makefile.PL PREP_HTTPD=1
panic% make && make test
panic# make install
panic% cd ../apache_1.3.xx
panic% ./configure --with-layout=RedHat --target=perlhttpd
--activate-module=src/modules/perl/libperl.a
you might see the following output:
gcc -c -I./os/unix -I./include -DLINUX=2 -DTARGET=\"perlhttpd\"
-DUSE_HSREGEX -DUSE_EXPAT -I./lib/expat-lite `./apaci` buildmark.c
gcc -DLINUX=2 -DTARGET=\"perlhttpd\" -DUSE_HSREGEX -DUSE_EXPAT
-I./lib/expat-lite `./apaci` \
-o perlhttpd buildmark.o modules.o modules/perl/libperl.a
modules/standard/libstandard.a main/libmain.a ./os/unix/libos.a ap/libap.a
regex/libregex.a lib/expat-lite/libexpat.a -lm -lcrypt
modules/perl/libperl.a(mod_perl.o): In function `perl_shutdown':
mod_perl.o(.text+0xf8): undefined reference to `PL_perl_destruct_level'
mod_perl.o(.text+0x102): undefined reference to `PL_perl_destruct_level'
mod_perl.o(.text+0x10c): undefined reference to `PL_perl_destruct_level'
mod_perl.o(.text+0x13b): undefined reference to `Perl_av_undef'
[more errors snipped]
This happens when Perl was built statically linked, with no shared
libperl.a. Build a dynamically linked Perl (with
libperl.a) and the problem will
disappear.
| | | 2.9. References | | 3.2. Building mod_perl |
Copyright © 2003 O'Reilly & Associates. All rights reserved.
|