Java SE 6
Packaging Java Applications for OS X
Packaging Java Applications for OS X
By: Ian McFarland
Jan. 1, 2003 12:00 AM
Java on OS X is a first class citizen. You can integrate your app so well that users probably won't even know they're using a Java application.
You can package your apps so they have one of those lovely 128x128 icons. Apps can be launched with a double-click, and can even be bound to particular file types so that your app gets launched when the documents are double-clicked. Swing apps also get the luscious Aqua user interface for free, and with a couple of lines of code you can also tell the runtime to let your app use the system menu bar, and even use the hardware acceleration, which you won't find on any other platform.
Let's look at how apps are packaged on OS X.
The Extremely Portable Approach
Of course, it won't have its own fancy icon, just the standard OS X JAR file icon (see Figure 1). However, in the write once, run anywhere tradition, this exact same file will run on OS X, Windows, Solaris, Linux, or any other Java platform. If all you're writing is a simple utility and you don't want to spend the extra effort to support OS X, then you're done.
The Extremely Well-Integrated Approach
Another advantage is that you can associate file types with your application when you package your app according to the Apple guidelines. That way, you can have your app launch automatically when any of its associated files is double-clicked on. I'll show you how to do that in detail in my next article. For now, though, suffice it to say that the little bit of extra work you do packaging your app gives you a lot nicer integration to the platform on OS X.
In the rest of this article, I'll first discuss how to package your app using one of the available tools. Then I'll walk you through the file hierarchy these tools create so you'll know what's really going on underneath it all.
You'll find MRJAppBuilder and Project Builder in /Developer/Applications once you install the developer tools. (These tools are found on a separate CD or in /Applications/Installers on your hard drive, depending on how you acquired OS X.)
I won't go into how to build an application with Project Builder here, but any application project you build with Project Builder is automatically packaged as a first class OS X application. (The JAR file inside is quite portable, however, unless you're using some specific native feature.)
In fact, to convert an existing JAR file to an OS X application, all you have to do is run the following command line:
java -jar osxize.jar -addjar MyApp.jar
If MyApp.jar has the Main-Class attribute set, in less than a second you'll have a new application called JavaApplication.app. Okay, so you probably want to specify a more descriptive name for your app. You can handle that by passing the -n attribute:
java -jar osxize.jar -n "My Fabulous Application" -addjar MyApp.jar
OSXize then generates My Fabulous Application.app for you. (It also does some nice things that MRJAppBuilder doesn't do, like making sure your app shows up as My Fabulous Application when you look at what processes are running, e.g., through ps or top.)
There are a number of other flags you can specify as well. No Main-Class attribute in the manifest? No problem. Just specify the main class with -m. Want to specify your own icon file? Make a new icon (see Figure 5) using the ICNS Editor (also in /Developer/Applications) and specify the path to the file with the -i option. Want to specify an application version to show up in the Get Info dialog? Use the -version flag. The full set of options is documented on the Web site as well as how to use the OSXize Ant task. You can download it from www.javaosx.com/apps/.
The .app Application Bundle
Instead, the Apple team based most of their packaging on special arrangements of files in the filesystem. Modern OS X applications (with the exception of some monolithic Carbon binaries) are a collection of files living in a directory with the .app extension, and not much more. The .app extension is a magic, or "blessed," extension that says: treat this directory differently. (There are a few other magic extensions, such as .kext, that contain other types of bundles, and other special file hierarchies like those in /Library/StartupItems.)
Inside an .app directory, you'll find a special directory hierarchy that's used to contain the files and resources that make up the application. These include the icon file, files with special information for the Finder describing the application, an executable binary file for Java applications, one or more JAR files, the MRJApp.properties file, and a number of other files as well.
The example command line shown earlier would create a file hierarchy as follows:
My Fabulous Application.app/
In the rest of this article, we'll look at what each of these files is and what it does.
The PkgInfo File
The Info.plist File
The Application Stub
The big thing to note here is that this file must have the execute bit set in order for the application to work. (In fact, if you use OSXize to generate your application on a Windows machine, you'll need to set the execute bit manually before you can run the app on OS X, since Windows filesystems don't have execute bits.) This execute bit issue is one that often comes up when an app mysteriously won't run. If this happens to you, cd to the /Contents/MacOS directory, and then chmod +x the file you find there. If everything else was okay, your app should now be double-clickable and run appropriately.
The MRJApp.properties File
The ICNS File
The JAR Files
That's really all there is to a typical packaged Java application. There are some additional attributes to add to the Info.plist if you want to associate a given file extension with your app, for instance, .foo. You'll also need to include additional .icns files in the Contents/Resources directory if you want to associate icons with the files owned by your app, for instance, a foo.icns file containing the icon the finder should use for all .foo files. Here again, there are some tweaks you'll need to make to Info.plist to tell the finder which icon to associate with which file type.
Having great looking double-clickable applications is just something you can use to make your friends on other platforms a little jealous while waiting for Apple to get the kinks out of their J2SE 1.4 port.
Reader Feedback: Page 1 of 1
Latest Cloud Developer Stories
Subscribe to the World's Most Powerful Newsletters
Subscribe to Our Rss Feeds & Get Your SYS-CON News Live!
SYS-CON Featured Whitepapers
Most Read This Week