=head1 NAME

mod_perl 1.0 Win32 Installation Instructions

=head1 Description

This document discusses how to install mod_perl 1.0 under Win32, both
in building from sources and in installing pre-compiled binary
packages. 

=head1 Synopsis

Unless you are using an all-in-one package, you should
first install Perl and Apache, either from the sources or as binaries.
The Perl sources are available from L<http://www.cpan.org/src/>,
with directions for building contained in F<README.win32>.
ActiveState also makes the sources available for their binary
builds at L<ftp://ftp.activestate.com/ActivePerl/src/>,
which may contain, in particular, Win32-specific fixes not in the
CPAN Perl sources. As a binary, at present, an ActivePerl-compatible 
Perl, compiled with Visual C++, is the most common one used in the Win32 
mod_perl/Apache environment; you can obtain such a prebuilt Perl
binary from L<http://www.activestate.com/>.

mod_perl 1 builds and tests successfully with either 
an ActivePerl Perl in the 6xx series, based on perl-5.6.1,
or with an ActivePerl Perl in the 8xx series, based on perl-5.8.0
(for the latter, this requires mod_perl-1.29 or later).
If you are using perl-5.8,
you may want to consider mod_perl 2.0, which although still
in a development phase offers several significant performance
improvements for Win32 - see
L<modperl-2 in Win32|docs::2.0::os::win32::install>
for details.

The Apache sources and binaries are available at
L<http://httpd.apache.org/>.

When installing Perl or other related binaries, subtleties may arise
in using path names that have spaces in them - you may, for example, 
have to specify F<C:\Program Files\> by the DOS 8.3 path name 
F<C:\Progra~1\> in certain Apache directives. If you want to avoid
this, install, if possible, these packages to locations without spaces
in their names (eg, F<C:\Perl> for Perl and F<C:\Apache> for Apache). 

In the following, it may be necessary to invoke certain commands 
through a DOS prompt. A DOS window may be opened either through
a I<Command Prompt> option of the I<Start> menu, or by choosing
to run, from the Start menu, C<command> or C<cmd>, as appropriate. 

=head1 Building from sources

You will need

=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 ActivePerl builds 8xx,
you will need mod_perl-1.29 or later.
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

First obtain the 
L<mod_perl 1.0 sources|download::source/Stable_Source_Distribution>
as a C<tar.gz> file -
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.
If you're building Apache yourself from sources, make sure to
obtain the I<win32-src.zip> archive, which has the necessary
VC++ makefiles.

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

  C:\modperl_src> perl Makefile.PL
  C:\modperl_src> 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]"

As well, if you are using a mod_ssl enabled Apache, you
should add I<EAPI> to the list of preprocessor definitions under

 "Project -> Settings -> [C/C++]"

=item Testing

Once mod_perl.so is built you may test mod_perl with:

   C:\modperl_src> nmake test

after which, assuming the tests are OK,

   C:\modperl_src> 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 Makefile.PL arguments

Generating the Makefile as, for example,

  C:\modperl_src> 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, 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 (in
mod_perl-1.29 or later, INSTALL_DLL, if not supplied, 
will assume a default of F<APACHE_SRC/modules>, if this directory
exists).

=item INSTALL_LIB

This option, which is available only in mod_perl-1.29
or later, gives the location of where to install
mod_perl.lib (eg, F<\Apache\libexec>). This library is needed for
building certain 3rd party Apache modules. If this is not supplied, 
a default of F<APACHE_SRC/libexec> will be assumed, 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

   C:\modperl_src> nmake
   C:\modperl_src> nmake test
   C:\modperl_src> 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.

If this build fails, you may want to try the sources obtained
from svn - see the discussion on the
L<Development Source Distribution|download::source/Development_Source_Distribution>
for details. Be aware, though,
that as well as providing bug fixes, there may be new features being
added and tested in the svn versions, so at any given time there are
no guarantees that these packages will build and test successfully.

=head1 Binaries

There are 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.

=head2 All-in-one packages

There are a number of binary packages for Win32 that contain the
necessary Perl and Apache binaries:

=over

=item *

IndigoPerl from
L<http://www.indigostar.com/>, 

=item *

XAMPP for Windows from
L<http://www.apachefriends.org/en/xampp-windows.html>

=item *

DeveloperSide.NET for Windows at
L<http://www.devside.net/web/server/free/software>

=item *

zangweb from
L<http://www.arbingersys.com/hostsites/zangweb/>

=back

As well, there is a package
F<perl-win32-bin.exe> from
L<http://www.apache.org/dyn/closer.cgi/perl/win32-bin/> - see the file
F<perl-win32-bin.readme> for a description. If you have trouble
fetching the whole file at once, the directory
L<http://www.apache.org/dyn/closer.cgi/perl/win32-bin/perl-win32-bin/>
contains this distribution split across multiple files -
see F<README.join> for instructions on how to join them.
Alternatively, if you have Perl already, you can get the script
F<distinstall> which, when invoked as
C<perl distinstall>, will fetch and join
the files for you.

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, 
or for those who want to avoid the 
L<multithreading limitations of mod_perl
1.0|docs::1.0::os::win32::multithread>, a 
mod_perl-2.0/Apache-2.0 binary distribution 
is available - see the discussion of
L<modperl-2 on Win32|docs::2.0::os::win32::install>
for details. Be aware though that mod_perl 2.0 is
still in a development phase, and that a minimum Perl version
of 5.8 (ActivePerl 8xx) is required.

=head2 PPM Packages

For ActivePerl users (or compatible), 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 L<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 their ppm
repository, so you must get it from a different location other than
ActiveState's site. A quick way to do this is to download
the script F<mpinstall> and save it as, for example, I<mpinstall>.
Invoking this as C<perl mpinstall> on a command line
will take you through a dialogue, based on your configuration, 
which will determine and install, via C<ppm>, the desired 
mod_perl ppm package.

The direct way to install mod_perl via ppm is simply as (broken over
two lines for readability)

  C:\> ppm install
       http://theoryx5.uwinnipeg.ca/ppmpackages/mod_perl.ppd

for Activeperl 6xx builds, and as

  C:\> ppm install
       http://theoryx5.uwinnipeg.ca/ppms/mod_perl-1.ppd

for 8xx builds. Another way, which will be useful if you plan 
on installing additional Apache modules, is to add the repository 
where the mod_perl package is kept to the C<ppm> shell utility. 
For C<ppm2> this may be done with the C<set repository alias location> 
command, while for C<ppm3> (the default with ActivePerl 8xx) the 
appropriate command is C<repository add alias location>; see the 
help utility within the C<ppm> shell for details. For 6xx builds, 
the appropriate location is

  http://theoryx5.uwinnipeg.ca/cgi-bin/ppmserver?urn:/PPMServer

while for for 8xx builds it is

  http://theoryx5.uwinnipeg.ca/cgi-bin/ppmserver?urn:/PPMServer58

After this, you can, within the ppm shell, use the C<install>
command to either install C<mod_perl>, for 6xx, or
C<mod_perl-1>, for 8xx. For C<ppm2>, use the C<set save> command to save 
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.
If you are running mod_ssl under Apache, then you should
obtain the C<mod_perl-eapi> package for 6xx or the 
C<mod_perl-eapi-1> package for 8xx instead.

Note that, because of binary incompatibilities, one should
I<not> install packages for ActivePerl 8xx from a repository
containing packages for ActivePerl 6xx, and vice-versa, particularly
if these packages contain XS-based 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 Apache modules directory (eg,
I<C:\Apache\modules>). If this fails, you can grab
the appropriate dll and install it manually. For 6xx builds,
this is at L<http://theoryx5.uwinnipeg.ca/ppmpackages/x86/>,
for which the relevant file is either C<mod_perl.so> or,
for EAPI support, C<mod_perl-eapi.so>. For 8xx builds,
the location is L<http://theoryx5.uwinnipeg.ca/ppms/x86/>,
for which the relevant file is either C<mod_perl-1.so> or,
for EAPI support, C<mod_perl-eapi-1.so>. You should then
copy this file to your Apache modules directory and rename
it as C<mod_perl.so>, if necessary.

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. If you encounter problems in loading
F<mod_perl.so>, ensure that the mod_perl version you are using matches
that of Apache, make certain C<Perl> is in your C<PATH> environment
variable, or try adding the Apache directive

  LoadFile "C:/Path/to/your/Perl/bin/perlxx.dll"

before loading F<mod_perl.so>. If all else fails, a reboot may help.

If the I<theoryx5.uwinnipeg.ca> repository is down, you can
access these packages at 
L<http://www.apache.org/dyn/closer.cgi/perl/win32-bin/ppms/>,
for builds 8xx, and
L<http://www.apache.org/dyn/closer.cgi/perl/win32-bin/ppmpackages/>,
for builds 6xx.

=head1 See Also

The directions for L<configuring mod_perl 1.0 on
Win32|docs::1.0::os::win32::config>, the L<mod_perl
documentation|docs::index>, and the
L<FAQs for mod_perl on Win32|docs::general::os::win32::faq>.
Help is also available through the archives of and subscribing to
the L<mod_perl mailing list|maillist::modperl>.

=head1 Maintainers

Maintainer is the person(s) you should contact with updates,
corrections and patches.

=over

=item * 

Randy Kobes E<lt>randy@theoryx5.uwinnipeg.caE<gt>

=back


=head1 Authors

=over

=item *

Randy Kobes E<lt>randy@theoryx5.uwinnipeg.caE<gt>

=back

Only the major authors are listed above. For contributors see the
Changes file.


=cut