 |  |
| |
We assume, to begin with, that you are running on some sort of Unix machine, you have downloaded the Apache sources, built Apache, and that now you are going to add mod_perl.
The first thing to do is to get the mod_perl sources. Go to http://apache.org. In the list of links to the left of the screen you should see "mod_perl": select it. This takes you to http://perl.apache.org, the home page of the Apache/Perl Integration Project.
The first step is to select "Download," which then offers you a number of ways of getting to the executables. The simplest is to download from http://perl.apache.org/dist (linked as this site), but there are many alternatives. When we did it, the gzipped tar on offer was mod_perl-1.24.tar.gz — no doubt the numbers will have moved on by the time this is in print. This gives you about 600 KB of file that you get onto your Unix machine as best you can.
It is worth saving it in a directory near your Apache, because this slightly simplifies the business of building and installing it later on. We keep all this stuff in /usr/src/mod_perl, near where the Apache sources were already stored. We created a directory for mod_perl, moved the downloaded file into it, unzipped it with gunzip <filename>, and extracted the files with tar xvf <filename> so we have: /usr/src/apache/mod_perl/mod_perl-1.24, and not very far away: /usr/src/apache/apache_1.3.26.
Go into /usr/src/apache/mod_perl/mod_perl-1.24, and read INSTALL. The simple way of installing the package offers no surprises:
perl Makefile.PL make make test make install
For some reason, we found we had to repeat the whole process two or three times before it all went smoothly without error messages. So if you get obscure complaints, go back to the top and try again before beginning to scream.
Some clever things happen, culminating in a recompile of Apache. This works because the mod_perl makefile looks for the most recent Apache source in a neighboring directory. If you want to take this route, make sure that the right version is in the right place. If the installation process cannot find an Apache source directory, it will ask you where to look. This process generates a new httpd in /usr/src/apache/apache_1.3.26/src, which needs to be copied to wherever you keep your executables — in our case, /usr/local/bin.
To make experimentation easier, you might not want to overwrite the old, non-mod_perl httpd, so save the new one as httpd.perl. The change of size is striking: up from 480 KB to 1.2 MB. Luckily, we will only have to load it once when Apache starts up.
In The mod_perl Guide, Bekman gives five different recipes for installing mod_perl.
The first is a variant on the method we gave earlier, with the difference that various makefile parameters allow you to control the operation more precisely:
perl Makefile.PL APACHE_SRC=../../apache_x.x.x/src DO_HTTPD=1 EVERYTHING=1
The x s represent numbers that describe your source for Apache. DO_HTTPD=1 creates a new Apache executable, and EVERYTHING=1 turns all the other parameters on. For a complete list and their applications, see the documentation. This seems to have much the same effect as simply running:
perl Makefile.PL
If you want to use the one-step, predigested method of creating APACHE using the APACI, you can do that with this:
perl Makefile.PL APACHE_SRC=../../apache_x.x.x/src DO_HTTPD=1 \ EVERYTHING=1 USE_APACI=1
Note that you must use \ to continue lines.
Two more recipes concern DSOs (Dynamic Shared Objects), that is, executables that Apache can load when needed and unload when not. We don't suggest that you use these for serious business, firstly because we are not keen on DSOs, and secondly because mod_perl is not a module you want to load and unload. If you use it at all, you are very likely to need it all the time.
So far so good, but in real life you may very well want to link more than one module into your Apache. The idea here is to set up all the modules in the Apache source tree before building it.
Download both source files into the appropriate places on your machine. Go into the mod_perl directory, and prepare the src/modules/perl subdirectory in the Apache source tree with the following:
perl Makefile.PL APACHE_SRC=../../apache_x.x.x/src \ NO_HTTPD=1 \ USE_APACI=1 \ PREP_HTTPD=1 \ EVERYTHING=1 \ make make test make install
The PREP_HTTPD option forces the preparation of the Apache Perl tree, but no build yet.
Having prepared mod_perl, you can now also prepare other modules. Later on we will demonstrate this by including mod_PHP.
When everything is ready, build the new Apache by going into the.../src directory and typing:
./configure --activate-module=src/modules/perl/libperl.a [and similar for other modules] make
Having built mod_perl, you should then test the result with make test. This process does its own arcane stuff, skipping various tests that are inappropriate for your platform. Hopefully it ends with the cheerful message "All tests successful..." If it finds problems, it writes them to the file ...t/logs/error_log. You can now do make install on the Perl side — and again on the Apache side — and copy the new httpd, perhaps as httpd.perl to the directory where your executables live — as described earlier.
Wherever there is Perl, there are "gotchas" — the invisible traps that nullify your best efforts — and there are a few lurking here.
If you use DO_HTTPD=1 or NO_HTTPD and don't use APACHE_SRC, then the Apache build will take place in the first Apache directory found, rather than the one with the highest release number.
If you are using Apache::Registry scripts (see later), line numbers will be wrongly reported in the error_log file. To get the correct numbers — or at least, an approximation to them, use PERL_MARK_WHERE=1. It is hard to see why anyone would prefer wrong line numbers, but this is part of the richness of the world of Perl.
If you use backslashes to indicate line breaks in the argument list to Makefile.PL and you are running the tcsh shell, the backslashes will be stripped out, and all the parameters after the first backslash will be ignored.
If you put the mod_perl directory inside the Apache directory, everything will go horribly wrong.
If you escaped these gotchas, don't be afraid that you have missed the fun: there are more to come. Building software the first time is a challenge, and one makes the effort to get it right.
Building it again, perhaps months or even years later, usually happens after some other drama, like a dead hard disk or a move to a different machine. At this stage one often has other things to think about, and repeating the build from memory can often be painful. mod_perl offers a civilized way of storing the configuration by making Makefile.PL look for parameters in the file makepl_args.mod_perl — you can put your parameters there the first time around and just run perl Makefile.PL. However, any command-line parameters will override those in the file.
One can always achieve this effect with any perl script under Unix by running:
perl Makefile.PL `cat ~/.build_parameters`
cat and the backticks cause the contents of the file build parameters to be extracted and passed as arguments to Makefile.PL
|  | |
| 17.2. mod_perl Documentation |  | 17.4. Modifying Your Scripts to Run Under mod_perl |
Copyright © 2003 O'Reilly & Associates. All rights reserved.