JEP 343: Packaging Tool (Incubator)

OwnerKevin Rushforth
TypeFeature
ScopeJDK
StatusCompleted
Release14
Componenttools / jpackage
Discussioncore dash libs dash dev at openjdk dot java dot net
EffortM
DurationM
Relates toJEP 311: Java Packager API & CLI
Reviewed byAlan Bateman, Alexander Matveev, Alexey Semenyuk, Andy Herrick, Mandy Chung, William Harnois
Endorsed byBrian Goetz
Created2018/04/04 19:22
Updated2020/01/13 15:34
Issue8200758

Summary

Create a 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. For example, on Windows users expect to be able to double-click on a package 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.

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 as part of the removal of JavaFX.

Description

The jpackage tool packages a Java application into a platform-specific package that includes all of the necessary dependencies. The application may be provided as a collection of ordinary JAR files or as a collection of modules. The supported platform-specific package formats are:

By default, jpackage produces a package in the format most appropriate for the system on which it is run.

Basic usage: Non-modular applications

Suppose you have an application composed of JAR files, all in a directory named lib, and that lib/main.jar contains the main class. Then the command

$ jpackage --name myapp --input lib --main-jar main.jar

will package the application in the local system's default format, leaving the resulting package file in the current directory. If the MANIFEST.MF file in main.jar does not have a Main-Class attribute then you must specify the main class explicitly:

$ jpackage --name myapp --input lib --main-jar main.jar \
  --main-class myapp.Main

The name of the package will be myapp, though the name of the package file itself will be longer, and end with the package type (e.g., myapp.exe). The package will include a launcher for the application, also called myapp. To start the application, the launcher will place every JAR file that was copied from the input directory on the class path of the JVM.

If you wish to produce a package in a format other than the default, then use the --type option. For example, to produce a pkg file rather than dmg file on macOS:

$ jpackage --name myapp --input lib --main-jar main.jar --type pkg

Basic usage: Modular applications

If you have a modular application, composed of modular JAR files and/or JMOD files in a lib directory, with the main class in the module myapp, then the command

$ jpackage --name myapp --module-path lib -m myapp

will package it. If the myapp module does not identify its main class then, again, you must specify that explicitly:

$ jpackage --name myapp --module-path lib -m myapp/myapp.Main

(When packaging a modular JAR or a JMOD file you can specify the main class with the --main-class option to the jar and jmod tools.)

Package metadata

The jpackage tool allows you to specify various kinds of metadata for your package. The options common to all platforms are:

The tool uses the arguments provided to these options in the manner appropriate to the package's type. Platform-specific package metadata options are described below.

File associations

You can define one or more file-type associations for your application via the --file-associations option, which can be used more than once. The argument to this option is a properties file with values for one or more of the following keys:

Launchers

By default, the jpackage tool creates a simple native launcher for your application. You can customize the default launcher via the following options:

If your application requires additional launchers then you can add them via the --add-launcher option:

The named <file> should be a properties file with values for one or more of the keys app-version icon arguments java-options main-class main-jar module, or win-console. The values of these keys will be interpreted as arguments to the options of the same name, but with respect to the launcher being created rather than the default launcher. The --add-launcher option can be used multiple times.

Application images

The jpackage tool constructs an application image as input to the platform-specific packaging tool that it invokes in its final step. Normally this image is a temporary artifact, but sometimes you need to customize it before it's packaged. You can, therefore, run the jpackage tool in two steps. First, create the initial application image with the special package type app-image:

$ jpackage --name myapp --module-path lib -m myapp --type app-image

This will produce an application image in the myapp directory. Customize that image as needed, and then create the final package via the --app-image option:

$ jpackage --name myapp --app-image myapp

Runtime images

An application image contains both the files comprising your application as well as the JDK runtime image that will run your application. By default, the jpackage tool invokes the the jlink tool to create the runtime image. The content of the image depends upon the type of the application:

In either case, if you want additional modules to be added to the runtime image you can use the --add-modules option with the jpackage tool. The list of modules in a runtime image is available in the image's release file.

Runtime images created by the jpackage tool do not contain debug symbols, the usual JDK commands, man pages, or the src.zip file.

If you wish to customize the runtime image further then you can invoke jlink yourself and pass the resulting image to the jpackage tool via the --runtime-image option. For example, if you've used the jdeps tool to determine that your non-modular application only needs the java.base and java.sql modules, you could reduce the size of your package significantly:

$ jlink --add-modules java.base,java.sql --output myjre
$ jpackage --name myapp --input lib --main-jar main.jar --runtime-image myjre

Platform-specific details

This section describes the platform-specific aspects of the jpackage tool, including application image layouts and platform-specific options. The command jpackage --help will print a summary of all options.

The application images created by the jpackage tool contain some files not shown in the layouts below; such files should be considered implementation details that are subject to change.

Linux
myapp/
  bin/              // Application launcher(s)
    myapp
  lib/
    app/
      myapp.cfg     // Configuration info, created by jpackage
      myapp.jar     // JAR files, copied from the --input directory
      mylib.jar
      ...
    runtime/        // JDK runtime image

The default installation directory on Linux is /opt. This can be overridden via the --install-dir option.

Linux-specific options:

macOS
MyApp.app/
  Contents/
    Info.plist
    MacOS/          // Application launcher(s)
      MyApp
    Resources/      // Icons, etc.
    app/
      MyApp.cfg     // Configuration info, created by jpackage
      myapp.jar     // JAR files, copied from the --input directory
      mylib.jar
      ...
    runtime/        // JDK runtime image

The default installation directory on macOS is /Applications. This can be overridden via the --install-dir option.

macOS-specific options:

Windows
MyApp/
  MyApp.exe         // Application launcher(s)
  app/
    MyApp.cfg     // Configuration info, created by jpackage
    myapp.jar     // JAR files, copied from the --input directory
    mylib.jar
    ...
  runtime/        // JDK runtime image

The default installation directory on Windows is C:/Program Files/. This can be overridden via the --install-dir option.

Windows-specific options:

Delivering jpackage

The jpackage tool will be delivered in the JDK as an incubator module named jdk.incubator.jpackage. As a feature delivered in an incubator module, the jpackage tool's command line options, application layout, and other exported interfaces are not guaranteed to be stable and may be revised in a future release. The tool will display a warning when run from the command line. The jdk.incubator.jpackage module will not be resolved by default, and will cause a warning to be displayed when it is resolved.

The jpackage tool is based on the javapackager tool, with all features related to Java Web Start and JavaFX removed. The command-line interface (CLI) conforms to JEP 293 (Guidelines for JDK Command-Line Tool Options). In addition to the command-line interface, jpackage is accessible via the ToolProvider API (java.util.spi.ToolProvider) under the name "jpackage".

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 is an additional tool that developers will need to install if they want to generate native packages:

There are efforts underway to enhance jlink to generate native launchers in a future version of the JDK. Some level of coordination may be needed between jlink and jpackage.