Development Environment Setup

If you intend to compile the code from the repository, you will need to do some setup work. These guidelines should help you in this task.

System Requirements

The condebase is mostly free of external requirements due to the low-level API nature of the code. While we used to support Java3D heavily the lack of active development of the API has resulted in us dropping mainline support for the Java3D-specific parts of the codebase. These are still in the SVN repository, but the default compile does not include it.

For other system requirements, you need at least a J2SE v1.2 JDK. Also, for the device handler we use the JAXP API processing XML configuration files. If you do not have either of these, you can download them from here:

• J2SE v1.5
• JavaCOMM 2.0
(used by the input device implementations)

We also include unit tests with much of the code. This is done through the JUnit test suite. You can download and read more about it here on the JUnit homepage.

There are no other hard requirements of the code. Of course, doing 3D graphics we recommend the best video card your money can buy.

Environmental Basics

The code is built around a standard unix environment for setup. We use the various GNU tools to build the code - in particular there is a heavy reliance on GNU Make for the compilation.

You can of course compile the codebase by hand using javac. This is entirely possible, and we make sure to architect the codebase so that you will not get caught with needing to compile 3 different directories simultaneously. However we do recommend using the build environment because it makes life soooooo much easier.

Win32

For Microsoft OS users, you will need to download and install cygwin from Redhat. This can be found at http://sourceware.cygnus.com/cygwin/. Follow the installation instructions. The default environment should be good enough for you.

Unix

You really don't need to do much at all. Make sure that you have the GNU tools installed as we use a number of features from GNU Make. Standard make will not work.

MacOS

Uses the same setup as unix. Requires OS/X 10.4 or later as we need Java 5 APIs and generics throughout the codebase.

Environment Settings

The code relies on a single environment variable to be set called PROJECT_ROOT.This variable will point to the root of the code, that you have installed. Usually it will be placed somewhere like

   /home/justin/projects/j3d.org/code

If you are using cygwin, you will have to put the dos path to your code. For example:

  c:/cygwin/home/justin/projects/j3d.org/code

Yes, the slashes are meant to be that way around. If you put the local unix-style path to the codebase then you will get javac complaining about errors or classes not found etc.

Many people have their own, personal classpath setups too. The makefile that comes with this codebase ignores you standard CLASSPATH. To include and of that system-level information, you can define another variable called PROJECT_CLASSPATH. This is used to bring in any other general/system JARs that you might wish to include other than the those used internally. The typical usage is to write the following:

  export PROJECT_CLASSPATH=${CLASSPATH}

If you are using BASH for your shell, then I find the following little setup handy in my .bashrc. This allows me to swap between various different projects on the fly:

J3D_HOME=${HOME}/j3d.org
J3D_DOS_HOME="c:/cygwin/home/justin/j3d.org"
J3D_SVNROOT=":pserver:anonymous@lists.j3d.org:/home/svn/j3d/svnroot"
J3D_CODE_PROJECT_ROOT="${J3D_DOS_HOME}/code"
J3D_BASE_CLASSPATH="${TEST_CLASSPATH}"
J3D_CODE_CLASSPATH="${J3D_CODE_PROJECT_ROOT}/classes"
J3D_CODE_CLASSPATH="${J3D_CODE_CLASSPATH};${J3D_CODE_PROJECT_ROOT}/config"
J3D_CODE_CLASSPATH="${J3D_CODE_CLASSPATH};${J3D_CODE_PROJECT_ROOT}/images"
J3D_LIB_PATH=
J3D_PATH=$PATH

cd()
{
  case $# in
    0)  builtin cd $HOME
        ;;
    1)  builtin cd $1
        echo `pwd`
        ;;
    2)  dir=$1/$2
        if [ ! -x $dir ] ; then
          echo $2 does not exist
          builtin cd $1
        else
          builtin cd $dir
          echo `pwd`
        fi
  esac
}

j3d()
{
  export PROJECT_HOME=${J3D_HOME}
  export AREA=j3d
  export PS1="[$AREA \W] \$ "
  export SVNROOT=$J3D_SVNROOT
  export LD_LIBRARY_PATH=$J3D_LIB_PATH
  export PATH=$J3D_PATH
  export PROJECT_ROOT=${J3D_code_PROJECT_ROOT}
  export CLASSPATH="${J3D_BASE_CLASSPATH};${J3D_code_CLASSPATH}"

  cd $PROJECT_HOME $1
}

Using the Build Environment

With the environment variable set up, all you need to do is

  bash$ cd $PROJECT_ROOT
  bash$ make

This will generate class files, a jar file and the javadoc for the classes. Various options with make are:

• class - Generates just the class files
• jar - Compiles the code and creates a JAR file
• javadoc - Creates javadoc for you
• clean - Cleans up everything!

The code directory structure has 7 subdirectories under the main code area. Five of these are there when you download the code:

• make The makefiles for building the code
• config Runtime configuration files and images
• docs Project documentation and the generated javadoc
• java Source files for the project
• examples Example code to show how to use the library

The classes and jar directory are created by the build process.

Building the class files

To build the entire codebase from scratch, change to the project root directory. Now type:

   [j3d code] $ make clean
   [j3d code] $ make class

You will now see make run off and do its thing. If everything compiles successfully, you will find all the .class files in the $PROJECT_ROOT/classes directory. You may elect to use these directly or build a JAR file for them

Building JAR files

If you wish for a binary distribution of the code, they you can create the jar file with the command

   [j3d code] $ make jar

These file will be built and placed in the $PROJECT_ROOT/jars directory (if the directory does not exist it will be created). Unfortunately the build process only currently creates a JAR for the executable content. The config files and images used in the user interface code is not included. You will need to create a separate, hand-built JAR for this. We do intend to get this working sometime in the near future.

Building Javadocs

Of course, no Java project is complete without the accompanying javadoc. This too can be generated using the make system. Before running the make process, you may want to customise the code for your system. We automatically attempt to link to any other javadoc that you have on your machine - in particular the Java 3D, JDK and XML projects. To include these, or to disable the ability, you will need to edit one of the makefiles.

Firstly change into the $PROJECT_ROOT/java directory. There you will find a file called Makefile. Open this up in your editor of choice and go to the very bottom of the file. There you will find a variable called LINK_URLS. Edit the values there to suit your system. Make sure you follow the instructions there and put fully qualified URLs.

Now, to generate the documentation, change back to the project root directory and type

   [j3d code] $ make javadoc

If everything goes according to plan, you will see a big stream of printouts as the documentation is produced. After all this is finished, you will find the docs in the $PROJECT_ROOT/docs/javadoc directory.

Example Code

The example code area does not use the makefiles to build the code. What this means is you have to hand compile each directory. Firstly, make sure that the classpath is setup correctly and points to your example directory(s) that you wish to compile and run.

Geometry Demo

The geometry demo area has a small program to show the different geometry primitive types available in the org.j3d.geom package. Menu items allow you to select each type of geometry and then the rendering style. This allows to to turn on/off the lighting and select the mode you want to render in - solid, wireframe or points.

Navigation Demo

This directory contains a number of demonstration applications that show different levels of navigation capabilities provided by the classes in the org.j3d.ui.navigation package.