/ 
mod_perl-1.99_04
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

Lots of prerequisites

Installing from Source

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/src/httpd-2.0.xx
% make

options an optional list of (key,value) pairs.

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 options: set them 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 Apache include/ directory can be found. If Apache is not installed yet, you can point to the source directory. For example if you've have installed Apache 2.0 in \Apache2 on Win32, you should use:

MP_AP_PREFIX=\Apache2
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 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.