A Guide to jpackage in Java 14

1. Overview

In this tutorial, we'll explore the new packaging tool introduced in Java 14, named jpackage.

2. Introduction

jpackage is a command-line tool to create native installers and packages for Java applications.

It's an incubating feature under the jdk.incubator.jpackage module. In other words, the tool's command-line options or application layout aren't yet stable. Once stable, the Java SE Platform or the JDK will include this feature in an LTE release.

3. Why jpackage?

It's standard practice while distributing software to deliver an installable package to the end-user. This package is compatible with the user's native platform and hides the internal dependencies and setup configurations. For example, we use DMG files on macOS and MSI files on Windows.

This allows the distribution, installation, and uninstallation of the applications in a manner that's familiar to our end users.

jpackage allows developers to create such an installable package for their JAR files. The user doesn't have to explicitly copy the JAR file or even install Java to run the application. The installable package takes care of all of this.

4. Packaging Prerequisite

The key prerequisites for using the jpackage command are:

1. The system used for packaging must contain the application to be packaged, a JDK, and software needed by the packaging tool.
2. And, it needs to have the underlying packaging tools used by jpackage:
   • RPM, DEB on Linux: On Red Hat Linux, we need the rpm-build package; on Ubuntu Linux, we need the fakeroot package
   • PKG, DMG on macOS: Xcode command line tools are required when the –mac-sign option is used to request that the package be signed, and when the –icon option is used to customize the DMG image
   • EXE, MSI on Windows: On Windows, we need the third party tool WiX 3.0 or later
3. Finally, the application packages must be built on the target platform. This means to package the application for multiple platforms, we must run the packaging tool on each platform.

5. Package Creation

Let's create a sample package for an application JAR. As mentioned in the above section, the application JAR should be pre-built, and it will be used as an input to the jpackage tool.

For example, we can use the following command to create a package:

jpackage --input target/ \
  --name JPackageDemoApp \
  --main-jar JPackageDemoApp.jar \
  --main-class com.baeldung.java14.jpackagedemoapp.JPackageDemoApp \
  --type dmg \
  --java-options '--enable-preview'

Let's go through each of the options used:

• –input: location of the input jar files(s)
• –name: give a name to the installable package
• –main-jar: JAR file to launch at the start of the application
• –main-class: main class name in the JAR to launch at the start of the application. This is optional if the MANIFEST.MF file in the main JAR contains the main class name.
• –type: what kind of the installer do we want to create? This depends on the base OS on which we're running the jpackage command. On macOS, we can pass package type as DMG or PKG. The tool supports MSI and EXE options on Windows and DEB and RPM options on Linux.
• –java-options: options to pass to the Java runtime

The above command will create the JPackageDemoApp.dmg file for us.

We can then use this file to install the application on the macOS platform. After the installation, we'd be able to use the application just like any other software.

6. Conclusion

In this article, we saw the usage of the jpackage command-line tool introduced in Java 14.