svn commit: r424043 - /httpd/mod_aspdotnet/trunk/README.txt

[wr...@apache.org]

Author: wrowe
Date: Thu Jul 20 13:17:26 2006
New Revision: 424043

URL: http://svn.apache.org/viewvc?rev=424043&view=rev
Log:

  Colm's question triggered a review of README.txt which became
  slightly out of date when the installer was migrated to a more
  recent msi.
 

Modified:
    httpd/mod_aspdotnet/trunk/README.txt

Modified: httpd/mod_aspdotnet/trunk/README.txt
URL: http://svn.apache.org/viewvc/httpd/mod_aspdotnet/trunk/README.txt?rev=424043&r1=424042&r2=424043&view=diff
==============================================================================
--- httpd/mod_aspdotnet/trunk/README.txt (original)
+++ httpd/mod_aspdotnet/trunk/README.txt Thu Jul 20 13:17:26 2006
@@ -12,19 +12,27 @@
 for Apache 2.0 with the syntax;
 
   set APACHE_PATH=d:\path\to\apache2
-  devenv mod_aspdotnet.sln /useenv /build Release /project installer
+  devenv mod_aspdotnet.sln /useenv /build Release /project mod_aspdotnet
 
 or to build for Apache 2.1-dev or Apache 2.2, invoke with the syntax;
 
   set APACHE22_PATH=d:\path\to\apache2.2
-  devenv mod_aspdotnet.sln /useenv /build "Release 2.2" /project installer
+  devenv mod_aspdotnet.sln /useenv /build "Release 2.2" /project mod_aspdotnet
 
 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.
+the top-level Release/ directory of this module.  
+
+The true "Debug" and "Debug 2.2" flavors work similarly, and eliminate 
+optimizations that make debugging difficult.  However, the installer is
+not designed to package the debug flavor into an .msi package.  See the
+"Deployment Notes" section later in this README for an explanation of
+how to manually install either flavor, locally, without an .msi package.
 
 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.
+.NET (al la 2002, or 7.0) version.  Older VS 6.0 compilers won't support 
+the module, and newer VS compilers are not entirely compatible with the
+original C++.NET syntax.
 
 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
@@ -32,11 +40,21 @@
 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.
+dll's.  This is important since Apache.Web.dll normally can't be loaded,
+even for the .NET framework tools to inspect the .dll, unless it is literally 
+adjacent (in the same directory) to Apache's .dll's.  And Apache.Web.dll must
+be in the Global Assembly Cache to participate in the system.web framework.
+So, using this alternate delay-load method, Apache.Web.dll can be loaded 
+(provided we don't instantiate an Apache.Web.WorkerRequest object), even when
+it cannot resolve the path to Apache's dll's in the Serverroot/bin directory.
+
+Before using InstallShield to actually package a release build, the syntax;
+
+  devenv mod_aspdotnet.sln /useenv /build Release /project resolve_apache
+  devenv mod_aspdotnet.sln /useenv /build "Release 2.2" /project resolve_apache
+
+will build the helper .dll to allow the installer to search the local machine
+for installations of Apache.exe (Release flavor) or httpd.exe (Release 2.2).
 
 
 Alternate Build Notes
@@ -56,17 +74,24 @@
 System.Web.Hosting framework), while the Apache .dll files remain in the
 Apache bin directory.
 
+This should be solved in a future release by migrating to VisualStudio 2005
+which offers a much more complete "Lite" flavor that users may obtain for
+free from Microsoft.
+
 
 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.
+YOU should test that the module runs under both the full .NET Framework SDK, 
+as well as within the .NET Framework Runtime environment only.  A number 
+of internal behaviors vary between these two environments, and Exceptions,
+destruction, construction and failure cases will manifest differently between
+the two environments.
 
 ASP.NET requires the Apache::Web::Request object to be registered in 
 the Global Assembly Cache in order to instantiate it's host container.
+So it is not possible to install Apache.Web.dll in the 'usual' modules
+subdirectory of Apache HTTP Server.
 
 The Debug build will do so automatically, copying mod_aspdotnet.so + .pdb
 into the $(APACHE_PATH)\modules directory, for testing.
@@ -95,6 +120,8 @@
 ----
 
 Consider pre-compiling the package into native code prior to distribution.
+(Apparently, InstallShield always does this for GAC-registered modules, so
+this consideration might be moot.)
 
 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
@@ -104,9 +131,12 @@
 
 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.
+a much more efficient method.  (This is no longer needed with .NET 1.1 as 
+it more thoroughly registers itself even in the absense of IIS on the target
+machine.)
 
 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.
-
+necessary, or allow explicitly long paths, if the user chooses.  The path can
+be manually specified in the installer, though, so the issue is not fatal,
+and the 3 level depth avoids waiting a half hour when invoking the installer.