MRJAppBuilder and Application Bundle Internals

by James Duncan Davidson

The easiest way of creating a double-clickable Java program on Mac OS X is to use Apple's MRJAppBuilder. It creates a nifty bundle which contains all of the class and resource files needed by an application as well as some information that helps Mac OS X run it. Unfortunately, the documentation on this tool is not as accessible, or as clear, as one might like. In a very uncharacteristic move for Apple, there isn't even a help menu.

Luckily, MRJAppBuilder is not very hard to use. After a couple of runs with the tool, I have come up with the following easy to use recipe:

  • In the Application tab, fill in the Main Classname text field with the main class of your application. This is the same classname that you'd pass to the Java Virtual Machine on the command line.
  • Also in the Application tab, fill in the Output File text field with the path and file name you would like your application to have.
  • Click over to the Merge tab and add all the Jar files of your application.
  • Click back to the Application tab and make sure that your recently added Jar files are on the classpath.
  • Build the Application with the aptly named Build Application button.

After following the above process, you will have an application ready to use or distribute. To be more accurate, you will have an application bundle. This bundle will look to users via the Finder as a single file that aides its ease of use and distribution. But, under the covers is an interesting hierarchy of files that contain the secrets of how your Java application is run when you double-click on it.

You can dig into the innards of your application bundle in one of two ways. The first is to control-click on the bundle and select Show Package Contents from the pop up menu. This will open up a Finder window that you can browser the contents of the bundle with. The other is to dive in using the Terminal. Just `cd [appname].app` (the .app extension is hidden by the Finder but all application bundles have it). The following is an example of one of the application bundles that I created using MRJAppBuilder:

The Info.plist file is an XML based description of some basic information that Mac OS uses to run the application. Most of the information in this file only makes sense if you have experience with building native Mac OS applications. The key configuration data it contains for our purposes tells the system to execute the JavaApplicationStub executable in the bundle. This stub is a very simple program that it copied from the JavaVM.framework. It looks at the file and then starts up a Java virtual machine based on the configuration information it finds there. Here are the important properties from my application:$SYSTEM$SYSTEM

Having access to all of this information in plain text files means that I can continue to use this created bundle even as my application is updated. For example, if I need to add a library in a Jar file, I can copy it into the Contents/Resources/Java directory of the bundle and add it to the classpath entry in the properties file. Even better, since the application bundle format is so simple, it is possible to set up a few simple build scripts and have bundles created on demand from automated build tools. This bypasses the need to manually execute MRJAppBuilder and recreate application bundles every time a program is updated.