2 Basic Packaging

If your application doesn't require customizations or support for features such as multiple launchers or file associations, then only a couple of options are needed for packaging.

The simplest form of packaging requires the location of the application to package and the name of the JAR or module that contains the main class.

  • The following example packages a non-modular application:

    jpackage --input app-directory --main-jar jar-file [--main-class main-class]

    app-directory is the name of the directory that contains the files for your application. The path can be absolute or relative to the current directory. jar-file is the name of the JAR file that contains the main class for the application. main-class is the name of the main class and is only required if the main class is not identified in the MANIFEST.MF file. Tool and platform defaults are used as needed to complete the package.

  • The following example packages a modular application:

    
    jpackage --module-path module-path --module main-module[/class]

    module-path is the path to either a directory of modules or to a modular JAR file. The path can be absolute or relative to the current directory. For more than one path, separate the paths with a colon (:) on Linux and macOS or a semi-colon (;) on Windows, or use multiple instances of the --module-path option. main-module/class is the name of the module that contains the main class and the name of the main class for the application. The name of the main class is only required if the main module does not identify the main class. Tool and platform defaults are used as needed to complete the package.

Defaults for Options Not Specified

Options are available to control the name of the application, type of package created, installation location, and other characteristics of the package. If an option is not provided, a default values is used.

The following defaults apply to options that are not specified when running jpackage:

  • The package type is platform-dependent:

    • On Linux, the default is deb for Debian Linux and rpm for other versions of Linux.
    • On macOS, the default is dmg.
    • On Windows, the default is exe.

    To generate a different type of package, use the --type option.

  • The generated package is written to the current working directory. To write the package to a different location, use the --dest option.

  • The name of the package is generated from the name of the application and the application version. If no application name is provided, the name of the main JAR or module is used, followed by the version, which defaults to 1.0, for example HelloWorld-1.0.exe. To change the name of the application, use the --name option. To change the version, use the --app-version option.

  • The Java runtime is generated during the packaging process using the jlink command. The --add-modules and --bind-services options can be used to add items to the runtime as part of the packaging process. To package a custom runtime, use the --runtime-image option.

  • The installation directory is platform-specific:
    • On Linux, the default is /opt/application-name
    • On macOS, the default is /Applications/application-name
    • On Windows, the default is c:\Program Files\application-name; if the --win-per-user-install option is used, the default is C:\Users\user-name\AppData\Local\application-name

    The name of the application directory defaults to the name of the application. To give the directory a different name, use the --install-dir option.

  • The name of the application launcher defaults to the name of the application. If your application has more than one launcher, use the --add-launcher option to identify them.

  • No default command line arguments or Java runtime options are passed to the application when it is started. The user can pass application arguments from the command line when launching the application, but not Java runtime options.

  • A default icon for the application is used. For a different icon, use the --icon option.

  • For Linux, the name of the package defaults to the application name. To give the package a different name, use the --linux-package-name option.

  • For macOS:

    • The application identifier defaults to the main class name. To use a different identifier, use the --mac-package-identifier option.

    • The name of the application shown in the menu bar defaults to the main class name of the application. To use a different name, use the --mac-package-name option.

Package a Non-Modular Application

A non-modular application package can be packaged by providing just the location of the files to package and the name of the main JAR file. Defaults are used for other options that describe the package and the application.

The following command when run on a Windows system packages the non-modular application in the mySamples\hwapp directory with the main class in the HelloWorld.jar file.

jpackage --input mySamples\hwapp --main-jar HelloWorld.jar 

Because no other options are used, the following defaults are applied:

  • The default type of package generated is exe.

  • The name of the package generated is HelloWorld-1.0.exe.

  • The package is written to the current directory.

  • The runtime packaged with the application is generated as part of the packaging process.

  • The application is installed in the c:\Program Files\HelloWorld directory.

  • The name of the launcher is HelloWorld.exe.

  • The default icon is used for the application.

  • No shortcut is created, and the application is not added to any menu. The user must go to the directory in which the application is installed to run it.

  • No default arguments or Java runtime options are passed to the application when it is started.

Package a Modular Application

A modular application package can be packaged by providing just the location of the modules to package and the name of the main module. Defaults are used for other options that describe the package and the application.

The following command when run on a Debian Linux system packages the modular application in the myModApps directory with the main class in the modhw/modhw.HelloWorldMod module

jpackage --module-path myModApps --module modhw/modhw.HelloWorldMod

Because no other options are used, the following defaults are applied:

  • The default type of package generated is deb for Debian systems

  • The name of the package generated is HelloWorldMod-1.0.deb.

  • The package is written to the current directory.

  • The runtime packaged with the application is generated as part of the packaging process.

  • The application is installed the /opt/HelloWorldMod directory.

  • The name of the launcher is HelloWorldMod.

  • The default icon is used for the application.

  • No shortcut is created, and the application is not added to any menu. The user must go to the directory in which the application is installed to run it.

  • No default arguments or Java runtime options are passed to the application when it is started.

Identify Your Application with Package Metadata

As you create the package, you might want to provide information about the application, such as a description, the vendor name, or perhaps a copyright statement.

To add information about your application to the package, use the relevant jpackage options to set the package metadata. The following examples are for a Windows system.
  • Set the name of the application.

    Use the --name option to give the application the name that you want users to see. If no name is provided, it defaults to the name of the main JAR file or module.

    The following command creates a package for the Dynamic Tree application named DynamicTreeDemo-1.0.exe:

    jpackage --name DynamicTreeDemo --input myApps \
       --main-jar DynamicTree.jar 
  • Set the application version.

    Use the --app-version option to identify the version of your application. If no application version is specified, the version defaults to 1.0.

    The following command customizes the version part of the package name and creates the package DynamicTreeDemo-2.0.exe:

    jpackage --name DynamicTreeDemo --app-version 2.0 \
       --input myApps --main-jar DynamicTree.jar
  • Describe the application.

    Use the --description option to include a brief description of your application. No default description is provided.

    The following command describes the Dynamic Tree application to users; note that quotes are required if the description includes spaces:

    jpackage --dest packages --name DynamicTreeDemo \
       --app-version 2.0 --input myApps --main-jar DynamicTree.jar \
       --description "Demo application for testing functionality"
  • Set the vendor for the application.

    Use the --vendor option to identify yourself or your company as the creator of your application. No default vendor is provided.

    The following command identifies the vendor of the Dynamic Tree application as Small, Inc; note that quotes are required if the vendor name includes spaces:

    jpackage --dest packages --name DynamicTreeDemo \
       --app-version 2.0 --input myApps --main-jar DynamicTree.jar \
       --description "Demo application for testing functionality" \
       --vendor "Small, Inc"
  • Set the copyright for the application.

    Use the --copyright option to provide a copyright for your application. No default copyright is provided.

    The following command provides an example of a copyright statement for the Dynamic Tree application; note that quotes are required if the copyright includes spaces:

    jpackage --dest packages --name DynamicTreeDemo \
       --app-version 2.0 --input myApps --main-jar DynamicTree.jar \
       --description "Demo application for testing functionality" \
       --vendor "Small, Inc" --copyright "Copyright 2020, All rights reserved"