randyk 02/05/29 22:50:21
Added: src/docs/2.0/os/win32 .cvsignore Changes.pod config.cfg
modperl2.pod
Log:
initial Win32 modperl2 doc.
Revision Changes Path
1.1 modperl-docs/src/docs/2.0/os/win32/.cvsignore
Index: .cvsignore
===================================================================
cache.*.dat
1.1 modperl-docs/src/docs/2.0/os/win32/Changes.pod
Index: Changes.pod
===================================================================
=head1 NAME
CHANGES
=head1 Description
Refer to this document to learn what changes were made to the
documents, since you've read these last time.
The most recent changes are listed first.
=head1 Thu May 30 12:20:02 SGT 2002
* win32::modperl2 initial docs
submitted by Randy Kobes E<lt>[EMAIL PROTECTED]<gt>
=cut
1.1 modperl-docs/src/docs/2.0/os/win32/config.cfg
Index: config.cfg
===================================================================
use vars qw(@c);
@c = (
id => 'win32',
title => "Win32 Platforms",
abstract => <<EOB,
Documents assisting mod_perl-2 users on the Win32 platforms
EOB
chapters => [qw(
modperl2.pod
Changes.pod
)],
);
1.1 modperl-docs/src/docs/2.0/os/win32/modperl2.pod
Index: modperl2.pod
===================================================================
=head1 NAME
win32_apache2 - obtaining and configuring mod_perl-2 for Win32
=head1 DESCRIPTION
As described in the discussion of issues in
L<multithreaded win32|docs::1.0::os::win32::multithread>,
a mod_perl-1 enabled
server based on Apache-1 on Win32 is limited to a single
thread serving a request at a time. This effectively
prevents concurrent processing, which can have serious
implications for busy sites. This problem is addressed
in the multi-thread/multi-process approach of mod_perl-2/Apache-2.
This document discusses how to obtain and configure mod_perl-2.
=head1 OBTAINING
Apache-2 and mod_perl-2 can be obtained in two ways - either
as binaries, or through building from the sources.
As with most packages of a more complex nature, it is best,
when possible, to build things from the sources. However,
this requires some experience with using Visual C++.
=head2 Building from sources
If you are building mod_perl-2 from sources, it is probably
also best to do the same for Apache-2. The Apache-2 sources
can be obtained from http://httpd.apache.org/, which when
unpacked will contain at the top-level a Visual Studio
project file. Choose the C<InstallBin - Win32 Release> target
to build and install Apache-2, which by default will
be placed in F</Apache2>.
Having built and installed Apache-2, next obtain the
mod_perl-2 sources from http://www.cpan.org/authors/id/D/DO/DOUGM/.
After unpacking, run the command
perl Makefile.PL MP_AP_PREFIX=\Path\to\Apache2
where F<\Path\to\Apache2> is the path to the Apache-2
package you earlier built. Then
nmake
nmake test
will build and test mod_perl-2. mod_perl-2 on Win32 is
considered at an alpha stage of development, so not
all the tests may pass.
The final command,
nmake install
will install the necessary mod_perl-2 files into your
Perl directory tree (you will also need to copy
F<src/modules/perl/mod_perl.so> into your F</Path/to/Apache2/modules/>
directory). If you are installing mod_perl-2 on a system that
also contains mod_perl-1, then some mod_perl-1 files will be
overwritten by this procedure. This can be avoided by preparing
the build as
perl Makefile.PL MP_AP_PREFIX=\Path\to\Apache2 MP_INST_APACHE2=1
which will subsequently lead to the mod_perl-2 files
being installed under an F<Apache2> subdirectory in your Perl tree.
You will then have to employ either a C<use Apache2;> line in your
scripts/packages or else a C<PerlModule Apache2> directive in
Apache's F<httpd.conf>.
If this build fails, you may want to try the latest cvs
sources - see http://perl.apache.org/mod_perl_cvs.html for
details. If you do try this, it is generally
a good idea to also use the cvs Apache-2 sources -
see http://httpd.apache.org/dev/ for information. Be aware,
though, that as well as providing
bug fixes, there may be new features being added and tested
in the cvs versions, so at any given time there are no
guarantees that these packages will build and test successfully.
=head2 Binary packages
There are two ways of obtaining a binary mod_perl-2 package.
=over 3
=item PPM
The first, for ActivePerl users, is through C<PPM> - this
assumes you already have ActivePerl (build 6xx) from
http://www.activestate.com/ and a Win32 Apache-2 binary
from http://httpd.apache.org/. In installing
this, you may find it convenient when transcribing any Unix-oriented
documentation to choose installation directories that do not have
spaces in their names (eg, F<C:/Apache2>).
After installing Perl and Apache-2, you can then install mod_perl via
the C<PPM> utility. ActiveState does not maintain mod_perl in their ppm
repository, so you must get it from a different location other than
ActiveState's site. One way is simply as (broken over two lines for
readability)
C:\> ppm install
http://theoryx5.uwinnipeg.ca/ppmpackages/mod_perl-2.ppd
Another way, which will be useful if you plan on installing additional
Apache modules, is to set the repository within the C<ppm> shell
utility as (broken over 2 lines for readability)
PPM> set repository theoryx5
http://theoryx5.uwinnipeg.ca/cgi-bin/ppmserver?urn:/PPMServer
or, for C<ppm3>,
PPM> rep add theoryx5
http://theoryx5.uwinnipeg.ca/cgi-bin/ppmserver?urn:/PPMServer
mod_perl-2 can then be installed as
PPM> install mod_perl-2
This will install the necessary modules under an F<Apache2>
subdirectory in your Perl tree, so as not to disturb an
existing F<Apache> directory from mod_perl-1. See the section
below on configuring mod_perl to add this directory to the
C<@INC> path for searching for modules.
The mod_perl PPM package also includes the necessary Apache DLL
C<mod_perl.so>; a post-installation script should be run which will
offer to copy this file to your Apache2 modules directory (eg,
F<C:/Apache2/modules/>). If this is not done, you can get
the file F<mod_perl-2.tar.gz> from
http://theoryx5.uwinnipeg.ca/ppmpackages/x86/ which, when
unpacked, contains F<mod_perl.so> in the top-level directory.
Note that the mod_perl package available from this site will always
use the latest mod_perl sources compiled against the latest official
Apache release; depending on changes made in Apache, you may or may
not be able to use an earlier Apache binary. However, in the Apache
Win32 world it is particularly a good idea to use the latest version,
for bug and security fixes.
=item Apache/mod_perl binary
At ftp://theoryx5.uwinnipeg.ca/pub/other/ one can find an
archive F<Apache2.tar.gz> containing a binary version
of Apache-2/mod_perl-2 - see the F<Apache2.readme> file
for further information. This archive unpacks into
an F<Apache2> directory, underneath which is a F<blib>
subdirectory containing the necessary mod_perl files (enabled
with a C<PerlSwitches> directive in F<httpd.conf>).
Some editing of F<httpd.conf> will be necessary to reflect
the location of the installed directory.
This package, which is updated periodically, is compiled against
recent cvs sources of Apache-2 and mod_perl-2. As such, it may
contain features, and bugs, not present in the current official
releases. Also for this reason, these may not be binary compatible
with other versions of Apache-2/mod_perl-2.
=back
=head1 CONFIGURATION
Add this line to F<C:/Apache2/conf/httpd.conf>:
LoadModule perl_module modules/mod_perl.so
Be sure that the path to your Perl binary (eg, F<C:/Perl/bin>) is in
your C<PATH> environment variable. You may also want to use
a start-up script to load commonly used modules; this can be
done with a directive as, eg,
PerlRequire "C:/Apache2/conf/extra.pl"
where a sample start-up script F<C:/Apache2/conf/extra.pl> is
use Apache2 ();
use ModPerl::Util ();
use Apache::RequestRec ();
use Apache::RequestIO ();
use Apache::RequestUtil ();
use Apache::Server ();
use Apache::ServerUtil ();
use Apache::Connection ();
use Apache::Log ();
use Apache::Const -compile => ':common';
use APR::Const -compile => ':common';
use APR::Table ();
use Apache::compat ();
use ModPerl::Registry ();
use CGI ();
1;
The C<Apache2> module is used to add to C<@INC> the
relevant directories underneath, eg, F</Perl/site/lib/Apache2/>
used when building mod_perl-2 with an C<MP_INST_APACHE2=1>
option to C<perl Makefile.PL> (the C<PPM> packages discussed
above were built this way). C<Apache::compat> is used to
provide backwards compatibility with mod_perl-1.
C<ModPerl::Registry>, named so as not to conflict with
C<Apache::Registry> of mod_perl-1, is used for registry scripts.
=head2 Registry scripts
Using C<ModPerl::Registry> to speed up cgi scripts may be done as
follows. Create a directory, for example, F<C:/Apache2/perl/>, which
will hold your scripts, such as
## printenv -- demo CGI program which just prints its environment
##
use strict;
print "Content-type: text/html\n\n";
print "<HTML><BODY><H3>Environment variables</H3><UL>";
foreach (sort keys %ENV) {
my $val = $ENV{$_};
$val =~ s|\n|\\n|g;
$val =~ s|"|\\"|g;
print "<LI>$_ = \"${val}\"</LI>\n";
}
#sleep(10);
print "</UL></BODY></HTML>";
Note that Apache takes care of using the proper line endings
when sending the I<Content-type> header. Next, insert in
F<C:/Apache2/conf/httpd.conf> the following directives:
Alias /perl/ "/Apache2/perl/"
<Location /perl>
SetHandler perl-script
PerlResponseHandler ModPerl::Registry
Options +ExecCGI
PerlOptions +ParseHeaders
</Location>
whereby the script would be called as
http://localhost/perl/name_of_script
The C<PerlOptions +ParseHeaders> directive is needed when
the script sends the header (in mod_perl-1, this was given
as C<PerlSendHeader ON)>. Note that if you use the C<CGI.pm>
module in your script, then the directive
PerlOptions +GlobalRequest
should be added within the relevant C<Location> block.
As an illustration of how mod_perl-2 addresses the issues
raised in the discussion of issues in
L<multithread win32|docs::1.0::os::win32::multithread>
concerning the threading limitations
of mod_perl-1 on Win32, consider the C<printenv> script above
with the C<sleep(10)> line uncommented. Using the Apache
benchmarking tool C<ab> of the Apache-2 Win32 distribution:
ab -n 5 -c 5 http://localhost/perl/printenv
to make 5 concurrent requests, we find the following results.
For mod_perl-1/Apache-1:
Server Software: Apache/1.3.23
Concurrency Level: 5
Time taken for tests: 50.51972 seconds
Complete requests: 5
Failed requests: 0
Requests per second: 0.10 [#/sec] (mean)
Time per request: 50.052 [ms] (mean)
Time per request: 10.010 [ms] (mean, across all concurrent requests)
Transfer rate: 0.14 [Kbytes/sec] received
while for mod_perl-2/Apache-2:
Server Software: Apache/2.0.36
Concurrency Level: 5
Time taken for tests: 1.81555 seconds
Complete requests: 5
Requests per second: 4.62 [#/sec] (mean)
Time per request: 1.082 [ms] (mean)
Time per request: 0.216 [ms] (mean, across all concurrent requests)
Transfer rate: 7.40 [Kbytes/sec] received
The dramatic difference is due to the fact that in Apache-1/mod_perl-1
a given request has to finish (taking essentially 10 seconds, due
to the C<sleep(10)> call) before the next request is processed, whereas
on Apache-2/mod_perl-2 the requests are processed as they arrive.
=head2 Hello World
As you will discover, there is much to mod_perl beyond simple speed-up
of cgi scripts. Here is a simple I<Hello, World> example that
illustrates the use of mod_perl as a content handler. Create a file
F<Hello.pm> as follows:
package Apache::Hello;
use strict;
use Apache::RequestRec (); # for $r->content_type
use Apache::RequestIO (); # for $r->puts
use Apache::Const -compile => ':common';
sub handler {
my $r = shift;
my $time = scalar localtime();
my $package = __PACKAGE__;
$r->content_type('text/html');
$r->puts(<<"END");
<HTML><BODY>
<H3>Hello</H3>
Hello from <B>$package</B>! The time is $time.
</BODY></HTML>
END
return Apache::OK;
}
1;
and save it in, for example, the F<C:/Perl/site/lib/Apache2/Apache/>
directory. Next put the following directives in
F<C:/Apache2/conf/httpd.conf>:
PerlModule Apache::Hello
<Location /hello>
SetHandler modperl
PerlResponseHandler Apache::Hello
</Location>
With this, calls to
http://localhost/hello
will use C<Apache::Hello> to deliver the content.
=head1 SEE ALSO
http://perl.apache.org/, http://take23.org/,
http://httpd.apache.org/, and http://www.activestate.com/.
Help on setting up and configuring mod_perl-2 can be
found by subscribing to the mod_perl mailing list,
details of which are at http://perl.apache.org/.
=cut
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
