Details

    • Author:
      Kevin Rushforth
    • JEP Type:
      Feature
    • Exposure:
      Open
    • Subcomponent:
    • Scope:
      JDK
    • Discussion:
      core dash libs dash dev at openjdk dot java dot net
    • Effort:
      M
    • Duration:
      M
    • JEP Number:
      343

      Description

      Summary

      Create a new 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 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 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.

      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.

      Description

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

      Features

      The tool provides 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).

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

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

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

      and might look like this on macOs:

        HelloWorld.app/
          Contents/
            Info.plist
            Java/
              [application configuration, and support files go here]
            MacOS/
              HelloWorld     [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, 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

      Examples of common use cases

      The following examples illustrate some common use cases. These examples show the application layout for the Linux platform. The layout on Windows is similar, with the only substantive difference being that the executable launchers have a .exe extension in the file name. The layout on macOS is different as shown above.

      Non-modular application

      A non-modular application is one that runs on the class path. The application must be in one or more jar files that reside in a single input directory tree. An "exploded jar" with a collection of separate class files is not supported.

      The following are examples of the layout of the input directory tree, where myapp.jar contains the main class of the application:

          myinput/
            myapp.jar

      or

          myinput/
            myapp.jar
            lib1.jar
            lib2.jar

      or

          myinput/
            myapp.jar
            lib/
              lib1.jar
              lib2.jar

      If myapp.jar has a Main-Class attribute, then you can use the following command to package up your application:

      jpackage --output myoutput --name myapp --input myinput --main-jar myapp.jar

      If there is no Main-Class attribute in your main jar, then you also need to specify the "--main-class" option:

      jpackage --output myoutput --name myapp --input myinput \
          --main-jar myapp.jar --main-class mypkg.MyApp

      When creating an application image from a non-modular application, jpackage will run jlink with a default set of arguments, including a default set of modules, to produce the Java runtime image that will be used to run the application. The default set of modules used are those modules visible to an application running on the class-path, and any modules needed by those modules (the transitive closure plus all service providers). More formally, this is default set of Root Modules for the unnamed module as defined by JEP 261. Additionally, the debug symbols, native launchers, man pages, and src.zip are all stripped from the Java runtime.

      The output of the above example would be something like this:

        myoutput/
          myapp/
            app/
              myapp.cfg
              myapp.jar
              lib/
                lib1.jar
                lib2.jar
            bin/
              myapp       [this is the native launcher]
            runtime/      [Java runtime; this is an implementation detail]

      You can see the list of modules in the packaged Java runtime by looking in the runtime/release text file.

      To execute the application, you run the launcher:

      myoutput/myapp/bin/myapp

      It will launch the application by putting all of the application jars on the class-path and launching the main class.

      Non-modular application with a limited set of system modules

      If you know ahead of time the set of modules that your non-modular application needs, then you can use the "--add-modules" option to specify the set of root modules that you depend on, thus creating a smaller application image. The "--add-modules" option will override the default set of modules that jpackage otherwise passes to jlink, and the "--bind-services" option is omitted, thus giving the application developer full control over the set of modules that are included.

      In this example, our application depends only on the java.desktop module, in addition to java.base, on which all Java applications implicitly depend. We will use the same jar file and layout as in the previous example, where myapp.jar contains the main class of the application:

          myinput/
            myapp.jar
            lib/
              lib1.jar
              lib2.jar

      You would use the following to create your application image with only those modules you need:

      jpackage --output myoutput --name myapp --input myinput \
          --add-modules java.desktop --main-jar myapp.jar

      The output layout remains the same as the previous example, but the Java runtime only has java.desktop and its dependencies. The runtime/release file has the list of modules

      Modular application

      A modular application is composed of one or more modules, each in its own jar or jmod file. In this case you use the "--module-path" and "--module" arguments to jpackage to specify where the modules are found, and which module and class is the entry point.

      The following are examples of the layout of the input directory tree, where mymod.jar is a named module that contains the main class of the application:

          myinput/
            mymod.jar

      If mymod.jar has a ModuleMainClass attribute, then you can use the following command to package up your application:

      jpackage --output myoutput --name myapp --module-path myinput \
          --module mymod

      If there is no ModuleMainClass attribute in your main jar, then you need to specify the main class name in addition to the module name:

      jpackage --output myoutput --name myapp --module-path myinput \
          --module mymod/mypkg.MyApp

      When creating an application image from a modular application, jpackage will run jlink with a default set of arguments, using the provided module as the root module with all service providers added, to produce the Java runtime image that will be used to run the application. As in the previous examples, the native launchers are stripped, along with the jmod files, man pages, and src.zip.

      The output layout is similar to the non-modular case, except that the modular jars are linked into the Java runtime image rather than being copied into the "app" directory.

        myoutput/
          myapp/
            app/
              myapp.cfg
            bin/
              myapp       [this is the native launcher]
            runtime/      [Java runtime; this is an implementation detail]

      You can see the list of modules in the packaged Java runtime by looking in the runtime/release text file. Since this is a modular application, you will see "mymod" in the list, since it has been jlinked into the Java runtime image.

      To execute the application, you run the launcher:

      myoutput/myapp/bin/myapp

      It will launch the application using "--module mymod/mypkg.MyApp"

      Modular example with multiple launchers (entry points)

      Running jpackage creates a primary (main) application launcher as configured by various command line options, including "--name", "--module", "--arguments", and "--java-options". Additional launchers can be created, with different entry points and arguments by running jpackage with the "--add-launcher" option. This example shows doing that for a modular application, but it can also be used for a non-modular application.

      We start with the same input layout as in the previous example. In this case, mymod.jar contains two main classes in the mymod module, mypkg.MyApp and mypkg.MyApp2. To create an additional launcher to execute the second main class, you would provide a properties file named "myapp2.properties" whose contents are as follows:

      module=mymod/mypkg.MyApp2

      In this case, you would use the following command to package up your application with multiple launchers:

      jpackage --output myoutput --name myapp \
          --add-launcher myapp2=myapp2.properties \
          --module-path myinput --module mymod/mypkg.MyApp

      The output layout is similar to the previous example, but with the additional launcher for the second entry point.

        myoutput/
          myapp/
            app/
              myapp.cfg
              myapp2.cfg
            bin/
              myapp       [this is the native launcher]
              myapp2      [this is the second native launcher]
            runtime/      [Java runtime; this is an implementation detail]

      To execute the first application, you run the launcher:

      myoutput/myapp/bin/myapp

      It will launch the application using "--module mymod/mypkg.MyApp"

      To execute the second application, you run the launcher:

      myoutput/myapp/bin/myapp2

      It will launch the application using "--module mymod/mypkg.MyApp2"

      Modular application using a custom runtime image produced by jlink

      If you want more control over the options that are used to create the custom Java runtime, or if you want to use jlink to package up an application with a different version of Java than the one used to run jpackage, you will need to run jlink first, and then use jpackage to create your application image from the runtime produced by jlink.

      Here is an example of running jlink with a specific set of arguments. It assumes the same input layout as in the previous modular application example.

      jlink --output myruntime --module-path myinput --add-modules mymod --bind-services \
          --compress=2 --strip-native-commands

      This will create a custom Java runtime in "myruntime" containing the application and dependent system modules.

      jpackage --output myoutput --name myapp --runtime-image myruntime \
          --module mymod/mypkg.MyApp

      The output layout will be similar to the other examples, but the Java runtime will be a copy of the "myruntime" as produced by jlink in the previous step.

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

      Command line options

      The jpackage usage is as follows:

      jpackage --help
      jpackage <options>

      Sample usages

      Generate a non-modular application image:

      jpackage -o outputdir -i inputdir -n name \
          --main-class className --main-jar MyJar.jar

      Generate a modular application image:

      jpackage -o outputdir -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 -o outputdir -n name \
          -m moduleName/className --runtime-image appRuntimeIMage

      Generate an application package:

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

      Generate a Java runtime package:

      jpackage --package-type <type> -o outputdir -n name \
          --runtime-image <runtime-image>

      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: {"exe", "msi", "rpm", "deb", "pkg", "dmg"}. If this option is not specified an application image 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

      --output -o <output path> — Path where generated output file is placed (absolute path or relative to the current directory)

      --temp-root <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-root 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", "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:

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

      --mac-bundle-identifier <ID string> — An identifier that uniquely identifies the application for MacOSX. Defaults to the value of --identifier option. 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 search for the signing identity (absolute path or relative to the current directory). If not specified, the standard keychains are used.

      --mac-signing-key-user-name <team name> — Team name portion in Apple signing identities' names. For example "Developer ID Application: "

      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.

      --identifier <id string> — An identifier that uniquely identifies the application. Defaults to the main class name. The value should be a valid DNS name.

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

      --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-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: " of the RPM .spec)

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

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                herrick Andy Herrick
                Reporter:
                vdrozdov Victor Drozdov (Inactive)
                Owner:
                Kevin Rushforth
                Reviewed By:
                Alan Bateman, Alexander Matveev, Alexey Semenyuk, Andy Herrick, Mandy Chung, William Harnois
                Endorsed By:
                Brian Goetz
              • Votes:
                4 Vote for this issue
                Watchers:
                28 Start watching this issue

                Dates

                • Due:
                  Created:
                  Updated: