Java 14 - Creating Self-Contained Java Applications With Packaging Tool (JEP 343)
A new tool,
jpackage is added in Java 14 for packaging self-contained Java applications. The idea behind this tool is to streamline the installation (or distribution) on a native platform. Instead of copying jars and configuring the classpath,
jpackage aims to make the distribution of Java applications easier. Java applications should be able to be install or uninstall in similar manner like another native applications in specific platform.
You can check the options for this tool with command:
jpackage --help. Beside generic options, this command also will list down some platform dependent options for creating the application package.
Creating a Package/Installer
In this article we only check some of options, which is the most frequent syntax you'll need for
jpackage to create a package:
jpackage --type <type> --name <name> --input <input path> --main-jar <main jar file> --main-class <class name> --java-options <java options>
Let's run through each options:
-t: the type of package we want to create, each platform (OS) have their own type format. These formats are
dmgon macOS, and
rpmon Linux. Another type valid for all platform is "app-image"
-n: name of the application package
-i: location of the input directory. All files in the directory will be packaged into the application image or installer.
--main-jar: the main JAR of the application that contains the main class (see
--main-class). This jar must be in input folder. Another option similar to this is
--main-class: application main class in the main JAR that will be launch at the start of the application.
--java-options: options for Java runtime
Packaging and Install for Linux
Here an example to run
jpackage in Ubuntu 20.04:
$ jpackage --type deb --name java14-examples --input java14-examples --main-jar java14-examples-1.0.0.jar --main-class com.dariawan.jdk14.JEP343Main --java-options '--enable-preview' WARNING: Using incubator modules: jdk.incubator.jpackage
The input folder java14-examples only have one jar file, java14-examples-1.0.0.jar. As the result,
java14-examples_1.0-1_amd64.deb is created. You can see, that --enable-preview option is specified, since we may run some Java 14 preview feature in our application. Then, we can install it (in Ubuntu) using command:
$ sudo apt install ./java14-examples_1.0-1_amd64.deb Reading package lists... Done Building dependency tree Reading state information... Done Note, selecting 'java14-examples' instead of './java14-examples_1.0-1_amd64.deb' The following NEW packages will be installed: java14-examples 0 upgraded, 1 newly installed, 0 to remove and 0 not upgraded. Need to get 0 B/36.6 MB of archives. After this operation, 162 MB of additional disk space will be used. Get:1 /home/dariawan/java14-examples_1.0-1_amd64.deb java14-examples amd64 1.0-1 [36.6 MB] Selecting previously unselected package java14-examples. (Reading database ... 113106 files and directories currently installed.) Preparing to unpack .../java14-examples_1.0-1_amd64.deb ... Unpacking java14-examples (1.0-1) ... Setting up java14-examples (1.0-1) ...
To check if the java-examples package is installed:
$ apt list --installed | grep java14-examples WARNING: apt does not have a stable CLI interface. Use with caution in scripts. java14-examples/now 1.0-1 amd64 [installed,local]
dpkg --contents java14-examples_1.0-1_amd64.deb you will get the idea where the package will be installed. Without specifying option
--install-dir, it's installed in /opt/java14-examples. Now, let's running it!
[email protected]:~$ cd /opt/java14-examples/bin/ [email protected]:/opt/java14-examples/bin$ ./java14-examples Main class for Packaging Tool (Incubator) - JEP343 test
Voila! And to uninstall it, also piece of cake:
$ sudo apt remove java14-examples Reading package lists... Done Building dependency tree Reading state information... Done The following packages will be REMOVED: java14-examples 0 upgraded, 0 newly installed, 1 to remove and 0 not upgraded. After this operation, 162 MB disk space will be freed. Do you want to continue? [Y/n] Y (Reading database ... 113378 files and directories currently installed.) Removing java14-examples (1.0-1) ...
Packaging and Install for Windows
And following command to run it on Windows:
C:\Projects\Java>jpackage --type msi --name java14-examples --input java14-examples --main-jar java14-examples-1.0.0.jar --main-class com.dariawan.jdk14.JEP343Main --java-options '--enable-preview' --win-console WARNING: Using incubator modules: jdk.incubator.jpackage Can not find WiX tools (light.exe, candle.exe) Download WiX 3.0 or later from https://wixtoolset.org and add it to the PATH. Error: Invalid or unsupported type: [msi]
You'll notified that there are two things extra in my Windows package creation:
--win-consoleis specified for this package, since the application and main class is a console application
- For Windows, for jpackage to create a package and/or installer, you need to have WiX tools.
Go to https://wixtoolset.org/ to download it. My version is WiX Toolset v3.11.2. I just get the
wix311-binaries.zip since I don't want to install the toolset. Just copy to your destinated location and extract it. Add extraction folder to your %PATH%. After WiX tools settled, rerun the command:
C:\Projects\Java>jpackage --type msi --name java14-examples --input java14-examples --main-jar java14-examples-1.0.0.jar --main-class com.dariawan.jdk14.JEP343Main --java-options '--enable-preview' --win-console WARNING: Using incubator modules: jdk.incubator.jpackage
java14-examples-1.0.msi that you can install to your system:
Then you can find it under "Program and Features"
Programs and Features
--install-dir, the application installed in folder C:\Program Files\java14-examples. And, when I'm running it:
C:\Program Files\java14-examples>java14-examples.exe Main class for Packaging Tool (Incubator) - JEP343 test
To uninstall it, just uninstall it from "Programs and Features"
Similarly, the jpackage also will work for macOS.
This tool is still an incubating feature, delivered under module named
jdk.incubator.jpackage. That means,
jpackage related features are not guaranteed to be stable and may be changed in a future release. You also can notice, the tool always display a warning when run from the command line.