=pod

=head1 NAME

Apache2::ASP::Manual::Installation::Windows - Installation instructions for Windows

=head1 DESCRIPTION

This document describes how to install Apache2::ASP on Windows.

=head1 WARNING

Performance on Windows is just terrible.  Do not use Apache2::ASP on Windows in a production
environment.

However, if you would like to simply develop or prototype or test things out on Windows, 
that would be fine.

=head1 PREREQUISITES

=head2 Step 1: Install Apache HTTPD v2.0 or newer

The MSI distribution available from http://httpd.apache.org/ is recommended.

B<IMPORTANT:> - Use the installation directory C<C:\Apache2> instead of the default
path C<C:\Program Files\Apache Group\blah\blah\blah>.

=head2 Step 2: Install mod_perl2

Assuming you have ActiveState ActivePerl 5.8x installed, you can install mod_perl2 by 
doing the following from a command prompt:

  > ppm repo add http://theoryx5.uwinnipeg.ca/ppms/
  > ppm install mod_perl-2.0

Answer all the questions (where to install, etc, etc) and you're done.

If you've got some extra time on your hands and would like to install from source, go for it.

=head2 Step 3: Install libapreq2

  > ppm install libapreq2-2.0

Answer all the questions and you're all set.

If you'd rather install from source, go for it.  Nothing is stopping you.

=head2 Step 3: Install missing Perl modules

You will need to install the following modules.  Fortunately they should install just fine
with CPAN.

  CGI
  CGI::Apache2::Wrapper - (you might need to force install this one)
  CGI::Simple
  Cwd
  DateTime::Duration
  DBD::SQLite
  DBI
  Digest::MD5
  HTML::FillInForm
  HTML::Form
  HTTP::Date
  HTTP::Request::AsCGI
  Ima::DBI - (version 0.35 or greater)
  YAML
  Data::Properties::YAML
  Mail::Sendmail
  MIME::Types
  Storable
  Sys::Hostname
  XML::Simple

If you plan on using MySQL to store your Application and Session data, you should also install
L<DBD::mysql> unless you've already got it.

B<IMPORTANT:> - If you are having a hard time installing modules with CPAN (because you don't 
have C<nmake.exe> or whatever) then just C<ppm install> the modules.  The only module that absolutely
B<must> be a specific version is L<Ima::DBI> version 0.35+ because of some important changes made
in that version.  But in a pinch, give 0.34 (or lower) a shot if that's all you can get installed.

=head1 INSTALLATION

Once you've installed the prerequisites (see above) you are all set to install Apache2::ASP.

Unfortunately the regular CPAN install won't work.  This might be addressed in the future, but
we'll cross that bridge when we get there.

Simply download the latest tar.gz file from CPAN and extract the tar.gz archive using your
favorite Gzip/Tar compatible unpacking program.  WinRAR is highly recommended.

  > cd Apache2-ASP-1.xx
  > perl Makefile.PL

At this point you will get some strange pop-up complaining about C<libapreq2.dll> and how it cannot be found.

  > make
  > make install

Now, when you run the command:

  % perl -MApache2::ASP -e 'print "Hello, World!\n"'

You should see:

  Hello, World!

If instead you see something like:

  Can't locate Apache2/ASP.pm in @INC (@INC contains: C:/Perl/lib C:/Perl/site/lib .).
  BEGIN failed--compilation aborted.

Then Apache2::ASP was not successfully installed.  Double-check your steps and make sure you didn't miss something.

Installing Apache2::ASP is only part of the deal.  You also need to configure a website to run on it.

=head1 DIRECTORY STRUCTURE

Assuming your server root is C<C:\Apache2\Apache2\Website> and your C<DocumentRoot> is C<C:\Apache2\Apache2\Website\html> then your directory
structure would look like this:

  C:\Apache2\Apache2\Website
  |
  +-\html
  | `- index.asp (All ASP scripts go here, along with images, css, javascript, etc.)
  |
  +-\handlers
  | +- MyHandler.pm    (Accessible as http://yoursite.com/handlers/MyHandler)
  | `- OtherHandler.pm (Accessible as http://yoursite.com/handlers/OtherHandler)
  |
  +-\conf
  | +- httpd.conf  (to be included by /etc/httpd/conf/httpd.conf)
  | `- apache2-asp-config.xml
  |
  +-\lib
  | `- Your application classes go here (i.e. Class::DBI or DBIx::Class modules)
  |
  +-\MEDIA
  | `- (Apache must have read/write permissions for this directory)
  |
  +-\PAGE_CACHE
  | `- (Apache must have read/write permissions for this directory)
  |
  +-\t
    `- (your test files will go here)

=head2 \conf

The C</conf> directory should contain only configuration files.

Specifically, it should contain the L<Apache2::ASP::Manual::ConfigXML|XML Config File> 
and the L<Apache2::ASP::Manual::HttpdConf|httpd.conf> file.

=head2 \handlers

Your Handlers go here.  All of them.

Learn more about what Handlers are by reading the following pages:

=over 4

=item Start with L<Apache2::ASP::Manual::Handlers>

=item L<Apache2::ASP::Handler>

=item L<Apache2::ASP::UploadHandler>

=item L<Apache2::ASP::FormHandler>

=item L<Apache2::ASP::MediaManager>

=back

=head2 \html

All of your ASP scripts, images, CSS, JavaScript, SWF, PDF and other files go here, 
just like a regular website.

In addition to your ASP scripts you can also place your C<GlobalASA.pm> file in this 
directory.

Learn more about the C<GlobalASA.pm> file by reading L<Apache2::ASP::GlobalASA> and
L<Apache2::ASP::Manual::GlobalASA>.

=head2 \MEDIA

This is where uploaded files are stored.

B<NOTE:> Your webserver must be able to both B<read> and B<write> to this directory.

=head2 \PAGE_CACHE

This is where compiled ASP scripts are stored.

"What are compiled ASP scripts?" you ask?  When L<Apache2::ASP::PageHandler> prepares 
your ASP script for execution the first time around, it converts it from ASP markup to 
a first-class Perl module.  Learn more by reading L<Apache2::ASP::Manual::ASP_Compilation>.

=head2 \lib

Any Perl module that is not a Handler should go here.  This includes (for example) your
L<Class::DBI> or L<DBIx::Class> modules (or what have you) as well as any other custom,
non-CPAN modules that your web application requires.

This directory is automatically added to C<@INC> by L<Apache2::ASP::Config> so you don't 
have to do it yourself.

=head1 BUGS

It's possible that some bugs have found their way into this release.

Use RT L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Apache2-ASP> to submit bug reports.

=head1 HOMEPAGE

Please visit the Apache2::ASP homepage at L<http://www.devstack.com/> to see examples
of Apache2::ASP in action.

=head1 AUTHOR

John Drago L<mailto:jdrago_999@yahoo.com>

=head1 COPYRIGHT AND LICENSE

Copyright 2007 John Drago, All rights reserved.

This software is free software.  It may be used and distributed under the
same terms as Perl itself.

=cut