stas 01/12/27 03:51:54
Modified: src/docs/2.0/user/config config.pod
src/docs/2.0/user/install install.pod
Log:
config and install sections moved from pod/modperl_dev.pod into
corresponding documents
Revision Changes Path
1.2 +214 -1 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.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- config.pod 2001/12/18 02:59:44 1.1
+++ config.pod 2001/12/27 11:51:54 1.2
@@ -1,7 +1,220 @@
=head1 NAME
-Server Configuration
+mod_perl Server Configuration
+
+=head1 mod_perl configuration directives
+
+=head2 Installing handlers
+
+=over 4
+
+=item PerlChildInitHandler
+
+=item PerlOpenLogsHandler
+
+=item PerlPostConfigHandler
+
+=item PerlPreConnectionHandler
+
+=item PerlProcessConnectionHandler
+
+=item PerlHeaderParserHandler
+
+=item PerlAccessHandler
+
+=item PerlAuthenHandler
+
+=item PerlAuthzHandler
+
+=item PerlTypeHandler
+
+=item PerlFixupHandler
+
+=item PerlOutputFilterHandler
+
+=item PerlResponseHandler
+
+=item PerlLogHandler
+
+=item PerlPostReadRequestHandler
+
+=item PerlInitHandler
+
+=item PerlTransHandler
+
+=back
+
+=head2 General directives
+
+=over 4
+
+=item PerlSwitches switches
+
+pass switches to the Perl command line. For example, to enable
+warnings:
+
+ PerlSwitches -w
+
+=item PerlTrace [level]
+
+set the trace level. This directive is enabled when mod_perl is compiled with
+the MP_TRACE option. C<level> is either:
+
+ all
+
+which sets maximum logging and debugging levels;
+
+a combination of one or more option letters (or option numerical
+equivalents) from the following list:
+
+ d ( 1) directive processing
+ f ( 2) filters
+ g ( 4) Perl runtime interaction
+ h ( 8) handlers
+ i ( 16) interpreter pool management
+ m ( 32) memory allocations
+ s ( 64) perl sections
+ t (128) benchmark-ish timings
+
+When C<level> is not specified, the tracing level will be set to the
+value of the MOD_PERL_TRACE environment variable.
+
+=back
+
+=head2 Threaded mode directives
+
+These directives are enabled only in a threaded mod_perl+Apache combo.
+
+=over 4
+
+=item PerlInterpStart
+
+Number of Perl interpreters to start
+
+=item PerlInterpMax
+
+Max number of running Perl interpreters
+
+=item PerlInterpMaxSpare
+
+Max number of spare Perl interpreters
+
+=item PerlInterpMinSpare
+
+Min number of spare Perl interpreters
+
+=item PerlInterpMaxRequests
+
+Max number of requests per Perl interpreters
+
+=item PerlInterpScope
+
+Scope for which selected interpreter should be held, one of:
+I<request>, I<connection>, I<handler>, I<subrequest>.
+
+The default is I<request>.
+
+=back
+
+=head2 PerlOptions Directive
+
+Enable/Disable Options. Options include:
+
+=over 4
+
+=item Parent
+
+Create a new parent Perl interpreter for the given VirtualHost and
+give it its own interpreter pool (implies Clone).
+
+=item Clone
+
+Share the parent Perl interpreter, but give the VirtualHost its own
+interpreter pool.
+
+Use:
+
+ PerlSwitches +inherit
+
+to inherit base Perl interpreter's C<PerlSwitches>.
+
+=item Enable
+
+On by default, used to disable mod_perl for a given VirtualHost.
+
+=item Perl*Handler
+
+Disable Perl*Handlers, all compiled in handlers are enabled by default.
+
+=item AutoLoad
+
+Resolve Perl*Handlers at startup time, includes loading the module
+from disk if not already loaded.
+
+=item GlobalRequest
+
+Setup the global request_rec for use with Apache->request
+
+=item ParseHeaders
+
+Scan output for HTTP headers, same functionality as 1.x's
+PerlSendHeaders, but more robust.
+
+=item MergeHandlers
+
+Turn on merging of Perl*Handler arrays, example:
+
+ PerlFixupHandler One::fixup
+
+ <Location /foo>
+ PerlFixupHandler Another::fixup
+ </Location>
+
+By default, a request for /foo only runs B<Another::fixup> (1.x behavior)
+I<PerlOptions +MergeHandlers> (inside Location /foo) will run both
+B<One::fixup> and B<Another::fixup>.
+
+=back
+
+Examples:
+
+ # disable mod_perl for this host
+ <VirtualHost ...>
+ PerlOptions -Enable
+ </VirtualHost>
+
+ # create 2 Parent Perls,
+ # each pointing to a different developer library tree
+ <VirtualHost ...>
+ ServerName dev1
+ PerlOptions +Parent
+ PerlSwitches -Mblib=/home/dev1/lib/perl
+ </VirtualHost>
+
+ <VirtualHost ...>
+ ServerName dev2
+ PerlOptions +Parent
+ PerlSwitches -Mblib=/home/dev2/lib/perl
+ </VirtualHost>
+
+ # give VirtualHost its own interpreter pool
+ <VirtualHost ...>
+ PerlOptions +Clone
+ PerlInterpStart 2
+ PerlInterpMax 2
+ </VirtualHost>
+
+ # disable handlers
+ <VirtualHost ...>
+ PerlOptions -Authen -Authz -Access
+ </VirtualHost>
+
+
+
+
+
+
=head1 Retrieving Server Startup Options
1.7 +219 -1 modperl-docs/src/docs/2.0/user/install/install.pod
Index: install.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/install/install.pod,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- install.pod 2001/11/22 03:46:09 1.6
+++ install.pod 2001/12/27 11:51:54 1.7
@@ -8,8 +8,217 @@
=head1 Installing from Source
-=head3 Re-using Build Options
+Download the httpd-2.0 and modperl-2.0 tarballs, and extract them in the
+same directory.
+Or use anoncvs (password is "anoncvs"):
+
+ % cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic login
+ % cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic co modperl-2.0
+ % cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic co httpd-2.0
+ % cd httpd-2.0/srclib
+ % cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic co apr
+ % cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic co apr-util
+ % cd ..
+ % ./buildconf
+ % ./configure --prefix=$HOME/apache-2.0 --with-mpm=prefork
+ % make && make install
+
+Once extracted, whenever you want to sync with the latest httpd-2.0
+version and rebuild, run:
+
+ % cd httpd-2.0
+ % cvs up -dP
+ % make distclean && ./buildconf
+ % ./configure --prefix=$HOME/apache-2.0 --with-mpm=prefork
+ % make && make install
+
+For bleeding edge Perl:
+
+ # (--delete to ensure a clean state)
+ % rsync -acvz --delete --force \
+ rsync://ftp.linux.activestate.com/perl-current/ perl-current
+ % cd perl-current
+ % ./Configure -des -Dprefix=$HOME/bleedperl \
+ -Dusethreads -Doptimize='-g' -Dusedevel
+ % make && make test && make install
+ % ln -s $HOME/bleedperl/bin/perl5.x.x $HOME/bleedperl/bin/perl
+
+or otherwise make sure that your perl was built with threads enabled if
+you want to use a threaded MPM.
+
+If you are re-building Perl after rsync-ing, make sure to cleanup:
+
+ % make distclean
+
+before running C<./Configure>.
+
+You'll also want to install (at least) LWP into the bleedperl/lib
+directory if you want to fully test mod_perl, because normally a
+privately installed bleedperl won't find libraries installed in the
+normal places; it only looks in it's own lib tree. You can install LWP
+with CPAN.pm shell:
+
+ % $HOME/bleedperl/bin/perl -MCPAN -e 'install("LWP")'
+
+
+=head1 Compiling
+
+=head2 Create the build environment
+
+ % cd modperl-2.0
+ % perl Makefile.PL MP_APXS=$apache_prefix/bin/apxs && make
+
+I<options> an optional list of (key,value) pairs.
+
+Boolean options: set them with MP_XXX=1.
+
+=over 4
+
+=item MP_PROMPT_DEFAULT
+
+Accept default values for all would-be prompts
+
+=item MP_GENERATE_XS
+
+Generate xs code from parsed source headers in I<xs/tables/$httpd_version>.
+Default is 1, set to 0 to disable.
+
+=item MP_USE_DSO
+
+Build mod_perl as a DSO (default)
+
+=item MP_APXS
+
+Path to apxs
+
+=item MP_AP_PREFIX
+
+Apache installation prefix
+(can be used to derive apxs values on platforms where apxs is not supported)
+
+=item MP_USE_STATIC
+
+Build mod_perl static
+
+=item MP_STATIC_EXTS
+
+Build Apache::*.xs as static extensions
+
+=item MP_USE_GTOP
+
+Link with libgtop and enable libgtop reporting
+
+=item MP_DEBUG
+
+Turn on debugging (-g -lperld) and tracing
+
+=item MP_MAINTAINER
+
+NOTE: apache must be build with --enable-maintainer-mode
+
+Maintainer compile mode, turn on MP_DEBUG and add gcc flags:
+
+ -DAP_DEBUG \
+ -Wall -Wmissing-prototypes -Wstrict-prototypes -Wmissing-declarations
+
+=item MP_TRACE
+
+Enable tracing
+
+=item MP_INST_APACHE2
+
+Install *.pm relative to Apache2/ directory
+
+=back
+
+Non-Boolean options: set them with MP_XXX=value.
+
+=over 4
+
+=item MP_CCOPTS
+
+Add to compiler flags, e.g.
+
+ MP_CCOPTS=-Werror
+
+(Notice that C<-Werror> will work only with the Perl version 5.007 and
+higher.)
+
+=item MP_OPTIONS_FILE
+
+Read options from given file
+
+=back
+
+mod_perl specific compiler options:
+
+=over 4
+
+=item -DMP_IOBUFSIZE
+
+Change the default mod_perl's 8K IO buffer size, e.g. 16K:
+
+ MP_CCOPTS=-DMP_IOBUFSIZE=16384
+
+=back
+
+Options can also be specified in the file I<makepl_args.mod_perl2> or
+I<.makepl_args.mod_perl2>. The file can be placed under $ENV{HOME},
+the root of the source package or its parent directory. So if you
+unpack the mod_perl source into I</tmp/mod_perl-2.x/> and your home is
+I</home/foo/>, the file will be searched in:
+
+ /tmp/mod_perl-2.x/makepl_args.mod_perl2
+ /tmp/makepl_args.mod_perl2
+ /home/foo/makepl_args.mod_perl2
+ /tmp/mod_perl-2.x/.makepl_args.mod_perl2
+ /tmp/.makepl_args.mod_perl2
+ /home/foo/.makepl_args.mod_perl2
+
+If the file specified in C<MP_OPTIONS_FILE> is found the
+I<makepl_args.mod_perl2> will be ignored.
+
+Command line options override those from I<makepl_args.mod_perl2> and
+those from C<MP_OPTIONS_FILE>.
+
+=head2 Compile mod_perl
+
+ % make
+
+=head2 Configure and compile Apache
+
+ % cd ../httpd-2.0
+ % ./configure --with-mpm=prefork
+ % make
+
+=head2 Test mod_perl
+
+ % make test
+
+L<../testing/testing.pod> document covers the C<make test> suite.
+
+META: probably need to link directly to the 'Running Tests' section.
+
+=head2 Howto generate source tables
+
+All mod_perl-2.0 xs code is generated from parsed header files. While
+in pre-release mode, a version of these tables will be checked in to
+I<xs/tables/current>. Should you wish to update these tables, here's
+how:
+
+NOTE: requires C::Scan 0.75, which at the moment is unreleased, there
+is a working copy here: http://perl.apache.org/~dougm/Scan.pm
+
+NOTE: source_scan.pl is a HEAVY process, do not be alarmed.
+
+ % perl build/source_scan.pl apxs $apache_prefix/bin/apxs
+
+META: this is covered in L<core_explained> should probably move/point
+there.
+
+=head2 Re-using Build Options
+
Since mod_perl remembers what build options were used to build it, you
can use this knowledge to rebuild it using the same options. Simply
chdir to the mod_perl source directory and run:
@@ -24,7 +233,16 @@
Maintainer is the person(s) you should contact with updates,
corrections and patches.
+Stas Bekman E<lt>stas (at) stason.orgE<gt>
+
=head1 Authors
+
+=over
+
+=item * Stas Bekman E<lt>stas (at) stason.orgE<gt>
+
+=back
+
=cut
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
