JEP 343: Packaging Tool

OwnerKevin Rushforth
TypeFeature
ScopeJDK
StatusCandidate
Componentdeploy / packager
Discussioncore dash libs dash dev at openjdk dot java dot net
EffortM
DurationM
Depends8212780: JEP 343: Packaging Tool Implementation
Relates toJEP 311: Java Packager API & CLI
Reviewed byAlexander Matveev, Alexey Semenyuk, Andy Herrick, Kevin Rushforth, William Harnois
Created2018/04/04 19:22
Updated2018/12/12 17:37
Issue8200758

Summary

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

Goals

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

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 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.gz zip 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:

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

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:

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:

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 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:

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.

Sample usages

Generate an application image from a non-modular jar file:

jpackage create-image --input inputdir --output outputdir \
    --name AppName --class package.ClassName --main-jar MyJar.jar
jpackage create-image -i inputdir -o outputdir -n AppName
    -c package.ClassName -j MyJar.jar

Generate an application image from a modular jar file:

jpackage create-image --output outputdir --name AppName \
    --class package.ClassName -module moduleName -p modulePath
jpackage create-image --o outputdir -n AppName \
    -c package.ClassName -m moduleName -p modulePath

Generate an application installer:

jpackage create-inataller -o outputdir -n "Installer Name" \
    --app-image <app image dir>
jpackage create-installer -i inputdir -o outputdir \
    -n "Installer Name" -c package.ClassName -j MyJar.jar

Generate a JRE installer:

jpackage create-jre-installer -n <jre-name> -o outputdir \
    --runtime-image <path>
jpackage create-jre-installer -name <jre-name> -output outputdir

The following options are valid for all platforms:

@<filename> — Read options and/or mode from a file

--help -h — Print the usage text with a list and description of each valid option for the current platform to the output stream, and exit

--version -v — Print the product version to the output stream and exit

--output -o <output dir> — Name of the directory where generated output file is placed

--input -i <input dir> — Name of the input directory that contains the files to package

--files -f <input files> — A <File.pathSeparator> separated list of files in the input dir to be packaged. If omitted, all files in the input directory will be packaged.

--name -n <application name> — Name of the application

--main-jar -j <main jar name> — The main JAR of the application. This JAR should have the main-class, and is relative to the assembled application directory.

--class -c <class name> — Qualified name of the application class to execute

--app-version <version string> — Version of the application

--arguments -a <main class arguments> — Command line arguments to pass to the main class if no arguments are specified by the launcher

--icon <icon file name> — Icon of the application bundle

--singleton — Prevents multiple instances of the application from launching (see SingleInstanceService API for more details)

--identifier <id string> — Machine readable identifier of the application. The format must be a DNS name in reverse order, such as com.example.myapplication.

--verbose — Enables verbose output

--strip-native-commands — Removes native executables from the custom run-time images

--jvm-args <java vm arguments> — JVM flags and options to pass to the application

--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.

--license-file <file name> — The license file, relative to the input directory

--copyright <copyright string> — Copyright for the application

--description <description string> — Description of the application

--category <category string> — Category or group of the application

--vendor <vendor string> — Vendor of the application

--force — Allow the deletion of any existing output root directory when creating an Application image

Modular options:

--module -m <module name> — Main module of the application. This module must contain the main-class, and be located on the module path.

--module-path -p <module path> — Path JLink looks in for modules when packaging the Java Runtime

--add-modules <module list> — A <File.pathSeparator> separated list of modules to add to JImage creation, including possible services

--limit-modules <module list> — A <File.path.Separator> separated list of Modules to limit JImage creation to

The following options are valid for Windows platforms:

--win-menu — Adds the application to the system menu

--win-menu-group <menu group name> — Start Menu group this application is placed in

--win-per-user-install — Request to perform an install on a per-user basis

--win-dir-chooser — Adds a dialog to enable the user to choose a directory in which the product is installed

--win-registry-name <registry name> — Name of the application for registry references. The default is the Application Name with only alphanumerics, dots, and dashes (no whitespace)

--win-upgrade-uuid <id string> — UUID associated with upgrades for this package

--win-shortcut — Creates a desktop shortcut for the application

--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.

--mac-app-store-entitlements <file path> — File location of a custom mac app store entitlements file

--mac-bundle-signing-prefix <prefix string> — When signing the application bundle, this value is prefixed to all components that need to be signed that don't have an existing bundle identifier.

--mac-signing-key-user-name <user name> — User name portion of the typical "Mac Developer ID Application: " signing key

--mac-signing-keychain <file path> — Location of the keychain to use. If not specified, the standard keychains are used.

The following options are valid for Linux platforms:

--linux-bundle-name <bundle name> — Name for Linux bundle, defaults to the application name

--linux-package-deps — Required packages or capabilities for the application

--linux-rpm-license-type <type string> — Type of the license ("License: " of the RPM .spec)

--linux-deb-maintainer <email address> — Maintainer for .deb bundle

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:

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:

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