Summary

Goals

Create a simple packaging tool, based on the JavaFX javapackager tool, that:

Supports native packaging formats to give the end user a natural installation experience. These formats include msi and exe on Windows, pkg and dmg on macOS, and deb and rpm on Linux.

Allows launch-time parameters to be specified at packaging time.

Can be invoked directly, from the command line, or programmatically, via the ToolProvider API.

Non-Goals

The following features of the javapackager tool will not be supported:

Java Web Start application support,

JavaFX-specific features,

jdeps usage for determining required modules, and

the Ant plugin.

There will be no GUI for the tool. A command-line interface (CLI) is sufficient.

There will be no support for cross compilation. For example, in order to create Windows packages one must run the tool on Windows. The tool can depend upon platform-specific tools.

There will be no special support for legal files beyond what is already provided in JMOD files (e.g., no aggregation of individual license files).

There will be no native splash screen support.

There will be no auto-update mechanism.

The tool will not be available on Solaris platforms.

Motivation

Many Java applications need to be installed on a native platform in a first-class way, rather than simply being placed on the class path or the 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 allows Java applications to be distributed, installed, and uninstalled in a manner that is familiar to users of that platform. For example, on Windows users expect to be able to double-click on an installer to install their software, and then use the control panel to remove the software; on macOS users expect to be able to double-click on a DMG file and drag their application to the Application folder. Applications installed as service daemons, moreover, may require registering the service with the operating system.

There is also a need for a tool that can package the JDK itself for installation on a target system. Absent such a tool, JDK images are only published in the tar.gzzip formats.

A packaging tool can also help fill gaps left by other technologies such as Java Web Start, which was removed from Oracle’s JDK 11, and pack200, which was deprecated in JDK 11 for removal in a future release. Developers can use jlink to strip the JDK down 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 address these requirements previously, a packaging tool called javapackager was distributed with Oracle’s JDK 8. However, it was removed from Oracle’s JDK 11 in connection with the removal of JavaFX.

Description

The jpackage tool will take as input a Java application and a Java run-time image, and produce a Java application image that includes all the necessary dependencies. It will also be able to produce a native package in a platform-specific format, such as an exe on Windows or a dmg on macOS. The tool will have options that allow packaged applications to be customized in various ways.

Features

The tool will provide the following features:

Creation of an application image

Support for native packaging formats to give the end user a more natural installation experience. Specifically, the tool will support the following formats:

Windows: msi, exe

macOS: pkg in a dmg, app in a dmg (drag the app into the Applications directory)

Linux: deb, rpm

The application will be installed in the typical default directory for each platform unless the end-user specifies an alternate directory during the installation process (for example, on Linux the default directory will be /usr/bin).

Support for packaging Java applications such that they are suitable for submission to the Windows or macOS app stores

The ability to specify JDK and application arguments at packaging time that will be used when launching the application

The ability to package applications in ways that integrate into the native platform, for example:

Setting file associations to allow launching an application when a file with an associated suffix is opened

Launching from a platform-specific menu group, such as Start menu items on Windows

Option to specify update rules for installable packages (such as in rpm/deb)

The following feature will be included if there is time, although it might be decoupled from this JEP:

Support for single vs. multiple instances, so that multiple instances of the application can be prevented from launching

Running the tool

The input to jpackage includes: a Java run-time image, a Java application in one of several formats, and various command line options to control the generation of the final image or package.

The following types of applications are supported:

Modular applications that have been jlinked into a custom run-time image

Modular applications that are in (one or more) modular jar files or jmod files

Legacy applications that run on the class path, and are in (one or more) jar files

If no custom run-time image is provided then the tool will run jlink to create a JDK for the application.

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

Native application launcher (generated by the tool)

Java run-time image (including the application modules, if the app has been modularized)

Application resources (e.g., jar, icns, ico, png)

Configuration files (e.g., plist, cfg, properties)

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

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 as a native, installable package (for example, in msi or dmg format).

In this latter case, the tool can either create a native package from a previously created application image, or it can create a native package directly. The native package will include the following:

The application image as defined above

Support for signing packages

Package post-processing steps such as setting up file associations

Delivering jpackage

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

Some features, such as the single-instance launcher, might require a run-time API that an application can call. If so, we will provide a run-time module with the necessary API.

Command line options

The jpackage usage is as follows:

jpackage --help
jpackage <mode> <options>

where mode is one of:

create-image —
Generates a platform-specific application image.

create-installer —
Generates a platform-specific installer for the application.
Valid values for type are msi, exe, rpm, deb, dmg,
pkg, and pkg-app-store.
If type is omitted, all supported types of installable
packages for the current platform will be generated.

create-jre-installer <type> —
Generates a platform-specific installer for JRE.
Valid values for type are msi, exe, rpm, deb, dmg,
and pkg.
If type is omitted, all supported types of installable
packages for the current platform will be generated.

--file-associations <file path> —
Properties file that contains list of key,value pairs that
describe a file association.
"extension", "mime-type", "icon", and "description"
can be used as keys for the association.

--secondary-launcher <file path> —
Properties file that contains a collection of options
for a secondary launcher

--build-root <file path> —
Directory in which to use and place temporary files

--runtime-image <file path> —
Location of the predefined runtime image that is used to build
an application image and installable package

--app-image <file path> —
Location of the predefined application image that is used
to build an installable package

--install-dir <file path> —
Installation directory of the application.
This option is ignored on Windows, use --win-dir-chooser to
provide user the ability to choose the installation directory.

--win-console —
Creates a console launcher for the application, should be
specified for application which requires console interactions

The following options are valid for Mac OS X platforms:

--mac-sign —
Request that the bundle be signed

--mac-bundle-name <name string> —
Name of the application as it appears in the Menu Bar.
This can be different from the application name.
This name must be less than 16 characters long and be suitable for
displaying in the menu bar and the application Info window.
Defaults to the application name.

--mac-bundle-identifier <ID string> —
An identifier that uniquely identifies the application for MacOSX
(and on the Mac App Store).
May only use alphanumeric (A-Z,a-z,0-9), hyphen (-),
and period (.) characters.

--mac-app-store-category <category string> —
Mac App Store Categories.
Note that the key is the string shown to
the user and the value is the ID of the category.

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, and so forth.

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

Testing

Most tests can be done with automated scripts, but there are a few considerations to be aware of:

Testing the native installers may require optional tools to be installed; those tests will need to be written such that they are skipped on systems without the necessary tools.

Verifying some types of native packages (e.g., exe on Windows or app in a dmg on macOS) may require some manual testing.

We need to ensure that native packages can be installed and uninstalled cleanly, so that developers can test in their local environment without fear of polluting their system.

Dependencies

Native packages will be generated using tools on the target platform. For Windows, there are two additional tools that developers will need to install if they want to generate native packages: