Going Pro #1

Making a Double-Clickable .jar File

CS 2530
Intermediate Computing


Some of you have written Java programs of which you are quite proud, such as your Pousse games. The program makes for an enjoyable conversation piece. Whenever we create things, it is natuarl to want to share our handiwork with your friends, family, neighbors, and potential employers.

But many of those folks won't want to start your program from a Unix command line or from Dr. Java, or even know how. You would like to give them your program as an application like any other on their desktops.

How you can you make a double-clickable application from your Java program?

Many industry-grade development environments include tools for creating double-clickable apps. For example, the developer tools in Mac OS X enable a programmer to create apps, design custom icons, and write all sorts of scripts for interacting with the OS. Unfortunately, the IDEs you are mostly likely to know at this point, such as Dr. Java, do not. Nor do vim or emacs.

Many of these professional tools are quite complex. Learning them just for the sake of creating a double-clickable app seems too expensive for the pay-off.

Therefore, use the Java Development Kit's jar tool to create a double-clickable Java archive file.

The jar tool packages all of the files needed to run a Java program into a single archive file, which you can then give to another person or offer as a for download on the web. Most important among these are the compiled Java files needed to run our program.

A .jar file also contains a manifest file that acts like a "read me" file for package to the Java virtual machine can read. When we run the jar tool, it automatically creates a manifest file for the archive.

Unfortunately, the default manifest file created by jar does not include an essential piece of information: the name of the class file that contains the main() method to be executed when we run the program. This information is what enables users to double-click on the file's icon and run it like a standalone application. So we have to be sure to add that information to the manifest files we generate.

Step-by-Step Instructions

Let's create a double-clickable jar file for our Pousse.

  1. Create a manifest file for your application.

    You can download this template manifest file and edit it, changing the string NAME-OF-CLASS-FILE-CONTAINING-MAIN to the name of the class file that contains your main() method.

    For me, that is PlayPousse, so I changed the file to read:

                 Manifest-Version: 1.0
                 Created-By: 1.4.1
                 Main-Class: PlayPousse

  2. Place this file in the directory that contains your *.class files.

    I placed manifest.mf in my directory named pousse/.

  3. Change into the directory containing your *.class files and manifest.mf.

    This requires that you open a Unix shell, or perhaps your Windows command shell, then change into the correct directory. For example,

                 cd pousse/

  4. Use jar to create your archive.

    The command you need is:

                 jar cfm jarFileName manifest.mf *.class

    where jarFileName is what you want to call your archive. To create my archive, I entered:

                 jar cfm pousse.jar manifest.mf *.class

  5. Move your jar file to whatever location you desire.

    I moved mine to the ~cs2530/resources/double-clickable-jars/ directory, from which you can download it. You can also rename the file something less geek-y, like Pousse.

Voilá! There you have it. Download Pousse, double-click on the file, and watch it go.

Making a Custom Icon

It's also fun to make your own icon for your double-clickable app. The standard "jar file" icon is boring! Developer tools and professional IDEs often provide tools that help us do this. jar does not.

I don't know how to do this in Linux or Windows, or if it is even possible. But in Mac OS X, the process is as simple as replacing the double-clickable file's icon in its Information So I did this:

  1. Play Pousse until I had a board that looked nice.

  2. Took a snapshot of the screen using shift-option-3:

    snapshot of me playing Pousse

  3. Clipped out the colored peg portion of the interface:

    part of a Pousse game board

  4. Pasted that image as the icon in the .jar file's OS X Information window. Now I see this on my desktop:

    the Pousse icon on my desktop

Not too bad. When I double-click on the icon, I am playing a game of Pousse.

You can read more about jar by typing man jar at your Unix prompt, or by visiting the JDK documentation.

Eugene Wallingford ..... wallingf@cs.uni.edu ..... December 6, 2012