


How to create a macOS installer for a Java application
(Updated for macOS High Sierra 10.13)
This information is for an older version of macOS.
For more current information, visit: Mac Java!
It's simple to turn your Java Swing program (.jar) into a proper macOS application with a native installer. The instructions below step you through the process from scratch with a sample program called "Show Time", which simply displays the current time. Once you have successfully completed the tutorial with the sample Java program, modify the steps to work for your Java program.

show-time-installer.pkg
This step-by-step tutorial is appropriate for beginner level developers.
(For the truly impatient, you can even run through the whole
tutorial in 30 seconds
)
1) Install Java SE Development Kit
Download and run the latest JDK installer for macOS:
https://jdk.java.net2) Launch Unix terminal
Using Finder go into "Applications" and then open the "Utilities" folder. Open Terminal and you're now at the Unix prompt.
Enter the following command to verify Java is installed:
java -version
3) Make project folder
Enter these two commands:
mkdir showtime cd showtime
The first command creates a folder called "showtime", and the second command moves you into the new folder.
4) Write some Java code
Get the sample Java code and take a look at the Swing commands that create a simple window for displaying the current time:
curl --remote-name https://centerkey.com/mac/java/ShowTime.java cat ShowTime.java
You'll see the code:
import java.util.Date;
import javax.swing.*;
public class ShowTime {
public static void main(String[] args) {
JFrame f = new JFrame();
f.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
f.setTitle("It's Showtime!");
f.getContentPane().add(new JLabel(new Date().toString()));
f.pack();
f.setVisible(true);
}
}
5) Compile Java program
Back at the Unix prompt, compile the Java program into a class file:
javac ShowTime.java ls -l
It is possible to run the class file directly, but that results in a poor user experience. Instead we will create a more convenient executable JAR file.
6) Make executable JAR
Before we make an executable JAR file, we need a manifest file to indicate which class contains the "main" function. Create the file:
echo "Main-Class: ShowTime" > MainClass.txt cat MainClass.txt
The resulting manifest file contains a single line:
Main-Class: ShowTime
Now use the following jar
command to create the "ShowTime.jar" file:
jar cmf MainClass.txt ShowTime.jar *.class ls -l
Test your executable JAR with the following command:
java -jar ShowTime.jar
The "It's Showtime!" window with the current time should display in the upper left corner of your screen. Click the red button (marble) to exit the program.
Note: While the manual commands above for steps #5 and #6 work fine, you could automate them using Ant with a build.xml file.
7) Create installer background and application icon
The default icon for an executable JAR is a coffee cup. To add a custom
icon, we need to create an .icns
file.
Use the following commands to download a sample PNG image, resize the
image to appropriate dimensions for an icon, and convert it into the .icns
format:
curl --remote-name https://centerkey.com/mac/java/ShowTime.png sips -z 100 100 -p 150 150 ShowTime.png --out ShowTime-background.png mkdir ShowTime.iconset sips -z 128 128 ShowTime.png --out ShowTime.iconset/icon_128x128.png iconutil --convert icns ShowTime.iconset ls -lNote:
For this tutorial, just ignore the Missing image for variant
warnings (or
create all the different sizes).
8) Build macOS application and installer
Use the following commands to move the icon file into the package
folder and
run the
javapackager
tool to build the ShowTime.app
appplication and wrap it in into an installer:
mkdir -p package/macosx cp -v *.png *.icns package/macosx jdk=$(/usr/libexec/java_home) $jdk/bin/javapackager -version $jdk/bin/javapackager -deploy -native pkg -name ShowTime \ -BappVersion=1.0.0 -Bicon=package/macosx/ShowTime.icns \ -srcdir . -srcfiles ShowTime.jar -appclass ShowTime \ -outdir out -v cp out/ShowTime-*.pkg show-time-installer.pkg ls -lNote 1:
The javapackager
tool is the way forward while the legacy JarBundler and
AppBundler approaches are now obsolete.
The executable JAR file ShowTime.jar
checks in at a mere 0.001 MB,
but the installer file show-time-installer.pkg
almost hits a whopping
70 MB.
The reason is that the installer bundles the JRE (an Apple requirement for publishing Java
programs to the Mac App Store).
When you are ready to distribute to the public, you'll want to sign your application with a
Developer ID certificate. Use the
productsign
tool to apply a certificate.
9) Try it out
Run the installer:
open show-time-installer.pkg
After completing the installation, go into the "Applications" folder and open the "ShowTime" application. Be sure to check out the "About ShowTime" option on the "ShowTime" menu.
Wrap-Up
If you run into any problems, compare your terminal commands and output to:
Output logFor an example of how you might distribute your installer, take a look at:
Snap BackupThat's it.