=head1 NAME
INSTALL - Apache mod_perl installation instructions
=head1 DESCRIPTION
How to build, test, configure and install mod_perl
=head1 PREREQUSITES
=over 3
Apache version 1.1.x, 1.2.0+ or 1.3a1+
Perl version 5.003 or higher
If you do not have Perl version 5.003_01 or higher,
fetch and install ExtUtils::Embed from CPAN
<URL:http://www.perl.com/CPAN/modules/by-module/ExtUtils/ExtUtils-Embed-1.12.tar.gz>
Win32 users, see INSTALL.win32
=back
=head1 Build and install mod_perl
=over 3
In this current directory run:
perl Makefile.PL
make
make test (optional)
make install
Makefile.PL will search for apache source trees to configure against,
if no source trees are found, you will be prompted for a path to one.
When asked:
"Configure mod_perl with ../apache_xxx ?"
answering 'y' just tells Makefile.PL where we can find src/*.h
When asked:
"Shall I build httpd in $adir for you?"
answering 'y' will run ../apache_xxx/Configure
and httpd will be built when running 'make'
To avoid this prompt and default to the first apache source tree found
to configure and build against, use the following command:
perl Makefile.PL DO_HTTPD=1
To avoid the prompts and avoid building httpd, use the following
command:
perl Makefile.PL NO_HTTPD=1
You may wish see the instructions below on how to build by hand.
In any case, you need to 'make install' so the perl side of mod_perl
will be installed.
By default, all callback hooks except for PerlHandler are turned off.
You may edit src/modules/perl/Makefile, or enable when running Makfile.PL
Possible arguments are:
PERL_INIT
PERL_TRANS
PERL_HEADER_PARSER
PERL_AUTHEN
PERL_AUTHZ
PERL_ACCESS
PERL_TYPE
PERL_FIXUP
PERL_LOG
PERL_CLEANUP
PERL_STACKED_HANDLERS
PERL_METHOD_HANDLERS
PERL_SECTIONS
PERL_SSI
Example to enable PerlAuthenHandler and PerlFixupHandler:
perl Makefile.PL PERL_AUTHEN=1 PERL_FIXUP=1
To enable all callback hooks:
perl Makefile.PL ALL_HOOKS=1
To enable _all_ of the above, set EVERYTHING=1
perl Makefile.PL EVERYTHING=1
To enable tracing set PERL_TRACE=1
perl Makefile.PL PERL_TRACE=1
=item Linking Perl extensions static with httpd
Normally, if an exension is linked static with Perl it is listed in
Config.pm's $Config{static_exts}, in which case, mod_perl will also
link this extension static with httpd. However, if an extension is
linked static with Perl after it is installed, it is not listed in
Config.pm. You may either edit Config.pm and add these extensions, or
configure mod_perl like so:
perl Makefile.PL "PERL_STATIC_EXTS=Something::Static Another::One"
=back
=head1 Testing mod_perl
=over 3
Running 'make test' will start an httpd on port 8529 running under
the uid and gid of the 'perl Makefile.PL' process, the httpd will
be terminated when the tests are finshed.
To change the default port say:
perl Makefile.PL PORT=xxxx
To simply start the newly build httpd before 'make install' run:
make start_httpd
To shutdown this httpd run:
make kill_httpd
See t/README on how to run the mod_perl test suite by hand
NOTE to Ben-SSL users:
httpsd does not seem to handle '/dev/null' as the location of certain
files, you'll have to change these by hand.
Tests are run with 'SSLDisable'
=back
=head1 Building apache and mod_perl by hand
=over 3
** Only if you did not let Makefile.PL take care of this already **
=item mod_perl source files
If you wish to link the Apache:: extensions static with httpd,
edit src/modules/perl/Makefile and uncomment these lines:
#STATIC_SRC = Apache.c Constants.c
#STATIC_EXTS = Apache Apache::Constants
Or, to build the Apache:: extensions as shared libraries:
(note: this does not work on some systems, such as aix and unixware)
Run:
% perl Makefile.PL DYNAMIC=1 && make
When prompted, you must tell Makefile.PL where to find apache sources
(for header files), answer 'n' when asked
"Shall I build httpd in ../apache_x.x.x/src for you?"
Now copy the source files into the apache build directory:
(For apache versions < 1.2 you'll need to mkdir src/modules/ first)
cp -r src/modules/perl apache_xxx/src/modules/
=item Makefile.tmpl
apache_1.1.x users: copy src/Makefile.tmpl to apache_xxx/src/
apache 1.2.0+ users: no need to modify the Makefile.tmpl for mod_perl
=item Configuration
Edit apache_xxx/src/Configuration, and add:
Module perl_module modules/perl/libperl.a
We suggest you add this entry at the end of the Configuration file if
you want your callback hooks to have precedence over core handlers.
Add the following to EXTRA_LIBS:
EXTRA_LIBS=`perl -MExtUtils::Embed -e ldopts`
Follow the apache install docs from there
=back
=head1 Configuring and building with Stronghold
=over3
You must first build and install Stronghold without mod_perl,
following Stronghold's install procedure.
Then, you may rebuild following the instructions above to:
Build and install mod_perl
or
Building apache and mod_perl by hand
Before running `make test', you must add your `StrongholdKey'
to t/conf/httpd.conf
I you are configuring by hand, be sure to edit
src/modules/perl/Makefile and uncomment #APACHE_SSL
For Solaris 2.5 users, there has been a report related to the REGEX
that comes with Stronghold, after building Apache with mod_perl would
produce core dumps.
To get around this:
In STRONGHOLD/src/Configuration, Change:
Rule WANTHSREGEX=default
To:
Rule WANTHSREGEX=no
=back
=head1 Installing on multiple machines
=over 3
You may wish to build httpd once, then copy it to other machines.
The Perl side of mod_perl needs the apache headers files to compile,
to avoid dragging and build apache on all your other machines, there
are a few Makefile targets to help you out:
'make tar_Apache'
This will tar all files mod_perl installs in your 'site_perl' directory,
into a file called 'Apache.tar'.
You can then unpack this under 'site_perl' on another machine.
'make offsite-tar'
This will copy all header files from the apache source directory you
configured mod_perl against, then it will 'make dist' where you'll
a mod_perl-x.xx.tar.gz created, ready to unpack on another machine
to compile and install the Perl side of mod_perl.
=back
=head1 Notes
=over 3
=item BSDI users
Gary Shea <shea@xmission.com> discovered a nasty BSDI bug (seen in
versions 2.1 and 3.0) related to dynamic loading and two workarounds:
Turns out they use argv[0] to determine where to find the link
tables at run-time, so if a program either changes argv[0],
or does a chdir() (like apache!), it can easily confuse the
dynamic loader. The short-term solutions to the problem are
pitifully simple. Either of the following will work:
1) Call httpd with a full path, e.g. /opt/www/bin/httpd
2) Put the httpd you wish to run in a directory in your PATH
before any other directory containing a version of httpd, then
call it as 'httpd' -- don't use a relative path!
=item AIX users
The following problem:
> I am having problems 'make'ing mod_perl 0.99. The 'make' command fails
> attempting to compile httpd with the message:
>
> 'ld: cannot findexport file: perl.exp'
>
> I am running Perl 5.004_01 on AIX 3.2.5.1. We currently have Apache
Is answered by Eric Bartley <bartley@cc.purdue.edu>:
Yes this is something I had run into with perl & mod_perl on AIX. It's a
nit between AIX's awkward dynamic libraries and perl's configuration and
installation. The story goes like this: to build a dynamically loaded
extension you have to provide the linker with a list of symbol names to be
exported. This is what perl.exp does for perl. Most people only need this
to build libperl, at which time the linker needs to find this file in the
current working directory so "-dE:perl.exp" works. However, Embeded
application will also need this because the will be exporting these
symbols (or importing I'm not exactly sure). Now that perl.exp is
installed in the PERL5LIB directory the linker needs the full path to
perl.exp (or you could copy it the the cwd of the compile). Edit Config.pm
and search for the line that reads ccdlflags='-bE:perl.exp'. Add the path
to the CORE directory for this version of perl. For example in my
installation of perl 5.004_01 this line now reads:
ccdlflags='-bE:/usr/local/lib/perl5/aix/5.00401/CORE/perl.exp'
This command will tell you where your Config.pm lives and the
path to the CORE directory:
perl -MConfig -e 'print "$Config{archlibexp}/Config.pm\n"'
=item Perl Static Extensions
If you wish to use a module that is normally linked static with your
Perl, it must be listed in static_ext in Perl's Config.pm to be linked
with httpd during the mod_perl build.
To list your static extensions, run this command:
perl -V:static_ext
If your module is not listed, add it to this line in Config.pm:
static_ext=' '
=item more info
Type 'perldoc mod_perl' for info on configuring, running
and writing Apache/Perl scripts and modules.
=back
=head1 Using PerlIO
=over 3
See 'perldoc mod_perl' for an explaination
See the Perl INSTALL document for more information.
Here's how to configure your perl with sfio:
% Configure -des -Duseperlio -Dusesfio
With Perl version 5.003_93 or higher, there is no need to configure
with sfio for using Perl's read() and print() functions, STDIN and
STDOUT are tie'd to the client connection.
=back
=head1 Support
=over 3
For comments, questions, bug-reports, announcements, etc., send mail
to majordomo@listproc.itribe.net with the string "subscribe modperl"
in the body. (Thanks to Mark A. Imbriaco <mark@itribe.net>)
Thanks to James Cooper <pixel@tiger.coe.missouri.edu>,
there is a hypermail archive for this list at:
http://www.coe.missouri.edu/~faq/lists/modperl/
=back
=head1 IF YOU HAVE PROBLEMS
=over 3
Please send mail to modperl@listproc.itribe.net with the output of:
Output of C<perl -v; perl -V>
version of the mod_perl package.
which script from the eg/ directory you are using.
(please try a script from there first.)
your apache server version details and your server configuration.
the output of 'make test'
if you get a core dump, please send a backtrace if possible (be sure
to add '-g' to EXTRA_CFLAGS in the Apache Configuration file).
If the dump is happening in libperl a -DDEBUGGING enabled libperl
would help show us what's really happening.
Go to your Perl source tree:
% rm *.[oa]
% make LIBPERL=libperld.a
% cp libperld.a $Config{archlibexp}/CORE
% cd $Config{archlibexp}/CORE
% mv libperl.a libperle.a
% ln -s libperld.a libperl.a
$Config{archlibexp} is:
% perl -V:archlibexp
Rebuild httpd, let's see a new backtrace. After we're done debugging,
ln -s libperle.a libperl.a
if you can compile but not run a mod_perl, send mail to
modperl@listproc.itribe.net with the output of:
Output of C<perl -v; perl -V>
version of the mod_perl package.
which script from the eg/ directory you are using.
(please try a script from there first.)
your apache server version