frenchy64 / hn

Example app that implements simple Hacker News reader

Cljfx-based Hacker News reader app

This is an example of a desktop application that can be built on top of cljfx/java stack. It uses:

• cljfx for UI and behavior;
• cljfx/css for styling;
• jpackage for packaging.

You can download the latest release here.

Context

Previously packaging java-based apps for distribution was one of the pain points compared to web: one had to strip down the JDK and figure out how to pack it with uberjar for every platform themselves. JDK 14 introduces a new tool called jpackage (part of JDK distribution) that does all this work. Now the year of Clojure on the desktop is finally right around the corner, all you need is this small example to get started.

What is intentionally left out

The purpose of this example application is to show packaging capabilities of cljfx and jpackage, to keep it simple some build steps where left out:

• startup time can be improved significantly by AOT-compiling clojure code;
• application package size can be reduced: you can use jlink to minify the JDK, and if your application does not need to use webkit (which is used in this example), you can exclude cljfx's dependency on javafx-web.

Walk-through

The code is pretty simple: hn.core is a main namespace that starts an app in its -main function. Note that it uses (Platform/setImplicitExit true) so closing the window will stop JavaFX application thread. This, together with custom daemon executor for agents, will allow to gracefully exit the app just by closing the app window.

The build process is 2-step:

1. Assemble an uberjar. Here it's done using Sean Corfield's depstar library with clj -A:uberjar alias.
2. Use jpackage with common options described in jpackage/common and platform-specific options having their own files: jpackage/linux, jpackage/mac and jpackage/windows. For example, if you are on Linux, you just need to execute jpackage @jpackage/common @jpackage/linux.

Cross-compiling is not supported by jpackage, so you will need access to all 3 OSes to assemble desktop packages. This repo has an example GitHub Actions workflow to create all 3 desktop packages: .github/workflows/build-release-artifacts.yml. To trigger it, simply push a tag with a semantic version number v[major].[minor].[patch] like v1.2.3. Note that:

• major version must be non-zero (for DMG packages)
• minor version must be present (Windows seems to need this)

Also note that JavaFX has platform-specific native libraries for every platform, which means uberjar needs to be assembled separately for every platform.