randyk 02/05/29 22:51:43
Added: src/docs/1.0/os/win32 .cvsignore Changes.pod binaries.pod
compile.pod config.cfg multithread.pod
Log:
moving 1.0 win32 docs under os/win32/
Revision Changes Path
1.1 modperl-docs/src/docs/1.0/os/win32/.cvsignore
Index: .cvsignore
===================================================================
cache.*.dat
1.1 modperl-docs/src/docs/1.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 Wed Apr 3 16:08:49 SGT 2002
* normalize the case, change the titles slightly (we won't need underscored
titles for the documentation, normal ones are much more readable), and
corrected some minors things (reference to nmake, and changed some spacing
in examples to make it one long code section as is advised in style.pod).
[Per Einar Ellefsen E<lt>[EMAIL PROTECTED]<gt>]
=head1 Fri Dec 21 12:20:02 SGT 2001
* win32::multithread, win32::binaries and win32::compile initial docs
submitted by Randy Kobes E<lt>[EMAIL PROTECTED]<gt>
=cut
1.1 modperl-docs/src/docs/1.0/os/win32/binaries.pod
Index: binaries.pod
===================================================================
=head1 NAME
Obtaining Apache mod_perl binaries for Win32
=head1 Description
This document discusses the two major types of binary packages
available for Win32 mod_perl - all-in-one Perl/Apache/mod_perl
binaries, and mod_perl ppm (Perl Package Manager) packages.
=head1 All-in-one packages
There are at least two binary packages for Win32 that contain the
necessary Perl and Apache binaries:
http://www.indigostar.com/
ftp://theoryx5.uwinnipeg.ca/pub/other/perl-win32-bin.exe
As well as including a number of non-core modules, both of these
packages contain mod_perl. See the documentation on the web sites and
that included with the packages for installation instructions. Both of
these also include an ActiveState-compatible C<ppm> (Perl Package
Manager) utility for adding and upgrading modules.
For the adventuresome who want a taste of things to come, a
mod_perl-2.0/Apache-2.0 binary distribution based on cvs
sources is available - see the discussion of
L<modperl-2 on Win32|docs::2.0::os::win32::modperl2>
for details. Be aware though that, being a pre-release version,
bugs are most likely present.
=head1 PPM Packages
For users of ActivePerl, available from
http://www.activestate.com/
there are also C<PPM> mod_perl packages available. For this, if you
don't already have it, get and install the latest Win32 Apache binary
from
http://httpd.apache.org/
Both ActivePerl and Apache binaries are available as C<MSI> files for
use by the Microsoft Installer - as discussed on the ActiveState site,
users of Windows 95 and 98 may need to obtain this. In installing
these packages, 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:\Perl> and F<C:\Apache>).
After installing Perl and Apache, you can then install mod_perl via
the PPM utility. ActiveState does not maintain mod_perl in the 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.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 (the C<set repository ...> command has been broken over two
lines for readability):
C:\> ppm
PPM> set repository theoryx5
http://theoryx5.uwinnipeg.ca/cgi-bin/ppmserver?urn:/PPMServer
PPM> install mod_perl
PPM> set save
PPM> quit
C:\>
The C<set save> command saves the C<theoryx5> repository to your PPM
configuration file, so that future PPM sessions will search this
repository, as well as ActiveState's, for requested packages.
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 Apache modules directory (eg,
I<C:\Apache\modules>).
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.
=head1 Configuration
Add this line to F<C:\Apache\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. If you have a C<ClearModuleList>
directive enabled in F<httpd.conf>, you may also need to add
AddModule mod_perl.c
See the descriptions of the C<ClearModuleList> and C<AddModule>
directives in the Apache documents for more details, especially
concerning the relative order of these and the C<LoadModule> directive.
=head2 Registry scripts
Using C<Apache::Registry> to speed up cgi scripts may be done as
follows. Create a directory, for example, F<C:\Apache\mod_perl>, which
will hold your scripts. Insert then in F<C:\Apache\conf\httpd.conf>
the following directives:
Alias /mod_perl/ "/Apache/mod_perl/"
<Location /mod_perl>
SetHandler perl-script
PerlHandler Apache::Registry
Options +ExecCGI
PerlSendHeader On
</Location>
whereby the script would be called as
http://localhost/mod_perl/name_of_script
=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::Constants qw(OK);
sub handler {
my $r = shift;
$r->send_http_header;
$r->print("<html><body>Hello World!</body></html>\n");
return OK;
}
1;
and save it in, for example, the F<C:\Perl\site\lib\Apache\>
directory. Next put the following directives in
F<C:\Apache\conf\httpd.conf>:
PerlModule Apache::Hello
<Location /hello>
SetHandler perl-script
PerlHandler Apache::Hello
</Location>
With this, calls to
http://localhost/hello
will use C<Apache::Hello> to deliver the content.
=head1 Apache modules
The C<theorxy5> repository containing the mod_perl ppm package also
contains a number of other Apache modules, such as C<Apache::ASP>,
C<HTML::Embperl>, and C<HTML::Mason>. However, there may be ones you
find that are not available through a repository; in such cases, you
might try sending a message to the maintainer of the repository asking
if a particular package could be included.
Alternatively, you can use the C<CPAN.pm> module to fetch, build, and
install the module - see C<perldoc CPAN> for details. You will need
the B<nmake> utility for this, download it from
http://download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/Nmake15.exe
(it's a self extracting archive, so run it and then copy the files
into your F<Windows> directory).
=head1 See Also
The L<mod_perl documentation|docs::index>, http://httpd.apache.org/,
and http://www.activestate.com/.
=head1 Maintainers
Maintainer is the person(s) you should contact with updates,
corrections and patches.
=over
=item *
Randy Kobes E<lt>[EMAIL PROTECTED]<gt>
=back
=head1 Authors
=over
=item *
Randy Kobes E<lt>[EMAIL PROTECTED]<gt>
=back
Only the major authors are listed above. For contributors see the
Changes file.
=cut
1.1 modperl-docs/src/docs/1.0/os/win32/compile.pod
Index: compile.pod
===================================================================
=head1 NAME
Apache mod_perl-1.xx compilation instructions for Win32
=head1 Description
This document discusses how to build, test, configure and
install mod_perl under Win32.
If you are only interested in running mod_perl, it might be a better idea
to L<get and install one of the binary
packages|win32::binaries>.
=head1 Prerequisites
=over
=item *
patience - mod_perl is considered alpha under Win32.
=item *
MSVC++ 5.0+, Apache version 1.3-dev or higher and Perl 5.004_02 or higher.
=item *
As of version 1.24_01, mod_perl will build on Win32 ActivePerls
based on Perl-5.6.x (builds 6xx). For binary compatibility you
should use the same compiler in building mod_perl that was used
to compile your Perl binary; for ActivePerl, this means using VC++ 6.
=back
=head1 Building
Obtain the mod_perl sources from CPAN:
http://www.cpan.org/authors/id/D/DO/DOUGM/mod_perl-1.xx.tar.gz
When unpacked, using Winzip or similar tools, a subdirectory
F<mod_perl-1.xx> will be created.
There are two ways to build mod_perl - with MS Developer Studio,
and through command-line arguments to 'perl Makefile.PL'. In both
cases Apache should previously have been built and installed - if
you are using a binary build of Apache, make sure that you obtain
a binary build that includes the Apache libraries and header files.
=head2 Building with MS Developer Studio
=over 3
=item Setup the Perl side
Run, from a DOS window in the top-level directory of the
mod_perl sources,
perl Makefile.PL
nmake
This will set up the Perl side of mod_perl for the library build.
=item Build mod_perl.so
Using MS developer studio,
select "File -> Open Workspace ...",
select "Files of type [Projects (*.dsp)]"
open mod_perl-x.xx/src/modules/win32/mod_perl.dsp
=item Settings
select "Tools -> Options -> [Directories]"
select "Show directories for: [Include files]", and add
C:\Apache\include
. (should expand to C:\...\mod_perl-x.xx\src\modules\perl)
C:\Perl\lib\Core
select "Project -> Add to Project -> Files", adding:
perl.lib (or perl56.lib) (e.g. C:\perl\lib\Core\perl.lib)
ApacheCore.lib (e.g. C:\Apache\ApacheCore.lib)
select "Build -> Set Active Configuration -> [mod_perl - Win32 Release]"
select "Build -> Build mod_perl.so"
You may see some harmless warnings, which can be reduced (along with
the size of the DLL), by setting:
"Project -> Settings -> [C/C++] -> Category: [Code Generation] ->
Use runtime library: [Multithreaded DLL]
=item Testing
Once mod_perl.so is built you may test mod_perl with:
nmake test
after which, assuming the tests are OK,
nmake install
will install the Perl side of mod_perl. The mod_perl.so file
built under F<mod_perl-1.xx/src/modules/win32/Release> should
be copied to your Apache modules directory (eg, F<C:\Apache\modules>).
=back
=head2 Building with arguments to C<perl Makefile.PL>
Generating the Makefile as, for example,
perl Makefile.PL APACHE_SRC=\Apache INSTALL_DLL=\Apache\modules
will build mod_perl (including mod_perl.so) entirely from
the command line. The arguments accepted include
=over 3
=item APACHE_SRC
This can be one of two values: either the path to the Apache build
directory (eg, F<..\apache_1.3.xx>), or to the installed Apache location
(eg, F<\Apache>). This is used to set the locations of ApacheCore.lib
and the Apache header files.
=item INSTALL_DLL
This gives the location of where to install mod_perl.so
(eg, F<\Apache\modules>). No default is assumed - if this argument
is not given, mod_perl.so must be copied manually.
=item DEBUG
If true (DEBUG=1), a Debug version will be built (this assumes
that a Debug Apache has been built). If false, or not given,
a Release version will be built.
=item EAPI
If true (EAPI=1), EAPI (Extended API) will be defined when
compiling. This is useful when building mod_perl against mod_ssl
patched Apache sources. If false, or not given, EAPI will
not be defined.
=back
After this, running
nmake
nmake test
nmake install
will complete the installation.
This latter method of building mod_perl will also install the
Apache and mod_perl header files, which can then be accessed
through the Apache::src module.
=head1 Configuration
Add this line to F<C:\Apache\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. If you have a C<ClearModuleList>
directive enabled in F<httpd.conf>, you may also need to add
AddModule mod_perl.c
See the descriptions of the C<ClearModuleList> and C<AddModule>
directives in the Apache documents for more details, especially
concerning the relative order of these and the C<LoadModule> directive.
=head1 See Also
The L<mod_perl documentation|docs::index>, and http://take23.org/.
=head1 Maintainers
Maintainer is the person(s) you should contact with updates,
corrections and patches.
=over
=item *
Randy Kobes E<lt>[EMAIL PROTECTED]<gt>
=back
=head1 Authors
=over
=item *
Randy Kobes E<lt>[EMAIL PROTECTED]<gt>
=back
Only the major authors are listed above. For contributors see the
Changes file.
=cut
1.1 modperl-docs/src/docs/1.0/os/win32/config.cfg
Index: config.cfg
===================================================================
use vars qw(@c);
@c = (
id => 'win32',
title => "Win32 Platforms",
abstract => <<EOB,
Documents assisting mod_perl-1 users on the Win32 platforms
EOB
chapters => [qw(
binaries.pod
compile.pod
multithread.pod
Changes.pod
)],
);
1.1 modperl-docs/src/docs/1.0/os/win32/multithread.pod
Index: multithread.pod
===================================================================
=head1 NAME
Discussion of multithreading on Win32 mod_perl-1.xx
=head1 Description
This document discusses the multithreading limitations of
mod_perl-1.xx on Win32.
=head1 The problem
On Win32, mod_perl is effectively single threaded. What this
means is that a single instance of the interpreter is created,
and this is then protected by a server-wide lock that prevents
more than one thread from using the interpreter at any one time.
The fact that this will prevent parallel processing of requests,
including static requests, can have serious implications for
production servers that often must handle concurrent or
long-running requests.
This situation changes with Apache/mod_perl 2.0, which is based on a
multi-process/multi-thread approach using a native Win32 threads
implementation See the L<mod_perl 2
overview|docs::2.0::user::overview::overview> for more details,
and the discussion of L<modperl-2 in Win32|docs::2.0::os::win32::modperl2>
on getting modperl-2 for Win32 in particular.
=head1 Does it really matter?
How serious is this? For some people and application classes it may be a
non-problem, assuming the static material issue is handled differently.
Low traffic and single user development sites will likely be
unaffected (though the lattest are likely to experience some surprises
when moving to an environment where requests are no longer serialized
and concurrency kicks in).
If your application is CPU bound, and all requests take roughly the
same time to complete, then having more processing threads than
processors (CPUs) will actually slow things down, because of the
context switching overhead. Note that, even in this case, the current
state of mod_perl will bar owners of multiprocessor Win32 machines
from gaining any load balancing advantage from their superior hardware.
On the other hand, applications dealing with a large service times
spread - say ranging from fractions of a second to a minute and above
- stand to lose a great deal of responsiveness from being single
threaded. The reason is that short requests that happen to be queueued
after long ones will be delayed for the entire duration of the "jobs"
that precede them in the queue; with multitasking they would get a chance
to complete much earlier.
=head1 Workarounds
If you need multithreading on Win32, either because your application
has long running requests, or because you can afford multiprocessor
hardware, and assuming you cannot switch operating systems, you may
want to consider a few workarounds and/or alternatives - which do not
require waiting for 2.0.
You may be able to make Win32 multithreading a non-issue by tuning or
rearranging your application and your architecture (useful tips on
both counts can be found elsewhere in this document). You may be able
to significantly reduce your worst-case timing problems or you may
find that you can move the webserver to a more mod_perl friendly
operating system by using a multi-tier scheme.
If your application needs the full power of the Apache modules (often
the case for people running outside Apache::Registry) you may want to
consider a multi-server load balancing setup which uses mod_rewrite
(or a similar URL partitioning scheme) to spread requests to several web
servers, listening on different ports.
The mod_proxy dual server setup, discussed in the "Strategy" section,
is also a possibility, although people who have tried it have reported
problems with Win32 mod_proxy.
If you code to Apache::Registry (writing CGI compliant code) and can
characterize the time demanded by a request from its URL, you can use
a rewrite-based load balancing with a single server, by sending short
requests to mod_perl while routing longer ones to the pure CGI
environment - on the basis that startup, compilation and init times
will matter less in this case.
If none of the above works for you, then you will have to turn to some
non mod_perl alternatives: this, however, implies giving up on most of
the flexibility of the Apache modules.
For CGI compliant scripts, two possible (portable) alternatives which
are supported in an Apache/perl environment are straight CGI and
FastCGI. In theory a CGI application that runs under mod_perl should
have very few or no problems to run under straight CGI (though its
performance may be unacceptable). A FastCGI port should also be
relatively painless. However, as always, your mileage may vary.
If you do not mind replacing Apache with IIS/PWS, you may want
to experiment with ActiveState's value added PerlEx extension, which
speeds up CGI scripts much in a way similar to what FastCGI
does. PerlEx is transparently supported by CGI.pm, so users of this
package should be more or less covered. (A IIS-FastCGI accelerator is,
regrettably, no longer available.)
=head1 See Also
http://perl.apache.org and http://httpd.apache.org, especially the
discussion of Apache-2 and modperl-2.
=head1 Maintainers
Maintainer is the person(s) you should contact with updates,
corrections and patches.
=over
=item *
Randy Kobes E<lt>[EMAIL PROTECTED]<gt>
=back
=head1 Authors
=over
=item *
Randy Kobes E<lt>[EMAIL PROTECTED]<gt>
=back
Only the major authors are listed above. For contributors see the
Changes file.
=cut
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
