=head1 NAME INSTALL.apaci - Installing mod_perl under Unix with the new hybrid build environment for Apache 1.3 =head1 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. =head1 ATTENTION I =head1 BACKGROUND The source configuration mechanism in Apache 1.3 provides four major highlights mod_perl can benefit from: =over 3 =item B 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 C/C sections inside IC<.module> files. =item B This is the new top-level C script from Apache 1.3 which provides a GNU Autoconf-style interface. It is useful for configuring the source tree without manually editing any C files. Any parametrization can be done via command line options to the C script. Internally this is just a nifty a wrapper to the old C script. =item B 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 C (usually named IC<.so>) which can be loaded via the C directives from within Apache's C file. The benefit is that the modules is part of the C program only on-demand, i.e. only when the user wants the module it is loaded into the address space of the C module. This is for instance interesting for memory consumption and easy upgrade issues. The DSO mechanism is provided by Apache's C which needs to be compiled into the C program. This is automatically done when DSO is enabled for module C via C or by explicitly adding C via C. =item B This is a new support tool from Apache 1.3 which can be used to build an Apache module as a DSO even B 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. =back Taking these four features together provides a way to integrate mod_perl into Apache in a very clean and smooth way. I. =head1 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 C program. They are usually copied to the subdirectory C in the Apache source tree. To integrate this subtree into the Apache build process a lot of adjustments were done by mod_perl's C in the past. And additionally the C 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 C subtree inside the Apache source tree I 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. =head1 THE GAME ITSELF There are various ways available to build Apache with the new hybrid build environment: =head2 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 and mod_perl into the C hierarchy of your existing Perl installation. All in one step. =head2 The flexible way This is the standard situation when you want to be flexible while building: Statically building mod_perl into the C binary of Apache but via different steps, so you have a chance for other third-party Apache modules, etc. =over 3 =item B<1. Prepare the Apache 1.3 source tree> The first step is the extract the distributions: $ gunzip The second step is to install the Perl-side of mod_perl into the Perl system and prepare the C 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 install $ cd .. (The C set the path to your Apache source tree, the C option forces this path and only this path to be used, the C option triggers the new hybrid build environment and the C forces only a preparation of the C 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 C as described above, to complete the build you must go into an apache source directory and run C and C. =item B<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. =item B<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 C<--prefix> option is usually always needed and the C<--activate-module> option activates mod_perl for the configuration process and thus also for the build process.) =back 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. =head1 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. I =head2 When DSO can be used If you want to build C as DSO you must make sure that Perl was built with system's native malloc(). If Perl was built with its own malloc() and C<-Dbincompat5005>, it pollutes the main C program with I and I symbols. When C restarts (happens at startup too), any references in the main program to I and I become invalid, and this causes 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 with C<-Ubincompat5005>. or C<-Uusemymalloc> for any version of Perl, but there's a chance that might hurt performance depending on platform, so C<-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 C<-Ubincompat5005>. For Perl versions pre-5.6.x, if you get: % perl -V:usemymalloc usemymalloc='y'; rebuild Perl with C<-Uusemymalloc>. now rebuild mod_perl. =head2 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 C stuff can be used to build mod_perl as a DSO, too. I. When you want to build C (sorry for the name, C would be more correct, but because of historic Apache issues the name has to be C. Don't confuse this with the real C or even C 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 C or C<--enable-shared=perl> option is needed. Anything else is done automatically: C is automatically enabled, the Makefiles are adjusted automatically and even the C target from APACI now additionally installs the C into the Apache installation tree. And even more: The C and C directives are automatically added to the C file. =head2 Build mod_perl as DSO outside Apache source tree via APXS Above we've seen how to build mod_perl as DSO I the Apache source tree. But there is a nifty alternative: Building mod_perl as DSO I the Apache source tree via the new Apache 1.3 support tool C (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 B the Apache source tree with the new Apache 1.3 support tool C and installs it into the existing Apache hierarchy. =head1 AUTHOR Ralf S. Engelschall rse@engelschall.com rse@apache.org