Liquid Liquid
Mac
Java
Mac Java!

How to Create a Mac OS X Installer for a Java Application
(Updated for Mac OS X 10.8 — Mountain Lion)

With some simple steps you can 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.

Screenshot
Icons
↓ 

1) Launch Unix Terminal and Get Java

Screen 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 see if you already have Java installed:
java -version
You will be prompted to download and install Java if needed.

2) Make Project Folder

Screen 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.

3) Write Some Java Code

Screen Mac OS X comes with a simple but effective text editor called Nano.  Use the following command to create and edit a new Java file:
nano ShowTime.java
Enter the following code:

ShowTime.java

import java.util.Calendar; 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( Calendar.getInstance().getTime().toString())); f.pack(); f.setVisible(true); } }
Use <control-x> to exit Nano.

4) Compile Java Program

Screen 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.

5) Make Executable JAR

Screen Before we make an executable JAR file, we need a manifest file to indicate which class contains the "main" function.  Use Nano again:
nano MainClass.txt
The manifest file only needs the single line:

MainClass.txt

Main-Class: ShowTime

Exit Nano and use the following jar command to create the "ShowTime.jar" file:
jar cmf MainClass.txt ShowTime.jar *.class
ls -l
Now 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 #4 and #5 work fine, you could automate them using Ant with this build.xml file.

6) 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.

Download and save (<control-click>) this sample PNG image to your "Desktop":  ShowTime.png

Then use the following commands to move the file into the "showtime" folder, resize the image to appropriate dimensions for an icon, and convert it into the .icns format:
mv ../Desktop/ShowTime.png .
mkdir ShowTime.iconset
sips -z 32 32 ShowTime.png --out ShowTime.iconset/icon_32x32.png
iconutil -c icns ShowTime.iconset
ls -l
Note: Warnings from the iconutil command just indicate that the icon will not display optimally at some sizes.

7) Install Xcode

Screen Apple's Xcode Developer Tools include utilities you'll need to bundle and package a Java application.  Go to the Mac App Store by selecting "App Store..." from the "Apple" menu (Apple).  Search for "xcode" and install the application (free).

7) Bundle the JAR

Screen Bring up Spotlight with the <command-space> keystroke and type "jar bundler" to find and the Jar Bundler application (it's in the "/usr/share/java/Tools" folder).  Launch the application.

Steps:
  1. For the "Main Class:", use the "Choose..." button and go to and choose "ShowTime.jar".
  2. Check the "Use Macintosh Menu Bar" option.
  3. Using Finder, go to the "showtime" folder and drag the "ShowTime.icns" file into the "Custom Icon" box.
  4. Click the "Properties" tab and enter "1.0" into both the "Version:" field and the "Get-Info String:" field.
  5. Click the "Create Application..." button.
  6. Navigate into the "showtime" folder.
  7. In the "File:" field, enter "Show Time".
  8. Click the "Create" button.
  9. Quit Jar Bundler.
We now have a proper Mac application.  Next we'll create an installer for the application.

8) Create Mac Installer

Return to Terminal and use the productbuild tool to create the installer:
productbuild --component "Show Time.app" /Applications show-time-installer-1.0.pkg
ls -l
rm -rf "Show Time.app"
The rm command deletes the original application bundle so that the installer will install into /Applications instead of just overwriting the original version.

Note: 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) Put Installer on a Web Page

Screen Now build a test download page to verify the installer will work correctly:
nano download.html
The HTML for the test page is:

download.html

<html> <body> Download: <a href="show-time-installer-1.0.pkg">show-time-installer-1.0.pkg</a> </body> </html>

Exit the editor and saving the web page file.  Now copy the file and the installer file to the document root folder of the Apache web server and start the web server:
sudo cp *.html *.pkg /Library/WebServer/Documents/
sudo apachectl start
Note: You will be prompted to enter your password when using the sudo command.  If your password is rejected, then you do not have root privileges.  First login as an administrator using:  su - <username>

The Apache web server is now running, and your download page is at:
Click the "show-time-installer-1.0.pkg" link.  Now look in your "Downloads" folder and double-click the installer file.  You will be presented with a "unidentified developer" security error.  Click "Ok" and then control-click the installer file and choose "Open".

After completing the installation, go into the "Applications" folder and run the "Show Time" application.  Be sure to check out the "About Show Time" option on the "Show Time" menu.

Troubleshooting

If your application does not install and run properly, the first place to look is step 5, which creates the JAR file.  Try double-clicking the JAR file to launch your application.  If it fails to launch, you need to fix that before continuing.

The next place to look is step 7, which creates the application file.  Try double-clicking the .app file.  If it fails to launch, you need to fix that before continuing.

Do the same for step 8, which creates the installer file (.pkg).

Wrap-Up

Here's the finished installer you can try out yourself:
For an example of how you might distribute your installer, take a look at:
If you want to add a "Visit Web Site" button to your application, check out:
That's it.

Comments or Questions

Send Us a Message

Powered by PERFECT

All the fields are optional.  However, if you want a response, make sure to provide your e-mail address.

Random

"Great tutorial."   — W.C., October 8, 2009

"Great tutorial!  Many thanks, this is really helpful for a programming assignment in a computer network class I'm taking."   — Z.L., October 6, 2009

"Great tut omg thanks so much!"   — S., October 4, 2009

"I love this tutorial!  Thank you!"   — S.R., March 4, 2009

"Fantastic!!!!!  Thank you very muchhhhh!!  I can start mac programing now.  The tutorial is great!!!"   — F., November 8, 2008

"Incredibly clear to follow, Thanks very much"   — J.G., October 1, 2008

More...
"Très bon tutorial, merci beaucoup"   — K., November 7, 2007

"This is exactly the information I was looking for!!  Great job explaining how to use the Jar Bundler.  I always wondered how to group my files into a single 'app' file."   — J.L.M., July 6, 2007

"Thanks for the tutorial."   — D.W., June 6, 2007

"Great tutorial!  Thank You very much!"   — T., May 19, 2007

"This is a very good developement friendly site"   — A.K., March 18, 2007

"Thankyou, I am very happy to read your content for MacJava.  Thankyou very much"   — A., January 12, 2007

"Very Good!!!!"   — D.A., August 10, 2006

"Great article - I found it very helpful!  Thanks!"   — J.T., August 1, 2006

"Hello, Great information, thank you very much!  Can I translate your article in french?"   — P.T., January 21, 2006

"Great article!"   — D., December 9, 2005

"Thank you so much.  Your instructions are perfectly concise.  There is plenty of information about programming, but not nearly enough about installing and packaging.  This page is a blessing."   — S.B., October 21, 2005

"This is a great info on mac application builder"   — S.S., October 11, 2005

"sweet article!  one of the clearest and simplest ive seen and everything just works!!"   — J.B., September 9, 2005

"Amazing, I would never have thought it was that easy...  You are truely the best!"   — M.F., September 7, 2005

"Couldn't be more clearer!"   — M.H., August 13, 2005

"THX a lot - very helpful and direct to the point"   — T.W., August 9, 2005

"Cool -- you solved the mystery!"   — C.M., June 27, 2005

Liquid Liquid