/ 
mod_perl-1.99_05
River stage three • 156 direct dependents • 183 total dependents
/ Installing

NAME

Installing mod_perl

Description

This chapter provides an indepth mod_perl 2.0 installation coverage.

Prerequisites

The mod_perl 2.0 prerequisites are:

  • Apache

    Apache 2.0 is required. mod_perl 2.0 does not work with Apache 1.3.

  • Perl

    prefork MPM

    Requires at least Perl version 5.6.0. But we strongly suggest to use at least version 5.6.1, since 5.6.0 is quite buggy.

    You don't need to have threads-support enabled in Perl. If you do have it, it must be ithreads and not 5005threads! If you have:

    % perl5.8.0 -V:use5005threads
use5005threads='define';

    you must rebuild Perl without threads enabled or with -Dusethreads. Remember that threads support slows things down, so don't enable it unless you really need it.

    threaded MPMs

    Require at least Perl version 5.8.0 with ithreads support built-in. That means that it should report:

    % perl5.8.0 -V:useithreads -V:usemultiplicity
useithreads='define';
usemultiplicity='define';

    If that's not what you see rebuild Perl with -Dusethreads.

Installing from Source

First of all:

Apache 2.0 doesn't work with mod_perl 1.0.
Apache 1.0 doesn't work with mod_perl 2.0.

XXX: For Win32 specific installation doc here.

Download the httpd-2.0 and modperl-2.0 tarballs, and extract them in the same directory.

Or use anoncvs (password is "anoncvs"):

% cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic login
% cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic co modperl-2.0
% cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic co httpd-2.0
% cd httpd-2.0/srclib
% cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic co apr
% cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic co apr-util
% cd ..
% ./buildconf
% ./configure --prefix=$HOME/apache-2.0 --with-mpm=prefork
% make && make install

Once extracted, whenever you want to sync with the latest httpd-2.0 version and rebuild, run:

% cd httpd-2.0
% cvs up -dP
% make distclean && ./buildconf
% ./configure --prefix=$HOME/apache-2.0 --with-mpm=prefork
% make && make install

For bleeding edge Perl:

# (--delete to ensure a clean state)
% rsync -acvz --delete --force \
  rsync://ftp.linux.activestate.com/perl-current/ perl-current
% cd perl-current
% ./Configure -des -Dprefix=$HOME/bleedperl \
  -Dusethreads -Doptimize='-g' -Dusedevel
% make && make test && make install
% ln -s $HOME/bleedperl/bin/perl5.x.x $HOME/bleedperl/bin/perl

or otherwise make sure that your perl was built with threads enabled if you want to use a threaded MPM.

If you are re-building Perl after rsync-ing, make sure to cleanup:

% make distclean

before running ./Configure.

You'll also want to install (at least) LWP into the bleedperl/lib directory if you want to fully test mod_perl, because normally a privately installed bleedperl won't find libraries installed in the normal places; it only looks in it's own lib tree. You can install LWP with CPAN.pm shell:

% $HOME/bleedperl/bin/perl -MCPAN -e 'install("LWP")'

Compiling

Create the build environment

% cd modperl-2.0
% perl Makefile.PL MP_AP_PREFIX=/home/stas/httpd/prefork \
  MP_INST_APACHE2=1
% make

XXX: MP_INST_APACHE2=1 should become the default

options an optional list of (key,value) pairs. Usually you need to use only the MP_AP_PREFIX option to complete the build. This and other options are discussed in the following sections.

Boolean Build Options

The following options are boolean and can be set with MP_XXX=1 or unset with MP_XXX=0, where XXX is the name of the option.

MP_PROMPT_DEFAULT

Accept default values for all would-be prompts.

MP_GENERATE_XS

Generate XS code from parsed source headers in xs/tables/$httpd_version. Default is 1, set to 0 to disable.

MP_USE_DSO

Build mod_perl as a DSO (mod_perl.so). This is the default. It'll be turned off if MP_USE_STATIC=1 is used.

MP_USE_STATIC

Build static mod_perl (mod_perl.a). This is the default. It'll be turned off if MP_USE_DSO=1 is used.

MP_USE_DSO and MP_USE_STATIC are both enabled by default. So mod_perl is built once as mod_perl.a and mod_perl.so, but afterwards you can choose which of the two to use.

META: The following is not implemented yet.

mod_perl and ends up with a src/modules/perl/mod_perl.{so,a} and
src/modules/perl/ldopts.  to link modperl static with httpd, we just
need some config.m4 magic to add `ldopts` and mod_perl.a to the build.
so one could then build httpd like so:

ln -s ~/apache/modperl-2.0/src/modules/perl $PWD/src/modules
./configure --with-mpm=prefork --enable-perl=static ...

we not be configuring/building httpd for the user as 1.x attempted.

downside is one will need to have configured httpd first, so that
headers generated.  so it will probably be more like:

./configure --with-mpm=prefork ...
(go build modperl)
./config.nice --enable-perl=static && make

we could of course provide a wrapper script todo this, but don't want
to have this stuff buried and tangled like it is in 1.x

MP_STATIC_EXTS

Build Apache::*.xs as static extensions.

MP_USE_GTOP

Link with libgtop and enable libgtop reporting.

MP_DEBUG

Turn on debugging (-g -lperld) and tracing.

MP_MAINTAINER

Enable maintainer compile mode, which sets MP_DEBUG=1 and adds the following gcc flags:

-DAP_DEBUG -Wall -Wmissing-prototypes -Wstrict-prototypes \
-Wmissing-declarations \
-DAP_DEBUG -DAP_HAVE_DESIGNATED_INITIALIZER

To use this mode Apache must be build with --enable-maintainer-mode.

MP_TRACE

Enable tracing

MP_INST_APACHE2

Install all the *.pm modules relative to the Apache2/ directory.

Non-Boolean Build Options

set the non-boolen options with MP_XXX=value.

MP_APXS

Path to apxs. For example if you've installed Apache 2.0 under /home/httpd/httpd-2.0 as DSO, the default location would be /home/httpd/httpd-2.0/bin/apxs.

META: this option most likely will go away, use MP_AP_PREFIX

MP_AP_PREFIX

Apache installation prefix, under which the include/ directory with Apache C header files can be found. For example if you've have installed Apache 2.0 in directory \Apache2 on Win32, you should use:

MP_AP_PREFIX=\Apache2

If Apache is not installed yet, you can point to the Apache 2.0 source directory, but only after you've built or configured Apache in it. For example:

MP_AP_PREFIX=/home/stas/apache.org/httpd-2.0

Though in this case make test won't automatically find httpd, therefore you should run t/TEST instead and pass the location of apxs or httpd, e.g.:

% t/TEST -apxs /home/stas/httpd/prefork/bin/apxs

or

% t/TEST -httpd /home/stas/httpd/prefork/bin/httpd

MP_CCOPTS

Add to compiler flags, e.g.:

MP_CCOPTS=-Werror

(Notice that -Werror will work only with the Perl version 5.7 and higher.)

MP_OPTIONS_FILE

Read build options from given file. e.g.:

MP_OPTIONS_FILE=~/.my_mod_perl2_opts

mod_perl-specific Compiler Options

-DMP_IOBUFSIZE

Change the default mod_perl's 8K IO buffer size, e.g. to 16K:

MP_CCOPTS=-DMP_IOBUFSIZE=16384

Options File

Options can also be specified in the file makepl_args.mod_perl2 or .makepl_args.mod_perl2. The file can be placed under $ENV{HOME}, the root of the source package or its parent directory. So if you unpack the mod_perl source into /tmp/mod_perl-2.x/ and your home is /home/foo/, the file will be searched in:

/tmp/mod_perl-2.x/makepl_args.mod_perl2
/tmp/makepl_args.mod_perl2
/home/foo/makepl_args.mod_perl2
/tmp/mod_perl-2.x/.makepl_args.mod_perl2
/tmp/.makepl_args.mod_perl2
/home/foo/.makepl_args.mod_perl2

If the file specified in MP_OPTIONS_FILE is found the makepl_args.mod_perl2 will be ignored.

Options specified on the command line override those from makepl_args.mod_perl2 and those from MP_OPTIONS_FILE.

If your terminal supports colored text you may want to set the environment variable APACHE_TEST_COLOR to 1 to enable the colored tracing which makes it easier to tell the reported errors and warnings, from the rest of the notifications.

Compile mod_perl

% make

Configure and compile Apache

% cd ../httpd-2.0
% ./configure --with-mpm=prefork
% make

Test mod_perl

% make test

Apache::Test Framework document covers the make test suite.

META: probably need to link directly to the 'Running Tests' section.

Howto generate source tables

All mod_perl-2.0 xs code is generated from parsed header files. While in pre-release mode, a version of these tables will be checked in to xs/tables/current. Should you wish to update these tables, here's how:

NOTE: requires C::Scan 0.75, which at the moment is unreleased, there is a working copy here: http://perl.apache.org/~dougm/Scan.pm

NOTE: source_scan.pl is a HEAVY process, do not be alarmed.

% perl build/source_scan.pl apxs $apache_prefix/bin/apxs

META: this is covered in Core Explained should probably move/point there.

Re-using Build Options

Since mod_perl remembers what build options were used to build it, you can use this knowledge to rebuild itself using the same options. Simply chdir(1) to the mod_perl source directory and run:

% cd modperl-2.0
% perl -MApache::Build -e rebuild

Installing from Binary Packages

As of this writing only the binaries for the Win32 platform are available, kindly prepared and maintained by Randy Kobes.

XXX: link to Win32 download doc.

Maintainers

Maintainer is the person(s) you should contact with updates, corrections and patches.

  • Doug MacEachern <dougm (at) covalent.net>

Authors

  • Doug MacEachern <dougm (at) covalent.net>

Only the major authors are listed above. For contributors see the Changes file.