Override jpackage Resources

6 Override jpackage Resources

Advanced customization of the package generated is possible by overriding resources used by jpackage, such as background images and template files for properties and scripts. The --resource-dir option is used to provide the overrides to the tool.

If the default resources that jpackage uses when packaging an application don't meet your needs, create a directory and add your customized files to it. If you override a file, your custom file must contain all of the properties that the default contains. Pass the path to the directory to jpackage using the --resource-dir option. The path can be absolute or relative to the current directory.

Note:

Resources such as icons, application version, application description, copyright, and others can be overridden from the command line. Use of the command line options is recommended when available.

The topics that follow describe the resources that you can override and explain how you can find out what the defaults are.

Topics:

Resources Used in Packaging

The packaging tool has default templates and other resources that it uses when it generates the package for your application.

The resources vary by platform and are described in the following sections. In most cases, resources overridden with command line options take precedence over resources in the resource directory. To override resources that can't be overridden from the command line, add your customized files to the resource directory that you pass to jpackage. Use the --verbose option described in View Resources to verify the name of the override file for each resource.

Linux (all versions)

Icon file, launcher.png, for the main launcher and any additional launchers. Each launcher can have a separate icon. The file name must match the name of the application or the name of a launcher. If an icon file is not provided for a launcher, the default icon is used.
Desktop shortcut file, launcher.desktop, for the main launcher and any additional launchers The file name must match the name of the application or the name of a launcher.

Linux DEB

Control template, control. File that contains information about the application.
Pre-installation script, preinst. Script that is run before the application is installed.
Pre-removal script, prerm. Script that is run before the application is uninstalled.
Post-installation script, postinst. Script that is run after installation completes.
Post-removal script, postrm. Script that is run after the application is uninstalled.
Copyright file, copyright. File that contains copyright and license information.

Linux RPM

Specification for packaging, package-name.spec. Instructions for packaging the application.

macOS (all formats)

Icon file, launcher.icns, for the main launcher and any additional launchers. More than one file can be provided. The file name must match the name of the application or the name of a launcher. If an icon file is not provided for a launcher, the default icon is used.
Runtime properties list, Runtime-Info.plist.
Information properties list, Info.plist.
Default entitlements file, default.plist.
Default entitlements file for application packages distributed through Mac App Store, sandbox.plist.
Post-image script, application-name-post-image.sh. Custom script that is executed after the application image is created and before the DMG or PKG installer is built. No default script is provided.

macOS DMG

DMG setup script, application-name-dmg-setup.scpt.
Applications license properties list, application-name-license.plist.
Background file, application-name-background.tiff.
Drive icon, application-name-volume.icns.

macOS PKG

Pre-installation script, preinstall. Script that is run before the application is installed.
Post-installation script, postinstall. Script that is run after installation completes.
Background image for Light Mode, application-name-background.png.
Background image for Dark Mode, application-name-background-darkAqua.png.

Windows

Post-image script, application-name-post-image.wsf. Custom script that is executed after the application image is created and before the MSI installer is built for both .msi and .exe packages. No default script is provided.
Main WiX source file, main.wxs.
WiX source file with WiX variables overrides, overrides.wxi. Values in this file override values in the main WiX file.
Icon file, launcher.ico, for the main launcher and any additional launchers. More than one file can be provided. The file name must match the name of the application or the name of a launcher. If an icon file is not provided for a launcher, the default icon is used.
Launcher properties file, launcher.properties.

View Resources

You can use the --verbose and --temp options for jpackage to get information about the resources used to package your application.

To decide if you need to override the jpackage resources, review the current defaults:

Use the --verbose option to see what is currently used.

The --verbose option provides detailed information about the process of creating the package. The information also includes instructions for customizing the resource, such as the name of the file to add to the resource directory.

The following example shows the jpackage command run on Windows to package the Dynamic Tree application, followed by snippets of the output from the --verbose option that show the default resources used. Note that to override the WinLauncher.template resource, a file named DynamicTree.properties is needed; to override the main.wxs resource, a file named main.wxs is needed

jpackage --input DynamicTree --main-jar DynamicTree.jar --verbose
WARNING: Using incubator modules: jdk.incubator.jpackage
Running [candle.exe, /?]
Running [C:\Program Files (x86)\WiX Toolset v3.11\bin\candle.exe, /?]
Windows Installer XML Toolset Compiler version 3.11.1.2318

   ...

Using default package resource java48.ico [icon] (add DynamicTree.ico to the resource-dir to customize).
Using default package resource WinLauncher.template [Template for creating executable properties file] 
(add DynamicTree.properties to the resource-dir to customize).

   ...

Using default package resource main.wxs [Main WiX project file] (add main.wxs to the resource-dir to 
customize).
Using default package resource overrides.wxi [Overrides WiX project file] (add overrides.wxi to the 
resource-dir to customize).

   ...

Use the --temp option to keep temporary files for review.

The --temp option provides jpackage with the name of a new or empty directory where temporary files are written during the packaging process. The path passed to jpackage can be absolute or relative to the current directory. When this option is used, the directory is not deleted at the end of the process.

Review this directory to see the resources that were used to package your application. Review each file to identify the properties and values that you might want to override. If you override a file, your custom file must contain all of the properties that the default contains.

The following example shows the directory created on Windows. The config directory contains resources that you can override.
```
jpackage --input DynamicTree --main-jar DynamicTree.jar \
   --temp DTtempfiles

\DTtempfiles
   \config
      DynamicTree.ico
      DynamicTree.properties
      main.wxs
      MsiInstallerStrings_en.wxl
      MsiInstallerStrings_ja.wxl
      MsiInstallerStrings_zh.wxl
      overrides.wxi
   \images
   \wixobj
```