JavaFX + Maven = Native Desktop Apps

JavaFX + jpackage + Maven template project for generating native desktop applications.

Goal

1. Build nice, small cross-platform JavaFX-based desktop apps with native installers
   • Apx 30-40mb .dmg, .msi and .deb installers - check out the example builds in releases.
2. Just use Maven - no shell scripts required.
   • Use standard Maven dependency system to manage dependencies
3. Generate macOS (.dmg), Windows (.msi) and Unix (e.g. deb/rpm) installers/packages automatically with GitHub Actions

Overview

This template uses a Maven plugin to generate a custom JVM and installer package for a JavaFX application.

The basic requirements are just Java 16 and Maven. Java 15 will work, although it requires a bit of setup.

• On macOS XCode is required.
• On Windows the free WiX Toolset is required.

The project includes GitHub Actions which automatically generate macOS, Windows, and Linux installers.

The generated installers come in at around 30-40mb. The example source in the project includes demonstrations of several native desktop features - for example, drag-and-drop from the Finder/Explorer, as well as a few macOS Dock integration examples. Removing the code and the demonstration dependendencies gets a "Hello World" build size closer to 30mb than 40mb.

Key Features

Here are few cool things in this template:

• Only uses Java and Maven. No shell scripts required.
• Includes sample GitHub Actions to build macOS, Windows and Linux installers
• Demonstrates setting the application icon
• Builds a .dmg on macOS, .msi on Windows, and .deb on Linux
• Bundles the JavaFX SDK & modules to simplify getting started.
• Template includes several examples of JavaFX / native desktop integration
  • Drag & drop with Finder / Explorer
  • Change the Dock icon dynamically on macOS
  • Menu on the top for macOS, in the window itself on Windows
  • Request user attention (bouncing dock icon) on macOS

Once you get started, you might find these lists of tutorials, tools, libraries for JavaFX and general Java desktop integration helpful.

Usage

Once everything is installed (see below) it's really easy to use:

To generate an installer, just run...

mvn clean install

To do everything up until the actual installer generation (including generating the custom JVM)...

mvn clean package

Installation

1. Install OpenJDK Java 16 or Oracle Java 16.
   • Verify by opening a fresh Terminal/Command Prompt and typing java --version.
2. Install Apache Maven 3.6.3 or later and make sure it's on your path.
   • Verify this by opening a fresh Terminal/Command Prompt and typing mvn --version.
3. macOS: verify XCode is installed and needed agreements accepted.
   • Launch XCode and accept the license, or verify in Terminal with the command sudo xcodebuild -license.
4. Windows: install Wix 3 binaries.
   • Installing Wix via the installer should be sufficient for jpackage to find it.
5. Clone/download this project.
6. Final step: run mvn clean install from the root of the project to generate the target\TestApp.dmg or target\TestApp.msi (installer).
   • Note that the actual generated installer will include a version number in the file name
   • For reference, here is a complete run log for a successful run.

Because these builds use stripped down JVM images, the generated installers are in the 30-40mb range.

Sponsor

This project is sponsored by ChangeNode.com - if you would like to add easy automatic updates, crash reporting, analytics, etc. to your Java/JavaFX desktop application, go check it out... and be sure to subscribe for more information about desktop Java development.

Help

Problems? Make sure everything is installed and working right!

• Compiler not recognizing the --release option? Probably on an old JDK.
• Can't find jdeps? Probably on an old JDK.
• Can't find jpackage? Probably haven't set up your system to allow Java 15 to enable preview packages.
• Unrecognized option: --add-modules jdk.incubator.jpackage
  • Could be a left-over MAVEN_OPTS setting when you switched from Java 15 to Java 16
  • If you are still on Java 15, you may not have MAVEN_OPTS set correctly.

If you need consulting support, feel free to reach out to ChangeNode.com.

Q&A

If you are using the template, browsing the Q&A is highly recommended.