README for the Apache/Perl modules

This Apache module embeds a perl interpreter in the HTTP server.  
One benefit of this is that we are able to run scripts without 
going through the expensive (fork/exec/parameter passing/parsing, 
perl-startup time, etc.) CGI interface.  
Not only will scripts run faster, they have direct access to the C API 
of the server, allowing the developer to extend Apache server 
functionality with modules written in Perl.

The current approach of mod_perl is to allocate and construct one
perl interpreter when the server starts.  At the same time, load,
parse and run one perl script, which may pull in other perl code such
as your favorite modules.  This also allows you to initiate persistent
connections such as to a database server.  Then, a subroutine in
memory is called to handle each request.  The interpreter is destroyed
upon restart or shutdown of the server.

This *is not CGI*, your existing scripts will need some changes.
Apache's i/o is not stream oriented.  So, by default, you cannot 
print() to STDOUT from your script, use $r->print() instead.  
Nor can you read() from STDIN, use $r->read() or the $r->content 
methods to read POST data.
As of Perl5.003_02, there are two mechanisms in place for redirecting
the STDIN and STDOUT streams.  
See the UsersGuide for more information.

See the eg/ directory and read the documentation in
Apache.pm for examples.

Your scripts will not run from the command line unless you use the 
CGI::Switch module.

For users of CGI.pm, see the Apache::CGI, CGI::XA and CGI::Switch 
modules.
There are modules on the way to support the CGI::* modules as well.

It is also possible to write full-blown Apache modules in Perl for
things such as server side includes.  See the Apache::SSI, Apache::Authen,
Apache::AuthzAge, Apache::AccessLimitNum and Apache::Registry modules as 
examples.
 
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/

Patrick Kane <modus@enews.com> maintains the mod_perl FAQ available at:
http://chaos.dc.enews.com/mod_perl/
 
The latest version of this software and other information is available
at: http://www.osf.org/~dougm/apache/

KNOWN BUGS

mod_perl leaks memory when the server is restarted, this is a
problem with perl itself, which is being fixed.

Installation needs work.

TODO
o Provide full support for CGI.pm and CGI::* module with Apache::* subclasses
o Apache::Database module or some such to manage 
  persistent database connections 
o Complete Apache.xs interface
o Provide an optional and configurable Safe wrapper around embedded scripts
  (almost there)

ACKNOWLEDGEMENTS - See 'Changes' file


---------------------------------------------------------------------------

Enjoy,
-Doug MacEachern <dougm@osf.org>