Brief Example Using the Early Access jpackage Utility

DZone 's Guide to

Brief Example Using the Early Access jpackage Utility

The new, early access jpackage utility build is here!

· Java Zone ·
Free Resource

JEP-343 (Java Enhancement Proposal 343) specifies the introduction and formal inclusion of an application packaging utility called jpackageinto 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 withjpackage, the 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.

Check out the video below:

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:

  1. Have a version of JDK 11 or later (either Oracle JDK or OpenJDK) installed and situated in your PATH so that it will be the first Java version found.
  2. If not already available, download and install Apache Maven and have it placed in your PATH also
  3. Likewise, if not already installed, download and install git and have it in your PATH too
  4. 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 are only a few steps needed to get to the point of creating an application image via jpackage, for example:

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) 

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

Let's 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 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 the 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-specific application directory. In the video, the MacOS-generated 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 that looks something like this: 

 /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

Please note: creating either an EXE or MSI installer on Windows requires the availability of third-party applications (like, for example, Inno or Wix, respectively) installed and available on your command-line PATH.


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.

Stay tuned as more information becomes available as this technology matures.

JEP-343, build, command line, early access, java, jdk 13, jpackage, jpackage tool, openjdk 13, shell

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}