Installation

This page is divided into three sections. The first is common for everyone. This section details all of the libraries that are needed beyond those that are included in the download. The second section is for users that would like to install swt_opengl for using it in developing other applications. The third section is for developers that are interested in compiling their own version of swt_opengl from source.

System Requirements

The first thing that you will need to do is download the latest version of swt_opengl. You can find these on our downloads page. swt_opengl is a relatively simple library with few dependencies. Most of those are in the utility section of the codebase, where we make use of code from the main j3d.org Code repository and provide swt_opengl-specific implementations. There are a few dependencies on external libraries that we do not include as part of the download. This is because they require native libraries, and they'll change depending on what operating system you will be running the code on. The following gives a list of what else you will need to install.

For all users, you need at least a J2SE v1.4.2 (JDK if you're a developer, JRE if you're an end user or installing this as part of a bigger app). This is required by JOGL as prior versions have some major bugs dealing with the native AWT interface code.

Note: Make sure that you do not have the existing Sun RI of JOGL findable in your classpath - that is both the DLL and the JAR files. We had to make a number of significant changes to their code to prevent it crashing under SWT. If you have it there we will guarantee that your application with crash. Get rid of it. Now. No ifs, no buts.

• J2SE v1.4.2
• SWT 3.2M3

There are no other hard requirements for the code. We do have our own custom hacked version of Sun's JOGL 1.2 Beta 1 RI code, however that is includeded as part of the binary and source downloads in a pre-compiled state. We're not distributing the source right now as we're waiting to see if Sun will take back our changes. If not, we'll send it off. If you do want them, send Justin an email at his usual address.

Since you are going to be doing 3D graphics coding, we recommend the best video card your money can buy. Either the nVidia GeForce or ATI Radeon cards are the current best of the crop in the PC market. Of course, the Sun hardware is well supported too :) Other platforms supported depend on what JOGL can handle. We know that a Mac version is running, but requires MacOS X 10.3, so you can't run this code on anything earlier than that.

Requirements for end user developers

For you, you will need to download the most recent release of swt_opengl. In the zip file, there will a number of JAR files. One of these are specifically swt_opengl, related, the rest are the modified versions of the JOGL RI. You'll also need at least SWT 3.2M3 or later.

Requirements if you want to compile swt_opengl from scratch

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. 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/swt_opengl

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

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/.bash_login. 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@svn.j3d.org:/svn/j3d/svnroot"
J3D_SWT_HOME=${J3D_SWT_HOME}/swt_opengl
J3D_SWT_PROJECT_ROOT="${J3D_DOS_HOME}/swt_opengl"
J3D_BASE_CLASSPATH="${TEST_CLASSPATH}"
J3D_SWT_CLASSPATH="${J3D_SWT_PROJECT_ROOT}/classes"
J3D_SWT_CLASSPATH="${J3D_SWT_CLASSPATH};${J3D_SWT_PROJECT_ROOT}/config"
J3D_SWT_CLASSPATH="${J3D_SWT_CLASSPATH};${J3D_SWT_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
}

swt()
{
  export PROJECT_HOME=${J3D_SWT_HOME}
  export AREA=j3d
  export PS1="[$AREA \W] \$ "
  export SVNROOT=$J3D_SVNROOT
  export LD_LIBRARY_PATH=$J3D_SWT_LIB_PATH
  export PATH=$J3D_SWT_PATH
  export PROJECT_ROOT=${J3D_SWT_PROJECT_ROOT}
  export CLASSPATH="${J3D_BASE_CLASSPATH};${J3D_SWT_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 6 subdirectories under the main code area. Five of these are there when you download the code:

• make The makefiles for building the code
• 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 swt_opengl] $ cp make/Makefile .
   [j3d swt_opengl] $ make clean
   [j3d swt_opengl] $ 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 swt_opengl] $ 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 swt_opengl] $ 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 swt_opengl] $ 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.

To run the demo code after you have compiled it, change to the appropriate directory and run the class file with the normal java command. You will need to be in the directory where the .class file is normally as a lot of the examples reference resources, like images for textures, using relative file paths.