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.	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>