6.3.1 Self-Contained Application Structure

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

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

The internal structure of a self-contained application folder is platform-specific and may change in future. However, the following points are guaranteed:

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

• A copy of Java Runtime is included as another folder, and the Java Runtime 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.

6.3.2 Basic Build

The easiest way to produce a self-contained application is to modify the deployment task. To request creation of all applicable self-contained application packages simply add nativeBundles="all" to the <fx:deploy> task, as shown in Example 6-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 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.

If you have a JavaFX project in Netbeans 7.2, you can add the above snippet as a post-build step by overriding the "-post-jfx-deploy" target, as shown in Example 6-2. Add the following code to the build.xml file in the main project directory.

<target name="-post-jfx-deploy">
       <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>          
     </target>

You can also produce native packages using the JavaFX Packager tool. self-contained application packages are built by default if you use the -makeall command, or you can request them explicitly using the -native option in the -deploy command. See the javafxpackager command reference.

Example 6-3 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:

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

6.3.3 Customization Using Drop-In Resources

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

For this you need to:

• Know what resources are used

• Drop custom resources into a location where the packaging tool will look for them

The following sections explain how to do this.

Using base JDK at: /Library/Java/JavaVirtualMachines/jdk1.7.0_06.jdk
  Using default package resource [Bundle config file] (add
    package/macosx/Info.plist to the class path to customize)
  Using default package resource [icon] (add package/macosx/DemoApp.icns
      to the class path to customize)
Creating app bundle: /tmp/test/TestPackage/bundles/DemoApp.app
Config files are saved to /var/folders/rd/vg2ywnnx3qj081sc5pn9_
    vqr0000gn/T/build7039970456896502625.fxbundler/macosx. Use them 
    to customize package.

<taskdef resource="com/sun/javafx/tools/ant/antlib.xml"
         uri="javafx:com.sun.javafx.tools.ant"
         classpath=".:path/to/sdk/lib/ant-javafx.jar"/>

Using base JDK at: /Library/Java/JavaVirtualMachines/jdk1.7.0_06.jdk
  Using default package resource [Bundle config file] (add
      package/macosx/Info.plist to the class path to customize)
Using custom package resource [icon] (loaded from
    package/macosx/DemoApp.icns on class path)
Creating app bundle: /tmp/test/TestPackage/bundles/DemoApp.app

6.3.4 Customization Options

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

6.3.5 Platform-Specific Customization for Basic Packages

Creation and customization of 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, and on Mac it is .icns. No icon is embedded into launcher on Linux.

• To ensure that the icon is set in runtime, you also need to add it to the application stage. For example, add the following code to to the start() method of your application:

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

• Consider signing files in output folder if you plan to redistribute them.

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

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

6.4.1 EXE Package

As of JavaFX 2.2, in order 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:

• Does not require admin privileges to install

• Is optimized to have a minimum number of dialogs

• Must be referenced from programs menu or have desktop shortcut (having both are fine)

• Is configured so the application launches at the end of installation

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

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

Customization tips:

• If you chose system-wide installation, then the user will need to have admin permissions, and the application will not be 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 it using the "drop-in technique" described in Section 6.3.3, "Customization Using Drop-In Resources."

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

• To ensure the icon is set in the runtime, make sure to explicitly add it to the stage. See Section 6.3.5, "Platform-Specific Customization for Basic Packages."

• Consider signing the resulting .exe package. If you distribute an unsigned executable, then many versions of Windows will scare the user with an "Unknown Publisher" warning dialog.

  If you sign your package, then this warning will be removed. You will need to get a certificate and then can use the 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.

  To do this, provide a Windows script file, using the technique from Section 6.3.3, "Customization Using Drop-In Resources."

6.4.2 MSI Package

MSI packages are generated using the Windows Installer XML (WiX) toolset (also known as WiX). As of JavaFX 2.2, WiX 3.0 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:

• Is optimized for deployment using enterprise deployment tools

• Installs to a system-wide location

• Does not have any click-through UI. Only a progress dialog is shown.

• Must to be referenced from the programs menu or have a desktop shortcut (having both is fine)

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

• Will try to use the application identifier as UpgradeCode.

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

• ProductCode is randomly generated. To use a fixed Product code, customize the WiX template file using the technique from Section 6.3.3, "Customization Using Drop-In Resources."

If you plan to distribute your MSI package on the network, then consider signing 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 6.4.1, "EXE Package."

To add a custom UI to the MSI package, you can customize WiX template file used by JavaFX Packager using technique from Section 6.3.3, "Customization Using Drop-In Resources.". Consult WiX documentation for more details.

6.4.3 DMG Package

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

Figure 6-3 Example of Default Installer for Mac 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 tweak sizes and positions of elements on the install view. For details about how to do this, see Section 6.3.3, "Customization Using Drop-In Resources."

To fine tune the self-contained application folder before it is wrapped, you can provide your own bash script to be executed after the application folder is populated. You can use it, for example, to enrich it with localization files, and so on. Figure 6-4 shows an example of a "tuned" application installer.

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

To create a Gatekeeper-friendly package (for Mac OS X 10.8 or later, see Section 6.3.5.1, "Mac OS X"), the application in the DMG package must be signed. It is not necessary to sign the DMG file itself. To sign the application, you can use a technique described in Section 6.3.3, "Customization Using Drop-In Resources" to provide a config script to be executed after the application bundle is populated. For sample DemoApp, the config script is located in the package/macosx/DemoApp-post-image.sh and has the content shown in Example 6-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 the text format. If use of rich text format is desired, then prepare the license.plist file externally, then add it to the package using the technique from Section 6.3.3, "Customization Using Drop-In Resources."

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

6.4.4 Linux Packages

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:

• Will install the application to /opt

• Will add a shortcut to the application menu

• Does not have any UI for installation (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>.

  Refer to 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 from Section 6.3.3, "Customization Using Drop-In Resources.".

  Consult the DEB/RPM packaging guides to get more background on available options.