JEP draft: Packaging Tool

OwnerKevin Rushforth
TypeFeature
ScopeJDK
StatusDraft
Componentdeploy / packager
Discussioncore dash libs dash dev at openjdk dot java dot net
EffortM
DurationM
Relates toJEP 311: Java Packager API & CLI
Reviewed byAlexander Matveev, Alexey Semenyuk, Andy Herrick, Kevin Rushforth, William Harnois
Created2018/04/04 19:22
Updated2018/08/13 21:23
Issue8200758

Summary

Create a new tool, jpackager, for packaging self-contained Java applications.

Goals

Create a simple packaging tool, based on the javapackager tool, to generate the following types of native packages:

The tool will provide the following features:

Developers will be able to access the tool either by running the jpackager executable or by using the ToolProvider API.

Non-Goals

Motivation

Many Java applications need to be installed on a native platform in a first-class way, rather than simply being placed on the classpath or module path. It is not sufficient for the application developer to deliver a simple JAR file; they must deliver an installable package suitable for the native platform. This will allow Java applications to be distributed, installed, and uninstalled in a manner that is familiar to users of that platform. For example, users expect to be able to double-click on an installer on Windows platforms to install their software, and then use the control panel to remove the software; users on Mac platforms expect to be able to double-click on a DMG file and drag their application to the Application folder. Applications installed as service daemons may require registering the service with the operating system.

There is also the need for a tool that enables packaging a JDK or JRE that can be installed on a target system. Absent such a tool, the OpenJDK bundles are only available in .tar.gz or .zip format.

A packaging tool can also help fill gaps left by other technologies such as Java Web Start, which was removed from JDK 11, and pack200, which was deprecated in JDK 11 for removal in a subsequent version of the JDK. Developers can use jlink to strip down the runtime to the minimal set of modules that are needed, and then use the packaging tool to produce a compressed, installable image that can be deployed to target machines.

To support these requirements previously, a packaging tool, javapackager, was distributed with Oracle JDKs 8, 9, and 10. However, it was removed from Oracle JDK 11 in connection with the removal of JavaFX.

Description

The jpackager tool takes as input a Java application and a Java runtime, and produces a Java application bundle that includes all necessary Java dependencies. It also produces a native package in a platform-specific format, such as a .exe on Windows or a .dmg on Mac. The tool provides options that allow packaged applications to be customized in various ways.

Features

The tool will provide the following features:

The following features will be included if there is time:

Running the tool

The input to jpackager includes: a Java runtime image, and a Java application in one of several formats, along with various command line options to control the generation of the final bundle or package.

The following types of applications are supported:

If no custom run-time image is provided, the tool will run jlink to create a JRE as the runtime image for the packager.

The output of jpackager is a Java application bundle that includes all necessary Java dependencies. The output bundle is an application image that is stored in a single directory in the filesystem and can include the following:

As an example, the image format for a HelloWorld application might look like this:

HelloWorld/
    HelloWorld.exe     [this is the native launcher]
    app/
      [application resource, configuration, and support files go here]
    runtime/
      [custom Java runtime image goes here]

When the application is started, the launcher will read the configuration files and launch the embedded Java run-time image with the specified arguments.

The application image can be redistributed as is, or it can be packaged up as a native, installable package (for example, in msi or dmg format).

In this latter case, the tool creates the native package from the previously created application image. This will include the following:

If the end-user does not specify a filesystem location during the installation process then the default location for the application will be the typical default for each platform (for example, on Linux it will be /usr/bin).

Delivering jpackager

The jpackager tool will be delivered as part of the JDK in a new jdk.packager module. This tool will be based on the javapackager tool, with all features related to Java Web Start and JavaFX excluded. The command-line interface (CLI) will conform to JEP 293: Guidelines for JDK Command-Line Tool Options. In addition to the command-line interface, jpackager will be accessible via the ToolProvider API (java.util.spi.ToolProvider) under the name "jpackager".

Command line arguments

The command-line arguments will be described in a separate document.

Issues

We need to specify the layout of an application image and define what is supported versus unsupported, to make it clear for developers what they should or should not depend on, for example, the location of the application launcher, any user-editable configuration files, etc.

We should include some command-line examples and describe the content of the run-time image produced.

Testing

It is expected that most tests will be done with automated scripts, but there are a few considerations to be aware of:

Dependencies

Generation of native packages is done using tools on the platform in question. For the Windows platform, there are two additional tools that developers will need to install if they want to generate native packages:

There are efforts underway to enhance jlink to generate native launchers too. Some level of coordination may be needed between jlink and jpackager.