$Id: BUILDING.txt 266902 2001-07-20 19:19:48Z craigmcc $


               Building The Java Servlet and JSP API Classes
               =============================================

This subproject contains the source code for the implementation classes of the
Java Servlet and JSP APIs (packages javax.servlet, javax.servlet.http,
javax.servlet.jsp, and javax.servlet.jsp.tagext).  In order to build these
sources successfully, you must do the following:


(1) Download and Install the Ant Binary Distribution

NOTE:  These instructions assume that you are using the Ant 1.3 release.
Procedures for Ant 1.4 and later versions should be similar, but have not
been tested.

* Download a binary distribution of Ant 1.3 from:

    http://jakarta.apache.org/builds/jakarta-ant/release/v1.3/bin/

  On a Windows platform, you will need:
    jakarta-ant-1.3-bin.zip
    jakarta-ant-1.3-optional.jar

  On a Unix platform, you will need:
    jakarta-ant-1.3-bin.tar.gz
    jakarta-ant-1.3-optional.jar

* Unpack the binary distribution into a convenient location so that the
  Ant release resides in its own directory (conventionally named
  "jakarta-ant-1.3").  For the purposes of the remainder of this document,
  the symbolic name "${ant.home}" is used to refer to the full pathname of
  the release directory.

* Copy the file "jakarta-ant-1.3-optional.jar", downloaded above, into
  the directory "${ant.home}/lib".  This makes available several Ant
  extension commands that are commonly required when building Jakarta
  based projects.

* Modify the PATH environment variable to include directory
  "${ant.home}/bin" in its list.  This makes the "ant" command line script
  available, which will be used to actually perform the build.


(2) Download and Install the JAXP/1.1 Reference Implementation (OPTIONAL)

NOTE:  Although this step is not required to build this particular subproject,
it is commonly required to build other Jakarta projects.  Hence, the steps
required are documented here.

* Download a binary distribution of JAXP 1.1 (Final Version) from:

    http://java.sun.com/xml/download.html

* Unpack the binary distribution into a convenient location so that the
  JAXP/1.1 release resides in its own directory (conventionally named
  "jaxp-1.1".  For the purposes of the remainder of this document, the
  symbolic name "${jaxp.home}" is used to refer to the full pathname of
  the release directory.

* Make the JAR files of this distribution ("crimson.jar", "jaxp.jar", and
  "xalan.jar") available for use by performing ONE of the following options:

  - Remove the existing "jaxp.jar" and "parser.jar" files found in the
    "${ant.home}/lib" directory, and copy these JAR files into the
    "${ant.home}/lib" directory (prefered option).

  - Add these files to your CLASSPATH environment variable.


(3) Download and Install Subproject Source Code

* Use Anonymous CVS (as described on the Jakarta web site at
  <http://jakarta.apache.org/site/cvsindex.html>, or
  download a source distribution from:

    http://jakarta.apache.org/builds/jakarta-servletapi-4/nightly/src/

  On a Windows platform, you will need:
    jakarta-servletapi-4-src-YYYYMMDD.zip

  On a Unix platform, you will need:
    jakarta-servletapi-4-src-YYYYMMDD.zip

  (Alternatively, you can download the Servlet API source distribution
  from the same directory as you find a released version of Tomcat 4.
  Such distributions will contain exactly the Servlet API classes used
  to build the "servlet.jar" file inside that Tomcat distribution.)

* Unpack the source distribution into a convenient location so that the
  distribution resides in its own directory (conventionally named
  "jakarta-servletapi-4").  For the purposes of the remainder of this document,
  the symbolic name "${servletapi.source}" is used to refer to the full
  pathname of the release directory.


(4) Customize Build Properties For This Subproject

Most Jakarta subprojects allow you to customize Ant properties (with default
values defined in the "build.xml" file.  This is done by creating a text file
named "build.properties" in the source distribution directory (for property
definitions local to this subproject) and/or your user home directory (for
property definitions shared across subprojects).

The "jakarta-servletapi-4" subproject does not define any customizable
build properties.


(5) Build A Binary Distribution

Open a command line shell, and issue the following commands:

  cd ${servletapi.source}
  ant -projecthelp

If everything is installed correctly, you should see a list of the Ant
"targets" that represent different commands you might wish to build.  By
convention, the "dist" target creates a complete binary distribution.  To
execute it, type the following commands:

  cd ${servletapi.source}
  ant dist

This will create a complete binary distribution of the subproject (equivalent
in structure to the corresponding binary distribution downloadable from the
Jakarta web site), in the "${servletapi.source}/dist" directory.  It will have
the contents described in the corresponding "README.txt" file.

The file most commonly required by other projects will be the "servlet.jar"
file, found in "${servletapi.source}/lib/servlet.jar".  Make a note of the
full pathname to this file, because you will need it when customizing build
properties for other Jakarta subprojects that depend on these classes.