liquid liquid
Mac Java
Mac Java!

How to Create a Mac OS X Installer for a Java Application
Mac OS X 10.4 (Tiger)


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


With some simple steps you can turn your Java Swing program (.jar) into a proper Mac application with a native installer.  The instructions below step you through the process from scratch with a sample program called "It's Showtime!"
Screen
Shot Icons
↓ 
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.

1) Install Xcode

Screen Apple's Xcode suite includes development tools you'll need to bundle and package a Java program.  First, download Xcode 2.5 (DMG) and open the downloaded .dmg file.  Now run the "XcodeTools.mpkg" file and complete the Xcode installation.

Before continuing to the next step, it's a good idea to perform a "Software Update..." to make sure your OS files are current.

2) Launch Unix Terminal

Screen Using "Finder" go into "Applications" and then open the "Utilities" folder.  Scroll down to the bottom until you see "Terminal".  Open "Terminal" and you're now at the Unix prompt.

3) Make Project Folder

Screen At the Unix prompt, enter these two commands:
mkdir ItsShowtime
cd ItsShowtime
The first command creates a folder called "ItsShowtime", and the second command moves you into the new folder.

4) Write Some Java Code

Screen Mac OS X comes with a simple but effective text editor called Pico.  Use the following command to create and edit a new Java file:
pico 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 <ctrl-x> to exit Pico.

5) Compile Java Program

Screen Back at the Unix prompt, compile your Java program into a class file:
javac ShowTime.java
ls -la
We could run the class file directly, but a class file is cumbersome.  Instead we will create an executable JAR file.

6) Make Executable JAR

Screen Before we make an executable JAR file, we need a manifest file to indicate which class contains the "main" function.  We'll use Pico again:
pico MainClass.txt
Our manifest file will only have one line:

MainClass.txt

Main-Class: ShowTime

Exit Pico and use the following "jar" command to create the "ShowTime.jar" file:
jar cmf MainClass.txt ShowTime.jar *.class
ls -la
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 dot to exit the program.

While the manual commands for steps #5 and #6 above work fine, you can automate them using Ant with this build.xml file.

7) Create Application Icon

Screen The default icon for an executable JAR is a coffee cup.  To add a custom icon, we need to use the "Icon Composer".

First, download and save (<ctrl-click>) this sample PNG image to the "Desktop":  ShowTime.png

Second, move the file into the "ItsShowtime" folder with the following command:
mv ../Desktop/ShowTime.png .
Third, use "Finder" to navigate into the "Developer:Applications:Utilities" folder and double-click "Icon Composer".

Under the "File" menu, select "Import Image".  Now navigate to the "ItsShowtime" folder (which is in your "Home" folder) and select the "ShowTime.png" file.  For "Import To", choose "Small 32bit data" and click "Open".  Select the default for subsequent prompts.

To make sure your icon will work in all places, repeat the above import step for "Large 32bit data", "Huge 32bit data", and "Thumbnail 32bit data".

Go into the "File" menu again.  Select "Save" and then save as "ShowTime.icns".  Now quit "Icon Composer".

8) Bundle the JAR

Screen Next we'll create a Mac application.  Using "Finder", navigate into the "Developer:Applications:Java Tools" folder and double-click "Jar Bundler".

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. Use the "Choose Icon" button to choose the "Snap Backup.icns" file (you'll need to navigate to the "Users" folder to find the "ItsShowtime" folder).
  4. Click the "Properties" tab and enter "1.0" into the "Version:" field.
  5. Also enter "1.0" into the "Get-Info String:" filed.
  6. Click the "Create Application..." button.
  7. In the "File:" field, enter "Show Time".
  8. Navigate into the "ItsShowtime" folder.
  9. Use the "New Folder" button to create a folder called "Show Time Mac App".
  10. Click the "Create" button.
Quit "Jar Bundler".

9) Create Mac Installer

Screen Next we'll create a Mac installer.  Using "Finder", navigate into the "Developer:Applications:Utilities" folder and double-click "PackageMaker".  (Prior to OS X Panther [10.4], the names of the fields, tabs, and menu items in the steps below are a little different, but they do the same thing).

Steps:
  1. On the first screen, select "Single Package Project" and click "OK".
  2. In the "Title:" field enter "Show Time".
  3. Click the "Contents" tab.  Then use the "Root:" chooser button to locate the "Show Time Mac App" folder and "Open" it.
  4. On the "Configuration" tab in the "Default Location:" field, enter "/Applications".
  5. Check the flags "Allow Revert to Previous Version" and "Relocatable".
  6. On the "Package Version" tab, fill out the fields as follows.
    Identifier:  com.centerkey.showtime
    Get Info String:  Show Time 1.0
    Version:  1.0
  7. Go to the "Project" menu and select "Build...".
  8. In the "Save As:" field, enter "ShowTimeInstaller.pkg".
  9. Navigate into the "ItsShowtime" folder and click the "Save" button.
You'll be given the option to save your installer settings when you quit "PackageMaker".

10) Put Installer on a Web Page

Screen Before putting the installer on the web, we need to zip it up into a single file.  Use "Finder" to navigate to the "ItsShowtime" folder.  Create a zip of "ShowTimeInstaller.pkg" using the archive option on the <ctrl-click> menu.

Back at the Unix prompt in the "Terminal", create a test web page:
pico download.html
The HTML for the test page is:

download.html

<html> <body> Download: <a href="ShowTimeInstaller.pkg.zip"> ShowTimeInstaller.pkg.zip</a> </body> </html>

After saving the web page (.html) file, copy it and the .zip file to your personal web server folder with the command:
cp *.html *.zip ../Sites
Now we need to turn on the Mac's Apache web server.

Steps:
  1. Go to the "Apple" menu (Apple) and choose "System Preferences..."
  2. In the "Internet & Networking" section, click "Sharing"
  3. Select the "Personal Web Sharing" service
  4. Click the "Start" button
When the checkmark appears next to "Personal Web Sharing", the Apache web server is running.

Launch Safari and go to  http://localhost/~you/download.html  where "you" is your user name.  Click the "ShowTimeInstaller.pkg.zip" link and the install should automatically start within a few seconds.

Troubleshooting

If your application does not install and run properly, the first place to look is step 6, 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 8, 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 9, which creates the installer file (.pkg).

Wrap-Up

For an example of how you might distribute your installer, take a look at:
If you want to add a "Visit Website" button to your application, check out:
That's it.

Center Key
liquid liquid