Liquid Liquid
Mac
Java

Mac Java!

How to Create a Mac OS X Installer
for a Java Application
(Updated for Mac OS X 10.10 — Yosemite)

This information is for an older version of Mac OS X.
For more current information, visit: Mac Java

It's simple to turn your Java Swing program (.jar) into a proper Mac OS X 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.

This step-by-step tutorial that can be easily completed by a beginner level developer (for the adventurous, you can even run through the whole tutorial in 30 seconds).

Screenshots
↓ 

1) Install latest JDK

Download and run the "Java SE Development Kit" installer for Mac OS X x64:

www.oracle.com/technetwork/java/javase/downloads

2) Launch Unix terminal

Screenshot

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

Screenshot

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

Screenshot

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 http://centerkey.com/mac/java/ShowTime.java
cat ShowTime.java

You'll see the code:

ShowTime.java

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

Screenshot

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

Screenshot

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:

MainClass.txt

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 the 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 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 http://centerkey.com/mac/java/ShowTime.png
mkdir ShowTime.iconset
sips -z 128 128 ShowTime.png --out ShowTime.iconset/icon_128x128.png
iconutil --convert icns ShowTime.iconset
ls -l

8) Build Mac OS X application with installer

The following commands move the icon file into the package folder and then use the javapackager tool to build the ShowTime.app appplication and wrap it in into an installer:

mkdir -p package/macosx
cp ShowTime.icns package/macosx
jdk=$(/usr/libexec/java_home)
$jdk/bin/javapackager -version
$jdk/bin/javapackager -deploy -native dmg \
   -srcfiles ShowTime.jar -appclass ShowTime -name ShowTime \
   -outdir deploy -outfile ShowTime -v
cp deploy/bundles/ShowTime-1.0.dmg show-time-installer.dmg
ls -l
Note 1:

The javapackager tool is the way forward while the legacy JarBundler and AppBundler approaches are now obsolete.

Note 2:

The executable JAR file ShowTime.jar checks in at a mere 0.001 MB, but the installer file show-time-installer.dmg is a whopping 66 MB.  The reason is that it bundles the JRE (an Apple requirement for publishing Java programs to the Mac OS X AppStore).

Note 3:

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

Screenshot

Run the installer:

open show-time-installer.dmg

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

For an example of how you might distribute your installer, take a look at:

Snap Backup

That's it.

Liquid Liquid