beehive/BUILDING.txt

178 lines
5.1 KiB
Plaintext

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