JavaFX 2 Tutorial - Part 7: Deployment with e(fx)clipse

→ UPDATED VERSION for Java 8 available: JavaFX 8 Tutorial

Update Feb 11th, 2013: New instructions for Deployment on Mac OS. Thank you Eskil for providing me with this information!

Update May 22nd, 2013: Updated step 3 and step 4 for e(fx)clipse plugin version 0.8.1.

Screenshot AddressApp Part 7

I thought I'd write one last part of this tutorial series to show how to deploy (i.e. package and publish) the AddressApp.

Download example AddressApp as

Topics in Part 7

  • Deploying our JavaFX application as Native Package with e(fx)clipse

What is Deployment

Deplyoment is the process of packaging and delivering software to the user. This is a crucial part of software development since it's the first contact a user has with our software.

Java advertises with the slogan Write Once, Run Anywhere to illustrate the cross-platform benefits of the Java language. Ideally, this means that our Java application can be run on any device equipped with a Java virtual machine (JVM).

In the past, the user experience for installing a Java application hasn't always been smooth. If the user didn't have the required Java version on his system, he had to be directed to install it first. This lead to some difficulties, e.g. need for admin rights, compatibility issues between Java versions, etc.

Fortunately, JavaFX 2 provides a new deployment option called Native Packaging (also called Self-Contained Application Package). A native package is a bundle containing both your application code and the (platform-specific) Java Runtime.

The official JavaFX documentation by Oracle contains an extensive guide for all possible JavaFX deployment options.

In this post I will show how to create a Native Package with with Eclipse and the e(fx)clipse plugin. My current e(fx)clipse version is 0.1.1.

Create a Native Package

The goal is to create a self-contained application in a single folder on the user's computer. Here is how it will look like for our AddressApp (on Windows):

AddressApp Native Package

The app folder contains our application data and the runtime folder contains the platform-specific Java runtime.

To make it even more comfortable for the user, we'll provide an installer:

  • A .exe file installer on windows
  • A dmg (drag and drop) installer for MacOS.

The e(fx)clipse plugin will help us generate the native package and installer.

Step 1 - eclipse.ini

Note: Step 1 might not be necessary with e(fx)clipse 0.8.0 and above.

JavaFX uses a tool called Ant to build and package the application. This tool is already included in Eclipse. As Ant depends on the JDK we need to make shure Eclipse itself runs with the JDK (not the JRE).

  1. Close Eclipse.
  2. Find the folder of your Eclipse installation and open the file eclipse.ini in a text editor. This file contains Eclipse startup settings. On Mac OS X, eclipse.ini can be found by right-clicking and selecting "Show package contents". The file is located under Contents/MacOS.
  3. After the line openFile add -vm and then specify your jdk installation directory. The end of the file should now look like this:
C:\Program Files\Java\jdk1.7.0_09\bin\javaw.exe

Mac OS: For Mac OS, path could be something like /Library/Java/JavaVirtualMachines/jdk1.7.0_07.jdk/Contents/Home/bin/java (In my version the javaw.exe does not exist but I specified "java" instead which seemed no problem)

Step 2 - Installer Icons

We would like to have some nice icons for our installer:

  1. Download AddressApp.ico, AddressApp-setup-icon.bmp and AddressApp.icns.
  2. Copy the three icons to the project root of your AddressApp project in Eclipse.

Installer Icons

Step 3 - Edit build.fxbuild

The file build.fxbuild is used by e(fx)clipse to generate a file that will be used by the Ant build tool. If you don't have a build.fxbuild file, create a new Java FX Project in Eclipse and copy the generated file.

  1. Open build.fxbuild from your project root.
  2. Fill out all the fields containing a star. For MacOS: Do not use spaces in Application title as this seems to cause a problem.
  3. As Packaging Format choose exe for Windows, dmg for MacOS, and rpm for Linux.
  4. Click on the link Generate ant build.xml only (found on the right side).
  5. Verify that a new build folder and a file build.xml is created.

Step 4 - Edit build.xml to include icons

E(fx)clipse has generated a file build/build.xml which is ready to be executed by Ant. Our installer icons and resource icons just won't work. If you don't want icons you may skip this step.

As e(fx)clipse can't be told (yet?) to include additional resources like our resources folder and the few installer icons we've added above, we have to manually edit the build.xml:

Open build.xml and find the path fxant. Add one line for the ${basedir} (will make our installer icons available):

<path id="fxant">
    <file name="${java.home}\..\lib\ant-javafx.jar"/>
    <file name="${java.home}\lib\jfxrt.jar"/>
    <file name="${basedir}"/>

Find the following block further down in the file:

<fx:resources id="appRes">
    <fx:fileset dir="dist" includes="AddressApp.jar"/>
    <fx:fileset dir="dist" includes="libs/*"/>

Replace the four lines obove with the following code:

<mkdir dir="dist/resources" />
<copy todir="dist/resources" >
    <fileset dir="../resources" />

<mkdir dir="package" />

<!-- Icons only for Windows -->
<mkdir dir="package/windows" />
<copy todir="package/windows">
    <fileset dir="..">
        <include name="AddressApp.ico" />
        <include name="AddressApp-setup-icon.bmp" />

<!-- Icons only for MacOS -->
<mkdir dir="package/macosx" />
<copy todir="package/macosx">
    <fileset dir="..">
        <include name="AddressApp.icns" />

<fx:resources id="appRes">
    <fx:fileset dir="dist" includes="AddressApp.jar"/>
    <fx:fileset dir="dist" includes="libs/*"/>
    <fx:fileset dir="dist" includes="resources/**"/>

Step 5 (WINDOWS) - Windows exe Installer

AddressApp on Windows

With Inno Setup we can create a Windows Installer of our application as a single .exe file. The resulting .exe will perform a user level installation (no admin permissions required). A shortcut will be created (menu or desktop)

  1. Download Inno Setup 5 or later. Install Inno Setup on your computer. Our Ant script will use it to automatically generate the installer.
  2. Tell Windows about the installation path to Inno Setup (e.g. C:\Program Files (x86)\Inno Setup 5): Add it to the Path variable in your windows environment variables. If you don't know where to find it, read How to set the path and environment variables in Windows.

Step 5 (MAC) - MacOS dmg Installer

AddressApp on Mac

To create a Mac OS dmg drag-and-drop installer, no additional tool is required.

Note: For the installer image to work it must have exactly the same name as the application.

Step 5 (LINUX etc.) - Linux rpm Installer

For other packaging options (msi for windows, rpm for Linux) see this native packaging blog post or this oracle documentation.

Step 6 - Run build.xml

As a final step, we run the build.xml with Ant: Right-click on the build.xml file | Run As | Ant Build.

Run Ant Build

The building will take a while (about 1 minute on my computer).

If everything was successful, you should find the native bundle in the folder build/deploy/bundles:

  • Windows: The file AddressApp-1.0.exe can be used as a single file to install the application. This installer will copy the bundle to C:/Users/[yourname]/AppData/Local/AddressApp.
  • Hint: You could also use the subfolder build/deploy/bundles/AddressApp to deploy the application as a .zip file.

What's Next?

I hope this tutorial was a help for you to get started with JavaFX and you'll be able to write your own JavaFX project from here. I might add some further JavaFX blog posts outside of this tutorial series, we'll see...

I appreciate any feedback. Feel free to write comments if you have any suggestions or if something was unclear.