INSTALLATION for mod_perl

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

Apache version 1.1 or higher.

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.07.tar.gz>

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

This install includes the module Apache::Registry, which uses the
standard module 'FileHandle'.  There was a bug in the version of this
module, that came with perl5.003, so if your perl is not younger than
5.003 we suggest you apply the patch 'FileHandle.patch' to fix the
problem until it is fixed in the standard distribution of Perl.
Although, it is a strange bug, you might not even see it without the
patch...

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

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/

Edit apache_xxx/src/Configuration (if you don't have Configuration
yet, this should be a copy of Configuration.tmpl in the same
directory):

For mod_perl add:

	Module perl_module	   modules/perl/libmodperl.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.

If you are using the most current public release of apache '1.1.1',
you can simply copy the src/Makefile.tmpl to apache_xxx/src/Makefile.tmpl

Otherwise, edit apache_xxx/src/Makefile.tmpl adding:
(!Be sure to read the comments first!) 
---%<----

#next line only for apache versions < 1.2
#RANLIB=ranlib

PERL=/usr/local/bin/perl
PERL_LD_OPTS=`$(PERL) modules/perl/ldopts`

modules/perl/libmodperl.a:
	(cd modules/perl; \
	make CC=$(CC) AUX_CFLAGS="$(CFLAGS)" RANLIB=$(RANLIB) PERL=$(PERL);)

#add $(PERL_LD_OPTS) to the httpd target, which may change with new releases
#but should look something like so:

#httpd: $(REGLIB) $(OBJS)
#	$(CC) $(LFLAGS)  -o httpd $(OBJS) $(REGLIB) $(LIBS) $(PERL_LD_OPTS)
---%<----

You may also wish to edit the on/off switches for callback hooks
during request stages in src/modules/perl/Makefile. The default is
that most callbacks are disabled.

Follow the Apache install docs from there.

See the 'UsersGuide' file for info on configuring, running
and writing Apache/Perl scripts and modules.
 
Using PerlIO
------------
When you Configure Perl as of 5.002_02, you will be given the option to
use sfio rather than stdio.  If you choose this option, STDOUT will be
hooked up to the client for writing (or print'ing), as will STDIN for
reading.
Perl scripts outside of Apache will run as expected.
See the Perl INSTALL document for more information.

You may also want to look at the Apache::TieHandle module.

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

    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 of your server configuration.

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


