Tutorial: Creating native binary executables for multi-platform Java apps with OpenGL and Eclipse RCP

Greets to my peeps, and to eybody reppin’ the 512! Wade Walker back in the house, and hype for some third-time tutorialization.

I also return to the dwelling! Debonair of aspect, felicitous of phrase: “Stitio” is my nom-de-guerre!

Hey, did I miss something? I thought your name was “Interstitius” or something Latiny like that.

“Interstitius” was not so swashbuckling as I had hoped. This shorter, Italianate version should manifest my dashing and adventurous persona to any pulchritudinous lady-beings who may chance upon these writings.

That kind of sounds like you’re an alien AI impersonating a Renaissance Italian Musketeer.

Even so! You have seized upon the very crux of my intent!

People keep telling me that.

So! In our last tutorial, me and the mutably-named Stitio showed how to speed up the rendering in our cross-platform scientific application by using OpenGL’s vertex buffer objects.

This time, we’ll show you how to create true native binaries for these sorts of Eclipse RCP apps. This lets you distribute them the same way as non-Java apps, so you don’t have to use wrapper scripts or other hackery.

Ante-ante-prelude: An overview of how “Java apps” are normally launched

When you compile a Java app, it’s turned into .class files, one per Java class. Eclipse puts them into the “bin” or “classes” directory inside the project directory. Here are the .class files for our previous tutorial:

These files are full of platform-independent Java byte code that the Java virtual machine (JVM) interprets. To run an app that’s compiled into a directory of files like this, you have to type

java –classpath MyClassDir MyMainClassName

But some users are gonna be put off by this. It would be nicer if you could just double-click “MyApp.exe” to run, like for a normal app.

We can get closer to that by packaging our .class files into a single JAR (Java ARchive) file. Here’s how you do it:

jar cfm MyApp.jar MyMainClassName MyClassDir/*.class

This makes a single .jar file containing all your .class files, with a “manifest” file inside that tells Java which class is your main class. Then you run it like this

java -jar MyApp.jar

Or on Windows if you have a Java Runtime Environment (JRE) installed, you can just double-click the JAR file and Windows will add in the java -jar for you.

They call these kinds of .jar files “executable JARs”, but they’re not native binary executables, they’re really just zip files full of .class files. And this type of JAR can’t hold the native libraries that are in Java OpenGL, because those libraries have to be sitting on the file system separately so the operating system can see them.

Ante-prelude: How might one create a “Java native binary”?

Well, there’s no way to do it by using the “java” and “jar” commands that come with a Java installation. You have to use some third-party system. If we weren’t already using Eclipse, we might use something like launch4j or JSmooth.

But! Eclipse itself comes as a native binary, and it has its own built-in system that lets you create similar ones for your Eclipse RCP apps. Take a look at the Eclipse installation:

You can see there’s a small native binary, “eclipse.exe”, plus a bunch of directories. These directories contain all the JAR files and other stuff that’s part of Eclipse. When you run “eclipse.exe”, it finds the JRE on your system, unpacks any native libraries into its “configuration” directory, shows a splash screen, then runs java -jar SomeEclipseJARFile.jar for you.

But why is there so much stuff in this installation directory? It’s possible to make a Java native binary that’s one single executable file: an executable header with the JAR file appended. So why doesn’t Eclipse do it like that?

Several reasons. First, having a “plugins” directory lets you drop additional JARs into the installation. You need to do this if your app is something like Eclipse, where you can download and install new features over time.

Second, if your app contains native libraries (.dll or .so files), they need to be unpacked and written out as separate files before the operating system can load them. Eclipse does that for you, and hides them down inside the “configuration” directory.

Third, the “eclipse.ini” file let users pass extra startup arguments to the app or the JVM without having to put them on the command line every time.

And fourth, you can include a “jre” directory in the installation that makes your app completely independent of any Java installation on the host computer.

So, bottom line: Eclipse’s native binary system is complex, but gives you lots of options and room to grow your app into something bigger later on.

Prelude: We augment our Eclipse installation

Eclipse can already export native binaries for the platform you’re running it on. But if you want to export native binaries for all the other platforms at the same time, you have to install the Eclipse Delta Pack. To find it, start at the Eclipse download site and click the “Other Downloads” link under “Eclipse Classic”.

Then click the version of Eclipse you’ve got installed under “Build Name”. I’ve got version 3.6.1 installed.

Then finally click on the delta pack download link. The one I got was “eclipse-3.6.1-delta-pack.zip”.

Unzip this file where you want to install the delta pack. I put it beside my Eclipse installation and called it “eclipse-3.6.1-delta-pack”. You can also unzip it directly onto your Eclipse installation, but everyone seems to advise against that. Here’s how mine looks.

We still have to tell Eclipse where to find the delta pack, but we can’t do that until we set up our workspace, since Eclipse stores that setting in your workspace’s “.metadata” directory.

Intermezzo: For expediency’s sake, we re-use our previous project

We’ll use our previous masterwork as a starting point. First, create a new workspace directory and unzip this file and this file from the last tutorial into it. Then follow the instructions from the last tutorial to import those projects into your workspace.

Or, as usual, if you just wanna skip to the end of this tutorial without all the typing and clicking, create your new workspace directory and unzip this file and this file into it, then import the projects. You’ll still have to point Eclipse at your delta pack, though.

Entremet: We inform Eclipse as to the location of our “delta pack”

Now that we have a workspace to store these settings, click “Window > Preferences” from the menu, open “Plug-in Development” on the left, click “Target Platform”, and select the “Running Platform” on the right. Then click “Edit…”.

When the “Edit Target Definition” dialog appears, click “Add…”.

Then select “Directory” and click “Next”.

Enter the directory where you put the delta pack. Mine is right beside Eclipse, so I can do it like this: “${eclipse_home}\..\eclipse-3.6.1-delta-pack”. Then click “Finish”.

Now you should see the delta pack in your platform like this. Click “Finish” again.

Finally, click “OK” to dismiss the Preferences dialog. Eclipse will grind for a moment, then the delta pack is in! Just remember, if you make a new workspace later, you gotta do this again.

Opus: The creation of our “product”

Now we tell Eclipse what it needs to know to export our tutorial as native binaries. Right-click the “name.wadewalker.tutorial” project in the Package Explorer and select “New > Product Configuration”. Enter “Tutorial” as the file name, then click “Finish”.

This creates a new file “Tutorial.product” in the “name.wadewalker.tutorial” directory. This file will hold all the settings we need to export native binaries. It should look like this to start with:

Now change the version to “1.0.0”. Click the “Application” drop-down and select “name.wadewalker.vbotutorial.application”.

Then click the “Launching” tab at the bottom of the Tutorial.product window. Enter “Tutorial” as the launcher name.

Then click the “Overview” tab to go back, and click the “Eclipse Product export wizard” link to start the native binary export.

When the export wizard comes up, set the root directory to “bin”. Then set the destination to an empty directory where you want the native binaries to go. I put mine in a directory called “installation” beside the workspace, but it can be anywhere. Minor annoyance: this apparently has to be an absolute path. Then check the “Export for multiple platforms” box and click “Next”.

Check the boxes of the platforms you want to export to. I’m doing Linux GTK 32- and 64-bit, Mac OS X Cocoa 64-bit, and Windows 32- and 64-bit. I don’t have a way to test the Mac version right now, but we can at least see that it exports. Click “Finish” to start the export process.

Exporting takes a minute or so, but once it’s done you should see this in your destination directory:

There’s one directory per platform, and one common “repository” that holds JARs and other files that are the same for all platforms. If you look down inside the “win32.win32.x86_64\bin” directory, you’ll see an installation that looks just like Eclipse:

Double-click on that executable, and pow! Here’s the binary running on Windows 7 64-bit:

And onomatopoeia! Here it is on CentOS 5.4 64-bit:

Now you can write one Java OpenGL app, export it, and get native binaries for five different platforms at once. And that, my friends, is super-genius-ness in action!

Postlude: Where further customization is left for your amusement, chiefly due to our laziness

You can see from all the tabs and fields of the “Tutorial.product” file that there’s a lot more customization you can do. You can put in a custom splash screen, custom icon, custom JVM arguments, and a lot more.

One thing that doesn’t work right as of Eclipse 3.6.1 is the “Bundle JRE for this environment with the product” check box on the “Launching” tab of “Tutorial.product”. If you check the box, re-export, and compare the exported product to the one you had before, you’ll see they’re freaken identical.

But then we open up the smartness hose on this problem. Find the JRE directory of your system’s Java installation, which looks like this:

Create a new directory in your app’s installation (under the same platform as your system) and name it “jre”. Then copy the contents of the above JRE directory into it. Now that platform in your installation should look like this:

And now when you double-click your “Tutorial.exe”, it will use the “java.dll” and “jvm.dll” from this new “jre” directory instead of using your system’s installation of the JRE. I’ve confirmed this with Windows Process Explorer, and I’ve done it on Linux the same way. The Eclipse launcher always looks here first, so we’re just putting a JRE right where it expects to find one.

I usually put this annoying little step in an installation script. I custom-made a zipped JRE for each platform, and I have the script unzip them into the right directories during the install process.

Resources which the reader may find helpful

Windows Process Explorer: Get it here. It helps verify that you’re really getting the JRE from where you think you are. It’s also handy for seeing where the JOGL DLLs get unpacked to.

Eclipse product configurations: There’s a tutorial from Lars Vogel here that has more details than I give.

A list of the revisions which we have made to this document

10/24/2010: Wrote the first version.

10/25/2010: Fixed the links to full-sized images.

11/19/2010: Added a link to the completed version of this tutorial.