=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.