Three assumptions in this process are:
- You have a single Jar file you can already run with the
- You aren’t concerned about implementing macOS-specific features, like enabling the Preferences and Quit menu items, or implementing Mac-specific keystrokes in your app
- I assume your application is a Java Swing or JavaFX GUI app
(I understand that those first two items can be big assumptions. More on those later.)
As those assumptions infer, you won’t have a “perfect” app whose menu items work exactly like a native Mac application, but you will at least have a Mac application that you can start by double-clicking an application icon.Back to top
If you don’t already know it, a macOS application is actually a directory that contains a series of files in a specific, well-defined layout. The directory must end with the extension, “.app”.
Many years ago, Sun (now Oracle) created a process by which you could create a Mac application from a Java Jar file (or even a series of Jar files). They created an “AppBundler” Jar file that can be used with Ant to build a Mac application, and that’s what I use in this process.
Update: While you can still use the AppBundler described in this article — and in some ways it’s a more obvious approach to building a Mac/Java application — Oracle now recommends building Mac/Java applications with their
javapackager tool. I write about it in my How to use javapackager to build a macOS application bundle tutorial.
The requirements for building a macOS/Java application with this specific build process are:
- You’ll need the Java SDK installed. I tested this with Java 1.8 on macOS 10.12.5.
- You’ll need Ant. I tested this with Ant 1.10.1, which I installed with Homebrew.
- Make sure
JAVA_HOMEis set. (You may get an error if it isn’t set.)
- Your Java application needs to be in one Jar file. This distribution includes a hello.jar file to show how things work.
- The application probably needs a META-INF/MANIFEST.MF file in that Jar file. (I didn’t test it without one.)
As mentioned earlier, the biggest assumption is that your application completely exists in one Jar file such that you can run it with the
java -jar command. If you have that, this build process should work; if you don’t have that, you’ll need a more-complicated build process.
Building your application
To build your application:
- Clone my Github project.
cdinto that directory.
- Copy your Jar file into the current directory.
- Change the variables at the top of the build.xml file to match your application.
- Eventually you’ll want to create your own icon file as a macOS icns file, but you can start with my world.icns file until you create your own.
- In the macOS Terminal (or similar app), type
antto build the application.
- Assuming you named your application “HelloWorld”, type
open release/HelloWorld.appto run your application.
If all goes well, your application will be shown in a few moments. (I assume your application is a Java Swing or JavaFX GUI app.) You can then type type
open release to open the folder that contains your app, and then you can use the Mac Finder to copy your app to your desktop (or anywhere else).
Note 1: Font smoothing
Java applications built like this seem to have non-smooth fonts on macOS. This is usually immediately apparent in the title bar of your application. To get a smooth font with your application, follow this build process:
- Edit the _addHiResKeyToPlistFile.sh file
- Set the
APP_NAMEvariable in that file to the same
app_nameyou use in the build.xml file
- Run the script named _build.sh to build your application. If you look at that script you’ll see that it (a) runs
ant, then (b) runs the _addHiResKeyToPlistFile.sh script. That script adds the
NSHighResolutionCapablekey to the application’s Info.plist file.
Note 2: Setting the “application category”
If you’re going to build an application that you want to distribute to other users — such as through the Apple/Mac store — you’ll want to be sure to set the
app_category variable in the build.xml file properly. This variable is used to set the
LSApplicationCategoryType key in the Info.plist file in your application.
See this apple.com url for more information on the possible values. In case that URL ever goes away, I also included those value names in the file in this project named LSApplicationCategoryType.txt.Back to top
The Mac/Java AppBundler
This build process uses the Sun/Oracle AppBundler Jar file, which is documented here.
If you want to build a Mac application that uses several Jar files, you’ll need a slightly more-complicated process. I use Proguard for this purpose, and you can search this website for something like “Mac Java Proguard” to find those examples.
If you want to build a Mac/Java application whose menu items work like native macOS applications, you’ll have to code that into your application. Search this website for something like “Mac Java quit preferences” to find examples of how that works.Back to top
In summary, if you wanted a simple way to convert a Java Jar file into a macOS application, I hope this process is helpful.Back to top