Installation Scenarios for Standalone mod_perl (Practical mod

3.5. Installation Scenarios for Standalone mod_perl

When building mod_perl, the mod_perl C source files that have to be compiled into the httpd executable usually are copied to the subdirectory src/modules/perl/ in the Apache source tree. In the past, to integrate this subtree into the Apache build process, a lot of adjustments were done by mod_perl's Makefile.PL. Makefile.PL was also responsible for the Apache build process.

This approach is problematic in several ways. It is very restrictive and not very clean, because it assumes that mod_perl is the only third-party module that has to be integrated into Apache.

A new hybrid build environment was therefore created for the Apache side of mod_perl, to avoid these problems. It prepares only the src/modules/perl/ subtree inside the Apache source tree, without adjusting or editing anything else. This way, no conflicts can occur. Instead, mod_perl is activated later (via APACI calls when the Apache source tree is configured), and then it configures itself.

There are various ways to build Apache with the new hybrid build environment (using USE_APACI=1):

Build Apache and mod_perl together, using the default configuration.
Build Apache and mod_perl separately, allowing you to plug in other third-party Apache modules as needed.
Build mod_perl as a DSO inside the Apache source tree using APACI.
Build mod_perl as a DSO outside the Apache source tree with APXS.

3.5.1. The All-in-One Way

If your goal is just to build and install Apache with mod_perl out of their source trees, and you have no interest in further adjusting or enhancing Apache, proceed as we described in Chapter 2:

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

This builds Apache statically with mod_perl, installs Apache under the default /usr/local/apache tree, and installs mod_perl into the site_perl hierarchy of your existing Perl installation.

3.5.2. Building mod_perl and Apache Separately

However, sometimes you might need more flexibility while building mod_perl. If you build mod_perl into the Apache binary (httpd) in separate steps, you'll also have the freedom to include other third-party Apache modules. Here are the steps:

Prepare the Apache source tree.

As before, first extract the distributions:

panic% tar xvzf apache_1.3.xx.tar.gz
panic% tar xzvf mod_perl-1.xx.tar.gz

Install mod_perl's Perl side and prepare the Apache side.
Next, install the Perl side of mod_perl into the Perl hierarchy and prepare the src/modules/perl/ subdirectory inside the Apache source tree:
```
panic% cd mod_perl-1.xx
panic% perl Makefile.PL \
    APACHE_SRC=../apache_1.3.xx/src \
    NO_HTTPD=1   \
    USE_APACI=1  \
    PREP_HTTPD=1 \
    EVERYTHING=1 \
    [...]
panic% make
panic# make install
```
The APACHE_SRC option sets the path to your Apache source tree, the NO_HTTPD option forces this path and only this path to be used, the USE_APACI option triggers the new hybrid build environment, and the PREP_HTTPD option forces preparation of the $APACHE_SRC/modules/perl/ tree but no automatic build.

This tells the configuration process to prepare the Apache side of mod_perl in the Apache source tree, but doesn't touch anything else in it. It then just builds the Perl side of mod_perl and installs it into the Perl installation hierarchy.

Note that if you use PREP_HTTPD as described above, to complete the build you must go into the Apache source directory and run make and make install.
Prepare other third-party modules.

Now you have a chance to prepare any other third-party modules you might want to include in Apache. For instance, you can build PHP separately, as you did with mod_perl.
Build the Apache package.

Now it's time to build Apache, including the Apache side of mod_perl and any other third-party modules you've prepared:
```
panic% cd apache_1.3.xx
panic% ./configure \
    --prefix=/path/to/install/of/apache \
    --activate-module=src/modules/perl/libperl.a \
    [...]
panic% make
panic# make install
```
You must use the —prefix option if you want to change the default target directory of the Apache installation. The —activate-module option activates mod_perl for the configuration process and thus also for the build process. If you choose —prefix=/usr/share/apache, the Apache directory tree will be installed in /usr/share/apache.
If you add other third-party components, such as PHP, include a separate —activate-module option for each of them. (See the module's documentation for the actual path to which —activate-module should point.) For example, for mod_php4:
```
--activate-module=src/modules/php4/libphp4.a
```
Note that the files activated by —activate-module do not exist at this time. They will be generated during compilation.

You may also want to go back to the mod_perl source tree and run make test (to make sure that mod_perl is working) before running make install inside the Apache source tree.
For more detailed examples on building mod_perl with other components, see Section 3.6.

3.5.3. When DSOs Can Be Used

If you want to build mod_perl as a DSO, you must make sure that Perl was built with the system's native malloc( ). If Perl was built with its own malloc( ) and -Dbincompat5005, it pollutes the main httpd program with free and malloc symbols. When httpd starts or restarts, any references in the main program to free and malloc become invalid, causing memory leaks and segfaults.

Notice that mod_perl's build system warns about this problem.

With Perl 5.6.0+ this pollution can be prevented by using -Ubincompat5005 or -Uusemymalloc for any version of Perl. However, there's a chance that -Uusemymalloc might hurt performance on your platform, so -Ubincompat5005 is likely a better choice.

If you get the following reports with Perl version 5.6.0+:

% perl -V:usemymalloc
usemymalloc='y';
% perl -V:bincompat5005
bincompat5005='define';

rebuild Perl with -Ubincompat5005.

For pre-5.6.x Perl versions, if you get:

% perl -V:usemymalloc
usemymalloc='y';

rebuild Perl with -Uusemymalloc.

Now rebuild mod_perl.

3.5.4. Building mod_perl as a DSO via APACI

We have already mentioned that the new mod_perl build environment (with USE_APACI) is a hybrid. What does that mean? It means, for instance, that you can use the same src/modules/perl/ configuration to build mod_perl as a DSO or not, without having to edit any files. To build libperl.so, just add a single option, depending on which method you used to build mod_perl.

libperl.so and libperl.a

The static mod_perl library is called libperl.a, and the shared mod_perl library is called libperl.so. Of course, libmodperl would have been a better prefix, but libperl was used because of prehistoric Apache issues. Be careful that you don't confuse mod_perl's libperl.a and libperl.so files with the ones that are built with the standard Perl installation.

If you choose the "standard" all-in-one way of building mod_perl, add:

USE_DSO=1

to the perl Makefile.PL options.

If you choose to build mod_perl and Apache separately, add:

--enable-shared=perl

to Apache's configure options when you build Apache.

As you can see, whichever way you build mod_perl and Apache, only one additional option is needed to build mod_perl as a DSO. Everything else is done automatically: mod_so is automatically enabled, the Makefiles are adjusted, and the install target from APACI installs libperl.so into the Apache installation tree. Additionally, the LoadModule and AddModule directives (which dynamically load and insert mod_perl into httpd) are automatically added to httpd.conf.

3.5.5. Building mod_perl as a DSO via APXS

We've seen how to build mod_perl as a DSO inside the Apache source tree, but there is a nifty alternative: building mod_perl as a DSO outside the Apache source tree via the new Apache 1.3 support tool called APXS. The advantage is obvious: you can extend an already installed Apache with mod_perl even if you don't have the sources (for instance, you may have installed an Apache binary package from your vendor or favorite distribution).

Here are the build steps:

panic% tar xzvf mod_perl-1.xx.tar.gz
panic% cd mod_perl-1.xx
panic% perl Makefile.PL \
    USE_APXS=1 \
    WITH_APXS=/path/to/bin/apxs \
    EVERYTHING=1 \
    [...]
panic% make && make test
panic# make install

This will build the DSO libperl.so outside the Apache source tree and install it into the existing Apache hierarchy.