You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs-cvs@perl.apache.org by st...@apache.org on 2002/05/21 18:26:44 UTC
cvs commit: modperl-docs/src/docs/2.0/user/overview overview.pod
stas 02/05/21 09:26:44
Modified: src/docs/2.0/user/design design.pod
src/docs/2.0/user/install install.pod
src/docs/2.0/user/overview overview.pod
Log:
cleanups, markup
Revision Changes Path
1.7 +2 -2 modperl-docs/src/docs/2.0/user/design/design.pod
Index: design.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/design/design.pod,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- design.pod 20 Mar 2002 17:44:04 -0000 1.6
+++ design.pod 21 May 2002 16:26:43 -0000 1.7
@@ -504,14 +504,14 @@
written to. It would be possible to implement copy-on-write strings
in the Perl core with little performance overhead.
-=head2 Compile time method lookups
+=head2 Compile-time method lookups
A known disadvantage to Perl method calls is that they are slower than
direct function calls. It is possible to resolve method calls at
compile time, rather than runtime, making method calls just as fast as
subroutine calls. However, there is certain information required for
method look ups that are only known at runtime. To work around this,
-compile time hints can be used, for example:
+compile-time hints can be used, for example:
my Apache::Request $r = shift;
1.13 +76 -62 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.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- install.pod 19 May 2002 09:38:21 -0000 1.12
+++ install.pod 21 May 2002 16:26:43 -0000 1.13
@@ -12,41 +12,43 @@
=head1 Installing from Source
+XXX: For Win32 specific installation doc here.
+
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:anoncvs@cvs.apache.org:/home/cvspublic login
- % cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic co modperl-2.0
- % cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic co httpd-2.0
- % cd httpd-2.0/srclib
- % cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic co apr
- % cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic co apr-util
- % cd ..
- % ./buildconf
- % ./configure --prefix=$HOME/apache-2.0 --with-mpm=prefork
- % make && make install
+ % cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic login
+ % cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic co modperl-2.0
+ % cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic co httpd-2.0
+ % cd httpd-2.0/srclib
+ % cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic co apr
+ % cvs -d :pserver:anoncvs@cvs.apache.org:/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
+ % 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
+ # (--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.
@@ -63,68 +65,62 @@
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")'
+ % $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
+ % 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.
+The following options are boolean and can be set with C<MP_XXX=1> or
+unset with C<MP_XXX=0>, where XXX is the name of the option.
=over 4
=item MP_PROMPT_DEFAULT
-Accept default values for all would-be prompts
+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>.
+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)
+Build mod_perl as a DSO. This is the default.
=item MP_USE_STATIC
-Build mod_perl static
+Build mod_perl static.
=item MP_STATIC_EXTS
-Build Apache::*.xs as static extensions
+Build C<Apache::*.xs> as static extensions.
=item MP_USE_GTOP
-Link with libgtop and enable libgtop reporting
+Link with I<libgtop> and enable I<libgtop> reporting.
=item MP_DEBUG
-Turn on debugging (-g -lperld) and tracing
+Turn on debugging (C<-g -lperld>) and tracing.
=item MP_MAINTAINER
-NOTE: apache must be build with --enable-maintainer-mode
+Enable maintainer compile mode, which sets C<MP_DEBUG=1> and adds the
+following C<gcc> flags:
-Maintainer compile mode, turn on MP_DEBUG and add gcc flags:
+ -DAP_DEBUG -Wall -Wmissing-prototypes -Wstrict-prototypes \
+ -Wmissing-declarations
- -DAP_DEBUG \
- -Wall -Wmissing-prototypes -Wstrict-prototypes -Wmissing-declarations
+To use this mode Apache must be build with
+C<--enable-maintainer-mode>.
=item MP_TRACE
@@ -132,7 +128,7 @@
=item MP_INST_APACHE2
-Install *.pm relative to Apache2/ directory
+Install all the I<*.pm> modules relative to the I<Apache2/> directory.
=back
@@ -140,18 +136,35 @@
=over 4
+=item MP_APXS
+
+Path to C<apxs>. For example if you've installed Apache 2.0 under
+I</home/httpd/httpd-2.0> as DSO, the default location would be
+I</home/httpd/httpd-2.0/bin/apxs>.
+
+=item MP_AP_PREFIX
+
+Apache installation prefix. This option can be used to derive C<apxs>
+values on platforms where C<apxs> is not supported (e.g., on Win32).
+For example if you've have installed Apache 2.0 in C<\Apache2> on
+Win32, you should use:
+
+ MP_AP_PREFIX=\Apache2
+
=item MP_CCOPTS
-Add to compiler flags, e.g.
+Add to compiler flags, e.g.:
- MP_CCOPTS=-Werror
+ MP_CCOPTS=-Werror
-(Notice that C<-Werror> will work only with the Perl version 5.007 and
+(Notice that C<-Werror> will work only with the Perl version 5.7 and
higher.)
=item MP_OPTIONS_FILE
-Read options from given file
+Read build options from given file. e.g.:
+
+ MP_OPTIONS_FILE=~/.my_mod_perl2_opts
=back
@@ -161,14 +174,14 @@
=item -DMP_IOBUFSIZE
-Change the default mod_perl's 8K IO buffer size, e.g. 16K:
+Change the default mod_perl's 8K IO buffer size, e.g. to 16K:
- MP_CCOPTS=-DMP_IOBUFSIZE=16384
+ 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},
+I<.makepl_args.mod_perl2>. The file can be placed under C<$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:
@@ -183,15 +196,13 @@
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>.
+Options specified on the command line override those from
+I<makepl_args.mod_perl2> and those from C<MP_OPTIONS_FILE>.
If your terminal supports colored text you may want to set the
environment variable C<APACHE_TEST_COLOR> to 1 to enable the colored
tracing which makes it easier to tell the reported errors and
-warnings, from the rest of the notifications. Make sure that the
-environment variable C<APACHE_TEST_COLOR> is set to 0 (or not set at
-all) if you redirect the output from the testing to a file.
+warnings, from the rest of the notifications.
=head2 Compile mod_perl
@@ -233,15 +244,18 @@
=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:
+can use this knowledge to rebuild itself using the same
+options. Simply chdir(1) to the mod_perl source directory and run:
% cd modperl-2.0
% perl -MApache::Build -e rebuild
=head1 Installing from Binary Packages
+As of this writing only the binaries for the Win32 platform are
+available, kindly prepared and maintained by Randy Kobes.
+XXX: link to Win32 download doc.
=head1 Maintainers
1.6 +32 -32 modperl-docs/src/docs/2.0/user/overview/overview.pod
Index: overview.pod
===================================================================
RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/overview/overview.pod,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- overview.pod 26 Apr 2002 05:33:53 -0000 1.5
+++ overview.pod 21 May 2002 16:26:44 -0000 1.6
@@ -33,7 +33,7 @@
enabled mod_perl to compile and run in a threaded windows environment,
with one major caveat: only one concurrent mod_perl request could be
handled at any given time. This was due to the fact that Perl did not
-introduce thread safe interpreters until version 5.6.0, released in
+introduce thread-safe interpreters until version 5.6.0, released in
March of 2000. Contrary to popular belief, the "threads support"
implemented in Perl 5.005 (released July 1998), did not make Perl
thread-safe internally. Well before that version, Perl had the notion
@@ -245,7 +245,7 @@
mechanisms, it is possible for any number of threads in the same
process to concurrently callback into Perl. This of course requires
each thread to have its own C<PerlInterpreter> object, or at least
-that each instance is only access by one thread at any given time.
+that each instance is only accessed by one thread at any given time.
mod_perl-1.xx has only a single C<PerlInterpreter>, which is
contructed by the parent process, then inherited across the forks to
@@ -264,28 +264,28 @@
=head2 New mod_perl Directives for Threaded MPMs
Rather than create a C<PerlInterperter> per-thread by default,
-mod_perl creates a pool of interpreters. The pool mechanism helps cut
-down memory usage a great deal. As already mentioned, the syntax tree
+mod_perl creates a pool of interpreters. The pool mechanism helps cut
+down memory usage a great deal. As already mentioned, the syntax tree
is shared between all cloned interpreters. If your server is serving
more than mod_perl requests, having a smaller number of
PerlInterpreters than the number of threads will clearly cut down on
memory usage. Finally and perhaps the biggest win is memory reuse.
That is, as calls are made into Perl subroutines, memory allocations
are made for variables when they are used for the first time.
-Subsequent use of variables may allocate more memory, e.g. if the
-string needs to hold a larger than it did before, or an array more
-elements than in the past. As an optimization, Perl hangs onto these
-allocations, even though their values "go out of scope". With the
-1.xx model, random children would be hit with these allocations. With
-2.0, mod_perl has much better control over which PerlInterpreters are
-used for incoming requests. The intepreters are stored in two linked
-lists, one for available interpreters one for busy. When needed to
-handle a request, one is taken from the head of the available list and
-put back into the head of the list when done. This means if you have,
-say, 10 interpreters configured to be cloned at startup time, but no
-more than 5 are ever used concurrently, those 5 continue to reuse
-Perls allocations, while the other 5 remain much smaller, but ready to
-go if the need arises.
+Subsequent use of variables may allocate more memory, e.g. if a scalar
+variable needs to hold a longer string than it did before, or an array
+more elements than in the past. As an optimization, Perl hangs onto
+these allocations, even though their values "go out of scope". With
+the 1.xx model, random children would be hit with these allocations.
+With 2.0, mod_perl has much better control over which PerlInterpreters
+are used for incoming requests. The intepreters are stored in two
+linked lists, one for available interpreters, one for busy. When
+needed to handle a request, one is taken from the head of the
+available list and put back into the head of the list when done. This
+means if you have, say, 10 interpreters configured to be cloned at
+startup time, but no more than 5 are ever used concurrently, those 5
+continue to reuse Perl's allocations, while the other 5 remain much
+smaller, but ready to go if the need arises.
Various attributes of the pools are configurable with the following
configuration directives:
@@ -944,11 +944,11 @@
be executed on the server side, with results sent back to the client.
The C<Apache::CommandServer> handler will support four commands:
-C<motd>, C<date>, C<who> and C<quit>. These are probably not
-commands which can be exploited, but should we add such commands,
-we'll want to limit access based on ip address/hostname,
-authentication and authorization. Protocol handlers need to take care
-of these tasks themselves, since we bypass the HTTP protocol handler.
+C<motd>, C<date>, C<who> and C<quit>. These are probably not commands
+which can be exploited, but should we add such commands, we'll want to
+limit access based on ip address/hostname, authentication and
+authorization. Protocol handlers need to take care of these tasks
+themselves, since we bypass the HTTP protocol handler.
As with all C<PerlProcessConnectionHandlers>, we are passed an
C<Apache::Connection> object as the first argument. Again, we will be
@@ -992,19 +992,19 @@
require user dougm
</Location>
-Given this configuration, I<some_auth_required> will return true.
-The I<user> method is then called, which will return false if we have
-not yet authenticated. A I<prompt> utility is called to read the
-username and password, which are then injected into the I<headers_in>
-table using the I<set_basic_credentials> method. The I<Authenticate>
-field in this table is set to a base64 encoded value of the
+Given this configuration, I<some_auth_required> will return true. The
+I<user> method is then called, which will return false if we have not
+yet authenticated. A I<prompt> utility is called to read the username
+and password, which are then injected into the I<headers_in> table
+using the I<set_basic_credentials> method. The I<Authenticate> field
+in this table is set to a base64 encoded value of the
username:password pair, exactly the same format a browser would send
for I<Basic authentication>. Next time through the loop
I<run_check_user_id> is called, which will in turn invoke any
authentication handlers, such as I<mod_auth>. When I<mod_auth> calls
the I<ap_get_basic_auth_pw()> API function (as all Basic auth modules
-do), it will get back the username and password we injected.
-If we fail authentication a B<401> status code is returned which we
+do), it will get back the username and password we injected. If we
+fail authentication a B<401> status code is returned which we
propagate up. Otherwise, authorization handlers are run via
I<run_auth_checker>. Authorization handlers normally need the I<user>
field of the I<request_rec> for its checks and that field was filled
@@ -1013,7 +1013,7 @@
Provided login is a success, a welcome message is printed and main
request loop entered. Inside the loop the I<getline> function returns
just one line of data, with newline characters stripped. If the
-string sent by the client is in our command table, the command is then
+string sent by the client is in our command table, the command is then
invoked, otherwise a usage message is sent. If the command does not
return a true value, we break out of the loop. Let's give it a try
with this configuration:
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org