JPackage Gradle Plugin

Gradle plugin for jpackage tool.

Finding jpackage

Plugin searches for jpackage executable using the following priority list:

1. Configured toolchain

2. java.home system property.

Though rarely required it is possible to override toolchain for particular jpackage task:

javaLauncher = javaToolchains.launcherFor {
    languageVersion = JavaLanguageVersion.of(21)
}

Configuration

There are generic jpackage parameters as well as OS-specific parameters for OS X, Linux, Windows. OS-specific parameters are processed when build is done on the corresponding OS.

If some generic parameters should have different values based on OS then they should be placed into configuration blocks:

• windows
• mac
• linux

Example:

// Windows specific parameters will be processed only during Windows build
winMenu = true
winDirChooser = true

mac {
    // Generic parameter value for OS X build
    icon = layout.projectDirectory.file("icons/icons.icns")
}

windows {
    // Generic parameter value for Windows build
    icon = layout.projectDirectory.file("icons/icons.ico")
}

Parameters

Parameter	Type	JPackage Argument	Min Version	Max Version
Generic
aboutUrl	Property<String>	--about-url <url>	17	*
addModules	ListProperty<String>	--add-modules <module>[,<module>]	14	*
appDescription	Property<String>	--description <description string>	14	*
appContent	ConfigurableFileCollection	--app-content additional-content[,additional-content...]	18	*
appImage	Property<String>	--app-image <name>	14	*
appName	Property<String>	--name <name>	14	*
appVersion	Property<String>	--app-version <version>	14	*
arguments	ListProperty<String>	--arguments <main class arguments>	14	*
copyright	Property<String>	--copyright <copyright string>	14	*
destination	DirectoryProperty	--dest <destination path>	14	*
fileAssociations	ConfigurableFileCollection	--file-associations <file association property file>	14	*
icon	RegularFileProperty	--icon <icon file path>	14	*
input	DirectoryProperty	--input <input path>	14	*
installDir	Property<String>	--install-dir <file path>	14	*
javaOptions	ListProperty<String>	--java-options <options>	14	*
jLink	Property<JLink>	--jlink-options <options>	16	*
jLinkOptions	ListProperty<String>	--jlink-options <options>	16	*
launchers	ListProperty<Launcher>	--add-launcher <name>=<property file>	14	*
launcherAsService	Property<Boolean>	--launcher-as-service	19	*
licenseFile	RegularFileProperty	--license-file <license file path>	14	*
mainClass	Property<String>	--main-class <class name>	14	*
mainJar	Property<String>	--main-jar <main jar file>	14	*
module	Property<String>	--module <module name>[/<main class>]	14	*
modulePaths	ConfigurableFileCollection	--module-path <module path>	14	*
resourceDir	DirectoryProperty	--resource-dir <resource dir path>	14	*
runtimeImage	DirectoryProperty	--runtime-image <file path>	14	*
temp	DirectoryProperty	--temp <temp dir path>	14	*
type	Property<ImageType>	--type <type>	14	*
vendor	Property<String>	--vendor <vendor string>	14	*
verbose	Property<Boolean>	--verbose	14	*
Windows
winConsole	Property<Boolean>	--win-console	14	*
winDirChooser	Property<Boolean>	--win-dir-chooser	14	*
winHelpUrl	Property<String>	--win-help-url <url>	17	*
winMenu	Property<Boolean>	--win-menu	14	*
winMenuGroup	Property<String>	--win-menu-group <menu group name>	14	*
winPerUserInstall	Property<Boolean>	--win-per-user-install	14	*
winShortcut	Property<Boolean>	--win-shortcut	14	*
winShortcutPrompt	Property<Boolean>	--win-shortcut-prompt	17	*
winUpdateUrl	Property<String>	--win-update-url <url>	17	*
winUpgradeUuid	Property<String>	--win-upgrade-uuid <id string>	14	*
OS X
macAppCategory	Property<String>	--mac-app-category <category string>	17	*
macAppStore	Property<Boolean>	--mac-app-store	17	*
macBundleSigningPrefix	Property<String>	--mac-bundle-signing-prefix <prefix string>	14	16
macDmgContent	ConfigurableFileCollection	--mac-dmg-content additional-content[,additional-content...]	18	*
macEntitlements	RegularFileProperty	--mac-entitlements <file path>	17	*
macPackageIdentifier	Property<String>	--mac-package-identifier <ID string>	14	*
macPackageName	Property<String>	--mac-package-name <name string>	14	*
macPackageSigningPrefix	Property<String>	--mac-package-signing-prefix <prefix string>	17	*
macSign	Property<Boolean>	--mac-sign	14	*
macSigningKeychain	Property<String>	--mac-signing-keychain <keychain name>	14	*
macSigningKeyUserName	Property<String>	--mac-signing-key-user-name <team name>	14	*
Linux
linuxAppCategory	Property<String>	--linux-app-category <category value>	14	*
linuxAppRelease	Property<String>	--linux-app-release <release value>	14	*
linuxDebMaintainer	Property<String>	--linux-deb-maintainer <email address>	14	*
linuxMenuGroup	Property<String>	--linux-menu-group <menu-group-name>	14	*
linuxPackageName	Property<String>	--linux-package-name <package name>	14	*
linuxPackageDeps	Property<String>	--linux-package-deps <package-dep-string>	14	*
linuxRpmLicenseType	Property<String>	--linux-rpm-license-type <type string>	14	*
linuxShortcut	Property<Boolean>	--linux-shortcut	14	*

Since version 1.7.0 the plugin does not check if parameter is applicable to jpackage tool version. Users are advised to consult the corresponding User's Guide.

Image Type

Plugin Value	JPackage Type
DEFAULT	Default image type, OS specific
APP_IMAGE	app-image
DMG	dmg
PKG	pkg
EXE	exe
MSI	msi
RPM	rpm
DEB	deb

Launchers

Launchers are defines using class Launcher:

launchers = listOf(
    Launcher("launcher_1", layout.projectDirectory.file("launcher_1.properties").asFile),
    Launcher("launcher_2", layout.projectDirectory.file("launcher_2.properties").asFile)
)

Destination Directory

jpackage utility fails if output directory already exists. At the same time gradle always creates plugin output directory.

In order to work around this behaviour plugin always tries to delete directory specified by destination before launching jpackage.

For safety reasons destination must point to the location inside ${layout.buildDirectory}.

Example:

destination = layout.buildDirectory.dir("dist")

Default Command-Line Arguments

Default command line arguments are passed to the main class when the application is started without providing arguments.

Example:

arguments = listOf(
    "SomeArgument",
    "Argument with spaces",
    "Argument with \"quotes\""
)

JVM Options

Options that are passed to the JVM when the application is started.

Example:

javaOptions = listOf(
    "-Xms2m",
    "-Xmx10m"
)

jlink options

Options that are passed to underlying jlink call.

Example:

jLinkOptions = listOf(
    "--strip-native-commands",
    "--strip-debug"
)

Another way is to use jLink property of class JLink:

Field	Type	jlink Option
bindServices	boolean	--bind-services
noHeaderFiles	boolean	--no-header-files
noManPages	boolean	--no-man-pages
stripDebug	boolean	--strip-debug
stripNativeCommands	boolean	--strip-native-commands
generateCdsArchive	boolean	--generate-cds-archive

Example:

jLink = JLink().apply {
    stripNativeCommands = true
    noHeaderFiles = true
    noManPages = true
    stripDebug = true
}

Both ways can be used together if required.

jpackage Environment Variables

Optionally environment variables can be passed to jpackage executable process.

Example:

jpackageEnvironment = mapOf(
    "GRADLE_DIR" to project.projectDir.absolutePath,
    "BUILD_DIR" to project.buildDir.absolutePath
)

null values as well as null or empty keys are ignored.

Logging

Plugin uses LogLevel.INFO to print various information about toolchain, jpackage parameters, etc. Use gradle option --info to check this output.

Dry Run Mode

To execute plugin tasks in dry run mode without calling jpackage set propertyjpackage.dryRun to true.

Example:

$ ./gradlew clean build jpackage --info -Djpackage.dryRun=true

Configuration Cache

This plugin should be compatible with Gradle configuration cache.

Examples

• Modular Application with Full Runtime
• Modular Application with jlink
• Non-Modular Application

References

Packaging Tool User's Guide