Building JOGL on the command line - WadeWalker/com.jogamp.jogl GitHub Wiki

Table of Contents

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.

Note: this version of the instructions is to build with Java 11. Original instructions for Java 8 are at https://web.archive.org/web/20180713053225/http://jogamp.org/wiki/index.php/Building_JOGL_on_the_command_line. Note 2: these instructions haven't yet been completely checked for accuracy. Contact me if you find any mistakes.

Supported platforms

Currently we support building JOGL on Linux (64-bit), Windows 10 (64-bit) and Mac OS X (64-bit).

Install a JDK

The first thing we need is a Java Development Kit (JDK). Here we use Oracle's JDK as an example.

  • Check if you have a JDK
    • You must use a JDK, not a JRE, because Ant needs bin/javac, which doesn't come in the JRE.
    • On Windows and Linux, 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 bin directory. If it contains javac, it's a JDK.
  • Get a JDK if needed
    • On Windows and Linux, download the JDK from at https://www.oracle.com/technetwork/java/javase/downloads. Make sure you get Java SE 11 or later. You can install the JDK wherever, but here's what I do:
    • Windows: download jdk-11.0.1_windows-x64_bin.exe
      • execute installer, install to C:\Program Files\Java\jdk-11.0.1\
      • add C:\Program Files\Java\jdk-11.0.1\bin to PATH
      • set JAVA_HOME to C:\Program Files\Java\jdk-11.0.1
    • Ubuntu: download jdk-11.0.2_linux-x64_bin.tar.gz
      • tar xzf jdk-11.0.2_linux-x64_bin.tar.gz, mv jdk-11.0.2 ../Programs
      • in .bashrc
      • PATH=$PATH:~/Programs/jdk-11.0.2/bin
      • export JAVA_HOME=~/Programs/jdk-11.0.2
    • MacOS: download jdk-11.0.2_osx-x64_bin.tar.gz
      • tar xzf jdk-11.0.2_osx-x64_bin.tar.gz
      • sudo mv ~/Downloads/jdk-11.0.2.jdk /Library/Java/JavaVirtualMachines
  • Add the JDK's bin directory to your path.
    • On Windows, append ;your JDK\bin to your Path environment variable.
    • On Linux, append :your JDK/bin to your PATH environment variable.
    • On Mac OS X, prepend /Library/Java/JavaVirtualMachines/jdk-11.0.2.jdk/Contents/Home/bin: to your PATH environment variable.
  • Set the JAVA_HOME environment variable
    • On Windows and Linux, set the JAVA_HOME environment variable to your JDK path.
    • On Mac OS X, set JAVA_HOME to /Library/Java/JavaVirtualMachines/jdk-11.0.2.jdk/Contents/Home.
  • Test your JDK by opening a shell and typing java --version and javac --version
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 strange build or runtime problems.
  • On Windows and Linux, delete any JOGL or ANTLR JARs from jre/lib/ext
  • On Mac OS X, delete any JOGL or ANTLR JARs from /Library/Java/Extensions and ~/Library/Java/Extensions

Install Ant

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

  • Download Ant 1.10 or later from http://ant.apache.org/bindownload.cgi.
    • For example, download the file apache-ant-1.10.5-bin.zip and unzip it to your desired installation directory.
  • Set your ANT_HOME environment variable to the new installation directory.
  • Add Ant executables to your path
    • On Windows, append ;your Ant dir\bin to your Path environment variable.
    • On Linux, append :your Ant dir/bin to your PATH environment variable.
    • On Mac OS X, prepend your Ant dir/bin: to your PATH environment variable.
  • Test your Ant installation by opening a shell and typing ant -version

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, remove it from your .cshrc or equivalent shell setup file.
  • On Mac OS X, remove it from your .bash_profile 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 2.17 or later.

  • On Windows
  • On Linux
    • sudo apt-get install git
  • On Mac OS X
    • Git should come with the Xcode tools; see below.
  • Test your Git installation by opening a new shell and typing git --version

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.

  • Get MSYS2 (file msys2-x86_64-20180531.exe) from https://www.msys2.org/
  • double-click, install to C:\msys64
  • run C:\msys64\msys2.exe, type "pacman -Syu", close window when it's done
  • run C:\msys64\msys2.exe again, type "pacman -Su"
  • run C:\msys64\msys2.exe again
  • pacman -S mingw-w64-x86_64-binutils mingw-w64-x86_64-crt-git mingw-w64-x86_64-gcc mingw-w64-x86_64-gcc-libs mingw-w64-x86_64-gdb mingw-w64-x86_64-headers-git mingw-w64-x86_64-libmangle-git mingw-w64-x86_64-libwinpthread-git mingw-w64-x86_64-make mingw-w64-x86_64-pkg-config mingw-w64-x86_64-tools-git mingw-w64-x86_64-winpthreads-git mingw-w64-x86_64-winstorecompat-git make
  • add C:\msys64\usr\bin and C:\msys64\mingw64\bin to PATH
Now you may test your MinGW installation by opening a new shell and typing gcc --version

Check and install developer packages (Linux only)

Depending on your Linux flavor and version, you may need to install some developer packages to build JOGL. For example, on Ubuntu you can install them all with:

  • sudo apt-get install gcc libgl1-mesa-dev libglu1-mesa-dev xorg-dev libice-dev libsm-dev libx11-dev libxext-dev libxxf86vm-dev libxinerama-dev libxrandr-dev libxrender-dev libxcursor-dev libudev-dev

Install Xcode (Mac OS X only)

The easiest way to set up GCC on Mac OS X is to install the Xcode command line tools.

  • xcode-select --install
Once you've installed it, open a new shell and type gcc --version to make sure GCC is available.

Pull the JOGL source code from GitHub or JogAmp

Open a shell and cd to where you want the code to go.

Check out the branch that will build with Java 11
  • cd gluegen
  • git checkout -t origin/java-11-fixes
  • cd ../jogl
  • git checkout -t origin/java-11-fixes
  • cd ../joal
  • git checkout -t origin/java-11-fixes
  • cd ..
If you're going to be contributing fixes or doing development, you'll need to check out from your own GitHub account after forking, instead of cloning like this.

After this is done, you should see gluegen, joal and jogl 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, then joal, then jogl.

  • Build gluegen
    • cd to gluegen/make
    • Type ant clean
    • Type ant
    • cd to joal/make
    • Type ant clean
    • Type ant
  • Build jogl
    • cd to jogl/make
    • Type ant clean
    • Type ant
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 (optional)

Before runing the tests, make sure the Z-Zip file archiver is installed.

  • If you don't have it, download the latest version from http://www.7-zip.org/ and install it.
  • Make sure 7z is visible in a command shell.
    • On Windows, append ;C:\Program Files\7-Zip to your PATH environment variable.
  • Test 7-Zip by opening a new shell and typing 7z
Then to run the full suite of JUnit tests:
  • For gluegen, cd to gluegen/make and type ant junit.run
  • For jogl, cd to jogl/make and type ant junit.run

Build Javadoc (optional)

Type ant javadoc in the jogl/make 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 gluegen/make/gluegen.properties and/or jogl/make/jogl.properties into your home directory (pointed to by the Java system property user.home) and edit them as desired.

For example, if you want to build JOGL with extra debugging information in the JARs and native libraries, create a jogl.properties file in your home directory and add these lines to it: 

javacdebuglevel=source,lines,vars
c.compiler.debug=true

The first line puts debugging information in the class files so you can step through Java files. The second line puts debugging information in the native libraries so you can step through C files containing JNI code.

WARNING: Make sure there are no trailing spaces on the property lines in this file, or they may have no effect. This seems to be due to the way Ant reads these files.

Acknowledgements

  • Revised for Java 11 by Wade Walker, March 2019
  • Revised by Wade Walker, January-March 2011.
  • Revised by Sven Gothel and Michael Bien, May 2010.
  • Original JOGL build instructions by Christopher Kline and Kenneth Russell, June 2003 (revised November 2006).
Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️