expand backend documentation

Add descriptions for PLP::Backend::FastCGI and ::Apache explaining
their configuration and advantages, and recommend/reorder backends
accordingly.

Document a major bug in mod_perl2, and discourage its use for now.
Not investigated, but easily reproducable with:

	<:
	use Cwd qw(cwd);
	say cwd, '<br>';
	sleep 10;  # now request a plp from a different directory
	say cwd, '<br>';

diff --git a/PLP.pm b/PLP.pm
index e7ec30c5c8a227515cb0f215d63533c84728ba33..8a535da02e100ada5c6e079e46f708d1c29c41f5 100644 (file)
--- a/PLP.pm
+++ b/PLP.pm
@@ -293,13 +293,15 @@ F<httpd.conf> for a L<mod_perl|PLP::Backend::Apache> setup:
 PLP is yet another Perl embedder, primarily for HTML documents. Unlike with
 other Perl embedders, there is no need to learn a meta-syntax or object
 model: one can just use the normal Perl constructs. PLP runs under
 PLP is yet another Perl embedder, primarily for HTML documents. Unlike with
 other Perl embedders, there is no need to learn a meta-syntax or object
 model: one can just use the normal Perl constructs. PLP runs under

-L<mod_perl|PLP::Backend::Apache> and L<FastCGI|PLP::Backend::FastCGI>
+L<FastCGI|PLP::Backend::FastCGI> and L<mod_perl|PLP::Backend::Apache>

 for speeds comparable to those of PHP, but can also be run as a standard
 L<CGI|PLP::Backend::CGI> script.
 
 =head2 Setup
 
 for speeds comparable to those of PHP, but can also be run as a standard
 L<CGI|PLP::Backend::CGI> script.
 
 =head2 Setup
 

-See either L<CGI|PLP::Backend::CGI>, L<FastCGI|PLP::Backend::FastCGI>
+See either
+L<CGI|PLP::Backend::CGI>,
+L<FastCGI|PLP::Backend::FastCGI> (recommended)

 or L<Apache|PLP::Backend::Apache>.
 At least the following servers are supported:
 
 or L<Apache|PLP::Backend::Apache>.
 At least the following servers are supported:
 


@@ -311,9 +313,9 @@ With L<mod_fastcgi|PLP::Backend::FastCGI> or L<mod_cgi|PLP::Backend::CGI>.
 
 =item Apache
 
 
 =item Apache
 

-Either version 1 or 2.
-Using L<mod_perl|PLP::Backend::Apache>,
-L<mod_fastcgi, mod_fcgid|PLP::Backend::FastCGI>,
+Either version 1 or 2. Using
+L<mod_fcgid, mod_fastcgi|PLP::Backend::FastCGI>,
+L<mod_perl|PLP::Backend::Apache>,

 or L<mod_action|PLP::Backend::CGI>.
 
 =back
 or L<mod_action|PLP::Backend::CGI>.
 
 =back

diff --git a/PLP/Backend/Apache.pm b/PLP/Backend/Apache.pm
index 89e32c632a9dac5af972c02e72d722e40923ec8d..eb13d361e44f4f01656e53755e76833e1b7deee3 100644 (file)
--- a/PLP/Backend/Apache.pm
+++ b/PLP/Backend/Apache.pm
@@ -92,33 +92,53 @@ Naturally, you'll need to enable I<mod_perl>:
 
     apache-modconf apache enable mod_perl
 
 
     apache-modconf apache enable mod_perl
 

-Setup F<httpd.conf> (often just create a F</etc/apache2/conf.d/plp>) with:
+Setup F<httpd.conf> (in new installs just create F</etc/apache/conf.d/plp>) with:

 
     <IfModule mod_perl.c>
         <Files *.plp>
             SetHandler perl-script
             PerlHandler PLP::Backend::Apache
             PerlSendHeader On
 
     <IfModule mod_perl.c>
         <Files *.plp>
             SetHandler perl-script
             PerlHandler PLP::Backend::Apache
             PerlSendHeader On

-            PerlSetVar PLPcache On

         </Files>
     </IfModule>
 
 =head1 DESCRIPTION
 
         </Files>
     </IfModule>
 
 =head1 DESCRIPTION
 

-=head2 PerlSetVar configuration directives
+=head2 Configuration directives
+
+PLP behaviour can be configured by B<PerlSetVar> rules.
+These can be added to a F<.htaccess> file or most any scope of server
+configuration.  For example, to disable caching for a specific site:
+
+       <Directory /var/www/somesite/>
+               PerlSetVar PLPcache Off
+       </Directory>

 
 =over 16
 
 =item PLPcache
 
 
 =over 16
 
 =item PLPcache
 

-Sets caching B<On>/B<Off>. When caching, PLP saves your script in memory and
-doesn't re-read and re-parse it if it hasn't changed. PLP will use more memory,
+Sets caching B<On>/B<Off>.
+When caching, PLP saves your script in memory and doesn't re-read
+and re-parse it if it hasn't changed. PLP will use more memory,

 but will also run 50% faster.
 
 B<On> is default, anything that isn't =~ /^off$/i is considered On.
 
 =back
 
 but will also run 50% faster.
 
 B<On> is default, anything that isn't =~ /^off$/i is considered On.
 
 =back
 

+=head1 BUGS
+
+With mod_perlB<2>, any new request will change the cwd for all processes.
+This means that if you're running files from multiple directories,
+you I<should not use the current path> for it may change at any time.
+
+The bug has been confirmed with at least mod_perl 2.0.2/3/4 on Apache 2.2.3/8.
+Using this backend on Apache2 is extremely discouraged until this is fixed.
+Instead, L<the FastCGI backend|PLP::Backend::FastCGI> is recommended.
+
+Apache1 does not show any problems.
+

 =head1 AUTHOR
 
 Mischa POSLAWSKY <perl@shiar.org>
 =head1 AUTHOR
 
 Mischa POSLAWSKY <perl@shiar.org>

diff --git a/PLP/Backend/CGI.pm b/PLP/Backend/CGI.pm
index 7058b3ec5b4d7f5c57fc02db40d6179f652e1d7f..1a4f49c8e765d52985fb67c6cf155ee285ddbe5b 100644 (file)
--- a/PLP/Backend/CGI.pm
+++ b/PLP/Backend/CGI.pm
@@ -102,8 +102,8 @@ enable I<mod_cgi> (add/outcomment in server.modules), and add:
 
 =head2 Apache
 
 
 =head2 Apache
 

-Enable I<mod_actions> and setup F<httpd.conf>
-(often just create a F</etc/apache2/conf.d/plp>) with:
+Enable I<mod_actions> and
+setup F<httpd.conf> (in new installs just create F</etc/apache/conf.d/plp>) with:

 
     <IfModule mod_actions.c>
         ScriptAlias /PLP_COMMON/ /foo/bar/
 
     <IfModule mod_actions.c>
         ScriptAlias /PLP_COMMON/ /foo/bar/

diff --git a/PLP/Backend/FastCGI.pm b/PLP/Backend/FastCGI.pm
index f83675a7ce3963244a6df7caef0c846ed94c2d37..85a5234b75cbc325fe8455ca832c188a9513d0f4 100644 (file)
--- a/PLP/Backend/FastCGI.pm
+++ b/PLP/Backend/FastCGI.pm
@@ -50,8 +50,8 @@ Example F</foo/bar/plp.fcgi>:
     #!/usr/bin/perl
     use PLP::Backend::FastCGI;
 
     #!/usr/bin/perl
     use PLP::Backend::FastCGI;
 

-Then enable either I<mod_fastcgi> or I<mod_fcgid>, and setup F<httpd.conf>
-(often just create a F</etc/apache2/conf.d/plp>) with:
+Then enable either I<mod_fcgid> (recommended) or I<mod_fastcgi>, and
+setup F<httpd.conf> (in new installs just create F</etc/apache/conf.d/plp>) with:

 
     <IfModule mod_fastcgi.c>
         AddHandler fastcgi-script plp
 
     <IfModule mod_fastcgi.c>
         AddHandler fastcgi-script plp


@@ -63,6 +63,30 @@ Then enable either I<mod_fastcgi> or I<mod_fcgid>, and setup F<httpd.conf>
         FCGIWrapper /foo/bar/plp.fcgi .plp
     </IfModule>
 
         FCGIWrapper /foo/bar/plp.fcgi .plp
     </IfModule>
 

+=head1 DESCRIPTION
+
+This is usually the preferred backend, providing persistent processes
+for speeds comparable to L<mod_perl|PLP::Backend::Apache> and
+reliability closer to L<CGI|PLP::Backend::CGI>.
+
+Servers often feature auto-adjusting number of daemons, script timeouts,
+and occasional restarts.
+
+=head2 Configuration directives
+
+PLP behaviour can be configured by setting environment variables.
+
+=over 16
+
+=item PLP_CACHE
+
+Sets caching off if false (0 or empty), on otherwise (true or undefined).
+When caching, PLP saves your script in memory and doesn't re-read
+and re-parse it if it hasn't changed. PLP will use more memory,
+but will also run 50% faster.
+
+=back
+

 =head1 AUTHOR
 
 Mischa POSLAWSKY <perl@shiar.org>
 =head1 AUTHOR
 
 Mischa POSLAWSKY <perl@shiar.org>