perl-docs-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From s...@apache.org
Subject cvs commit: modperl-docs/src/docs/2.0/user/config config.pod
Date Wed, 19 Jun 2002 19:25:02 GMT
stas        2002/06/19 12:25:02

  Modified:    src/docs/2.0/user/config config.pod
  Log:
  moving on with config docs
  
  Revision  Changes    Path
  1.17      +197 -58   modperl-docs/src/docs/2.0/user/config/config.pod
  
  Index: config.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/config/config.pod,v
  retrieving revision 1.16
  retrieving revision 1.17
  diff -u -r1.16 -r1.17
  --- config.pod	15 Jun 2002 18:25:58 -0000	1.16
  +++ config.pod	19 Jun 2002 19:25:02 -0000	1.17
  @@ -41,11 +41,93 @@
   
   If mod_perl has been statically linked it's automatically enabled.
   
  +Win32 users need to make sure that the path to the Perl binary (e.g.,
  +I<C:\Perl\bin>) is in the C<PATH> environment variable.
   
   
   
   
   
  +=head1 Accessing the mod_perl 2.0 Modules
  +
  +In order to prevent from inadvertently loading mod_perl 1.0 modules
  +mod_perl 2.0 Perl modules are installed into dedicated directories
  +under I<Apache2/>. The C<Apache2> module prepends the locations of the
  +mod_perl 2.0 libraries to C<@INC>, which are the same as the core
  +C<@INC>, but with I<Apache2/> appended. This module has to be loaded
  +just after mod_perl has been enabled. This can be accomplished with:
  +
  +  use Apache2 ();
  +
  +in the startup file. Only if you don't use a startup file you can add:
  +
  +  PerlModule Apache2
  +
  +to I<httpd.conf>, due to the order the C<PerlRequire> and
  +C<PerlModule> directives are processed.
  +
  +
  +
  +
  +
  +
  +=head1 Startup File
  +
  +Next usually a startup file with Perl code is loaded:
  +
  +  PerlRequire "/home/httpd/httpd-2.0/perl/startup.pl"
  +
  +It's used to adjust Perl modules search paths in C<@INC>, pre-load
  +commonly used modules, pre-compile constants, etc. Here is a typical
  +I<startup.pl> for mod_perl 2.0:
  +
  +  file:startup.pl
  +  ---------------
  +  use Apache2 ();
  +  
  +  use lib qw(/home/httpd/perl);
  +  
  +  # enable if the mod_perl 1.0 compatibility is needed
  +  # use Apache::compat ();
  +  
  +  use ModPerl::Util (); #for CORE::GLOBAL::exit
  +  
  +  use Apache::RequestRec ();
  +  use Apache::RequestIO ();
  +  use Apache::RequestUtil ();
  +  
  +  use Apache::Server ();
  +  use Apache::ServerUtil ();
  +  use Apache::Connection ();
  +  use Apache::Log ();
  +  
  +  use APR::Table ();
  +  
  +  use ModPerl::Registry ();
  +  
  +  use Apache::Const -compile => ':common';
  +  use APR::Const -compile => ':common';
  +  
  +  1;
  +
  +In this file the C<Apache2> modules is loaded, so the 2.0 modules will
  +be found. Afterwards C<@INC> in adjusted to include non-standard
  +directories with Perl modules:
  +
  +  use lib qw(/home/httpd/perl);
  +
  +If you need to use the backwards compatibility layer load:
  +
  +  use Apache::compat ();
  +
  +Next we preload the commanly used mod_perl 2.0 modules and precompile
  +common constants.
  +
  +Finally as usual the I<startup.pl> file must be terminated with C<1;>.
  +
  +
  +
  +
   
   
   =head1 Perl's Command Line Switches
  @@ -71,10 +153,121 @@
   
   
   
  +=head1 mod_perl 2.0 Handlers
  +
  +mod_perl 2.0 provides two types of handlers: C<modperl> and
  +C<perl-script>.
  +
  +=head2 modperl
  +
  +Configured as:
  +
  +  SetHandler modperl
  +
  +The bare mod_perl handler type, which just calls the C<Perl*Handler>'s
  +callback function. If you don't need the features provided by the
  +I<perl-script> handler, with the C<modperl> handler, you can gain even
  +more performance. (This handler isn't available in mod_perl 1.0.)
  +
  +Unless the C<Perl*Handler> callback running under the C<modperl>
  +handler is configured with:
  +
  +  PerlOptions +SetupEnv
  +
  +or calls:
  +
  +  $r->subprocess_env;
  +
  +in a void context (which has the same effect as C<PerlOptions
  ++SetupEnv> for the handler that called it), only the following
  +environment variables are accessible via C<%ENV>:
  +
  +=over
  +
  +=item *
  +
  +C<MOD_PERL> and C<GATEWAY_INTERFACE> (always)
  +
  +=item *
  +
  +C<PATH> and C<TZ> (if you had them defined in the shell or
  +I<httpd.conf>)
  +
  +=back
  +
  +Therefore if you don't want to add the overhead of populating C<%ENV>,
  +when you simply want to pass some configuration variables from
  +I<httpd.conf>, consider using C<PerlSetVar> and C<PerlAddVar> instead
  +of C<PerlSetEnv> and C<PerlPassEnv>. In your code you can retrieve the
  +values using the C<dir_config()> method. For example if you set in
  +I<httpd.conf>:
  +
  +  <Location /print_env2>
  +      SetHandler modperl
  +      PerlResponseHandler Apache::VarTest
  +      PerlSetVar VarTest VarTestValue
  +  </Location>
   
  +this value can be retrieved inside C<Apache::VarTest::handler()> with:
   
  +  $r->dir_config('VarTest');
   
  -=head1 PerlOptions Directive
  +Alternatively use the Apache core directives C<SetEnv> and C<PassEnv>,
  +which always populate C<r->suprocess_env>, but this doesn't happen
  +until the Apache fixup phase, which could be too late for your needs.
  +
  +=head2 perl-script
  +
  +Configured as:
  +
  +  SetHandler perl-script
  +
  +Most mod_perl handlers use the I<perl-script> handler. Among other
  +things it does:
  +
  +=over
  +
  +=item *
  +
  +C<PerlOptions +GlobalRequest> is in effect unless:
  +
  +  PerlOptions -GlobalRequest
  +
  +is specified.
  +
  +=item *
  +
  +C<PerlOptions +SetupEnv> is in effect unless:
  +
  +  PerlOption -SetupEnv
  +
  +is specified.
  +
  +=item *
  +
  +C<STDOUT> and C<STDOUT> get tied to the request object C<$r>, which
  +makes possible to read from C<STDIN> and print directly to C<STDOUT>
  +via C<CORE::print()>, instead of implicit calls like
  +C<$r-E<gt>puts()>.
  +
  +=item *
  +
  +Several special global Perl variables are saved before the handler is
  +called and restored afterwards (similar to mod_perl 1.0). This
  +includes: C<%ENV>, C<@INC>, C<$/>, C<STDOUT>'s C<$|> and
C<END> blocks
  +array (C<PL_endav>).
  +
  +=back
  +
  +
  +
  +
  +
  +
  +
  +
  +
  +=head1 C<PerlOptions> Directive
   
   The directive C<PerlOptions> provides fine-grained configuration for
   what were compile-time only options in the first mod_perl generation.
  @@ -132,6 +325,8 @@
   one for each C<E<lt>VirtualHostE<gt>>, each with its own namespace and
   pointing to a different paths in C<@INC>:
   
  +META: is -Mblib portable? (problems with -Mlib on Darwin/5.6.0?)
  +
     <VirtualHost ...>
         ServerName dev1
         PerlOptions +Parent
  @@ -351,64 +546,8 @@
   
   =head1 Handlers Directives
   
  -META: need to add descriptions
  -
  -=head2 PerlChildInitHandler
  -
  -=head2 PerlOpenLogsHandler
  -
  -=head2 PerlPostConfigHandler
  -
  -=head2 PerlPreConnectionHandler
  -
  -=head2 PerlProcessConnectionHandler
  -
  -=head2 PerlHeaderParserHandler
  -
  -=head2 PerlAccessHandler
  -
  -=head2 PerlAuthenHandler
  -
  -=head2 PerlAuthzHandler
  -
  -=head2 PerlTypeHandler
  -
  -=head2 PerlFixupHandler
  -
  -=head2 PerlResponseHandler
  -
  -=head2 PerlLogHandler
  -
  -=head2 PerlPostReadRequestHandler
  -
  -=head2 PerlInitHandler
  -
  -=head2 PerlTransHandler
  -
  -=head2 PerlOutputFilterHandler
  -
  -The mod_perl 2.0 interface to the Apache filtering API is much simpler
  -than the C API, hiding most of the details underneath.  Perl filters
  -are configured using the C<PerlOutputFilterHandler> directive. For
  -example:
  -
  -  PerlOutputFilterHandler Apache::ReverseFilter
  -
  -This simply registers the filter, which can then be turned on using
  -the core C<AddOutputFilter> directive:
  -
  -  <Location /filterme>
  -      AddOutputFilter Apache::ReverseFilter
  -  </Location>
  -
  -The C<Apache::ReverseFilter> handler will now be called for anything
  -accessed in the I</filterme> URL space.  The C<AddOutputFilter>
  -directive takes any number of filters. For example, the configuration:
  -
  -  AddOutputFilter INCLUDE Apache::ReverseFilter
  +See L<The handlers chapter|docs::2.0::user::handlers::handler>.
   
  -will first send the output to I<mod_include>, which will in turn pass
  -its output down to C<Apache::ReverseFilter>.
   
   
   
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org


Mime
View raw message