JdbcMapper/BUILDING.txt

Welcome to Beehive
==================

To build Beehive, you will first need to check the source out from
Apache SVN and then install / configure required external software and
your shell environment.

Checkout Beehive from SVN
=========================

To do this, run the command:

  svn checkout https://svn.apache.org/repos/asf/beehive/trunk

After running this command, you should have a directory "trunk/" which
contains the current Beehive source.  If you ran this command in:

  d:\java\beehive

you should have the directory:

  d:\java\beehive\trunk

In the following steps, we'll refer to this as ${beehive.home}.

Install / configure external software and setup your shell
==========================================================

1) Java 5

  Download: http://java.sun.com/j2se/1.5.0/download.jsp

  Install Java 5 and set the JAVA_HOME environment variable to
refernce the JDK install directory.  Ensure that $JAVA_HOME/bin is
available in your $PATH. 

2) Ant 1.6.2+

  Download: http://ant.apache.org/bindownload.cgi 

  Ant 1.6.2 is the minimum version required to build Beehive.  Install
Ant 1.6.2 and set the ANT_HOME environment variable to reference the
Ant install directory.  Ensure that $ANT_HOME/bin is available in your
$PATH. Copy junit.jar (in external/junit/) to $ANT_HOME/lib.  This step is
required in order for the Ant <junit> tasks to work correctly.

3) Tomcat 5.0.x

  Download:  http://jakarta.apache.org/site/binindex.cgi#tomcat 

  Tomcat is used as the default test environment for Beehive.  Install
Tomcat and set the CATALINA_HOME environment variable to reference the
Tomcat install directory.  If you're installing Tomcat on Linux,
be sure to set the execute bit on the shell scripts in $CATALINA_HOME/bin.

  If you installed these into d:\java, your environment variables
might look something like:

  JAVA_HOME=d:\java\jdk1.5.0
  CATALINA_HOME=d:\java\jakarta-tomcat-5.0.25
  ANT_HOME=d:\java\apache-ant-1.6.2

Configure installed products

In order to run the Beehive tests, ensure that Tomcat has the the 
"manager" role is defined in ${CATALINA_HOME}/conf/tomcat-users.xml 
with a "manager" role and manager username/password of manager/manager.  
This step is required in order to use the Tomcat Ant tasks to deploy 
applications to Tomcat. An example of this file is available here:

  ${beehive.home}/test/conf/tomcat-users.xml

In the following examples, '$>' is your propmpt at $BEEHIVE_HOME, so if 
you see '$>ant', type 'ant' (without the quotes) and press [enter].

In addition to the external software installed above, Beehive requires
one additional JAR to provide JSR 173 support for StAX, which is
required by XMLBeans.  This JAR is downloaded from the network when
running Beehive's "bootstrap" target, so be sure to have a network
connection for your first build.  A network connection is not required
for any subsequent builds.  To install the JSR 173 API, run:

    $>ant bootstrap

To check your Beehive build setup, run:

    $>ant check.setup

This should end with "BUILD SUCCESSFUL" if you see any failures, be
sure to re-check your setup steps above.

To build Beehive, run:

    $>ant clean deploy

To run the Beehive tests, run:

    $>ant drt

Using Proxies With a Beehive Build
====================================

If you need to use proxies you can setup additional environment variables
so that the Ant "bootstrap" target is successful in downloading the 
JSR 173 API JAR file.  

PROXYHOST=<name of proxy host>
PROXYPORT=<port used for proxying>
PROXYUSER=<username for proxy authentication>
PROXYPASSWORD=<password for proxy authentication>
NONPROXYHOSTS=<hosts that should not be proxied>
SOCKSPROXYHOST=<socks proxy host name>
SOCKSPROXYPORT=<socks proxy port>

At a minimum, you will need to set PROXYHOST and PROXYPORT if your
network environment requires a proxy connection.  To set these
environment variables in your shell, run:

    set PROXYHOST=<name of proxy host>

in a Windows shell and 

    export PROXYHOST=<name of proxy host>

in a UNIX shell.

For information on proxy support using the <setproxy> task, please
visit http://ant.apache.org/manual/OptionalTasks/setproxy.html

Building Beehive documentation
=============================
The following documentation-related targets in
beehive/trunk/build.xml require that you have 
Apache Forrest installed locally: 

    $>ant docs
    $>ant build.dist  

Before running these targets, complete the following steps.

1) Download and install Forrest 0.7 on your machine.
A list of available download locations is available at:

   http://forrest.apache.org/mirrors.cgi
     

2) Copy the JAR file 

    apache-forrest-0.7/lib/core/xml-commons-resolver-1.1.jar

into 

    $ANT_HOME/lib

(This allows the Ant targets to call Forrest tasks.)

3) Ensure that FORREST_HOME is set to the following path.

    On Windows machines:
    set FORREST_HOME=C:\MyApacheStuff\apache-forrest-0.7

    On Unix machines:
    export FORREST_HOME=/MyApacheStuff/apache-forrest-0.7

4) Set the PATH as follows:

    On Windows machines: 
    set PATH=%FORREST_HOME%\bin;%PATH%

    On Unix machines:
    export PATH=$FORREST_HOME/bin:$PATH

You are now ready to run these targets: 

    $>ant docs
    $>ant build.dist