Home

Awesome

Java + Maven + GitHub Actions = Native Desktop Apps

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

Goals

  1. Build nice, small cross-platform JavaFX or Swing desktop apps with native installers!
  2. Just use Maven - no shell scripts required!
  3. Use standard Maven dependency system to manage dependencies.
  4. Generate MacOS (.dmg), Windows (.msi) and Unix (e.g. deb/rpm) installers/packages in the cloud with GitHub Actions.

Out of the box, this template generates "Hello World" installers - 30-40mb .dmg, .msi and .deb files. Check out the example builds in releases.

If you are on MacOS, you notice the MacOS builds are not signed. Current versions of MacOS will report installers downloaded via browsers as damaged/unopenable. You can clear this flag via the command-line. As this is not a reasonable solution for end users, a GitHub Action is included to notarize, sign, and staple MacOS installers, but the secrets aren't set up for this repository by default. You will need an Apple Developer account to get this working. More information on MacOS signing.

Overview

This template uses a Maven plugin to generate a custom JVM and installer package for a JavaFX application. It can easily be adapted to work with Swing instead.

Check out the announcements and recent updates.

Requirements

Installation

If you are on Windows, you will need to install Java, Maven, and Wix manually.

If you are on MacOS or Linux, you can use SDKMAN! to simplify installing Java and Maven. Once SDKMAN! is installed, you can run the following to install Liberica or Azul Zulu and Maven.

sdk install java 18.0.2.fx-librca
# or
sdk install java 18.0.2.fx-zulu
sdk current java
sdk install maven

Installation Verification

  1. Verify that Java is installed by opening a fresh Terminal/Command Prompt and enter java --version. As of this writing, the Java version should be 18.0.2 or later.
  2. Verify that Maven is installed with mvn --version. Maven should be version 3.8.6 or later.
  3. Install platform-specific tools.
    1. MacOS only: Verify that XCode is installed & license accepted by a) launching it and b) running sudo xcodebuild -license.
    2. Windows only: Install Wix 3 binaries.
  4. Clone/download this project.
  5. Run mvn clean install from the root of the project to generate the target\TestApp.dmg or target\TestApp.msi installers.
    • The 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.

On MacOS you should add signing to avoid error messages related to the security system(s).

To [re]generate an installer, run...

mvn clean install

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

mvn clean package

To generate reports, include to check if you are using the current version[s] of your dependencies, run...

mvn site

...and open target/site/index.html to see the generated reports.

Key Features

Here are few cool things in this template:

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

Version Numbering

Usually you want a "marketing version" of an app as released to customers, and a "developer version" for use in internal testing. For example, to the end user it's just "Windows 11" but there are countless build numbers for all the different versions of Windows 11.

The end-user value is set in the pom.xml as app.version. This value is updated to use a GitHub environment variable when the installers are run on GitHub.

If you look in the src/main/resources you will see a version.txt file. This file has information in it that will be useful for creating a developer build UI. You might want to convert this to a properties file or a JSON file and display the information in your about UI.

Most projects will want to set up a coherent versioning strategy to manage both the user visible and development build version numbers. This is usually project specific.

Does this work with Apple Silicon aka M1/M2?

Yes, although as of this writing I don't believe there are GitHub Action runners that support M1. But building locally on my M1/M2 systems works great and generates native Apple Silicon builds.

Does this support macOS signing, notarization, and stapling?

Yes, there is a GitHub Action and a Maven profile to assist with setting all of this up for macOS applications.

For more information, see the documentation on getting MacOS signing/notarization/stapling set up.

To get this working, you will need to:

  1. You need to sign up for an Apple Developer account.
  2. Add four GitHub Secrets based on information from Apple.
  3. Update the build all installer GitHub Action yaml
  4. Update the pom.xml.

What about Linux?

The JavaFX builds include several other architectures, including aarch64 and arm32. In theory, you should be able to add those just like the other builds. Haven't tested it though, as I only use Linux for server-side stuff. Feel free to post in the discussion section and also check the Q&A if you are using Linux.

Can I Use this with Swing instead of JavaFX?

tl;dr absolutely.

Just delete the JavaFX stuff, including the JavaFX modules declarations in pom.xml and add a Swing main class instead. If you are reasonably familiar with Maven this shouldn't be very hard to do.

I highly recommend the FlatLaf as a must for working with Swing in 2022. That look-and-feel plus designers such as the IntelliJ GUI Designer or JFormDesigner can work very well, arguably with an easier learning curve than JavaFX.

Suggested changes to the pom.xml for Swing:

  1. Remove the javafx modules from the jvm.modules property
  2. Remove the javafx.version property.
  3. Remove the three org.openjfx dependencies
  4. Remove the configuration/excludeGroupIds section from the maven-dependency-plugin
  5. Remove javafx-maven-plugin from the plugins list
  6. Remove the modulePath delcaration from the jtoolprovider-plugin execution/configuration

Debugging

  1. If the built app fails to run, make sure the JavaFX app runs as expected first by using the mvn javafx:run command. This will run the app in development mode locally, and you should see standard System.out debug lines appear in your console.
  2. Check the Maven build logs (of course).
  3. By default, the app will generate debug*****.log files containing the output from System.out. You can look at the main method of BaseApplication.java to see how this is done. For a production app, you would want to place these logs in the correct OS specific location. On a Unix machine you can tail -f the log normally.

Help

Problems? Make sure everything is installed and working right!

If you need consulting support, feel free to reach out at ChangeNode.com. I've helped several companies with Swing and JavaFX clean up/modernize their old apps to include updated look & feels, add MacOS sign/staple/notarization, or even in a few cases helped port the app to Spring Boot.

Q&A

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