=====================================================================
JRun Apache connector build for ColdFusion MX and JRun4 
=====================================================================

The connector source works with ColdFusion MX Updater 3 or higher,
ColdFusion MX 6.1 or higher, (and JRun4 SP1 or higher if JRun4 user).  
Connectors compiled from this version will not work with prior versions of 
either of these products.

=============================================================================
Building from source is required for Apache 1.3.x in the following conditions
=============================================================================

1) The Apache 1.3.x version is a mod_ssl or derivative or Apache StrongHold.
2) EAPI warning messages appear on startup similar to this:
[warn] Loaded DSO /opt/coldfusionmx/runtime/lib/wsconfig/1/mod_jrun.so uses 
plain Apache 1.3 API, this module might crash under EAPI! 
(please recompile it with -DEAPI). 

There are no changes in the build steps regardless of Apache configuration.

The apxs utility can intelligently detect what type of Apache installation 
and what switches are needed (-DEAPI) to build the connector correctly 
without user intervention.

=============================================================================
Instructions for building an Apache connector from source files
=============================================================================

=====================
Terms and Definitions
=====================
Environment variables:

	CFMX_CONNECTOR = the ColdFusion web server connector directory (ColdFusion MX users) 
	    e.g.  /opt/coldfusionmx/runtime/lib/wsconfig/1 
	    or  /opt/coldfusionmx/runtime/lib/wsconfig/2 if a second web server is configured

	JRUN_CONNECTOR = the JRun4 Sp1 web server connector directory (JRun4 users). 
	    e.g.  /opt/jrun4/runtime/lib/wsconfig/1 
	    or  /opt/jrun4/runtime/lib/wsconfig/2 if a second web server is configured
		
	APACHE_BIN = the Apache binaries directory. 
	    e.g. /usr/sbin or /opt/apache/bin


NOTE:  It is assumed that an Apache connector is already configured on the system 
which will be replaced by the newly built connector.

==============
Detailed steps
==============

(Replace CFMX_CONNECTOR location with JRUN_CONNECTOR location where appropriate below for
JRun4 users)

1.)  Stop Apache (it is not necessary to stop ColdFusion MX or JRun)

2.)  Place the ApacheModule.zip file in the CFMX_CONNECTOR directory and 
use the unzip utility to extract the source files here.

	unzip -a ApacheModule.zip
	chmod 777 *

3.)  Rename or delete the existing mod_jrun.so (Apache 1.3.x) or mod_jrun20.so (Apache 2.0.x) file.

4.)  Use the Apache apxs utility to build the JRun connector from the source files:

  Apache 1.3.x - 

	${APACHE_BIN}/apxs  -c  -Wc,-w -DJRUN_SSL   mod_jrun.c  \
		jrun_maptable_impl.c  jrun_property.c  jrun_session.c \
		platform.c  jrun_mutex.c  jrun_proxy.c  jrun_ssl.c
		
	strip   mod_jrun.so

  Apache 2.0.x -

	${APACHE_BIN}/apxs  -c  -Wc,-w -n jrun20 -S LIBEXECDIR=${CFMX_CONNECTOR}  mod_jrun20.c  \
		jrun_maptable_impl.c  jrun_property.c  jrun_session.c platform.c \
		jrun_mutex.c  jrun_proxy.c  jrun_ssl.c

	${APACHE_BIN}/apxs -i -n jrun20 -S LIBEXECDIR=${CFMX_CONNECTOR} mod_jrun20.la

	strip   mod_jrun20.so

5.)  Restart Apache and check the Apache logs/error_log file.

6.)  Delete the source files from the CFMX_CONNECTOR/JRUN_CONNECTOR directory when you have finished building the connector.

	rm  *.h  *.c  *.o  *.lo  *.slo  *.la *.rc *.rc2


This procedure will need to be repeated after each ColdFusion MX/JRun4 Updater is installed since 
ColdFusion MX/JRun4 updaters automatically install updated connectors from the wsconfig.jar file for all
installed web server connectors overwriting the user-compiled mod_jrun.so or mod_jrun20.so.  

The wsconfig.jar binaries are standard modules.  
Apache EAPI versions are not built automatically in wsconfig.jar.

==================================
Explanation of switches & options
=================================

unzip options:

	-a	convert source (text) files line endings as appropriate for platform

apxs options:

	-c 		compile an Apache module

	-i		install an Apache module

	-Wc,-w		compiler switch to supress warnings

	-DJRUN_SSL	define the JRUN_SSL symbol 
		(note that this refers to SSL between the connector 
		  and JRun, not to Web Server SSL on port 443)

	-n jrun20	module name is jrun20

	-S LIBEXECDIR=${CFMX_CONNECTOR} create mod_jrun20.so in the current directory


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Versions tested
===============	
OK - Linux Redhat 7.2 Apache 2.0.43 
OK - Linux Redhat 7.2 Apache 1.3.27 
OK - Linux Redhat 7.2 Apache 1.3.27 with mod_ssl ( EAPI build )
OK - Linux Redhat 9.0 Apache 2.0.40
OK - Solaris 8 Apache 1.3.27  
OK - Solaris 8 Apache 2.0.44

    Note: be sure to set the PATH environment variable as required by your C compiler

FAILED -  Solaris 8 Apache 2.0.43 - did not build (mod_jrun20.la incorrect values - apxs error?).  
A working mod_jrun20.so can still be built by using the following command in place of the 'apxs -i' command:

	ld -G -o mod_jrun20.so   mod_jrun20.o \
		jrun_maptable_impl.o jrun_property.o \
		jrun_session.o jrun_mutex.o jrun_proxy.o \
		platform.o jrun_ssl.o