Documentation Contents
Java Platform, Standard Edition Deployment Guide
Contents Previous Next

# 8 Packaging for Distribution on a Mac

This page describes how to convert a simple Java application to a version you can distribute on a Mac.

To follow along, download the ButtonDemo (.zip) example from the Java Tutorial. This example was created using the NetBeans IDE, which uses the Ant utility. You can run all necessary tools and make all necessary edits from the command line, without launching the IDE. The Ant tool is required.

Packaging for a Mac requires the following steps:

## 8.1 Create a JAR File

This step creates the ButtonDemo.jar file.

Execute ant JAR in the high-level project directory to create the `dist/ButtonDemo.jar` file. This JAR file is used to create the .app package.

## 8.2 Bundle the JAR File into an App Package

To create the `ButtonDemo.app` package, use the `appbundler` tool. The `appbundler` is not shipped with the 7u6 version of the Oracle JDK for the Mac. You can download it from the Java Application Bundler project on `java.net`. AppBundler Documentation is also available.

As of this writing, the most recent version is `appbundler-1.0.jar`, which is used by this document. Download the latest version available and substitute the file name accordingly.

1. Install the `appbundler-1.0.jar` file. In this case, create a lib directory in the high-level project directory and add the `appbundler-1.0.jar` file.

2. Modify the `build.xml` file in the high-level project directory as shown in the following example.

       <?xml version="1.0" encoding="UTF-8"?>
       <project name="ButtonDemo" default="default" basedir=".">
       <import file="nbproject/build-impl.xml"/>

        <taskdef name="bundleapp"
        classname="com.oracle.appbundler.AppBundlerTask"
       classpath="lib/appbundler-1.0.jar" />

        <target name="bundle-buttonDemo">
        <bundleapp outputdirectory="dist"
        name="ButtonDemo"
        displayname="Button Demo"
        identifier="components.ButtonDemo"
        mainclassname="components.ButtonDemo">
        <classpath file="dist/ButtonDemo.jar" />
        </bundleapp>
        </target>

       </project>

3. Invoke the `appbundler` by typing `ant bundle-buttonDemo` from the high-level project directory. This creates the `ButtonDemo.app` package in the `dist` directory.

4. You should now be able to launch the application by double clicking `ButtonDemo.app` in the Finder, or by typing `open ButtonDemo.app` at the command line.

## 8.3 Bundle the JRE with the App Package

To distribute a Java application, you want to avoid dependencies on third party software. Your app package should include the Java Runtime Environment, or JRE. In fact, the Apple Store requires the use of an embedded JRE as a prerequisite for Mac App Store distribution. The runtime sub-element of the `<bundleapp>` task specifies the root of the JRE that will be included in the app package.

In this example, the location of the JRE is defined using the `JAVA_HOME` environment variable. However, you might choose to bundle a JRE that is not the same as the one you are using for development. For example, you might be developing on 7u60, but you need to bundle the app with 7u51. You will define runtime accordingly.

Since this example defines the runtime sub-element using `JAVA_HOME`, make sure it is configured correctly for your environment. For example, in your `.bashrc` file, define `JAVA_HOME` as shown in the following statement:

    export JAVA_HOME=`/usr/libexec/java_home`

Use the following steps to modify the build.xml file at the top of the project directory:

1. Specify an environment property, named `env`:

       <property environment="env" />

2. In the target that creates the bundle, specify the location of the JRE on your system, using the `env` property:

       <runtime dir="${env.JAVA_HOME}" />

The resulting `build.xml` file should look like the following example.

    <?xml version="1.0" encoding="UTF-8"?>
    <project name="ButtonDemo" default="default" basedir=".">
     <import file="nbproject/build-impl.xml"/>

    <property environment="env" />

    <taskdef name="bundleapp"
     classname="com.oracle.appbundler.AppBundlerTask"
     classpath="lib/appbundler-1.0ea.jar" />

    <target name="bundle-buttonDemo">
     <bundleapp outputdirectory="dist"
     name="ButtonDemo"
     displayname="Button Demo"
     identifier="components.ButtonDemo"
     mainclassname="components.ButtonDemo">
     <runtime dir="${env.JAVA_HOME}" />
     <classpath file="dist/ButtonDemo.jar" />
     </bundleapp>
    </target>

    </project>

Create a fresh version of `ButtonDemo.app`, using the ant `bundle-buttonDemo` command. The resulting version includes the JRE in the app package. You can confirm this by examining the `Contents/PlugIns` directory inside of the app package.

## 8.4 Sign the App

The Gatekeeper feature, introduced in Mountain Lion (OS X 10.8), allows users to set the level of security for downloaded applications. By default, Gatekeeper is set to allow only OS X App Store and Developer ID signed applications. Unless your app is signed with a Developer ID certificate provided by Apple, your application will not launch on a system with Gatekeeper's default settings.

For information on the signing certificates available, see Code Signing Tasks on developer.apple.com.

The signing certificate contains a field called Common Name. Use the string from the Common Name field to sign your application.

Sign your app using the `codesign(1)` tool, as shown in the following example:

    % codesign -s "Developer ID Application: CommonNameFromCertificate" ExampleApp.app

To verify that the app is signed, the following command provides information about the signing status of the app:

    % codesign -d --verbose=4 ExampleApp.app

To check if an application can be launched when Gatekeeper is enabled, use the `spctl` command:

    % spctl --assess --verbose=4 --type execute ExampleApp.app

If you leave off the `--verbose` tag, and it does not print any output, indicates 'success'.

For more information, see Distributing Outside the Mac App Store on developer.apple.com.

## 8.5 Submitting an App to the Mac App Store

Packaging an app for the Mac App Store is similar to packaging for regular distribution up until the step of signing the app. Signing the app for the Mac App Store requires a few more steps, and a different kind of certificate.

You will need to create an application ID and then obtain a distribution certificate for that application ID. Submit your app using Application Loader. For more information, see the following links on developer.apple.com:

- Submitting to the Mac App Store

- Submit Your Application Using Application Loader

Contents Previous Next

Copyright © 1993, 2014, Oracle and/or its affiliates. All rights reserved.
Contact Us