README for mod_aspdotnet + Apache.Web 
-----------------------------------


Build Notes
-----------

The top level workspace mod_aspdotnet.sln is invoked for a release build
with the syntax;

  set APACHE_PATH=d:path\to\apache\serverroot
  devenv mod_aspdotnet.sln /useenv /build Release /project installer

The necessary files, mod_aspdotnet.so [+.pdb for debug symbols] and the
Apache.Web.dll [+.pdb] are built into the installer.msi package at 
the top-level Release/ directory of this module.

It is absolutely critical that this build occurs using the Visual Studio
.NET (7.0) version.  Older VS 6.0 compilers won't support the module.

Note that the Apache.Web.dll is temporarily registered, it's type library
(.tlb file) is extracted, and it is unregistered as a post-build step for
both the Debug and Release builds of the Apache.web.  This assures us that
the usual build environment remains clean of excess COM registration gunk.

We build Apache.Web.dll with delay-load of libhttpd, libapr and libaprutil 
dll's.  This is important since Apache.Web.dll can't be touched unless
it is literally adjacent (in the same directory) to those Apache 2.0 .dll's.
With this method, Apache.Web.dll can be loaded (provided we don't instantiate
an Apache.Web.WorkerRequest object) even without resolving the path to those
dll's in the Serverroot/bin directory.


Alternate Build Notes
---------------------

We have attempted to build the modules with the free Microsoft Visual C++ 
Toolkit, Microsoft's .NET Framework SDK and Windows Platform SDK.  Sadly,
this combination is not a complete replacement for the Developer Studio,
and is insufficient to build the mod_aspdotnet and Apache.Web.dll modules.

Notably, none of these packages includes the DelayImp.lib which is
required to link libhttpd, libaprutil and libapr .dll files to the
Apache.Web.dll module.  This allows the regasm and gacutil utilities,
amoung others, to load and process the Apache.Web.dll, without loading
the actual Apache .dll files.  Without this feature it's impossible to
place Apache.Web.dll in the GAC (required for loading inside Microsoft's
System.Web.Hosting framework), while the Apache .dll files remain in the
Apache bin directory.


Deployment Notes
----------------

YOU MUST test both the .NET Framework SDK, as well as the .NET Framework
Runtime environments.  A number of internal behaviors vary between these
two releases, and Exceptions, destruction, construction and failure cases
will manifest differently between the two variants.

ASP.NET requires the Apache::Web::Request object to be registered in 
the Global Assembly Cache in order to instantiate it's host container.

The Debug build will do so automatically, copying mod_aspdotnet.so + .pdb
into the $(APACHE_PATH)\modules directory, for testing.
Apache.Web.dll + .pdb files are copied into $(APACHE_PATH)\bin
so that it can discover libapr.dll, libaprutil.dll and libhttpd.dll when
running in the System.Web.Hosting's AppDomain.  Apache.Web.dll is then 
registered and installed into the Global Assembly Cache by the Debug build's
post-build custom command.

In order to install a reference into the Global Assembly Cache (for testing
the release build instead of the debug build) use;

  regasm d:\path-to-apache\bin\Apache.Web.dll 
  gacutil /ir Apache.Web.dll FILEPATH d:\path-to-apache\bin\Apache.Web.dll Apache.Web 

This will *NOT* work on an end-user's machine without the .Net SDK.  Those
tools [regasm/gacutil] aren't installed with the retail .Net-redist install.
Instead, the .msi installer package, with the details for registering the
Apache.Web assembly into the Global Assembly Cache, is used for end-users.


TODO
----

Consider pre-compiling the package into native code prior to distribution.

Consider building a roll-up assembly integrating the libhttpd et. al. with
the Apache.Web.dll package.  Perhaps we can force them to live in different
locations with this method.  Note roll up assemblies -reference- the other
.dll's [that assembly is a .dll itself] but it does not actually merge the
other .dll's into a single package.

Consider registering aspnet_isapi.dll keys in the registry.  This could
occur as part of the installer or module startup.  The installer would be
a much more efficient method.

Note that the .msi package searches for apache/bin/apache.exe up to 3 levels 
deep from the local hard drives, in sequence.  It aught to test further, as
necessary, or allow explicitly long paths.

