Summary
-------

Create a tool for packaging self-contained Java applications.


Goals
-----

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

  - Supports native packaging formats to give end users 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 packaging tool will depend upon platform-specific tools.
  -  There will be no special support for legal files beyond what is already provided in JMOD files. There will be 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.


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:

  - Linux: `deb` and `rpm`
  - macOS: `pkg` and `dmg`
  - Windows: `msi` and `exe`

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:

  - `--app-version <version>`
  - `--copyright <string>`
  - `--description <string>`
  - `--license-file <file>`
  - `--name <string>`
  - `--vendor <string>`

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](#Platform-specific-details).


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

  - `extension` specifies the extension of files to be associated with the application,
  - `mime-type` specifies the MIME type of files to be associated with the application,
  - `icon` specifies an icon, within the application image, for use with this association, and
  - `description` specifies a short description of the association.


### Launchers

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

  - `--arguments <string>`
          — Command-line arguments to pass to the main class if no command
          line arguments are given to the launcher
          (this option can be used multiple times)
  - `--java-options <string>`
          — Options to pass to the JVM
          (this option can be used multiple times)

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

  - `--add-launcher <launcher-name>=<file>`

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](https://openjdk.java.net/jeps/282) to create the runtime image.  The content of the image depends upon the type of the application:

  - For a non-modular application composed of JAR files, the runtime image contains the same set of JDK modules that is [provided to class-path applications in the unnamed module](https://openjdk.java.net/jeps/261#Root-modules) by the regular `java` launcher.

  - For a modular application composed of modular JAR files and/or JMOD files, the runtime image contains the application's main module and the transitive closure of all of its dependencies.  It will not include all the available service providers; if you want those to be bound then specify the `--bind-services` option to the `jpackage` tool.

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][jdeps] 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

[jdeps]: https://docs.oracle.com/en/java/javase/13/docs/specs/man/jdeps.html


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

  - `--linux-package-name <package name>`
          — Name for the Linux package, defaults to the application name
  - `--linux-deb-maintainer <email address>`
          — Maintainer for a DEB package
  - `--linux-menu-group <menu-group-name>`
          — Menu group this application is placed in
  - `--linux-package-deps <deps>`
          — Required packages or capabilities for the application
  - `--linux-rpm-license-type <type string>`
          — Type of the license (`License: <value>` of the RPM `.spec` file)
  - `--linux-app-release <release value>`
          — Release value of the RPM `<name>.spec` file, or the
            Debian revision value of the DEB control file
  - `--linux-app-category <category value>`
          — Group value of the RPM `<name>.spec` file, or 
            the Section value of the DEB control file
  - `--linux-shortcut`
          Creates a shortcut for the application


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

  - `--mac-package-identifier <string>` —
          An identifier that uniquely identifies the application for macOS
          (defaults to the main class name; limited to alphanumeric, hyphen, and period characters)
  - `--mac-package-name <string>` —
          Name of the application as it appears in the menu bar
          (defaults to the application name;
          must be less than 16 characters long and be suitable for
          displaying in the menu bar and the application Info window)
  - `--mac-package-signing-prefix <string>` —
          When signing the application bundle, the value prepended to all
          components that need to be signed but don't have
          an existing bundle identifier
  - `--mac-sign` —
          Request that the bundle be signed
  - `--mac-signing-keychain <file>` —
          Path of the keychain to search for the signing identity
          (defaults to the standard keychains)
  - `--mac-signing-key-user-name <team name>` —
          Team name portion of the Apple signing identity
          (for example, "Developer ID Application: ")

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

  - `--win-console` —
          Creates a console launcher for the application (should be
          specified for applications which require console interactions)
  - `--win-dir-chooser` —
          Adds a dialog to enable the user to choose a directory in which
          to install the application
  - `--win-menu` —
          Adds the application to the system menu
  - `--win-menu-group <menu-group-name>` —
          Start Menu group in which to place this application
  - `--win-per-user-install` —
          Install the application on a per-user basis
  - `--win-shortcut` —
          Create a desktop shortcut for the application
  - `--win-upgrade-uuid <string>` —
          UUID associated with upgrades for this package


### Delivering `jpackage`

The `jpackage` tool will be delivered in the JDK as an [incubator module](https://openjdk.java.net/jeps/11) 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)](http://openjdk.java.net/jeps/293).  In addition to the command-line interface, `jpackage` is accessible via the [ToolProvider API](https://docs.oracle.com/javase/10/docs/api/java/util/spi/ToolProvider.html) (`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:

  - Testing the native packages 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 `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 systems.


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:

  - Wix, a third-party tool, is required to generate `msi` or `exe` 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`.