Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8213087

CSR for JEP 343: Packaging Tool

    Details

    • Subcomponent:
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      new tool
    • Interface Kind:
      add/remove command in $JDK/bin
    • Scope:
      JDK

      Description

      Summary

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

      Problem

      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.

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

      Solution

      Create a new tool, jpackage, based on the JavaPackager delivered as part of JavaFX in JDK10.

      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, 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 /opt).

      • 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)

      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:

      • Non-modular applications that run on the class path, and are in (one or more) jar files
      • Modular applications that are in (one or more) modular jar files or jmod files
      • Modular applications that have been jlinked into a custom run-time image

      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 self-contained Java application image. The image is stored in a single directory in the filesystem that can include the following:

      • Native application launcher (generated by the tool)
      • Application resources (e.g., jar, icns, ico, png)
      • Configuration files (e.g., plist, cfg, properties)
      • Helper libraries for the launcher
      • The Java run-time image (including the application modules, if the app has been modularized)

      Sample usages

      Generate a non-modular application image:

      jpackage --package-type app-image -d destdir -i inputdir -n name \
          --main-class className --main-jar MyJar.jar
      

      Generate a modular application image:

      jpackage --package-type app-image -n name -p modulePath
          -m moduleName/className

      To provide your own options to jlink, run jlink separately:

      jlink --output appRuntimeImage -p ModulePath -m moduleName \
          --no-header-files [<additional jlink options>...]
      jpackage --package-type app-image -n name \
          -m moduleName/className --runtime-image appRuntimeImage

      Generate an application package:

      jpackage --package-type <type> -n name \
          -p modulePath -m moduleName/className
      
      jpackage --package-type <type> -i inputdir -n name \
          --main-class package.ClassName --main-jar MyJar.jar
      
      jpackage --package-type <type> -n <name> \
          --app-image <app image dir>

      Generate a Java runtime package:

      jpackage  -n name  --runtime-image <runtime-image>

      Specification

      API Documentation

      src/jdk.jpackage/share/classes/module-info.java :

          /**
           * Defines the Java Packaging tool, jpackage.
           *
           * <p>jpackage is a tool for generating self-contained application bundles.
           *
           * <p> This module provides the equivalent of command-line access to <em>jpackage</em>
           * via the {@link java.util.spi.ToolProvider ToolProvider} SPI.
           * Instances of the tool can be obtained by calling
           * {@link java.util.spi.ToolProvider#findFirst ToolProvider.findFirst}
           * or the {@link java.util.ServiceLoader service loader} with the name
           * {@code "jpackage"}.
           *
           * @implNote The {@code jpackage} tool is not thread-safe. An application
           * should not call either of the
           * {@link java.util.spi.ToolProvider ToolProvider} {@code run} methods
           * concurrently, even with separate {@code "jpackage"} {@code ToolProvider}
           * instances, or undefined behavior may result.
           * <p></p>
           *
           * @moduleGraph
           * @since 14
           */
      
          module jdk.jpackage {
          }
      

      Application Layout

      The image format for an application named 'MyApp' will look like this on Windows:

        MyApp/
          MyApp.exe   [this is the native launcher]
          MyApp.ico
          app/
            [application configuration, and support files go here]

      and will look like this on linux:

        MyApp/
          app/
            [application configuration, and support files go here]
          bin/
            MyApp   [this is the native launcher]
            MyApp.icns

      and will look like this on macOs:

        MyApp.app/
          Contents/
            Info.plist
            app/
              [application configuration, and support files go here]
            MacOS/
              MyApp     [this is the native launcher]
            Resources/
              [application resource files go here]

      Note that the helper libraries for the launcher and the Java run-time image used to run the application are not shown. The location and contents of these support files are implementation details that should not be relied upon or used directly by applications.

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

      Command line options

      The jpackage usage is as follows:

      jpackage --help
      jpackage <options>

      Generic Options:

      `@<filename>` —
                Read options and/or mode from a file
                This option can be used multiple times.
      
      `--package-type <type>` ---
                The type of package to create
                Valid values are: {"app-image", "exe", "msi", "rpm", "deb", "pkg", "dmg"}
                If this option is not specified a platform dependent
                default package type will be created.
      
      `--app-version <version>` —
                Version of the application and/or package
      
      `--copyright <copyright string>` —
                Copyright for the application
      
      `--description <description string>` —
                Description of the application
      
      `--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
      
      `--name -n <name>` —
                Name of the application and/or package
      
      `--dest -d <destination path>` —
                Path where generated output file is placed
                Defaults to the current working directory.
                (absolute path or relative to the current directory)
      
      `--temp <file path>` —
                Path of a new or empty directory used to create temporary files
                (absolute path or relative to the current directory)
                If specified, the temp dir will not be removed upon the task
                completion and must be removed manually
                If not specified, a temporary directory will be created and
                removed upon the task completion.
      
      `--vendor <vendor string>` —
                Vendor of the application
      
      `--verbose` —
                Enables verbose output
      
      `--version` —
                Print the product version to the output stream and exit

      Options for creating the runtime image:

      `--add-modules <module name>[,<module name>...]` —
                A comma (",") separated list of modules to add.
                This module list, along with the main module (if specified)
                will be passed to jlink as the --add-module argument.
                if not specified, either just the main module (if --module is
                specified), or the default set of modules (if --main-jar is
                specified) are used.
                This option can be used multiple times.
      
      `--module-path -p <module path>...` —
                A ; separated list of paths
                Each path is either a directory of modules or the path to a
                modular jar.
                (each path is absolute or relative to the current directory)
                This option can be used multiple times.
      
      `--runtime-image <file path>` —
                Path of the predefined runtime image that will be copied into
                the application image
                (absolute path or relative to the current directory).
                If --runtime-image is not specified, jpackage will run jlink to
                create the runtime image using options:
                --strip-debug, --no-header-files, --no-man-pages, and
                --strip-native-commands.  --bind-services will also be added if
                --add-modules is not specified.
      
      Options for creating the application image:
      
      `--icon <icon file path>` —
                Path of the icon of the application bundle
                (absolute path or relative to the current directory)
      
      `--input -i <input path>` —
                Path of the input directory that contains the files to be packaged
                (absolute path or relative to the current directory).
                All files in the input directory will be packaged into the
                application image.

      Options for creating the application launcher(s):

      `--add-launcher <launcher name>=<file path>` ---
                Name of launcher, and a path to a Properties file that contains
                a list of key, value pairs
                (absolute path or relative to the current directory)
                The keys "module", "add-modules", "main-jar", "main-class",
                "arguments", "java-options", "app-version", "icon", and
                "win-console" can be used.
                These options are added to, or used to overwrite, the original
                command line options to build an additional alternative launcher.
                The main application launcher will be built from the command line
                options. Additional alternative launchers can be built using
                this option, and this option can be used multiple times to
                build multiple additional launchers. 
      
      `--arguments <main class arguments>` —
                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 <java options>` —
                Options to pass to the Java runtime
                This option can be used multiple times.
      
      `--main-class <class name>` —
                Qualified name of the application main class to execute
                This option can only be used if --main-jar is specified.
      
      `--main-jar <main jar file>` —
                The main JAR of the application; containing the main class
                (specified as a path relative to the input path).
                Either --module or --main-jar option can be specified but not
                both.
      
      `--module -m <module name>[/<main class>]` —
                The main module (and optionally main class) of the application
                This module must be located on the module path.
                When this option is specified, the main module will be linked
                in the Java runtime image.  Either --module or --main-jar
                option can be specified but not both.

      Platform dependent option for creating the application launcher:

      
      Windows platform options:
      
      `--win-console` —
                Creates a console launcher for the application, should be
                specified for application which requires console interactions
      
      MacOS platform options: 
      
      `--mac-bundle-identifier <ID string>` —
                An identifier that uniquely identifies the application for MacOS.
                Defaults to the main class name.
                May only use alphanumeric (A-Z,a-z,0-9), hyphen (-),
                and period (.) characters.
      
      `--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-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-sign` —
                Request that the bundle be signed
      
      `--mac-signing-keychain <file path>` —
                Path of the keychain to use
                (absolute path or relative to the current directory).
                If not specified, the standard keychains are used.
      
      `--mac-signing-key-user-name <user name>` —
                User name portion of the typical
                "Mac Developer ID Application: <user name>" signing key

      Options for creating the application package:

      `--app-image <file path>` —
                Location of the predefined application image that is used
                to build an installable package
                (absolute path or relative to the current directory).
      
      `--file-associations <file path>` —
                Path to a Properties file that contains list of key, value pairs
                (absolute path or relative to the current directory).
                The keys "extension", "mime-type", "icon", and "description"
                can be used to describe the association.
                This option can be used multiple times.
      
      `--install-dir <file path>` —
                Absolute path of the installation directory of the application on OS X
                or Linux. Relative sub-path of the installation location of the application
                such as "Program Files" or "AppData" on Windows.
      
      `--license-file <file path>` —
                Path to the license file
                (absolute path or relative to the current directory)
      
      `--resource-dir <path>` —
                Path to override jpackage resources.
                Icons, template files, and other resources of jpackage can be
                over-ridden by adding replacement resources to this directory.
                (absolute path or relative to the current directory)
      
      `--runtime-image <file-path>` —
                Path of the predefined runtime image to install
                (absolute path or relative to the current directory).
                Option is required when creating a runtime package.

      Platform dependent options for creating the application package:

      
      Windows platform options: 
      
      `--win-dir-chooser` —
                Adds a dialog to enable the user to choose a directory in which
                the product is installed
      
      `--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-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-shortcut` —
                Creates a desktop shortcut for the application
      
      `--win-upgrade-uuid <id string>` —
                UUID associated with upgrades for this package
      
      `--linux-shortcut` —
                Creates ashortcut for the application
      
      Linux platform options:
      
      `--linux-bundle-name <bundle name>` —
                Name for Linux bundle, defaults to the application name
      
      `--linux-deb-maintainer <email address>` —
                Maintainer for .deb bundle
      
      `--linux-menu-group <menu-group-name>` —
                Menu group this application is placed in
      
      `--linux-package-deps` —
                Required packages or capabilities for the application
      
      `--linux-rpm-license-type <type string>` —
                Type of the license ("License: <value>" of the RPM .spec)
      
      `--linux-app-category <category value>` --
                Group value of the RPM <name>.spec file or Section value of DEB control file.
      
      `--linux-deb-copyright-file <file path>` --
                Path to custom copyright file for Debian packaging
                (absolute path or relative to the current directory)
      

      Additional Notes

      --app-image <app image dir>
            An app-image is a directory  that can be the output of a previous
            invocation of jpackage specifying --package-type "app-image".  An app image directory 
            can alternatively contain anything you want bundled as the application,
            It must contain at least the executable application .
      
      --add-launcher <name>=<additional launcher properties file path>
           An application image will contain at least one main application launcher,
           defined by the options passed to jpackage.
           It may also create one or several additional launchers defined by this
           option.  The additional launcher with the name <name> is defined by the
           combination of those options and the properties in given properties file.
           The <name> given must be a valid filename different than the name of 
           the main application, or any other previous additional launcher.
           "name", and it's value cannot be the same as the main app.
           A secondary launcher properties file may optionally have any of 
           the following properties:
            * app-version
            * module
            * main-jar
            * main-class
            * icon
            * arguments
            * java-options
            * win-console
          Using the same input files as the main launcher, jpackage will then create a
          additional launcher with the given name using the combined options.
      
      -- when an option value is a string:
          If a string value contains space characters, the argument must be quoted, 
          else the shell will consider each word a separate argument.
      
      -- when option value is a list:
          If an option value is a list of file paths, each element in the list must be
          separated by File.pathSeparator. The above help output was generated on 
          windows platform, so help text says "A ; separated list of file ..." If run on 
          linux or Mac, the help output would be "A : separated list of file ...".
          If an option value is a list of module names then they must be separated by
          a comma.
          If an option value is otherwise a list of strings, they must separated by 
          space characters.  Since the shell would otherwise take them as separate 
          arguments, the list must be quoted.
          If a list of strings contains a string which contains space characters, quote 
          the string and list of strings with different quote characters such as:
          --java-options "-ea '-Dmy.tmp.path=\Program Files\temp'"
      
      --  Specifying an option multiple times.
          The following options can be specified multiple times in one command:
            * --java-options
            * --arguments
            * --module-path
            * --add-modules
            * --file-associations
            * --add-launcher
           If any of the above options are given multiple times, the value used will
           be the  combination of the given values (as described below).
           If any other option is given multiple times, only the last value will be used.
      
      -- Options whose value is a list can optionally be specified multiple times,
          so that :
          --java-options "-server -ea -Dfoo=bar"
          is the same as
          --java-options -server --java-options "--ea -Dfoo=bar"
          or
          --java-options -server --java-options -ea --java-options -Dfoo=bar
      
          The options --java-options, --arguments,  --module-path, and --add-modules
          are lists that can either be specified in one option or by multiple options.
      
          The options --file-associations and --add-launcher are file paths, so to
          create multiple associations or additional launchers, multiple options 
          must be used as:
          "--file-associations assoc1.properties --file-associations assco2.properties", or
          "--add-launcher launcher2.properties --add-launcher launcher3.properties".

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                herrick Andy Herrick
                Reporter:
                herrick Andy Herrick
                Reviewed By:
                Alexander Matveev, Kevin Rushforth, Philip Race
              • Votes:
                0 Vote for this issue
                Watchers:
                7 Start watching this issue

                Dates

                • Created:
                  Updated: