Building The Phoenix Application Server
               =======================================

This subproject contains the source code Phoenix @version@, a container
that implements a Service API similar to the API under development in the JSR 111,
Services Framework.  In order to build a binary distribution version of the
container from a source distribution, you must have a Java Development Kit (JDK)
for version 1.3 (or later) downloaded and installed (version 1.3.1 recommended),
and do the following:

(0) Download and Install a Java Development Kit

* Download a Java Development Kit (JDK) release (version 1.3 or later) from:

    http://java.sun.com/j2se/

* Install the JDK according to the instructions included with the release.

* Set an environment variable JAVA_HOME to the pathname of the directory
  into which you installed the JDK release.


(1) Download and Install the Ant Binary Distribution

* Download a binary distribution of Ant 1.4.1 from:

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

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

  On a Unix platform, you will need:
    jakarta-ant-1.4.1-bin.tar.gz
    jakarta-ant-1.4.1-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.4.1").  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.4.1-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 JMX 1.0 Reference Implementation

NOTE:  This step is only required if you wish to build the Config/Admin
component of Phoenix.

* Download the JMX Instrumentation and Agent Reference Implementation
  (version 1.0 or later) from

    http://java.sun.com/products/JavaManagement/download.html

* Unpack the reference implementation into a convenient location so that
  it resides in its own subdirectory.

(3) Download and Install the Java Service Wrapper 2.2.2 Implementation

NOTE:  This step is only required if you wish to allow the Phoenix server
to be accessible as a win32 Service or a unix daemon.

* Download the Java Service Wrapper (version 2.2.2 or later) from

    http://wrapper.sourceforge.net/

* Unpack the product into a convenient location so that it resides in
  its own subdirectory.

(4) Download and Install Checkstyle, 2.1 or later (OPTIONAL)

NOTE: This is only required if you wish to generate reports regarding code style.

* Download the Checkstyle package (version 2.1 or later) from:

    http://checkstyle.sourceforge.net/

* Unpack the package into a convenient location so that it resides in its
  own subdirectory.

(5) 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 ".ant.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).  You can use the included
"ant.properties.sample" file as a starting point for this.

Phoenix has a few external dependencies that are satisfied by configuring
appropriate values in your <code>.ant.properties</code> file.  The easiest
way to satisfy these dependencies is to copy the "ant.properties.sample"
file (in the top-level Phoenix source directory) to ".ant.properties", and
then edit it to suit your environment.  On Unix, this would be done as:

  cd @dist.name@
  cp ant.properties.sample .ant.properties
  emacs .ant.properties

NOTE:  Be *sure* that you do not check "ant.properties" in to the CVS
repository.  This file is local to your own development environment, and
each developer will have their own version.

(6) Build A Binary Distribution

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

  cd @dist.name@
  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-lite" target creates a binary distribution minus
the javadocs and other documentation.  To execute it, type the following
commands:

  cd @dist.name@
  ant dist-lite

This will create a binary distribution of the project (equivalent in structure
to the corresponding binary distribution downloadable from the Jakarta web
site minus the docs/ directory), in the "@dist.name@/dist" directory.  It
will have the contents described in the corresponding "README.txt" file.

See the document RUNNING.txt for instructions on how to start up and shut down
the Service container.