INSTALLATION for mod_perl.c, mod_perl_fast.c and Apache.*

**IMPORTANT**
-------------

Currently, you can only use mod_perl *or* mod_perl_fast.
You may however, build Apache with both modules.
To "turn off" mod_perl, simply #comment out the AddType httpd/perl .pl in srm.conf.
To "turn off" mod_perl_fast, simply #comment out the PerlScript scriptname.pl in srm.conf.


Prerequisites
-------------

You need apache1.1b2 or better.

Make sure you have perl version 5.002_01 or better, compiled with -DEMBED
(this is the default with 5.002_01+ anyway)

Fetch and install ExtUtils::embed from CPAN 
<URL:http://www.perl.com/cgi-bin/cpan_mod?module=ExtUtils::embed>.


Build and install the perl part of this module
----------------------------------------------

The perl modules under lib/ can be installed by saying (in this current directory):

  perl Makefile.PL
  make
  make install

See Apache.pm on how to use the Perl-Apache API.

See the eg/ directory for example scripts.


Build apache
------------

To build the apache server, you'll need to use the Makefile.tmpl file
in this directory for 1.1b4+, (Makefile.tmpl.1.1b2 for 1.1b2), or make
changes to your copy. So either copy the Makefile.tmpl in this
directory to the apache_xxx/src/ directory or edit
apache_xxx/src/Makefile.tmpl first.

You'll also need to edit the apache_xxx/src/Configuration file in the
apache build directory:

For mod_perl add:

    Module perl_module mod_perl.o

For mod_perl_fast add:

    Module perl_fast_module mod_perl_fast.o

Copy the files in this src/ to apache's src/

Follow the Apache install docs from there.

To tell Apache you want mod_perl to handle your scripts add to your
srm.conf:

    AddType httpd/perl .pl

To tell Apache you want mod_perl_fast to handle your scripts add to
your srm.conf:

    AddType httpd/fast-perl .fpl

and:

    PerlScript  script_to_load_at_startup.pl

Optionally you may also load a module via

    PerlModule Module::Name

	
This script will be loaded when the server starts. See eg/mpf_eg.pl
for an example to start with.

In an access.conf <Directory /foo> or .htaccess you need:

    PerlResponse sub_routine_name

This is the name of the subroutine to call (defined in PerlScript)
to handle each request. (In the mpf_eg.pl this is "response").


Let it run, but read this WARNING
*********************************

For *both* mod_perl and mod_perl_fast:

Your scripts *cannot* be in a ScriptAlias(ed) (which is usually /cgi-bin) directory.

Your scripts *will not* run from the command line (yet).


Support
-------

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/
 

IF YOU HAVE PROBLEMS
--------------------

Please send mail to modperl@listproc.itribe.net with the output of:

    Output of perl -v; perl -V

    which module you are trying to use (mod_perl or mod_perl_fast),
    and version of the package.

    which script from the eg/ directory you are using.
    (please try a script from there first.)

    your apache server version details of your server configuration.

    if you get a core dump, please send a backtrace if possible.


