2 Self-Contained Application Packaging

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 the following example.

<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. You can request specific formats using the -native option with the -deploy command. See the javapackager command reference in Java Platform, Standard Edition Tools Reference.

Example 2-1 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"

The packaging tools use several built-in resources to produce a package, such as the application icon or configuration files. One way to customize the resulting package is to substitute a built-in resource with your customized version.

The following actions are needed:

• Prepare Custom Resources

• Substitute a Built-In Resource

Creating and customizing the basic form of self-contained application packages is a fairly straightforward process, but note the following points:

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

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>

Create installable packages for self-contained applications based on the target operating system and the packaging tools available.

To generate an EXE package, you must have Inno Setup 5 or later installed and available on the PATH. To validate that it is available, try running iscc.exe from the command line where you launch the build or from your build script.

By default, the generated package has the following characteristics:

• Admin privileges not required

• Optimized to have a minimum number of dialogs

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

• Launches the application at the end of installation

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

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

Description of "Figure 2-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 can be different from the application icon.

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

• For JavaFX applications, the icon can be added to the application stage to ensure that the icon is set in the runtime.

• The resulting .exe package can be signed.

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

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

The techniques for adding a custom image and providing a Windows script file are described in Customizing the Package Using Drop-In Resources. To add an icon to the application stage in a JavaFX application, see Platform-Specific Customization for Basic Packages.

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.

To use a fixed Product code or add a custom UI to the MSI package, customize the WiX template file used by Java Packager as described in Customizing the Package Using Drop-In Resources. For a custom UI, also see WiX documentation.

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.

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

Figure 2-3 Example of Default Installer for macOS

Description of "Figure 2-3 Example of Default Installer for macOS"

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. See Customizing the Package Using Drop-In Resources.

Figure 2-4 Example of Customized Appearance of Installable Package for macOS

Description of "Figure 2-4 Example of Customized Appearance of Installable Package for macOS"

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 use the script for such actions as adding localization files to the package. Figure 2-4 shows an example of a "tuned" application installer.

To create a Gatekeeper-friendly package, 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 2-4.

To sign the application manually, you can use a technique described in macOS 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 the following example.

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 Customizing the Package Using Drop-In Resources.

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

Producing install packages for Linux assumes that the native tools needed to build install packages are installed. For RPM packages, this typically means the RPMBuild package and its dependencies. For DEB packages, dpkg-deb and dependencies are needed.

No admin permissions are needed to build the package.

By default the resulting package has the following characteristics:

• Installs the application to the /opt directory

• Adds a shortcut to the application menu

• Does not have any UI for installation, which is normal behavior for Linux packages

Customization tips:

• 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 Customizing the Package Using Drop-In Resources..

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