Aviatrix3D 2.0 
                 Compiling and Installation Guide

Aviatrix3D is a pure-Java scene graph API that utilitises a number of lower
level libraries. To compile Aviatrix3D, you will need to make sure you have 
these extra libraries installed. Some libraries are included with the basic
download (either pre-built or from CVS). These libraries are those that do not
require any native code. Anything that uses native code, we require you to 
download that separately for your platform. 

External Downloads
-------------------

The following libraries are required:

J2SE (Java development environment)

Where: 
Version: 1.5.0 or later

JOGL (SWT Java OpenGL Bindings)

Where: http://opengl.j3d.org/swt/jogl.html
Version: 0.7 or later

Our code supports AWT, Swing and SWT. While you could download the reference
implementation of JOGL, sections of Aviatrix3D will not compile as the RI does
not support SWT. If you have no intentions of using the SWT capabilities, then 
you may use the JOGL Reference Implementation from Sun. You'll need v1.1.0 RC1
or later. 

JOAL (Java OpenAL Bindings)

Where: https://joal.dev.java.net/
Version: 1.1 Beta 01 only (The Jan 2006 or later, the numbering seems to have 
  gone backwards after the old 1.1.0b04!)

Vecmath 

Where: https://vecmath.dev.java.net/
Version: 1.3.1

SWT (Standard Windowing Toolkit)

Where: http://www.eclipse.org/swt/
Version: 3.2 or later


Build Environment
------------------

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 or another tool like
ant. 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 and ensures that code that is not yet ready for 
compilation is not accidently compiled, such as indescriminant tools like ant
do.

When installing the native code libraries required above, we recommend that you
do not place them into your JRE lib/ext directory. Instead, place them 
somewhere common that all users can get to, but where different versions of 
the same toolkit can co-exist depending on your runtime needs. 

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. Make sure you have at least Make and Bash installed.

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. The local 
vendor-specific make will not work as the build system uses several GNU 
features to provide cross-platform compile ability.

MacOS

No idea at this stage. We're looking for someone to help us out on this part.

			   -----------------

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 your code will be placed somewhere like

   /home/justin/projects/j3d.org/aviatrix3d

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/aviatrix3d

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.

(Special Note! Cygwin have changed to make 3.8.1 which broke all our path handling.
We have not yet corrected this. Please downgrade to 3.8.0 to make sure you can
build it. We'll have a fix before the final 2.0 release).

Many people have their own, personal classpath setups too - that include all of
the downloaded libraries and points to their current path. 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 (ie those native JARs that you've
had to download to compile this codebase). 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/.bash_login. This allows me to swap between various 
different projects on the fly and work regardless of whether I'm on a Windows 
or unix machine:

JOGL_DEV_ROOT="/cygdrive/c/java/jogl/jsr231/jogl/build"
JOGL_DEV_DOS_ROOT="c:/java/jogl/jsr231/jogl/build"
JOGL_DEV_CLASSPATH="${JOGL_DEV_DOS_ROOT}/jogl.jar"
JOGL_DEV_LIB_PATH="${JOGL_DEV_ROOT}/obj"

ECLIPSE_DEV_DOS_ROOT="c:/Program Files/eclipse/plugins"

SWT_DEV_ROOT="/cygdrive/c/java/swt-3.2M3"
SWT_DEV_DOS_ROOT="c:/java/swt-3.2M3"

SWT_DEV_CLASSPATH="${SWT_DEV_DOS_ROOT}/swt.jar;${ECLIPSE_DEV_DOS_ROOT}/org.eclipse.ui.workbench_3.1.1.jar"
SWT_DEV_CLASSPATH="${SWT_DEV_CLASSPATH};${ECLIPSE_DEV_DOS_ROOT}/org.eclipse.core.runtime_3.1.1.jar"
SWT_DEV_CLASSPATH="${SWT_DEV_CLASSPATH};${ECLIPSE_DEV_DOS_ROOT}/org.eclipse.jface_3.1.1.jar"
SWT_DEV_LIB_PATH="${SWT_DEV_ROOT}"

J3D_HOME=${HOME}/j3d.org
J3D_DOS_HOME="c:/cygwin/home/justin/j3d.org"
J3D_CVSROOT=":ext:justin@case.vlc.com.au:/cvs/j3d/cvsroot"
J3D_CVS_RSH='/usr/bin/ssh'
J3D_LIB_PATH=
J3D_PATH="$PATH:${JAVA_CYG_HOME}/bin"

J3D_BASE_CLASSPATH="${JUNIT_CLASSPATH}"

J3D_SWT_PROJECT_ROOT="${J3D_DOS_HOME}/swt_opengl"
J3D_SWT_CLASSPATH="${J3D_SWT_PROJECT_ROOT}/classes"
J3D_SWT_CLASSPATH="${J3D_SWT_CLASSPATH};${JOGL_DEV_CLASSPATH}"
J3D_SWT_CLASSPATH="${J3D_SWT_CLASSPATH};${SWT_DEV_CLASSPATH}"
J3D_SWT_PROJECT_CLASSPATH="${JUNIT_CLASSPATH}"
J3D_SWT_LIB_PATH="${JOGL_DEV_LIB_PATH}:${SWT_DEV_LIB_PATH}"
J3D_SWT_PATH="{$J3D_PATH}:${J3D_SWT_LIB_PATH}"

J3D_AVIATRIX_PROJECT_ROOT="${J3D_DOS_HOME}/aviatrix3d"
J3D_AVIATRIX_CLASSPATH="${J3D_AVIATRIX_PROJECT_ROOT}/classes"
J3D_AVIATRIX_CLASSPATH="${J3D_AVIATRIX_CLASSPATH};${J3D_AVIATRIX_PROJECT_ROOT}/config"
J3D_AVIATRIX_CLASSPATH="${J3D_AVIATRIX_CLASSPATH};${J3D_AVIATRIX_PROJECT_ROOT}/images"
J3D_AVIATRIX_CLASSPATH="${J3D_AVIATRIX_CLASSPATH};${J3D_CODE_PROJECT_ROOT}/classes"
J3D_AVIATRIX_CLASSPATH="${J3D_AVIATRIX_CLASSPATH};${J3D_SWT_CLASSPATH}"
J3D_AVIATRIX_PROJECT_CLASSPATH="${JOGL_DEV_CLASSPATH};${SWT_DEV_CLASSPATH}"
J3D_AVIATRIX_LIB_PATH="${JOGL_DEV_LIB_PATH}:${SWT_DEV_LIB_PATH}"
J3D_AVIATRIX_PATH="{$J3D_PATH}:${J3D_AVIATRIX_LIB_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
}

av3d()
{
  export PROJECT_HOME=${J3D_HOME}/aviatrix3d
  export AREA=AV3D
  export PS1="[${RED}$AREA ${WHITE}\W${NORMAL}] \$ "
  export CVSROOT=${J3D_CVSROOT}
  export CVS_RSH=$J3D_CVS_RSH
  export LD_LIBRARY_PATH=${J3D_AVIATRIX_LIB_PATH}
  export PATH=${J3D_AVIATRIX_PATH}
  export PROJECT_ROOT=${J3D_AVIATRIX_PROJECT_ROOT}
  export CLASSPATH="${J3D_BASE_CLASSPATH};${J3D_AVIATRIX_CLASSPATH}"
  export PROJECT_CLASSPATH=${J3D_AVIATRIX_PROJECT_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 (if defined)
    * docs Project documentation and the generated javadoc
    * src Source files for the project. Sub directories broken down by implementation language
    * examples Example code to show how to use the toolkit

The classes, jar and docs/javadoc directories are created by the build process.

Building the class files

To build the entire codebase from scratch, change to the project root 
directory. First time up, you will need to copy one file from the make 
directory. After the first time you will never need to do it again. Now type:

   [j3d aviatrix3d] $ cp make/Makefile .
   [j3d aviatrix3d] $ make clean
   [j3d aviatrix3d] $ 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

If you only wish to recompile a single directory then you can change to that
directory and just type:

   [j3d aviatrix3d] $ make

This will then build only the local files.

Building JAR files

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

   [j3d aviatrix3d] $ 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 aviatrix3d] $ 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.

Justin Couch
justin@vlc.com.au