A Brief Example Using the Early Access jpackage Utility

A Brief Example Using the Early Access jpackage Utility
by Jim Connors - 4 March 2019

JEP-343 (Java Enhancement Proposal 343) specifies the introduction and formal inclusion of an application packaging utility called jpackage into a future JDK. Based on an earlier version of the JavaFX javapackager program, the goal of this tool is to provide native packaging options for Java applications on Windows, MacOS and Linux. From an end-user perspective, once Java applications have been packaged up with jpackage, installation experience should be no different than installing any other native app. An early access, (and admittedly incomplete) build of OpenJDK 13 is now available for those who wish to experiment with this new feature.

As examples of this new utility are currently in scant supply, the video that follows walks through the process of taking a sample Java application and creating a native installer on MacOS for that program.

In a few short steps, the application source code is pulled from GitHub, built and packaged. For those that wish to duplicate this demonstration, they can do so with the following prerequisites:

Have a version of JDK 11 or later (either Oracle JDK or OpenJDK) installed and situated in your PATH such that it will be the first Java version found.
If not already available, download and install Apache Maven and have it placed in your PATH also
Likewise, if not already installed, download and install git and have it in your PATH too
Download and install an early access version of OpenJDK that includes the jpackage utility. You can find a version here. Note, you currently must have both Java versions available. You cannot attempt to take the jpacakage utility from the EA version of OpenJDK 13 and move it into JDK 11. It won’t work.

Assuming your environment is set up correctly, there's only a few steps needed to get to the point of creating an application image, via jpackage, for our sample application:

git clone https://github.com/jtconnors/SocketClientFX.git
cd SocketClientFX
mvn package
sh/link.sh -e (on MacOS) or powershell ps1\link.ps1 -e(on Windows) - this creates a runtime image via the jlink utility in the image/ directory.

With this done you can run either version of the script below which invokes jpackage to create a native application installer:

MacOS: sh/create-appimage.sh -e
Windows: powershell ps1\create-appimage.ps1 -e

Here's what a sample jpackage incantation on MacOS looks like:

/Users/jtconnor/Downloads/jdk-13.jdk/Contents/Home/bin/jpackage create-image --runtime-image image --input target --output appimage --name SocketClientFX --main-jar SocketClientFX-11.0.jar

Lets take a look at each individual component of the command:

/Users/jtconnor/Downloads/jdk-13.jdk/Contents/Home/bin/jpackage - The jpackage utility is not part of the latest (JDK 11) distribution. Currently an early access version of Open JDK 13 is available which contains this utility. So we need this version of Open JDK just to run jpackage. Note: if attempting to recreate this demonstration, you may need to edit the sh/env.sh or ps1/env.ps1 file and change the value of the JPACKAGE_HOME variable. It is, by default, set to reside under user's Downloads directory.
create-image - one of three different modes that must be supplied on the command-line (create-image, create-installer or create-jre-installer), create-image instructs jpackage to create a platform-specific application image for our program.
--runtime-image image - directory containing the jlink'ed runtime image created by the sh/link.sh script.
--input target - this points to the directory containing the modules(s) comprising this application. As this application is built by Apache maven, that directory is, by default, target/.
--output appimage - this is the directory under which the generated application image will be placed.
--name SocketClientFX - this is what the application image will be named.
--main-jar SocketClientFX-11.0.jar - this is the main jar file containing the main class. It is located inside the directory specified by the --input option (in this case target/).

When complete, the single appimage/ directory contains the platform-specifc application directory. In the video, the MacOS-genertated appimage/ directory has a SocketClientFX.app icon which is in reality a directory with multiple subdirectories. To the MacOS finder application though, it looks like a properly formatted application and by simply dragging the SocketClientFX.app icon to the Applications folder, the SocketClientFX application is formally installed.

For the final step, you can convert the application image into a proper platform-specific installer using the jpackage create-installer directive. The SocketClientFX project contains the following scripts which aid in the creation of installers:

sh/create-dmg-installer.sh - creates a native MacOS dmg installer of this application using JEP-343 jpackage tool
ps1\create-exe-installer.ps1 - creates a native Windows EXE installer of this application using JEP-343 jpackage tool
ps1\create-msi-installer.ps1 - creates a native Windows MSI installer of this application using JEP-343 jpackage tool

As an example invocation on Windows, issuing

powershell ps1\create-exe-installer.ps1 -e

would have a jpackage command-line which looks something like this:

~\Downloads\jdk-13\bin\jpackage.exe create-installer --installer-type exe --output "installer" --app-image "appimage/SocketClientFX" --name "SocketClientFX"

Please note, to create either an EXE or MSI installer on Windows does require third party applications (like, for example Inno or WiX toolkit respectively) to be installed and available on your command-line PATH.

Conclusion
This article barely scratches the surface of the proposed jpackage tool. For example, there are literally dozens of additional command options to provide image and installation customizations. But it does at least provide one working example, which at this point is a bit of a rarity. Expect more information to become available the this technology matures.