=head1 NAME

INSTALL.win32 - Apache mod_perl installation instructions for Win32

=head1 DESCRIPTION

How to build, test, configure and install mod_perl under Win32

=head1 PREREQUISITES

=over 3

patience - mod_perl is considered alpha under NT and Windows9x.

MSVC++ 5.0+, Apache version 1.3-dev or higher and Perl 5.004_02 or higher.

As of version 1.24_01, mod_perl will build on Win32 ActivePerls
based on Perl-5.6.1 (builds 6xx). Versions 1.28_01 will build on
ActivePerls 8xx, based on Perl-5.8.0.

=back

=head1 BINARIES

See http://perl.apache.org/distributions.html for Win32 binaries,
including ActivePerl ppms of mod_perl and some Apache::* packages.

=head1 CHANGES

Beginning with version 1.3.15, Apache has changed the convention 
for naming Win32 modules in order to follow that for Unix systems. 
Consequently, the name of the mod_perl module built here has
been changed from ApacheModulePerl.dll to mod_perl.so. This
is just a change in convention; if you are building mod_perl
against pre-1.3.15 Apache sources, and wish to follow the old
convention, simply copy mod_perl.so to your Apache modules directory 
as ApacheModulePerl.dll.

=head1 BUILDING

There are two ways to build mod_perl - with MS Developer Studio,
and through command-line arguments to 'perl Makefile.PL'.

=head2 Building with MS Developer Studio

=over 3

=item Setup the Perl side

Run 

  perl Makefile.PL
  nmake install

This will install the Perl side of mod_perl and setup files 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]"

You'll need to add the following paths:
 
 C:\apache_x.xx\src\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 and apache.exe is installed you may
test mod_perl with:

 nmake test

=item Apache setup

You do not need to rebuild apache, just copy mod_perl.so to
$SERVER_ROOT/modules 

=back

=head2 Building with arguments to 'perl Makefile.PL'

Generating the Makefile as, for example,

 perl Makefile.PL APACHE_SRC=\Apache

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, ..\apache_1.3.xx), or to the installed Apache location
(eg, \Apache). This is used to set the locations of ApacheCore.lib
and the Apache header files. Also, mod_perl.so will be installed
to APACHE_SRC\modules, if such a directory exists and if an
INSTALL_DLL argument isn't used.

=item INSTALL_DLL

This gives the location of where to install mod_perl.so
(eg, \Apache\modules). If not given, a value of APACHE_SRC\modules
will be used, if this directory exists.

=item INSTALL_LIB

This gives the location of where to install mod_perl.lib
(eg, \Apache\libexec). If not given, a value of APACHE_SRC\libexec
will be used, if this directory exists.

=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 httpd.conf:

 LoadModule perl_module modules/mod_perl.so

Be sure that 'C:\perl\bin' is in your path so apache can find perl.dll.
You may also want to use the directive

 LoadFile "C:/Perl/bin/perl56.dll"

(before loading mod_perl.so) to load your perl dll.

See the cgi_to_mod_perl.pod and mod_perl.pod documents for general
configuration.

=head1 NOTES

mod_perl-win32 is considered alpha, at the time of this writing,
and Apache 1.xx is not as well developed for Win32 as the
Unix counterpart. 

CGI::Switch does not work with apache_1.3a1 because basic_http_header() 
is not exported by the ApacheCore.dll. For now, just change:

 use CGI::Switch ();
 my $q = CGI::Switch->new;

 - to -

 use CGI ();
 my $q = CGI->new;

There are basic multi-threading limitations of mod_perl 1 on
Win32. See the Win32 documentation at http://perl.apache.org/
for a discussion, and also for details of the use of mod_perl 2
(with Apache 2) which overcomes this limitation.