
   +-------------------------------------------------------------------+
   | A P A C H E   J S E R V   I N S T A L L A T I O N   O N   U N I X |
   +-------------------------------------------------------------------+


  Introduction
  ============

  This file guides you through the installation process for UNIX systems.

  NOTE: Win32 users are highly recommended to use the self-installing 
  distribution (the "exe" distribution) or read the proper instructions 
  in the docs/install/ directory.


  Installing the Apache JServ servlet engine
  ==========================================

  1. Requirements
     ------------

     The following requirements exist for building Apache JServ:

     o  Disk Space: 
     
        The complete Apache JServ installation requires less than 2Mb of 
        hard disk space. The compiled, not-compressed jar archive is more or
        less 100Kb.

     o  Apache HTTP Server:
    
        Apache JServ 1.0 works only with the Apache HTTP Server (both
        versions 1.2 and 1.3 are supported).
        
     o  Java Runtime Environment:
  
        A fully compliant Java 1.1 Runtime Environment is required for Apache 
        JServ to execute. 
  
        The official list of compatible ports is found on the Sun Java 
        web site:

        <http://java.sun.com/cgi-bin/java-ports.cgi>
  
        The list of supported platforms and Java ports may be found in the 
        documentation (docs/support.html).
  
        NOTE: since Apache JServ uses _only_ standard Java APIs (java.*),       
        please, do not submit a bug report if your Java virtual machine fails 
        to execute Apache JServ because of broken compliance. Send it to your
        Java virtual machine implementors.
  
     o  Java Servlet Development Kit 2.0:
  
        The Sun Java JSDK 2.0 is required by Apache JServ for proper servlet 
        execution.  This package is freely available from the Sun Java web 
        site: 

        <http://java.sun.com/products/servlet/index.html>
        
        NOTE: this version of Apache JServ requires _exactly_ the 2.0
        version of the JSDK in order to operate properly. Any other version
        (past, present or future and including the version that comes 
        with the Java Server Pages (JSP) jar file) is not supported.
        
     o  Java Compiler:
  
        Since most distributions include the precompiled Java binary archive,
        compilation of the Java source is optional.
        
        A list of supported Java compilers may be found in the documentation 
        (docs/support.html)
        
        NOTE: a Java compiler is needed to build servlets if you plan to write 
        your own.

     o  ANSI-C Compiler: 

        Make sure you have an ANSI-C compiler installed and relative Make 
        tools. The GNU C compiler (GCC version 2.7.2 is fine) and GNU Make 
        (make preferably version 3.75) from the Free Software Foundation (FSF) 
        is recommended. If you don't have GCC then at least make sure your
        vendors compiler is ANSI compliant. You can find the homepage of GNU
        at <http://www.gnu.org/> and the GCC distribution under
        <http://www.gnu.org/order/ftp.html>.
        
     o  Dynamic Shared Object (DSO) support [OPTIONAL]:

        See your Apache documentation for more information on how to add
        DSO support and if your system is supported.


  2. Choose how to add the Apache JServ module to Apache
     ---------------------------------------------------

  There are two choices:
    
     o  Compile it in -  This requires that you have a source distribution 
        of the Apache server handy as it adds our source to that tree and 
        lets Apache build the Apache JServ module into itself statically.    
 
     o  DSO - This requires that you have an installation of Apache 1.3.*
        that was configured to have DSO support when it was built.  If you're 
        not sure whether yours does follow the instructions on configuring 
        Apache JServ for DSO and the configure script will tell you.


  3. Configure Apache
     ----------------

  If you are using a source distribution then you have to configure apache
  first (some generated header files are needed for Apache JServ to pass its
  configure checks).  You do not need to worry about specifying the 
  Apache JServ module.

  If you are using DSO then you can ignore this step.  If you have a source
  distribution and would like to build it with DSO support and install it
  for use by Apache JServ then use the following options when configuring
  Apache:

     --enable-rule=SHARED_CORE --enable-module=so
     

  4. Configure Apache JServ
     ----------------------

  Now you are ready to configure Apache JServ.  To do this you may (or may not)
  need to specify quite a few arguments to configure.  These are:

  o  Apache Dir

     For DSO use:

       --with-apache-install=/path/to/apache/installation

     NOTE: The configure script will check the default installation dir
     so if you have it there you may leave this argument out.	

     For a static compile use:

       --with-apache-src=/path/to/apache/source

     NOTE: For those using a source distribution Apache JServ will configure 
     apache for you (taking care to preserve your previous configuration) 
     if you use this option:

       --enable-apache-conf	

  o  JDK programs (java, javac, javadoc and jar)

     By default configure will first look at the JDK_HOME and JAVA_HOME 
     environment variables, if they aren't set then configure will check 
     your PATH environment variable. The results from using the PATH can 
     be overriden by:

       --with-jdk-home=/path/to/jdk

     If they are not found, configure will tell you and default back to 
     whatever is in your PATH.

     NOTE: By default, debugging symbols are left out of the JServ 
     classes, you can put them back in by using this option:

       --enable-debugging

     NOTE: By default the jar file is not compressed, this can be 
     changed like so:
 
       --enable-compressed-jar

  o  JSDK classes

     Apache JServ needs to know where your servlet classes are.
     If they are not in your CLASSPATH then you need to specify them like so:

       --with-jsdk=/path/to/jsdk.jar
          or
       --with-jsdk=/path/to/unpacked/jsdk


  5. Build
     -----

  Once you have configured Apache JServ you can run make. If you are
  using a source distribution then you also have to run make in the
  Apache source directory.

  See the HTML docs for info on setting up and running servlets.
  

  6. Manual Installation
     -------------------

  If you want to install Apache JServ manually, you'll need to compile
  the Java classes by hand.  Make sure you have the JSDK classes in your
  classpath, and compile src/java/org/apache/java/*/*.java and
  src/java/org/apache/jserv/*.java.  Make a jar file from these, or copy
  them into your classpath, or list this directory in your classpath.

  Next, you'll need to setup Apache.  First, create a subdirectory in
  $apache_dir/src/modules called 'jserv'.  Then copy Makefile.tmpl, and
  *.[ch] from src/c to $apache_dir/src/modules/jserv.  Then either edit
  Configuration, adding 'AddModule modules/jserv/mod_jserv.o' (if you use
  'Configure'), or run 'configure' with (in addition to whatever options
  are appropriate for you) '--activate-module=src/modules/jserv/mod_jserv.c'.
  Then build Apache as you normally do.

  This will create mod_jserv.o and link it in (statically); docs for creating
  mod_jserv.so (a DSO) will be added later.  For the mean time, you can use
  Apache JServ's 'configure' to create this.

  Last, you'll need to create a jserv.properties file;
  example/jserv.properties provides a sample.  You'll also need to add certain
  directives to your Apache configuration files (or include another file via
  'Include'); example/jserv.conf provides a sample for this.
   
  7. Problems
     --------

  First read the Frequently Asked Questions and documentation to see if 
  your issues have already been covered. If think that you have found a 
  bug, please report it to the Apache Bug Database at: 

  <http://bugs.apache.org/>

  Note that manual mode operation is not supported in this beta release;
  it will be in a future release.

  If you just have a question, please join the Apache JServ Users mailing 
  list and ask there. Please do not mail project group members directly 
  because this is a 100% volunteer project and most of us have day jobs. :)

  Enjoy!

  -The Apache JServ Project
