Mac Java! • • • Tutorial: Create a Mac OS X Installer for a Java Application (.jar)

How to Create a Mac OS X Installer for a Java Application (.jar)

With some simple steps you can turn your Java Swing program 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

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

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

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

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

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

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 #4 and #5 above work fine, you can automate them using Ant with this 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 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

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

Steps:

For the "Main Class:", use the "Choose..." button and go to and choose "ShowTime.jar".
Check the "Use Macintosh Menu Bar" option.
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).
Click the "Properties" tab and enter "1.0" into the "Version:" field.
Also enter "1.0" into the "Get-Info String:" filed.
Click the "Create Application..." button.
In the "File:" field, enter "Show Time".
Navigate into the "ItsShowtime" folder.
Use the "New Folder" button to create a folder called "Show Time Mac App".
Click the "Create" button.

Quit "Jar Bundler".

9) Create Mac Installer

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:

On the first screen, select "Single Package Project" and click "OK".
In the "Title:" field enter "Show Time".
Click the "Contents" tab. Then use the "Root:" chooser button to locate the "Show Time Mac App" folder and "Open" it.
On the "Configuration" tab in the "Default Location:" field, enter "/Applications".
Check the flags "Allow Revert to Previous Version" and "Relocatable".
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
Go to the "Project" menu and select "Build...".
In the "Save As:" field, enter "ShowTimeInstaller.pkg".
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

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:

Go to the "Apple" menu () and choose "System Preferences..."
In the "Internet & Networking" section, click "Sharing"
Select the "Personal Web Sharing" service
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

Here's the finished installer you can try out yourself:

ShowTimeInstaller.pkg.zip

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

Snap Backup

If you want to add a "Visit Web Site" button to your application, check out:

Bare Bones Browser Launch for Java

That's it.

Comments or Questions

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

Google
Development Guide
Integration
Java to Mac | 2 | 3
About Box
Installationspaket

Random

"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