Portico v0.8 and JSAF 2007

Like much of JSAF, the process of configuring it to use Portico involves a number of little tricks. As Portico is drop-in compliant with any piece of software that links to the DMSO RTI-NGv6 interface, there isn't anything fundamental that a user needs to do. However, there are a few little tweaks necessary to massage things into place.

Requirements
All the information in this guide was obtained from using JSAF 2007 on Fedora Core 6. While more recent versions of Fedora may be used (and may be more friendly) I make no guarantees as to whether or not they will work.

You will also need a reasonably up-to-date version of Java to get things working (the version shipped with FC6 is neither real java, nor recent enough). We recommend getting the JDK 1.5.0_11 (or _13) from the Java website.

Finally, you will need to have a number of environment variables set to build/run JSAF with Portico:


 *  : Should point to the location of Portico
 *  : Should point to the place you installed Java
 *  : This needs to include an entry that points to the  library located in your JDK install (typically on the path  ). This is necessary for linking and running applications that use the Portico libraries.

Portico with a new JSAF Install
Thus far I have only been successful in getting JSAF and Portico to play together by building JSAF from scratch (via source). Attempting to get a previously built version of JSAF to "switch" to Portico has been unsuccessful and necessitated a complete recompile. This section outlines the complete install process I used to get JSAF up and running. If you already have JSAF installed and working happily with rti-s, you will probably need to recompile the whole thing. If anyone has more success, please let me know how you did it.

With all this in mind, I give you the steps I used to install JSAF with Portico (synthesized from an install process given to me by Jon Shuttleworth).

Setting up the System
1. Lubricate yourself generously

2. Insall FC 6 ensuring following packages installed:


 * Desktop Environments - Gnome
 * Development - Development Libs
 * Development - Development Tools
 * Development - Gnome Software Development
 * Development - Java Development
 * Development - X Software Development
 * Base System - Java
 * Base System - X Windows System

3. Install the Required RPMs

Create a location where you want to install JSAF into. Under this directory, create another into which you can extract all the RPMs to be installed:

[tim@localhost ~]$ mkdir ~/jsaf [tim@localhost ~]$ mkdir ~/jsaf/rpms [tim@localhost ~]$ cd ~/jsaf/rpms

Under this directory, extract the contents of the  tarball from the install DVD. After this, install the relevant RPMs:

[tim@localhost rpms]$ tar -zxvf /media/DVD/JSAF2007/sources/JSAF_requiredRPMs_32Bit.tgz [tim@localhost rpms]$ sudo rpm -ivh ./libXp-1.0.0-8.i386.rpm [tim@localhost rpms]$ sudo rpm -ivh ./libXp-devel-1.0.0-8.i386.rpm [tim@localhost rpms]$ sudo rpm -ivh ./openmotif-2.3.0-0.1.9.3.i386.rpm [tim@localhost rpms]$ sudo rpm -ivh ./openmotif-devel-2.3.0-0.1.9.3.i386.rpm [tim@localhost rpms]$ sudo rpm -ivh ./xorg-x11-xbitmaps-1.0.1-4.1.i386.rpm

Compiling JSAF 2007
4. Extract the JSAF source code

Create a directory for the JSAF source code and extract it to there

[tim@localhost rpms]$ mkdir ~/jsaf/source [tim@localhost rpms]$ cd ~/jsaf/source

5. Create the "externals" Symbolic Link

To get JSAF to use Portico, we are going to have it masquerade as RTI-NG. Portico is compatible with RTI-NGv6, so this should work happily enough. To tell JSAF to use "RTI-NG" (*wink*), place a symbolic link in the  directory and point it at the root of your Portico install. In the example below, you should have  pointing at that location.

[tim@localhost source]$ mkdir external/ [tim@localhost source]$ cd external/ [tim@localhost external]$ echo $RTI_HOME /home/tim/portico/portico-0.8-devel [tim@localhost external]$ ln -sf $RTI_HOME/ ./rti13ng

5. Hack the Configure Script

Now that we have the external link set up, the JSAF configure script will attempt to use the RTI pointed to by it rather than rti-s. However, the script is highly dependent on the directory structure under that link, and as the Portico directory structure is not the same as RTI-NG, this causes some problems.

To solve these problems, you will need to make a couple of minor edits to the configure script.

[tim@localhost source]$ vim ./configure (because real men use vim)

First, on about like 1569, change:

rtidir="unknown"

to read:

rtidir="."

Secondly, on around line 1575, change:

if test -f $srcdir/external/rti13ng/$rtilibs/librti13.so then rti_ver="RTI-1.3NG -- DLC" rtiinclude=$rtidir/include/1_3DlcApi else

to read:

if test -f $srcdir/external/rti13ng/$rtilibs/librti13.so then rti_ver="RTI-1.3NG -- DLC" rtiinclude=$rtidir/include/ng6 **change is here else

6. Edit the TCI make files

For some reason (don't ask me, I don't know), there are some lines that cause some pain in the makefiles for TCI. You need to edit these files to remove (or comment out) those lines in order to save you some compile errors later on:

[tim@localhost source]$ vim src/TCI/GNUmakefile [tim@localhost source]$ vim src/TCI/GNUmakefile.in

Remove  from both files.

7. Build JSAF

Once you have made your edits, run the configure script and build JSAF. Be warned, this can take a LONG time. Note that you will need to include the path to the location of the  file, otherwise you will get linking errors at the end of the process.

[tim@localhost source]$ ./configure [tim@localhost source]$ LD_LIBRARY_PATH=$JAVA_HOME/jre/lib/i386/client/ make jsaf

Get JSAF Up and Running
8. Install the terrain

One of the last steps is to install the terrain files from the DVD so that the JSAF GUI will run happily.

[tim@localhost source]$ mkdir terrain [tim@localhost source]$ cd terrain [tim@localhost terrain]$ tar -zxvf /media/DVD/JSAF2007/sources/world_thin_fmtblahblah.tgz

9. Cross fingers and run JSAF

Remember to start an RTI in another window first!

[tim@localhost source]$ cd ../src/JSAF [tim@localhost source]$ LD_LIBRARY_PATH=$JAVA_HOME/jre/lib/i386/client/ ./jsaf -federation standard

Editing Portico Properties
Once you have JSAF up and running with Portico, you may want to edit various Portico properties to get the RTI or LRC using different communications bindings, or providing more logging information. You can do this by putting data in the RTI.rid file.

This file is structured in the typical Java properties file format (see Configuring Portico). Just create a file called RTI.rid and place is in the directory where JSAF is being executed from.

Known Limitations
At the moment, the central nature of the JSOP communications binding is a big performance limitation. There also appears to be a bug in the binding that causes a crash due to an "OutOfMemoryError" when more than a couple of entities have been created in the federation.

If you are happy to just play around and limit yourself to a single PVD/JSAF GUI, you can tell it to use the JVM Binding (which will automatically start an instance of the RTI *inside* JSAF). The performance benefits will be immediately obvious.

To get this working, create an RTI.rid file in the directory where you execute JSAF from and ensure it contains the line:

portico.lrc.connection=org.portico.binding.jvm.JVMClientConnection

Be warned, I have noticed that there will still be crashes after a certain number of entities have entered the simulation. These seem to be JNI related errors, the source of which is still unknown. I found this occurred after I had placed more than about 14-15 M1A1 companies in a single simulation (with each company having 14 tanks). So you still have a reasonable amount of wiggle room to play around when using the JVM binding.

Turning up the Portico Log Output
If you want to turn up the amount of log information the Portico LRC provides, add the following line to the RTI.rid file (where LEVEL is the log level you want, typically either "DEBUG" or "TRACE"):

portico.lrc.loglevel=LEVEL

Getting the JSAF PVD running in GDB
Another useful debugging step is to run the JSAF PVD under GDB. To do this, you will want to edit the make files for both libril and the jsaf PVD itself so that they compile with debug symbols:

[tim@localhost source]$ vim libsrc/libril/GNUmakefile [tim@localhost source]$ vim src/JSAF/GNUmakefile

[tim@localhost source]$ touch libsrc/libril/* [tim@localhost source]$ touch src/JSAF/*

[tim@localhost source]$ LD_LIBRARY_PATH=$JAVA_HOME/jre/lib/i386/client/ make jsaf

Add a -g to the end of the  and   lines to be sure you get what you want. After this, touch all the files in the two directories to ensure the compiler knows they need to be rebuilt, and recompile jsaf.

When running the JSAF PVD with GDB, remember to set all the necessary environment variables (RTI_HOME, JAVA_HOME, LD_LIBRARY_PATH).