|
Show Contents Previous Page Next Page
Chapter 2 - A First Module
Installing mod_perl
In this section...
|
In order to use the Perl API, you'll need to download and install mod_perl
if you haven't done so already. This section will describe the simplest way
to do this. If you've already installed mod_perl you'll want to
skip this section or jump directly to Appendix B,
Building and Installing mod_perl, where we give you the lowdown
on mod_perl's advanced installation options.
If you are a Win32 user, you can skip to the section "Win32
Installation" and download the precompiled ApacheModulePerl.dll
loadable module. We'll show you how to activate ApacheModulePerl.dll
at the end of the section.
mod_perl is part of the CPAN archive. FTP to a CPAN site close
to you and enter the directory modules/by-module/Apache/. Download
the file mod_perl-X.XX.tar.gz, where X.XX is the highest
version number you find.
It is easiest to build mod_perl when it is located at the same
level as the Apache source tree. Change your working directory to the source
directory of the server root, and unpack the mod_perl distribution
using the gunzip and tar tools:4
% cd ~www/build % gunzip -c mod_perl-X.XX.tar.gz | tar xvf - mod_perl-/t/ mod_perl-/t/docs/ mod_perl-/t/docs/env.iphtml mod_perl-/t/docs/content.shtml mod_perl-/t/docs/error.txt .... % cd mod_perl-X.XX
Now, peruse the README and INSTALL files located
in the mod_perl directory. These files contain late-breaking news,
installation notes, and other information.
The next step is to configure, build, and install mod_perl. Several
things happen during this process. First, an installation script named Makefile.PL
generates a top-level Makefile and runs Apache's configure
script to add mod_perl to the list of C modules compiled into the
server. After this, you run make to build the mod_perl
object file and link it into a new version of the Apache server executable.
The final steps of the install process are to test this new executable and,
if it checks out, to move mod_perl's support files and documentation
into the Perl library directory.
If you have other third-party modules to add to Apache, such as PHP, you can
add them during the mod_perl build process by providing arguments
to the installation script that will be passed through to Apache's configure.
Alternatively, you can separate the mod_perl build from the Apache
build and run configure yourself.
The outline of the whole process is as follows:
perl Makefile.PL # run installation script make # make httpd executable make test # run tests (optional) make install # install mod_perl
The perl Makefile.PL line is supplemented by a series
of tag=value pairs that control a bewildering array of options. The full list
of options is given in Appendix B. Most options
are concerned with activating handlers for various phases of the HTTP transaction.
For example, to enable the handlers for the authentication and log phases (which
we explain in more detail later), you would configure mod_perl
with this command:
perl Makefile.PL PERL_LOG=1 PERL_AUTHEN=1
You'll probably want to enable all the handlers in order to get access to the full Apache API. The easiest way to do this is by issuing this command:
perl Makefile.PL EVERYTHING=1 APACHE_PREFIX=/usr/local/apache
EVERYTHING=1 enables all the handlers and activates a variety
of other neat features, including server-side includes written in Perl and support
for <Perl> sections in the Apache configuration files. Providing
an APACHE_PREFIX option with the location of the server root allows
the install script to automatically copy the new version of the Apache server
and its support files into the server root. If you don't provide this option,
you can still copy the files manually after they're built. More details on these
options can be found in the mod_perl manual pages and in Appendix B.
Other configuration options are not involved in building mod_perl
itself, but are passed through to Apache's configure script to
control other aspects of Apache's configuration. The most frequently used of
these is ADD_MODULE, which accepts a comma-delimited list of additional
modules to compile into Apache. Use this if there are optional modules such
as the mod_status and mod_proxy that you wish to build
Apache with.
When run, Makefile.PL will search the immediate vicinity for
the Apache source tree. When it finds it, it will print the path and ask you
for confirmation. If the search fails, Makefile.PL will prompt
you to type in the path. You should type in the full path to the Apache src
directory. Next you'll be asked whether httpd should be built during
the make. You should answer "y" to this question. At this point,
Makefile.PL will run Apache's own configure script
and you'll see a series of messages from configure.
After running configure, Makefile.PL will display
a list of the options that are enabled. Then it checks for the presence of the
LWP and CGI.pm packages and warns you if one or both are absent or outdated.
Neither package is essential to successfully install mod_perl,
but LWP is required to run the regression tests. If you wish, you can install
mod_perl without running the tests. If at some later date you wish
to run the regression tests, just install LWP and run Makefile.PL
again.
Here's an example configuration session:
% perl Makefile.PL EVERYTHING=1 APACHE_PREFIX=/usr/local/apache ReadLine support enabled Configure mod_perl with ../apache_1.3.3/src ? [y] y Shall I build httpd in ../apache_1.3.3/src for you? [y] y cp src/modules/perl/perl_PL.h ../apache_1.3.3/src/modules/perl/perl_PL.h ... many similar lines deleted ... Will run tests as User: 'johnd' Group: 'users' Configuring for Apache, Version 1.3.3 + activated perl module (modules/perl/libperl.a) Creating Makefile Creating Configuration.apaci in src + id: mod_perl/1.16 + id: Perl/5.00404 (linux) [perl] ... many similar lines deleted ...
PerlDispatchHandler.........enabled
PerlChildInitHandler........enabled
PerlChildExitHandler........enabled
PerlPostReadRequestHandler..enabled
PerlTransHandler............enabled
... many similar lines deleted ...
Writing Makefile for Apache Writing Makefile for Apache::Connection Writing Makefile for Apache::Constants Writing Makefile for Apache::File Writing Makefile for Apache::Log Writing Makefile for Apache::ModuleConfig Writing Makefile for Apache::Server Writing Makefile for Apache::Symbol Writing Makefile for Apache::Tie Writing Makefile for Apache::URI Writing Makefile for Apache::Util Writing Makefile for mod_perl
If something goes wrong during configuration, there should be a diagnostic warning that will point to the problem (for example, "no Apache source directory found"). Correct the problem and try again. If you need to pass a long series of configuration options, you will probably find it convenient to turn the configuration command into a short shell script along these lines:
#!/bin/sh
# mod_perl configuration 9/28/98
perl Makefile.PL EVERYTHING=1 \
ADD_MODULE=unique_id,status,proxy,info \
APACHE_PREFIX=/usr/local/apache
This makes it easy to edit the configuration and run the command again. Plus,
you'll have a record of the configuration you used the next time you upgrade
Apache or mod_perl.
The next step is to run make. A new Apache server with an integrated
mod_perl will now be built in front of your eyes. At the end of
the process you'll find a brand-new httpd in the Apache source
tree. It will look just like the old one, except significantly larger (fourfold
increases in size are not uncommon). This is because the Perl interpreter has
just been made part of httpd. It's unlikely that you'll encounter
any problems during the make if you were previously successful in compiling
both Apache and Perl, but if the make process does abort because of a fatal
error, you'll have to do some detective work to determine where things went
wrong. It helps to redirect the messages from the build process into a file
for later perusal:
% make |& tee make.out
You can now run the optional tests. This step is recommended. During the tests the newly built server will be launched and a series of scripts will barrage it with requests to determine whether it produces the expected answers. Because the server listens to a nonstandard port during the tests, you can run the tests on the same machine that already hosts a web server. You do not need to be the super-user (or Administrator) in order to run the tests; however, you do need to have the LWP library installed. Otherwise, the tests will abort at an early stage.
To run the tests, run make test from within the mod_perl
directory:
% make test
cp t/conf/mod_perl_srm.conf t/conf/srm.conf
../apache-1.3/src/httpd -f `pwd`/t/conf/httpd.conf -X -d `pwd`/t &
httpd listening on port 8529
will write error_log to: t/logs/error_log
letting apache warm up...done
/opt/perl5/bin/perl t/TEST 0
modules/actions.....ok
modules/cgi.........ok
modules/constants...ok
modules/embperl.....ok
modules/eperl.......ok
... many similar lines deleted ...
All tests successful. Files=35, Tests=350, 35 secs (26.13 cusr 2.56 csys = 28.69 cpu) kill `cat t/logs/httpd.pid` rm -f t/logs/httpd.pid rm -f t/logs/error_log
Don't worry about any tests that are skipped. This just indicates that you
haven't installed one of the optional mod_perl features. You can
always install the feature and rerun the tests later. Any messages about failed
tests, however, are cause for concern. If you see such a message, you should
rerun the tests with the verbose flag (make test TEST_VERBOSE=1).
You can try to track down the problem yourself, or post the results to the mod_perl
mailing list (which we'll discuss presently).
Provided that all goes well, you can now finish the installation. You may
need to have super-user or Administrator privileges in order to do this. Run
make install to move mod_perl's support files and
documentation to the main Perl library directory. You will see a long series
of copy commands. If you specified the APACHE_PREFIX option, then
make install will also install the Apache side of things, including
httpd, its configuration files, document, and log trees. Otherwise,
change to the Apache source directory and copy the new httpd by
hand to your server root directory. Make sure to keep a copy of the old httpd
binary around, just in case.
For Windows users, download the ApacheModulePerl binary distribution from
CPAN, in the subdirectory authors/Jeffrey_Baker/. The Win32 distribution
file uses a very long name, following the CPAN conventions for binary distribution
file names.5 Make sure you download the one with
the highest version number, and unpack it with your favorite ZIP file extractor.
Now copy the contents of the lib subdirectory into your Perl
library tree, usually C:\perl5\lib (be careful to copy the contents
of lib, not the directory itself, or you run the risk of clobbering
your Perl library tree!). Next, move the file Apache-Mod-ule-Perl.dll
to the Apache loadable modules directory, usually C:\Apache\modules.
Open httpd.conf with your favorite text editor and add the following
line:
LoadModule perl_module modules/ApacheModulePerl.dll
Kill and restart the server if it's already running. mod_perl
should now be installed. Should you wish to build mod_perl from
source code, consult the INSTALL.win32 file located at the top
of the mod_perl distribution directory.
Copyright © 1999 by O'Reilly & Associates, Inc.
