Installation Scenarios for Standalone mod_perl (Practical mod_perl)

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.


3.4. Installation		3.6. Building mod_perl with Other Components

3.5. Installation Scenarios for Standalone mod_perl

3.5.1. The All-in-One Way

3.5.2. Building mod_perl and Apache Separately

3.5.3. When DSOs Can Be Used

3.5.4. Building mod_perl as a DSO via APACI

libperl.so and libperl.a

3.5.5. Building mod_perl as a DSO via APXS