Robotics Service Bus

h1. Installation of RSB Java Implementation

For compilation and installation of the Java implementation, we use the "Ant":http://ant.apache.org/ build tool.

h2. Dependencies

h3. Dependencies on Externals Libraries and Tools

Required:
* "CMake":http://www.cmake.org/ (tested with CMake version 2.8)
* libprotobuf-java
* ant
* Daemon program of the "Spread group communication system":http://www.spread.org/

Optional:
** javadoc

h3. Dependencies on other RSB Sub-projects

The Java implementation of RSB depends on RSB's language independent network protocol specification. This specification is maintained in the "protocol sub-project of the RSB source tree":https://code.cor-lab.org/projects/rsb/repository/show/trunk/protocol.

Assuming the entire RSB source tree has been checked out into the current directory, the protocol sub-project can be built and installed using the following commands (@$prefix@ has to be replaced with a desired installation prefix):
<pre>
cd protocol/build && cmake .. -DCMAKE_INSTALL_PREFIX=$prefix && make && make install
</pre>

h2. Installation of RSB Core

*After installing the protocol sub-project* (see above)
# Checkout code from Subversion repository (see "front page":https://code.cor-lab.org/projects/rsb)
# Invoke @ant@ supplying build properties on the commandline or via @build.properties@ (see below)

The following properties are used to configure the build:
|_.Ant Property |_.Meaning |_.Example |
| @prefix@ | Location into which RSB should be installed | @/vol/cit/share@ |
| @pbuf.protoc@ | Location of protocol buffer compiler (@protoc@ or @protoc.exe@ | @/usr/bin/protoc@ |
| @pbuf.protopath@ | Location of RSB protocol IDL files (see TODO) | @/vol/cit/share/RSBProtocol@ |
| @pbuf.lib@ | Location of Java protocol buffer runtime library | @/usr/share/java/protobuf.jar@ |
| @spread.daemon@ | Location of Spread Daemon Executable | @/vol/cit/sbin/spread@ |

All properties can be supplied on the @ant@ commandline using the @-DNAME=VALUE@ syntax or by creating a @build.properties@ file containing lines of the form @NAME = VALUE@.

An exemplary @ant dist@ command, which builds the RSB jar library, may look as follows:
<pre>
ant -Dpbuf.protoc=/usr/bin/protoc -Dpbuf.protopath=/vol/cit/share/RSBProtocol -Dpbuf.lib=/usr/share/java/protobuf.jar -Dspread.daemon=/vol/cit/sbin/spread dist
</pre>
The equivalent @build.properties@ file looks like this:
<pre>
pbuf.protoc = /usr/bin/protoc
pbuf.protopath = /vol/cit/share/RSBProtocol
pbuf.lib = /usr/share/java/protobuf.jar
spread.daemon = /vol/cit/sbin/spread dist
</pre>
In the presence of this file, the @ant@ command reduces to
<pre>
ant dist
</pre>

In order to test your freshly compiled RSBJava version, you may execute the RSBJava test suite. To do so, the following @ant@ target needs to be invoked (please note that a spread daemon is automatically started by the ant script):

<pre>
ant test
</pre>

You should see a console output similar to the following (shortened excerpt):

<pre>
ubi-1-165-178:RSBJava swrede$ ant -Dpbuf.protoc=/opt/local/bin/protoc -Dpbuf.protopath=/vol/cit/share/RSBProtocol -Dpbuf.lib=/opt/local/share/java/protobuf.jar -Dspread.daemon=/vol/cit/sbin/spread test
Buildfile: /Users/swrede/Workspace/RSBJava/build.xml

init:
[echo] Using pbuf: /opt/local/share/java/protobuf.jar
[echo] Test report dir: /Users/swrede/Workspace/RSBJava/testreports

protocol:

compile:
[javac] /Users/swrede/Workspace/RSBJava/build.xml:105: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
[javac] Compiling 1 source file to /Users/swrede/Workspace/RSBJava/build/classes
[javac] /Users/swrede/Workspace/RSBJava/build.xml:110: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
[javac] Compiling 1 source file to /Users/swrede/Workspace/RSBJava/build/examples

test-compile:
[javac] Compiling 25 source files to /Users/swrede/Workspace/RSBJava/build/test

test:
[junit] Running rsb.DefaultErrorHandlerTest
[junit] Testsuite: rsb.DefaultErrorHandlerTest
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0,083 sec
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0,083 sec
[junit] ------------- Standard Error -----------------
[junit] 05.09.2011 11:12:38 rsb.DefaultErrorHandler warning
[junit] SCHWERWIEGEND: A warning was reported to the ErrorHandler: java.lang.RuntimeException: test
[junit] 05.09.2011 11:12:38 rsb.DefaultErrorHandler error
[junit] SCHWERWIEGEND: An error was reported to the ErrorHandler: java.lang.RuntimeException: test
[junit] ------------- ---------------- ---------------
[junit]
[junit] Testcase: testError took 0,009 sec
[junit] Running rsb.EventIdTest
[junit] Testsuite: rsb.EventIdTest
[junit] Tests run: 2, Failures: 0, Errors: 0, Time elapsed: 0,141 sec
[junit] Tests run: 2, Failures: 0, Errors: 0, Time elapsed: 0,141 sec
[junit]
[junit] Testcase: testEqualsObject took 0,074 sec
[junit] Testcase: testGetAsUUID took 0 sec
[junit] Running rsb.EventTest
[junit] Testsuite: rsb.EventTest
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0,126 sec
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0,126 sec
[junit]
[junit] Testcase: comparison took 0,063 sec
[junit] Running rsb.InformerTest
[junit] Testsuite: rsb.InformerTest
[junit] Tests run: 15, Failures: 0, Errors: 0, Time elapsed: 3,324 sec
[junit] Tests run: 15, Failures: 0, Errors: 0, Time elapsed: 3,324 sec
[junit] ------------- Standard Output ---------------
[junit] No rsb.conf found in configuration directory '/Users/swrede/.config'
[junit] Found rsb.conf in working directory '/Users/swrede/Workspace/RSBJava'
[junit] ------------- ---------------- ---------------
[junit] ------------- Standard Error -----------------
[junit] 05.09.2011 11:12:43 rsb.transport.spread.SpreadPort push
[junit] WARNUNG: No converter with key java.lang.String registered in ConverterMap
[junit] 05.09.2011 11:12:43 rsb.transport.spread.SpreadPort push
[junit] WARNUNG: No converter with key java.lang.String registered in ConverterMap
[junit] 05.09.2011 11:12:43 rsb.transport.spread.SpreadPort push
[junit] WARNUNG: No converter with key java.lang.String registered in ConverterMap
[junit] 05.09.2011 11:12:44 rsb.transport.spread.SpreadPort push
[junit] WARNUNG: No converter with key java.lang.String registered in ConverterMap
[junit] ------------- ---------------- ---------------

<output of more tests omitted>

[junit] Running rsb.util.UUIDToolsTest
[junit] Testsuite: rsb.util.UUIDToolsTest
[junit] Tests run: 2, Failures: 0, Errors: 0, Time elapsed: 0,164 sec
[junit] Tests run: 2, Failures: 0, Errors: 0, Time elapsed: 0,164 sec
[junit]
[junit] Testcase: testGetNameBasedUUID took 0,069 sec
[junit] Testcase: testByteArrayConversion took 0,001 sec

BUILD SUCCESSFUL
Total time: 48 seconds
</pre>

If no failed test cases are reported, RSBJava works correctly on your machine.

To install RSB jars into the configured prefix (e.g., into @${prefix}/share/java@), the following @ant@ command can be used
<pre>
ant install
</pre>

h2. Installation of RSB-XML

* for rsb-xml, you need to additionally install XOM (available via ubuntu)
* and pass the following parameters to the ant build script

|_.Ant Property |_.Meaning |_.Example |
| @pbuf.lib@ | Location of Protobuf Library | @/usr/share/java/protobuf.jar@ |
| @spread.daemon@ | Location of Spread Daemon Executable | @/vol/cit/sbin/spread@ |
| @xom.lib@ | Location of XOM XML Library | @/usr/share/java/xom-1.2.1.jar@ |
| @rsb.lib@ | Location of RSB Core Library | @/vol/cit/lib/java/RSBJava.jar@ |