Building JOGL on the command line

= Overview =

To build JOGL on the command line, we'll need to install prerequisites like Ant, pull the code from a Git repository, and run the Ant build scripts.

= Supported platforms =

Currently we support building JOGL on Linux (x86 32- and 64-bit), Windows XP/Vista/7 (32- and 64-bit) and Mac OS X (x86 32- and 64-bit). Additional platforms like Solaris/OpenSolaris, FreeBSD and HP/UX are handled by the build system, but are not officially supported.

= Install a JDK =

The first thing we need is a Java Development Kit (JDK). JOGL will work with OpenJDK and IcedTea, but here we use Oracle's JDK as an example.

If you've got some kind of Java installed, but you're not sure whether it's a JDK or a Java Runtime Environment (JRE), look inside the directory. If it's got a jre subdirectory inside, it's a JDK. A JRE contains only bin and lib directories.


 * Download the JDK from at http://www.oracle.com/technetwork/java/javase/downloads/index.html.
 * Make sure you get Java SE 6 update 23 or later.
 * Install the JDK wherever you like.
 * Add the JDK's bin directory to your path.
 * You must use a JDK, not a JRE, because Ant needs bin/javac, which doesn't come in the JRE.
 * On Windows, append ;your JDK\bin to your Path environment variable.
 * On Linux, append :your JDK/bin to your PATH environment variable.
 * Set the JAVA_HOME environment variable to your JDK path.
 * You must use a JDK, not a JRE, because Ant needs lib/tools.jar</tt>, which doesn't come in the JRE.
 * Test your JDK by opening a shell and typing java -version</tt> and javac -version</tt>

If you're using an existing JDK instead of installing a new one, make sure you don't have any JOGL or ANTLR JARs in its extension directory. This can cause build problems.
 * On Windows and Linux, delete any JOGL or ANTLR JARs from jre/lib/ext</tt>
 * On Mac OS X, delete any JOGL or ANTLR JARs from /Library/Java/Extensions</tt>

= Install Ant =

If you don't already have Ant installed, or your version is older than 1.8, you'll need to install a new version of Ant.


 * Download Ant 1.8 or later from http://ant.apache.org/bindownload.cgi.
 * For example, download the file apache-ant-1.8.2-bin.zip and unzip it to your desired installation directory.
 * Set your ANT_HOME</tt> environment variable to the new installation directory.
 * Add Ant executables to your path
 * On Windows, append ;your Ant dir\bin</tt> to your Path environment variable.
 * On Linux or Mac OS X, append :your Ant dir/bin</tt> to your PATH environment variable.
 * Test your Ant installation by opening a shell and typing ant -version</tt>
 * If you have problems, more detailed installation instructions are at http://ant.apache.org/manual/index.html.

= Unset the classpath =

Unset the CLASSPATH environment variable if it exists. Having this set with random JARs on it is one of the main causes of build problems.


 * On Windows, remove it from the list of environment variables in "My Computer > Properties > Advanced > Environment Variables > System Variables".
 * On Linux or Mac OS X, remove it from your .cshrc</tt> or equivalent shell setup file.

= Install Git =

The JOGL project uses Git for source code management and collaboration. If you don't already have it, you'll need to install Git 1.6.0 or later.


 * On Windows
 * Go to http://code.google.com/p/msysgit/downloads/list.
 * Click the download link for an installer (for example Git-1.7.3.1-preview20101002.exe</tt>), then run it.
 * Choose "Run Git from the Windows Command Prompt" during the install process.
 * On Linux and Solaris
 * Download in your preferred format from http://git-scm.com/download.
 * On Mac OS X
 * Go to http://code.google.com/p/git-osx-installer/downloads/list.
 * Click the download link for an installer (for example git-1.7.3.4-x86_64-leopard.dmg</tt>), then open it.
 * Drag the Git icon into your Applications folder.
 * Test your Git installation by opening a new shell and typing git --version</tt>

= Install MinGW (Windows only) =

For the JOGL build scripts to run on Windows, you'll need Minimalist GNU for Windows (MinGW) so you can use the gcc compiler.


 * Create a C:\MinGW</tt> directory.
 * Download the installer from http://sourceforge.net/projects/mingw/files/Automated%20MinGW%20Installer/mingw-get/ into the new directory.
 * For example, version mingw-get-0.1-alpha-5 is in a file called mingw-get-0.1-mingw32-alpha-5-bin.zip</tt>
 * Extract the installer file.
 * The bin</tt>, <tt>libexec</tt>, and <tt>var</tt> directories should be directly inside <tt>C:\MinGW</tt>
 * Append <tt>;C:\MinGW\bin</tt> to the end of your Path environment variable.
 * Open new shell and type <tt>mingw-get install gcc</tt>
 * This may take a few minutes to download and install the rest of MinGW.
 * Test your MinGW installation by opening a new shell and typing <tt>gcc --version</tt>

= Check and install developer packages (Linux and Solaris only) =

Depending on your Linux or Solaris flavor and version, you may need to install some developer packages to build JOGL. See the list of developer packages for each operating system distribution to check if you're missing one.

= Pull the JOGL source code from GitHub =

You'll need to get the source code for two projects, gluegen and jogl. The simple way to get it is by cloning the canonical repository.


 * Open a shell and cd to where you want the code to go.
 * Type <tt>git clone git://github.com/sgothel/gluegen.git gluegen</tt> and wait for the code to download.
 * Type <tt>git clone git://github.com/sgothel/jogl.git jogl</tt> and wait for the code to download.

If you're going to be contributing fixes or doing development, you'll need to check out from your own GitHub account. The instructions at "Contributing a new feature or fix" explain how to do that.

After this is done, you should see a <tt>gluegen</tt> and a <tt>jogl</tt> directory side by side in your working directory. They need to be together like this or the build won't work properly.

= Build JOGL =

You actually have to build gluegen first, then jogl.


 * Build gluegen
 * cd to <tt>gluegen/make</tt>
 * Type <tt>ant clean</tt>
 * Type <tt>ant</tt>
 * Build jogl
 * cd to <tt>jogl/make</tt>
 * Type <tt>ant clean</tt>
 * Type <tt>ant</tt>

During the build, ANTLR produces lots of warnings about the C grammar and our modifications to some of the signatures of the productions. The C grammar warnings have been documented by the author of the grammar as having been investigated completely and harmless, and the warnings about our modifications are also harmless.

= Test the JOGL build =

To test the build, cd to <tt>jogl/make</tt> and type <tt>ant junit.run</tt>. This will run the full suite of JUnit tests.

= Build Javadoc (optional) =

Type <tt>ant javadoc</tt> in the <tt>jogl/make</tt> directory. This will produce the end-user documentation for JOGL along with some auxiliary utility packages.

= Set up custom Ant properties (optional) =

If you want to set different options for components and compilers during the Ant build, copy <tt>gluegen/make/gluegen.properties</tt> and/or <tt>jogl/make/jogl.properties</tt> into your home directory (pointed to by the Java system property <tt>user.home</tt>) and edit them as desired.

For example, if you want to build JOGL with extra debugging information in the JARs so you can see variable values when you step through in a debugger, create a <tt>jogl.properties</tt> file in your home directory and add this line to it:

<tt>javacdebuglevel="source,lines,vars"</tt>

= Try the experimental nvidia Cg toolkit binding (optional) =

If you want to try the experimental binding to nvidia's Cg shader language, first download the Cg toolkit for your platform. Then, when you build the jogl project, add the <tt>-Djogl.cg=1</tt> option to the ant command line. The Cg binding has been tested on Windows, Linux, and Mac OS X.

= Acknowledgements =


 * Original JOGL build instructions by Christopher Kline and Kenneth Russell, June 2003 (revised November 2006).
 * Revised by Sven Gothel and Michael Bien, May 2010.
 * Revised by Wade Walker, January 2011.