# Building the Apache River Packages

The Apache River distribution includes support for generating binary (JAR) files and documentation from the provided source code using the Apache Ant build tool (available from the Ant project site at Apache.org, `http://ant.apache.org`).

This page describes how to use `ant` to build the distribution from the source code. This Ant build process was originally based on Geoff Arnold's Ant build script, located at `http://user-garnold.jini.org` (link dead), and we thank him for his contribution.

It is not necessary to build the JAR files from source code to get started with Jini technology. The JAR files are provided for you as part of the starter kit, depending on your installation options. The location of the JAR files is documented in info-index.html . In the instructions below, install_dir is the directory into which you installed the Apache River distribution.

NOTE: Please do not attempt to build the Apache River JAR files without first taking referencing the platforms on which the starter kit has been tested (link dead).

## Build instructions

The following prerequisites must be met before a build can be executed:

- The `bin` directory of the Java(TM) 2 SDK, Standard Edition, v 1.5 (or later) must be in your executable search path. You can obtain the Java software at `http://java.sun.com` .

- Apache Ant, version 1.6.2 or later, must be installed on your system. You can obtain the Ant software from Ant's project site at `http://ant.apache.org` .

The following build options are currently available:

- The `debug` parameter can be used to override the default debuglevel values. The possible values are "`none`", "`lines`", "`source`", and "`vars`". If two or more values are used together, they must be comma-separated (eg, "`lines,source,vars`"). Refer to the javac documentation or the javac task section of the Ant documentation for further details regarding these debuglevel options.

          ant -Ddebug=lines,source,vars <target>

To build the starter kit JAR files, you must:

        cd install_dir

        ant <target>

where the basic targets are:

> all.build
> This target is also the default target and can be invoked by simply running `ant` without specifying any target. This target compiles the class files for all of the distribution source code, generates Java Remote Method Invocation (Java RMI) stub classes, and generates the configentry files. The class files and configentry files will be placed in the following directories, respectively:
> `install_dir/build/classes`
> `install_dir/build/configentry`
> Additionally, this target will build all subprojects (currently 'qa' and 'examples/hello').

> jars
> Creates the JAR files for the distribution, using the compiled class files. The compiled class files must already have been created. The resulting JAR files will be placed in the following directories:
> `install_dir/lib`
> `install_dir/lib-dl`
> `install_dir/lib-ext`
> NOTE:
> During the jars build, warning messages similar to the following are generated:
> `[java] Nested class LogManager$Probe has different preferred state than outer class LogManager`
> Messages of this sort are expected and pose no concern to the resulting build.

> clean
> Removes the class files, configentry files, docs, JAR files, and all associated directories generated during the build.

> doc
> Generates all the documentation for the starter kit. The documentation will be placed in the following directory:
> `install_dir/doc`

> javadoc-api
> Generates API documentation for the starter kit, using the Javadoc(TM) tool. The documentation will be placed in the following directory:
> `install_dir/doc/api`

> javadoc-spec
> Generates the specification-only documentation for the starter kit, using the Javadoc(TM) tool. The documentation will be placed in the following directory:
> `install_dir/doc/specs/api`

> release
> This target will compile everything, generate the jar files, generate the javadoc, and produce the distribution bundles (binary and source) in the top-level "dist" directory.

> install-policy and uninstall-policy
> This target will install/uninstall jsk-policy.jar into the JVM extensions directory.

## Testing your Build

There are three test harnesses:

- Unit Tests: The build target is test. JUnit testing is provided because of the popularity of this Unit test framework, reducing the initial learning curve for developers, enabling more developers to participate.
- Regression Tests: The build target is jtreg from the build.xml file in the qa directory. Jtreg is the Regression Test framework for Jini, also utilised by Sun's JRE, you'll need to download jtreg separately from openjdk.java.net/jtreg and ensure jtreg is available on your execution path.
- Integration and Compliance Tests: The build target is qa.run from the main build.xml file. The Jini QA Test Harness, was developed by Sun, specifically to cater for testing of the Jini Architecture, more information can be found in the qa directory.

If you make any modifications and/or corrections to this build process and want those changes considered for use in our next release, please submit your modifications to `river-user@incubator.apache.org` for consideration.

Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.