content/release-doc/current/build.html - river-site - Git at Google

 <!--
  ! 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.
  !-->
 <html>
 <body text="#000000" bgcolor="#ffffff" link="#9b37cc"
       vlink="#cc1877" alink="#ffffff">

 <title>Building the Apache River Packages</title>
 <a name="TOP">
 <center><h1>Building the Apache River Packages</h1></center>

 <br>
 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, <a href="http://ant.apache.org">
                <code>http://ant.apache.org</code></a>).
 <p>
 This page describes how to use <code>ant</code> to build the distribution from
 the source code. This Ant build process was originally based on Geoff Arnold's
 Ant build script, located at <a href="http://user-garnold.jini.org">
 <code>http://user-garnold.jini.org</code> (link dead)</a>, and we thank him for his
 contribution.

 <p>
 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 <a href="info-index.html#examine">info-index.html</a> .  In the
 instructions below, <B><VAR>install_dir</VAR></B> is the directory into which
 you installed the Apache River distribution.

 <p>
 <b>NOTE</b>:<i> Please do not attempt to build the Apache River JAR files
 without first taking referencing the
 <a href="http://developer.java.sun.com/developer/products/jini/tested.html">
 platforms on which the starter kit has been tested (link dead)</a></i>.

 <p>
 <hr>
 <h2>Build instructions</h2>

 <p>
 The following prerequisites must be met before a build can be executed:
 <ul>
   <li>
     The <b><code>bin</code></b> 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 <a href="http://java.sun.com">
     <code>http://java.sun.com</code></a> .
   </li>
   <p>
   <li>
     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
     <a href="http://ant.apache.org"><code>http://ant.apache.org</code></a> .
   </li>
   <p>
 </ul>

 <p>
 The following build options are currently available:
 <ul>
   <li>
     The <b><code>debug</code></b> parameter can be used to override the
     default debuglevel values.  The possible values are "<code>none</code>",
     "<code>lines</code>", "<code>source</code>", and "<code>vars</code>".
     If two or more values are used together, they must be comma-separated
     (eg, "<code>lines,source,vars</code>").  Refer to the javac documentation
     or the javac task section of the Ant documentation for further details
     regarding these debuglevel options.
     <pre>
     ant -Ddebug=lines,source,vars &lt;<i>target</i>&gt;
     </pre
   </li>
 </ul>

 <p>
 To build the starter kit JAR files, you must:

 <pre>
     cd <B><VAR>install_dir</VAR></B>

     ant &lt;<i>target</i>&gt;
 </pre>

 where the basic targets are:
 <blockquote>
   <dl>
     <dt>
     <b>all.build</b><br>
     This target is also the default target and can be invoked by simply running
     <code>ant</code> 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:
     <br><br>
       &nbsp;&nbsp; <code><B><VAR>install_dir</VAR></B>/build/classes</code>
       <br>
       &nbsp;&nbsp; <code><B><VAR>install_dir</VAR></B>/build/configentry</code>
     <br><br>
     Additionally, this target will build all subprojects (currently 'qa' and 'examples/hello').
     <p>
     <dt>
     <b>jars</b><br>
     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:
     <br><br>
       &nbsp;&nbsp; <code><B><VAR>install_dir</VAR></B>/lib</code>    <br>
       &nbsp;&nbsp; <code><B><VAR>install_dir</VAR></B>/lib-dl</code> <br>
       &nbsp;&nbsp; <code><B><VAR>install_dir</VAR></B>/lib-ext</code><br>
     <br>
     <b>NOTE</b>:
     <br>
     <i>
     During the jars build, warning messages similar to the following are generated:
     </i>
     <br><br>
     &nbsp;&nbsp;&nbsp;&nbsp;<code>[java] Nested class LogManager$Probe has different preferred state than outer class LogManager</code>
     <br><br>
     <i>
     Messages of this sort are expected and pose no concern to the resulting build.
     </i>

     <p>
     <dt>
     <b>clean</b><br>
     Removes the class files, configentry files, docs, JAR files, and all associated
     directories generated during the build.

     <p>
     <dt>
     <b>doc</b><br>
     Generates all the documentation for the starter kit.
     The documentation will be placed in the following directory:
     <br><br>
       &nbsp;&nbsp; <code><B><VAR>install_dir</VAR></B>/doc</code>

     <p>
     <dt>
     <b>javadoc-api</b><br>
     Generates API documentation for the starter kit, using the Javadoc(TM) tool.
     The documentation will be placed in the following directory:
     <br><br>
       &nbsp;&nbsp; <code><B><VAR>install_dir</VAR></B>/doc/api</code>

     <p>
     <dt>
     <b>javadoc-spec</b><br>
     Generates the specification-only documentation for the starter kit, using the Javadoc(TM) tool.
     The documentation will be placed in the following directory:
     <br><br>
       &nbsp;&nbsp; <code><B><VAR>install_dir</VAR></B>/doc/specs/api</code>

     <p>
     <dt>
     <b>release</b><br>
     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.

     <p>
     <dt>
     <b>install-policy</b> and <b>uninstall-policy</b><br>
     This target will install/uninstall jsk-policy.jar into the JVM extensions directory.

   </dl>
 </blockquote>

 <h2>Testing your Build</h2>
 <p>There are three test harnesses:
 <ul>
     <li><b>Unit Tests:</b> The build target is <b>test</b>.  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.
     </li>
     <li><b>Regression Tests:</b> The build target is <b>jtreg</b> 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 <a href="http://openjdk.java.net/jtreg/">openjdk.java.net/jtreg</a>
     and ensure jtreg is available on your execution path.
     </li>
     <li><b>Integration and Compliance Tests:</b> The build target is <b>qa.run</b> 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.
     </li>
 </ul>
 </p>


 <p>
 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 <code>river-user@incubator.apache.org</code> for consideration.

 <p>
 <hr>
 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
 <ul>
      <a href="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</a>
 </ul>
 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.

 </body>
 </html>
	<!--
	! 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.
	!-->
	<html>
	<body text="#000000" bgcolor="#ffffff" link="#9b37cc"
	vlink="#cc1877" alink="#ffffff">

	<title>Building the Apache River Packages</title>
	<a name="TOP">
	<center><h1>Building the Apache River Packages</h1></center>

	<br>
	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, <a href="http://ant.apache.org">
	<code>http://ant.apache.org</code></a>).
	<p>
	This page describes how to use <code>ant</code> to build the distribution from
	the source code. This Ant build process was originally based on Geoff Arnold's
	Ant build script, located at <a href="http://user-garnold.jini.org">
	<code>http://user-garnold.jini.org</code> (link dead)</a>, and we thank him for his
	contribution.

	<p>
	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 <a href="info-index.html#examine">info-index.html</a> . In the
	instructions below, <B><VAR>install_dir</VAR></B> is the directory into which
	you installed the Apache River distribution.

	<p>
	<b>NOTE</b>:<i> Please do not attempt to build the Apache River JAR files
	without first taking referencing the
	<a href="http://developer.java.sun.com/developer/products/jini/tested.html">
	platforms on which the starter kit has been tested (link dead)</a></i>.

	<p>
	<hr>
	<h2>Build instructions</h2>

	<p>
	The following prerequisites must be met before a build can be executed:
	<ul>
	<li>
	The <b><code>bin</code></b> 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 <a href="http://java.sun.com">
	<code>http://java.sun.com</code></a> .
	</li>
	<p>
	<li>
	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
	<a href="http://ant.apache.org"><code>http://ant.apache.org</code></a> .
	</li>
	<p>
	</ul>

	<p>
	The following build options are currently available:
	<ul>
	<li>
	The <b><code>debug</code></b> parameter can be used to override the
	default debuglevel values. The possible values are "<code>none</code>",
	"<code>lines</code>", "<code>source</code>", and "<code>vars</code>".
	If two or more values are used together, they must be comma-separated
	(eg, "<code>lines,source,vars</code>"). Refer to the javac documentation
	or the javac task section of the Ant documentation for further details
	regarding these debuglevel options.
	<pre>
	ant -Ddebug=lines,source,vars <<i>target</i>>
	</pre
	</li>
	</ul>

	<p>
	To build the starter kit JAR files, you must:

	<pre>
	cd <B><VAR>install_dir</VAR></B>

	ant <<i>target</i>>
	</pre>

	where the basic targets are:
	<blockquote>
	<dl>
	<dt>
	<b>all.build</b><br>
	This target is also the default target and can be invoked by simply running
	<code>ant</code> 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:
	<br><br>
	<code><B><VAR>install_dir</VAR></B>/build/classes</code>
	<br>
	<code><B><VAR>install_dir</VAR></B>/build/configentry</code>
	<br><br>
	Additionally, this target will build all subprojects (currently 'qa' and 'examples/hello').
	<p>
	<dt>
	<b>jars</b><br>
	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:
	<br><br>
	<code><B><VAR>install_dir</VAR></B>/lib</code> <br>
	<code><B><VAR>install_dir</VAR></B>/lib-dl</code> <br>
	<code><B><VAR>install_dir</VAR></B>/lib-ext</code><br>
	<br>
	<b>NOTE</b>:
	<br>
	<i>
	During the jars build, warning messages similar to the following are generated:
	</i>
	<br><br>
	<code>[java] Nested class LogManager$Probe has different preferred state than outer class LogManager</code>
	<br><br>
	<i>
	Messages of this sort are expected and pose no concern to the resulting build.
	</i>

	<p>
	<dt>
	<b>clean</b><br>
	Removes the class files, configentry files, docs, JAR files, and all associated
	directories generated during the build.

	<p>
	<dt>
	<b>doc</b><br>
	Generates all the documentation for the starter kit.
	The documentation will be placed in the following directory:
	<br><br>
	<code><B><VAR>install_dir</VAR></B>/doc</code>

	<p>
	<dt>
	<b>javadoc-api</b><br>
	Generates API documentation for the starter kit, using the Javadoc(TM) tool.
	The documentation will be placed in the following directory:
	<br><br>
	<code><B><VAR>install_dir</VAR></B>/doc/api</code>

	<p>
	<dt>
	<b>javadoc-spec</b><br>
	Generates the specification-only documentation for the starter kit, using the Javadoc(TM) tool.
	The documentation will be placed in the following directory:
	<br><br>
	<code><B><VAR>install_dir</VAR></B>/doc/specs/api</code>

	<p>
	<dt>
	<b>release</b><br>
	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.

	<p>
	<dt>
	<b>install-policy</b> and <b>uninstall-policy</b><br>
	This target will install/uninstall jsk-policy.jar into the JVM extensions directory.

	</dl>
	</blockquote>

	<h2>Testing your Build</h2>
	<p>There are three test harnesses:
	<ul>
	<li><b>Unit Tests:</b> The build target is <b>test</b>. 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.
	</li>
	<li><b>Regression Tests:</b> The build target is <b>jtreg</b> 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 <a href="http://openjdk.java.net/jtreg/">openjdk.java.net/jtreg</a>
	and ensure jtreg is available on your execution path.
	</li>
	<li><b>Integration and Compliance Tests:</b> The build target is <b>qa.run</b> 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.
	</li>
	</ul>
	</p>


	<p>
	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 <code>river-user@incubator.apache.org</code> for consideration.

	<p>
	<hr>
	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
	<ul>
	<a href="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</a>
	</ul>
	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.

	</body>
	</html>