4 Manage the Installation of Your Application

You have some control over how your application is installed and launched on the user's system. Using options provided by the packaging tool, you can specify such things as the license to be accepted, where to install the application, and if a console is needed.

Topics:

• Include a License

• Set the Installation Directory

• Create a Shortcut

• Add the Application to a Menu

• Launch in Console

Include a License

If you have terms and conditions that you want users to accept to install your application on Windows or macOS, use the --license-file option when you package your application.

If the directory that contains your application also includes a license file, that file is installed on the user's machine with the application. If you want to require the user to accept the license before installing on Windows or macOS, use the --license-file option. Be aware that if you provide a license file that is not in the application directory, the user is shown the license when installing, but the file is not installed with the application. Also, for silent and other types of installs, the license file is not shown.

The following command adds the license file myApps/myLicense.txt to the package for the Dynamic Tree application.

jpackage --type exe --name DynamicTreeDemo --input myApps \
   --main-jar DynamicTree.jar --license-file myApps/myLicense.txt

Create a Shortcut

To have a shortcut created when users install your application, use the --linux-shortcut or --win-shortcut option when you package your application. To show a custom icon for your application, use the --icon option.

Shortcuts are supported for Linux and Windows platforms. If you don't provide an icon, a default icon is used. If you provide a custom icon on Linux, a shortcut is automatically created and the --linux-shortcut option is not needed. Custom icons must be in a format that meets the requirements of the platform.

The following command creates a shortcut with the default icon for the Dynamic Tree application when it is installed on Linux.

jpackage --name DynamicTreeDemo --input myApps --main-jar DynamicTree.jar \
   --linux-shortcut

The following command creates a desktop shortcut with a custom icon for the Dynamic Tree application when it is installed on Windows.

jpackage --name DynamicTreeDemo --input myApps --main-jar DynamicTree.jar \
   --icon DTDemo.ico --win-shortcut

Set the Installation Directory

If you want the name of the installation directory to be different than the name of the package, use the --install-dir option. On Windows you can let the user choose where to install your application by using the --win-dir-chooser option.

Your application is installed in the default platform-specific installation directory described in Defaults for Options Not Specified. The directory name for the application defaults to the package name, but this can be changed with the --install-dir option when you package the application.

On Windows, you also have the option to enable the user to choose the installation location. The dialog shown defaults to a directory with the package name.

The following command installs the Dynamic Tree application in c:\Program Files\DTDemo instead of c:\Program Files\DynamicTreeDemo.

jpackage --type exe --name DynamicTreeDemo --input myApps \
   --main-jar DynamicTree.jar --install-dir DTDemo

The following command lets the user choose the directory where the application is installed.

jpackage --type exe --name DynamicTreeDemo --input myApps \
   --main-jar DynamicTree.jar --win-dir-chooser

Add the Application to a Menu

To let users access your application from a menu, use the --linux-menu-group option, or the --win-menu and --win-menu-group options when you package your application.

On the Linux platform, if the --linux-menu-group option is not used, your application is added to the Unknown group in a menu specific to the window manager being used.

On the Windows platform, you can have your application added to the Start menu in the group of your choosing. If the group doesn't exist, it is created. If you don't provide a group name, the application is added to the Unknown group. The --win-menu-group option is only meaningful if the --win-menu option is used.

The following command adds the Dynamic Tree application to the Windows Start menu in the "Small, Inc" group. Quotes are needed only if the name includes spaces.

jpackage --type exe --name DynamicTreeDemo --input myApps \
   --main-jar DynamicTree.jar --win-menu --win-menu-group "Small, Inc"

On macOS, the application is shown in the menu bar. The name shown defaults to the name of the package. The following command uses the --mac-package-name option to show DTDemo in the menu bar.

jpackage --name DynamicTreeDemo --input myApps --main-jar DynamicTree.jar \
   --mac-package-name DTDemo

Launch in Console

If your application runs from the command line or requires console interaction, use the --win-console option to let Windows know to start the application in a console window.

The following command tells Windows to start the Hello World application with a console window.

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