=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.1+1.3.ssl, 1.1.1 or 1.2b2+

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

=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' only means there is 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'

You can avoid this prompt by setting the environment variable 'NO_HTTPD'
or by starting with 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_TRANS
  PERL_AUTHEN
  PERL_AUTHZ
  PERL_ACCESS
  PERL_TYPE
  PERL_FIXUP
  PERL_LOG

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 tracing set PERL_TRACE=1

  perl Makefile.PL PERL_TRACE=1
 
=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/1.1.1+1.3 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 **

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/

Copy src/Makefile.tmpl     to apache_xxx/src/ for apache_1.1.1
			- or -
Copy src/Makefile.tmpl-1.2 to apache_xxx/src/ for apache_1.2

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.

Follow the apache install docs from there

=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 directroy 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

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...

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.

To hookup STDOUT and STDIN to the client I configure my Perl like so:

 % Configure -des -Duseperlio -Dusesfio 

=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.

if you can compile but not run a mod_perl script, recompile with:
 
 % make TRACE=-DPERL_TRACE

then send the output of the server startup and run   

=back

=head1 IF YOU DON'T HAVE PROBLEMS

Feel free to send a note to the list and let us know what you're 
doing with mod_perl!