AppBundler Task

## AppBundler

### Description

Generates a native launcher for a Java application.

### Parameters

Attribute | Description | Required
outputdirectory | The output folder for the generated bundle. | Yes
name | The name of the application. Corresponds to the `CFBundleName` key in the `Info.plist` file. | Yes
displayname | The display name of the application. Corresponds to the `CFBundleDisplayName` key in the `Info.plist` file. | Yes
identifier | An identifier string that specifies the application type. Corresponds to the `CFBundleIdentifier` key in the `Info.plist` file. | Yes
icon | The icon file for the application. Corresponds to the `CFBundleIconFile` key in the `Info.plist` file. | No
hideDockIcon | Set to true to prevent display of the application icon on the Mac OS X dock. Corresponds to the `LSUIElement` key in the `Info.plist` file. (Details) | No
shortversion | The release version number string for the application. Corresponds to the `CFBundleShortVersionString` key in the `Info.plist` file. | No
signature | The four-letter code identifying the application creator. Corresponds to the `CFBundleSignature` key in the `Info.plist` file. | No
copyright | The copyright notice for the application. Corresponds to the `NSHumanReadableCopyright` key in the `Info.plist` file. | No
applicationCategory | The application category. Corresponds to the `LSApplicationCategoryType` key in the `Info.plist` file. | No
privileged | Bool value if the bundled application is to be launched as privileged. | No
mainclassname | The name of the bundled application's main class. | Yes, alternative to `jnlplaunchername` | Yes
plistClassPaths | A comma-separated list of classpath-elements which are used for the java application. `$APP_ROOT` is replaced by the path of the `.app`-bundle. Required only if not the libraries specified by the `classpath` and `librarypath` should be used. | No
jvmRequired | Specifies the required Java virtual machine version. | No (defaults to `1.7`)
jrePreferred | If set to `true`, a Java Runtime Edition is required for execution. If both `jrePreferred` and `jdkPreferred` are set `true`, then a JRE is preferred but a JDK ia also accepted. | No
jdkPreferred | If set to `true`, a Java Development Kit is required for execution. If both `jrePreferred` and `jdkPreferred` are set `true`, then a JRE is preferred but a JDK ia also accepted. | No
minimumSystemVersion | Indicates the minimum version of OS X required for this app to run. Corresponds to the `LSMinimumSystemVersion` key in the `Info.plist` file. (Details) | No
jnlplaunchername | The name of the bundled applications's jnlp file. The file has to be be copied to the `Contents/Java` folder. It has to be present during execution of the application. This serves as option to deliver signed applications based upon JNLP files. The application can then be signed and the signature won't break when modifying the JNLP file. | No, alternative to `mainclassname`
workingdirectory | Specifies the working directory of the application. `$APP_ROOT` is replaced by the path of the `.app`-bundle. | No
privileged | If set, the application is started with administrator privileges. | No
highResolutionCapable | Sets the High Resolution Capable flag. Corresponds to the `NSHighResolutionCapable` key in the `Info.plist` file. | No
supportsAutomaticGraphicsSwitching | Allow OpenGL applications to utilize the integrated GPU. Corresponds to the `NSSupportsAutomaticGraphicsSwitching` key in the `Info.plist` | No
ignorePSN | If set to `true`, the `-psn...` arguments passed by the OS to the application is filtered out. | No
isDebug | If set to `true`, additiona console output will be produced during startup. | No

### Parameters specified as nested elements

#### runtime

A fileset representing the Java runtime environment to embed in the application.

This element is optional. If specified, the base directory of the fileset must point to the root directory of a valid Java runtime environment. The contents of the runtime will be copied to the `Contents/PlugIns/` folder of the generated application bundle.

By default, only the contents of the `jre/` directory will be included with the bundled application. All executable content (i.e. `bin/`, `jre/bin/`) is excluded. Additional content can be included or excluded using nested `<include>` and `<exclude>` elements, respectively.

If this element is omitted, a Java runtime environment will not be copied into the generated bundle, and target systems must have a shared JRE installed in `/Library/Internet Plug-Ins/JavaAppletPlugin.plugin/` in order to run the application.

#### classpath

A fileset representing the class path of the bundled application. Corresponds to the `java.class.path` system property. Entries will be copied to the `Contents/Java/` folder of the generated bundle.

#### librarypath

A fileset representing the library path of the bundled application. Corresponds to the `java.library.path` system property. Entries will be copied to the `Contents/MacOS/` folder of the generated bundle.

#### option

Specifies a command-line option to be passed to the JVM at startup.

Options may be named, which allows the bundled Java program itself to override the option (e.g. to adjust heap settings). Changes will take effect upon restart of the application. Assuming your `CFBundleIdentifier` (settable via the attribute `identifier`) is `com.oracle.appbundler`. Then you can override a named option by calling

       import java.util.prefs.Preferences;
       [...]
       Preferences jvmOptions = Preferences.userRoot().node("/com/oracle/appbundler/JVMOptions");
       jvmOptions.put("name", "value"); // use option name and desired value here
       jvmOptions.flush();

The corresponding entries will be stored in a file called `~/Library/Preferences/com.oracle.appbundler.plist`. To manipulate the file without Java's `Preferences` from the command line, you should use the tool defaults. For example, to add an entry via the command line, use:

       defaults write com.oracle.appbundler /com/oracle/appbundler/ -dict-add JVMOptions/ '{"name"="value";}'

Of named options, only the value is passed to the JVM, not the name. The name merely serves as identifier.

Attribute | Description | Required
value | The option value. | Yes
name | The option name. | No

#### argument

Specifies a command-line argument to be passed to the bundled application at startup.

Attribute | Description | Required
value | The argument value. | Yes

#### environment

Specifies an environment variable set via LSEnvironment entry in the `Info.plist` file. See the Apple Documentation for details.

The string `$APP_ROOT` will be replaced by the application bundle path in all environment variables on runtime.

Attribute | Description | Required
name | The variable name. | Yes
value | The variable value. | Yes

#### architecture

Specifies the elements of the `LSArchitecturePriority` array in `Info.plist`. (Details)

Attribute | Description | Required
name | The architecture name. | Yes

#### plistentry

Adds an arbitrary entry to the generated `Info.plist`.

Attribute | Description | Required
key | The entry's key. | Yes
value | The entry's value. | Yes
type | The entry's type. | No (defaults to `String`)

#### scheme

Specifies a protocol for which the bundled application should be registered as a handler.

Attribute | Description | Required
value | The protocol scheme. | Yes

#### bundledocument

Describes a document associated with your application.

Attribute | Description | Corresponding `CFBundleDocumentTypes` key | Required
contentTypes | A comma-separated list of Uniform Type Identifiers defining each a supported file type. If you reference custom filetypes, declare them using a typedeclaration. If set, extensions and isPackage are ignored. See the UTI reference for a list of default UTIs. | `LSItemContentTypes` | Yes (or extensions)
extensions | A comma-separated list of filename extensions (minus the leading period) to map to this document type. | `CFBundleTypeExtensions` | Yes (or contentTypes)
icon | The name of the icon file (.icns) to associate with this OS X document type. | `CFBundleTypeIconFile` | No (But recommended)
name | The abstract name for the document type. | `CFBundleTypeName` | No (But recommended)
role | This key specifies the app's role with respect to the type. The value can be `Editor`, `Viewer`, `Shell`, or `None`. | `CFBundleTypeRole` | No (default: `Editor`)
handlerRank | Determines how Launch Services ranks this app among the apps that declare themselves editors or viewers of files of this type. The possible values are: `Owner` (this app is the creator of files of this type), `Alternate` (this app is a secondary viewer of files of this type), `None` (this app must never be used to open files of this type, but it accepts drops of files of this type), `Default` (default; this app doesn't accept drops of files of this type). | `LSHandlerRank` | No
isPackage | Specifies whether the document is distributed as a bundle. If set to true, the bundle directory is treated as a file. | `LSTypeIsPackage` | No (default: `false`)
exportableTypes | A comma-separated list of Uniform Type Identifiers defining a supported file type to which this document can export its content. If you reference custom filetypes, declare them using a typedeclaration. See also the Additional Document Type Considerations of the Document-Based App Programming Guide for Mac. | `NSExportableTypes` | No

#### typedeclaration

Declares a new Uniform Type Identifier. Required if you reference non-system UTIs in bundledocument's contentTypes or exportableTypes

.

Attribute | Description | Corresponding `UT...TypeDeclarations` key | Required
identifier | The unique UTI for the declared type. Following the reverse-DNS format beginning with com.companyName is a simple way to ensure uniqueness. | `UTTypeIdentifier` | Yes
description | A user-visible description of this type. | `UTTypeDescription` | No
icon | The name of the icon file (.icns) to associate with this UTI. | `UTTypeIconFile` | No
referenceUrl | The URL of a reference document describing this type. | `UTTypeReferenceURL` | No
conformsTo | A comma-separated list of UTIs to which this identifier conforms. Although a custom UTI can conform to any UTI, `public.data` or `com.apple.package` must be at the root of the conformance hierarchy. | `UTTypeConformsTo` | No (defaults to `public.data`)
extensions | A comma-separated list of filename extensions (minus the leading period) to map to this UTI. | `UTTypeTagSpecification -> public.filename-extension` | No (but recommended)
mimeTypes | A comma-separated list of mime types which identify this UTI. | `UTTypeTagSpecification -> public.mime-type` | No
osTypes | Comma-separated list of four-character codes formerly used to identify types. Only specify OSTypes if you really know what you're doing. | `UTTypeTagSpecification -> com.apple.ostype` | No
imported | If set to `true`, the declaration is listed under the `UTImportedTypeDeclarations` key. Otherwise, it is listed under `UTExportedTypeDeclarations`. If your code relies on third-party UTI types that may not be present on the system, you should declare those UTIs as imported types. | - | No

### Examples

Generate a launcher for the "Swing Set" demo, bundling the JRE defined by the `JAVA_HOME` environment variable with the resulting executable.

    <-- Import environment variables -->
    <property environment="env"/>

    <-- Define the appbundler task -->
    <taskdef name="bundleapp" classname="com.oracle.appbundler.AppBundlerTask"/>

    <-- Create the app bundle -->
    <target name="bundle-swingset" depends="package">
        <bundleapp outputdirectory="."
            name="SwingSet2"
            displayname="SwingSet 2"
            identifier="com.oracle.javax.swing.SwingSet2"
            shortversion="1.0"
            applicationCategory="public.app-category.developer-tools"
            mainclassname="SwingSet2">
            <runtime dir="${env.JAVA_HOME}"/>
            <classpath file="/Library/Java/Demos/JFC/SwingSet2/SwingSet2.jar"/>
            <option value="-Dapple.laf.useScreenMenuBar=true"/>
            <scheme value="mailto"/>
        </bundleapp>
    </target>

### Example 2: JNLP Launcher

Generate a launcher for a JNLP File, copy it into the package and sign the package. You need to have a Developer ID Profile to sign the application.

You can now dynamically modify the zip content (only the JNLP file), deliver it with your web service and the application should directly unpack and can be run

    <-- Define the appbundler task -->
    <taskdef name="bundleapp" classname="com.oracle.appbundler.AppBundlerTask"/>

    <-- Create the app bundle -->
    <target name="bundle-swingset" depends="package">

        <mkdir dir="./app">

        <bundleapp outputdirectory="./app"
            name="SwingSet2"
            displayname="SwingSet 2"
            identifier="com.oracle.javax.swing.SwingSet2"
            shortversion="1.0"
            icon="icon.icns"
            applicationCategory="public.app-category.developer-tools"
            jnlplaunchername="Contents/_CodeSignature/SwingSet2.jnlp">

            <value="-Xdock:icon=Contents/Resources/icon.icns" />
            <option value="-Dapple.laf.useScreenMenuBar=true"/>
        </bundleapp>

        <!-- Optionally copy an original file -->
        <copy todir="./SwingSet2.app/Contents/_CodeSignature" includeemptydirs="true" overwrite="false">
            <fileset dir=".">
                <include name="**/*.jnlp" />
            </fileset>
        </copy>

        <!-- Sign File -->
        <exec executable="codesign" os="Mac OS X" failonerror="true">
            <arg value="-f" />
            <arg value="--deep" />
            <arg value="-s" />
            <arg value="Developer ID Application" />
            <arg value="./app/SwingSet2.app" />
        </exec>

        <zip destfile="./SwingSet2.app.zip" basedir="${copyroot}/app"></zip>
    </target>