NAME

INSTALL.apaci - Installing mod_perl under Unix with the new hybrid build environment for Apache 1.3

SUMMARY

This document describes how to build and install mod_perl as clean as possible with Apache 1.3 under Unix platforms by making use of both the Apache 1.3 ConfigStart/End facility and the new Autoconf-style Interface (APACI). In addition the Dynamic Shared Object (DSO) mechanism can be used to build mod_perl as an Apache module which can be loaded on-demand under run-time.

ATTENTION

This currently is a pure Unix-based solution because the complete Apache 1.3 source configuration mechanism currently is only workable under Unix. It doesn't work under the Win32 platform, so mod_perl cannot use it, too. For Win32 installation instructions please read the INSTALL.win32 document.

BACKGROUND

The source configuration mechanism in Apache 1.3 provides four major highlights mod_perl can benefit from:

Per-module configuration scripts (ConfigStart/End)

This is a mechanism modules can use to link theirself into the configuration processing. It is useful for automatically adjusting configuration and build parameters from the modules sources. It is triggered by ConfigStart/ConfigEnd sections inside modulename.module files.

Apache Autoconf-style Interface (APACI)

This is the new top-level configure script from Apache 1.3 which provides a GNU Autoconf-style interface. It is useful for configuring the source tree without manually editing any src/Configuration files. Any parametrization can be done via command line options to the configure script. Internally this is just a nifty a wrapper to the old src/Configure script.

Dynamic Shared Object (DSO) support

This is beside Windows NT support one of most interesting features in Apache 1.3. Its a way to build Apache modules as so-called dynamic shared objects (usually named modulename.so) which can be loaded via the LoadModule directives from within Apache's httpd.conf file. The benefit is that the modules is part of the httpd program only on-demand, i.e. only when the user wants the module it is loaded into the address space of the httpd module. This is for instance interesting for memory consumption and easy upgrade issues. The DSO mechanism is provided by Apache's mod_so.c which needs to be compiled into the httpd program. This is automatically done when DSO is enabled for module mod_xxx via configure --enable-module=xxx or by explicitly adding mod_so via configure --enable-module=so.

APache eXtenSion (APXS) support tool

This is a new support tool from Apache 1.3 which can be used to build an Apache module as a DSO even outside the Apache source-tree. One can say APXS is what MakeMaker and XS is for Perl. It knows the platform dependent build parameters for making DSO files and provides an easy way to run the build commands with them.

Taking these four features together provides a way to integrate mod_perl into Apache in a very clean and smooth way. No patching of the Apache source tree is needed in the standard situation and even not only the source tree itself is needed in the APXS situation.

DESCRIPTION

To benefit from the above described features a new hybrid build environment was created for the Apache-side of mod_perl. The Apache-side consists of the C source files of mod_perl which have to be compiled into the httpd program. They are usually copied to the subdirectory src/modules/perl/ in the Apache source tree. To integrate this subtree into the Apache build process a lot of adjustments were done by mod_perl's Makefile.PL in the past. And additionally the Makefile.PL controlled the Apache build process. The side-effect of this approach was that it is both an not very clean and especially captive way. Because it assumed mod_perl is the only third-party modules which has to be integrated into Apache. This is very problematic.

The new approach described below avoids these problems. It only prepares 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 (and then configures itself) when the Apache source tree is configured via standard APACI calls later.

THE GAME ITSELF

There are various ways available to build Apache with the new hybrid build environment:

The all-in-one way

If your goal is just to build and install Apache 1.3 with mod_perl out of their source trees and have no special interests in further adjusting or enhancing Apache do the following:

$ gunzip <apache_1.3.X.tar.gz | tar xvf -
$ gunzip <mod_perl-1.X.tar.gz | tar xvf -
$ cd mod_perl-1.X
$ perl Makefile.PL \
    APACHE_PREFIX=/path/to/install/of/apache \
    APACHE_SRC=../apache-1.3.X/src \
    DO_HTTPD=1 \
    USE_APACI=1 \
    EVERYTHING=1 \
    APACI_ARGS='[...]' \
    [...]
$ make
$ make test
$ make install

This builds Apache statically with mod_perl, installs Apache under /path/to/install/of/apache/ and mod_perl into the site_lib hierarchy of your existing Perl installation. All in one step.

The flexible way

This is the standard situation when you want to be flexible while building: Statically building mod_perl into the httpd binary of Apache but via different steps, so you have a chance for other third-party Apache modules, etc.

1. Prepare the Apache 1.3 source tree

The first step is the extract the distributions:

$ gunzip <apache_1.3.X.tar.gz | tar xvf -
$ gunzip <mod_perl-1.X.tar.gz | tar xvf -

2. Install mod_perl's Perl-side and prepare the Apache-side

The second step is to install the Perl-side of mod_perl into the Perl system and prepare the src/modules/perl/ subdirectory inside the Apache source tree:

$ cd mod_perl-1.XX
$ perl Makefile.PL \
    APACHE_SRC=../apache_1.3.X/src \
    DO_HTTPD=1 \
    USE_APACI=1 \
    PREP_HTTPD=1 \
    EVERYTHING=1 \
    [...]
$ make
$ make test
$ make install
$ cd ..

(The APACHE_SRC set the path to your Apache source tree, the DO_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 forces only a preparation of the APACHE_SRC/modules/perl/ tree but no automatic builds.)

This now prepares the Apache-side of mod_perl in the Apache source tree but don't touches anything else inside it. It then just builds the Perl-side of mod_perl and installs it into the Perl installation hierarchy.

Important: If you use PREP_HTTPD as described above, to complete the build you must go into an apache source directory and run make and make install.

3. Additionally prepare other third-party modules

Now you still have a chance to prepare more third-party modules. For instance the PHP3 language can be added similarly to the above mod_perl procedure.

4. Build the Apache package

Finally its time to build the Apache package and thus also the Apache-side of mod_perl and any other prepared third-party modules:

$ cd apache_1.3.X
$ ./configure \
    --prefix=/path/to/install/of/apache \
    --activate-module=src/modules/perl/libperl.a \
    [...]
$ make
$ make test
$ make install

(The --prefix option is usually always needed and the --activate-module option activates mod_perl for the configuration process and thus also for the build process.)

Now bask in the glow and be happy to received a mod_perl-aware Apache 1.3 system without having to mangle the Apache source tree for mod_perl plus the freedom of being able to adding more third-party modules.

EXPERIMENTAL

With Apache 1.3 there is support for building modules as Dynamic Shared Objects (DSO). So there is support for DSO in mod_perl now, too. BUT THIS IS STILL EXPERIMENTAL, SO BE WARNED!

Build mod_perl as DSO inside Apache source tree via APACI

We already said that the new mod_perl build environment is a hybrid one. What does it mean? It means for instance that the same src/modules/perl/ stuff can be used to build mod_perl as a DSO, too. And again without having to edit anything specially for this. When you want to build libperl.so (sorry for the name, libmodperl.so would be more correct, but because of historic Apache issues the name has to be libperl.so. Don't confuse this with the real libperl.a or even libperl.so from the Perl installation) all you have to do is to add one single option to the above steps.

You have two options here, dependend on which way you choose above: If you choose the all-in-one way above then add

USE_DSO=1

to the mod_perl/Makefile.PL options. If you choose the flexible way then add

--enable-shared=perl

to the Apache/configure options.

As you can see only an additional USE_DSO=1 or --enable-shared=perl option is needed. Anything else is done automatically: mod_so is automatically enabled, the Makefiles are adjusted automatically and even the install target from APACI now additionally installs the libperl.so into the Apache installation tree. And even more: The LoadModule and AddModule directives are automatically added to the httpd.conf file.

Build mod_perl as DSO outside Apache source tree via APXS

Above we've seen how to build mod_perl as DSO inside the Apache source tree. But there is a nifty alternative: Building mod_perl as DSO outside the Apache source tree via the new Apache 1.3 support tool apxs (APache eXtension). 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 installed an Apache binary package from your vendor).

Here are the steps:

$ gunzip <mod_perl-1.X.tar.gz | tar xvf -
$ cd mod_perl-1.X
$ perl Makefile.PL \
    USE_APXS=1 \
    WITH_APXS=/path/to/bin/apxs \
    EVERYTHING=1 \
    [...]
$ make 
$ make test
$ make install

This will build the DSO libperl.so outside the Apache source tree with the new Apache 1.3 support tool apxs and installs it into the existing Apache hierarchy.

AUTHOR

Ralf S. Engelschall
rse@engelschall.com
rse@apache.org

cpanm Error

perl -MCPAN -e shell
install Error