7 Self-Contained Application Packaging

The basic form of a self-contained application package is a single folder on your hard drive, such as the example in Figure 7-1. When any of the packages are installed, the result is a folder with the same content.

Figure 7-1 Example of a Self-Contained Application Package

Description of "Figure 7-1 Example of a Self-Contained Application Package"

The internal structure of a self-contained application folder is platform-specific, and might change in the future. However, the following items apply to all platforms and are not likely to change:

• The application package, as defined in Chapter 5, "Packaging Basics," is included as a folder, preserving the application directory structure.

• A copy of the JRE is included as another folder, and the JRE directory structure is preserved.

Because directory structure is preserved, the application can load external resources using paths relative to the application JAR or java.home system property.

The easiest way to produce a self-contained application is to modify the deployment task. To request the creation of all types of self-contained application packages for the platform on which you are running, add nativeBundles="all" to the <fx:deploy> task, as shown in Example 7-1.

<fx:deploy width="${javafx.run.width}" height="${javafx.run.height}"
           nativeBundles="all"
           outdir="${basedir}/${dist.dir}" outfile="${application.title}">
    <fx:application name="${application.title}" mainClass="${javafx.main.class}"/>
    <fx:resources>
        <fx:fileset dir="${basedir}/${dist.dir}" includes="*.jar"/>
    </fx:resources>
    <fx:info title="${application.title}" vendor="${application.vendor}"/>
</fx:deploy>

You can also specify the exact package format that you want to produce. Use the value image to produce a basic package, exe to request an EXE installer, dmg to request a DMG installer, and so on. For the full list of attribute values, see the nativeBundles attribute in the <fx:deploy> entry in the Ant Task Reference.

You can also produce native packages using the Java Packager tool. Self-contained application packages are built by default when you use the -makeall command. You can request specific formats using the -native option with the -deploy command. See the javapackager command reference for Windows or for Solaris, Linux, or OS X.

Example 7-2 shows the use of the -native option with the -deploy command, used to generate all applicable self-contained application packages for the BrickBreaker application. The -deploy command requires a JAR file as input, so it assumes that dist/BrickBreaker.jar has already been built:

javapackager -deploy -native -outdir packages -outfile BrickBreaker 
    -srcdir dist -srcfiles BrickBreaker.jar -appclass brickbreaker.Main 
    -name "BrickBreaker" -title "BrickBreaker demo"

Many of the existing Java Ant elements are used to customize self-contained application packages. Different sets of parameters are needed for different packages, and the same element might have different roles. Table 7-1 introduces many of the customization options.

• Different icon types are needed for different platforms.

  For example, on Windows, the .ico format is expected, on Linux, the fomat is .png, and on OS X the format is .icns. No icon is embedded into the launcher on Linux, instead the .desktop file references the icon.

• For JavaFX applications, add the icon to the application stage to ensure that the icon is set in the runtime. For example, add the following code to the start() method of your JavaFX application:

  stage.getIcons().add(new
      Image(this.getClass().getResourceAsStream("app.png")));
  

• Sign files in the output folder if you plan to distribute the application.

  For example, on Windows, the launcher executable can be signed using signtool.exe.

// Using javapackager tool
 javapackager ... -Bmac.signing-key-user-name="Jane Appleseed"

// Using Ant tasks
   <fx:deploy>
      //...
<fx:bundleArgument arg="mac.signing-key-user-name" value="Jane Appleseed"/>
      //...
    </fx:deploy>

Arguments can be passed to a self-contained application when the application is started from the command line. You can also define a set of arguments to pass to the application if no arguments are provided. To define default arguments, use the -argument option with the javapackager deploy command or the <fx:argument> element in an Ant task when the application package is created. Arguments entered from the command line override the default arguments. If the application is started from the launcher icon, the default arguments are used.

The installer for a self-contained application can be set up to register file associations for the application. The <fx:association> element is used in an Ant task to identify the files that can be handled by the application. File associations are based on either the file extension or MIME type.

The following example associates the application with files that have the MIME type application/x-vnd.MyAppFile.

<fx:info title="Association example">
  <fx:association mimetype="application/x-vnd.MyAppFile" description="Sample Test Files">
  </fx:association>
</fx:info>

The package for self-contained applications can be built to support a suite of products with more than one entry point. Each entry point can have its own shortcut or icon. The mainClass attribute for the <fx:application> element identifies the primary entry point. Use the <fx:secondaryLauncher> element with the <fx:deploy> task to define each secondary entry point.

The following example defines entry points for the TestSuite application for Windows.

<fx:deploy outdir="test/apps" nativeBundles="image">
    <fx:application name="TestSuite Sample"
                    mainClass="samples.TestSuite"/>

    <fx:info title="Test Suite"/>

    <fx:secondaryLauncher
        mainClass="samples.TestSuite"
        name="Suite Applications"/>
        shortcut="true"/>
 
    <fx:secondaryLauncher name="Editor">
        <fx:bundleArgument arg="icon" value="../resources/editor.ico"/>
    </fx:secondaryLauncher>
 
    <fx:secondaryLauncher name="Spreadsheet">
        <fx:bundleArgument arg="icon" value="../resources/spreadsheet.ico"/>
    </fx:secondaryLauncher>
</fx:deploy>

Figure 7-2 shows a typical dialog box for a self-contained JavaFX application being installed on Windows.

Figure 7-2 Windows Installation Dialog for a Self-Contained JavaFX Application

Description of "Figure 7-2 Windows Installation Dialog for a Self-Contained JavaFX Application"

Customization tips:

• If you chose system-wide installation, then the user needs to have admin permissions, and the application is not launched at the end of installation.

• A click-through license is supported. An .rtf file is required.

• The image shown in the installation dialogs is different from the application icon.

  You can customize the image using the "drop-in technique" described in Section 7.3.3, "Customizing the Package Using Drop-In Resources."

  The current version of Inno Setup assumes the image is a bitmap file with a maximum size of 55x58 pixels.

• For JavaFX applications, add the icon to the application stage to ensure that the icon is set in the runtime. See Section 7.3.5, "Platform-Specific Customization for Basic Packages."

• Sign the resulting .exe package.

  You need to get a certificate from a Trusted Certificate Authority (TSA), then use the Windows signtool.exe utility to sign the code.

• You can fine tune the self-contained application folder before it is wrapped into an .exe file, for example to sign the launcher executable.

  Provide a Windows script file, using the technique described in Section 7.3.3, "Customizing the Package Using Drop-In Resources."

MSI packages are generated using the Windows Installer XML (WiX) toolset (also known as WiX). WiX 3.8 or later is required, and it must be available on the PATH. To validate, try running candle /? from the command line where you launch the build or from your build script.

By default, a generated MSI package has the following characteristics:

• Optimized for deployment using enterprise deployment tools

• Installs to a system-wide location

• No click-through UI, only a progress dialog is shown

• Referenced from the programs menu or a desktop shortcut, or both

• Removes all files in the installation folder, even if they were created outside of the installation process. (WiX 3.5 or later is required.)

• Tries to use the application identifier as UpgradeCode.

  If the application identifier is not a valid GUID, then a random GUID for UpgradeCode is generated.

• Randomly generates ProductCode is randomly.

  To use a fixed Product code, customize the WiX template file using the technique described in Section 7.3.3, "Customizing the Package Using Drop-In Resources."

If you plan to distribute your MSI package on the network, sign it for the best user experience.

You can also fine tune the self-contained application folder before it is wrapped into the .msi file, for example, to sign the launcher executable. For details, see Section 7.4.1, "EXE Package."

To add a custom UI to the MSI package, customize the WiX template file used by Java Packager using the technique described in Section 7.3.3, "Customizing the Package Using Drop-In Resources." Consult WiX documentation for more details.

By default, a DMG package provides a simple drag-and-drop installation experience. Figure 7-3 shows an example of the default behavior during installation.

Figure 7-3 Example of Default Installer for OS X

Description of "Figure 7-3 Example of Default Installer for OS X"

To customize the appearance of the installation window, you can provide a custom background image.

If the background image has different dimensions or you need to position the icons differently, then you must also customize the DMG setup script that is used to modify sizes and positions of elements in the install view. For information on customization, see Section 7.3.3, "Customizing the Package Using Drop-In Resources."

Figure 7-4 Example of Customized Appearance of Installable Package for OS X

Description of "Figure 7-4 Example of Customized Appearance of Installable Package for OS X"

To fine tune the self-contained application folder before it is wrapped, provide your own bash script to be executed after the application folder is populated. You can the script for such actions as adding localization files to the package. Figure 7-4 shows an example of a "tuned" application installer.

To create a Gatekeeper-friendly package (for OS X 10.8 or later, see Section 7.3.5.1, "OS X"), the application in the DMG package must be signed. It is not necessary to sign the DMG file itself. The Mac bundler handles the signing of your application. If your local user information differs from the name of the certificate, you might need to set the bundle argument mac.signing-key-user-name, as shown in Example 7-6.

To sign the application manually, you can use a technique described in Section 7.3.3, "Customizing the Package Using Drop-In Resources" to provide a configuration script that is executed after the application bundle is populated. For the sample DemoApp, the configuration script is located at package/macosx/DemoApp-post-image.sh and has the content shown in Example 7-7.

echo "Signing application bundle"
#Move to the folder containing application bundle
cd ../images/dmg.image
#do sign
codesign -s "Developer ID Application" *.app
echo "Done with signing"

The DMG installer also supports a click-though license provided in text format. If use of rich text format is desired, then prepare the license.plist file externally and add it to the package using the technique described in Section 7.3.3, "Customizing the Package Using Drop-In Resources."

No third party tools are needed to create a DMG package.

• To place the application into a specific category in the application menu, use the category attribute of <fx:info>.

  See Desktop Menu Specification, and your window manager docs for the list of category names.

• The icon is expected to be a .png file

• Advanced customization is possible by tuning the build template files using techniques described in Section 7.3.3, "Customizing the Package Using Drop-In Resources.".

  See the DEB/RPM packaging guides for more information on available options.