JPACKAGE(1)

📦 version 21.0.12.1.1, in centos-stream 10, opensuse-leap 16.0

💖 NAME 💖

jpackage — from the JDK Commands manual — is literally the tool for packaging self-contained Java applications, bestie. Iconic behavior only. 🫶

✨ SYNOPSIS ✨

jpackage [options]

options — command-line options separated by spaces. See jpackage Options. Slay. 💅

🦋 DESCRIPTION 🦋

Okay so here's the vibe: the jpackage tool takes a Java application and a Java runtime image as input, and produces a Java application image that includes all the necessary dependencies. It can produce a native package in a platform-specific format, like an exe on Windows or a dmg on macOS. ✨

Important bestie warning: each format must be built on the platform it runs on. There is no cross-platform support. No cap. 🚫

The tool has options that allow packaged applications to be customized in various ways. Customization era. 🎀

🌈 JPACKAGE OPTIONS 🌈

🧸 Generic Options:

  • @filename — reads options from a file. This option can be used multiple times. File-based era. 📄
  • --type or -t type — the type of package to create. Valid values are: {"app-image", "exe", "msi", "rpm", "deb", "pkg", "dmg"}. If this option is not specified, a platform dependent default type will be created. Pick your fighter. 💅
  • --app-version version — version of the application and/or package. ✨
  • --copyright copyright — copyright for the application. 🫶
  • --description description — description of the application. 🌸
  • --help or -h — prints the usage text with a list and description of each valid option for the current platform to the output stream, and exits. Your little helper. 🧚
  • --icon path — path of the icon of the application package. It's an absolute path or relative to the current directory. Icon moment. 🎀
  • --name or -n name — name of the application and/or package. Main character name energy. 👑
  • --dest or -d destination — path where the generated output file is placed. Absolute path or relative to the current directory. Defaults to the current working directory. 💖
  • --temp directory — path of a new or empty directory used to create temporary files. Absolute path or relative to the current directory. If specified, the temp dir will not be removed upon task completion and must be removed manually. If not specified, a temporary directory will be created and removed upon task completion. Cleanup lore. 🧹
  • --vendor vendor — vendor of the application. 🫶
  • --verbose — enables verbose output. Spill the details. 📢
  • --version — prints the product version to the output stream and exits. Version check, but make it 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 stacking, but make it legal. 💅
  • --module-path or -p module-path [,module-path...] — a File.pathSeparator separated list of paths. Each path is either a directory of modules or the path to a modular jar, and is absolute or relative to the current directory. This option can be used multiple times. Path buffet. 🍓
  • --jlink-options options — a space separated list of options to pass to jlink. If not specified, defaults to "--strip-native-commands --strip-debug --no-man-pages --no-header-files". This option can be used multiple times. Jlink said customize me. ✨
  • --runtime-image directory — 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 specified by --jlink-options. Runtime image glow-up. 💖

🎀 Options for creating the application image:

  • --input or -i directory — 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. Everything goes in the bag. 👜
  • --app-content additional-content [,additional-content...] — a comma separated list of paths to files and/or directories to add to the application payload. This option can be used more than once. Extra content, because we love a loaded payload. 🎁

👑 Options for creating the application launcher(s):

  • --add-launcher name=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", "description", "arguments", "java-options", "app-version", "icon", "launcher-as-service", "win-console", "win-shortcut", "win-menu", "linux-app-category", and "linux-shortcut" 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. Launcher multiverse. 🌈
  • --arguments 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 options — options to pass to the Java runtime. This option can be used multiple times. Runtime gossip. 💬
  • --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 class said pick me. 👑
  • --main-jar main-jar — 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. Choose one, bestie. ⚖️
  • --module or -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. Module era, but again: not both. 🌀

🖥️ Platform dependent option for creating the application launcher:

🪟 Windows platform options (available only when running on Windows):

  • --win-console — creates a console launcher for the application, should be specified for application which requires console interactions. Console girlies rise. 💻

🍎 macOS platform options (available only when running on macOS):

  • --mac-package-identifier identifier — an identifier that uniquely identifies the application for macOS. Defaults to the main class name. May only use alphanumeric (A-Z,a-z,0-9), hyphen (-), and period (.) characters. Identifier rules are strict, bestie. 🎀
  • --mac-package-name name — 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. Menu bar moment. ✨
  • --mac-package-signing-prefix prefix — when signing the application package, this value is prefixed to all components that need to be signed that don't have an existing package identifier. Prefix behavior. 🫶
  • --mac-sign — requests that the package or the predefined application image be signed. Signature vibes. ✍️
  • --mac-signing-keychain keychain-name — name of the keychain to search for the signing identity. If not specified, the standard keychains are used. 🔑
  • --mac-signing-key-user-name name — team or user name portion in Apple signing identities. 🍎
  • --mac-app-store — indicates that the jpackage output is intended for the Mac App Store. App Store intended, no cap. 🛍️
  • --mac-entitlements path — path to file containing entitlements to use when signing executables and libraries in the bundle. Entitlements file lore. 📜
  • --mac-app-category category — string used to construct LSApplicationCategoryType in application plist. The default value is "utilities". Categorize it. 🗂️

📦 Options for creating the application package:

  • --about-url url — URL of the application's home page. Link moment. 🔗
  • --app-image directory — location of the predefined application image that is used to build an installable package (on all platforms) or to be signed (on macOS). Absolute path or relative to the current directory. App image said reuse me. ♻️
  • --file-associations path — path to a Properties file that contains a 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. Association station. 🚉
  • --install-dir path — absolute path of the installation directory of the application (on macOS or linux), or relative sub-path of the installation directory such as "Program Files" or "AppData" (on Windows). Install directory said know your place. 📁
  • --license-file path — path to the license file. Absolute path or relative to the current directory. Legal bestie. 📄
  • --resource-dir path — path to override jpackage resources. Absolute path or relative to the current directory. Icons, template files, and other resources of jpackage can be over-ridden by adding replacement resources to this directory. Resource override era. 🎨
  • --runtime-image path — path of the predefined runtime image to install. Absolute path or relative to the current directory. Option is required when creating a runtime installer. Runtime installer said don't forget me. 🚨
  • --launcher-as-service — request to create an installer that will register the main application launcher as a background service-type application. Background service behavior. 🫡

🪟 Platform dependent options for creating the application package:

🪟 Windows platform options (available only when running on Windows):

  • --win-dir-chooser — adds a dialog to enable the user to choose a directory in which the product is installed. User choice unlocked. 📂
  • --win-help-url url — URL where user can obtain further information or technical support. Help link, bestie. 🆘
  • --win-menu — request to add a Start Menu shortcut for this application. Start Menu said hi. 🪟
  • --win-menu-group menu-group-name — Start Menu group this application is placed in. Group assignment. 🗂️
  • --win-per-user-install — request to perform an install on a per-user basis. Per-user install vibes. 👤
  • --win-shortcut — request to create a desktop shortcut for this application. Desktop shortcut era. 🖥️
  • --win-shortcut-prompt — pops a dialog into the installer so the user gets to choose whether shortcuts get created or not ✨
  • --win-update-url url — the URL where the available update info for your app lives 💖
  • --win-upgrade-uuid id — the UUID associated with upgrades for this package 🎀

🐧 Linux platform options (available only when running on Linux)

  • --linux-package-name name — the name for the Linux package. Defaults to the application name, bestie 💅
  • --linux-deb-maintainer email-address — the maintainer for the .deb bundle
  • --linux-menu-group menu-group-name — the menu group this application gets placed in 🌸
  • --linux-package-deps — the required packages or capabilities for the application
  • --linux-rpm-license-type type — what type of license it is (that's the "License: value" of the RPM .spec, iykyk)
  • --linux-app-release release — the release value of the RPM <name>.spec file, or the Debian revision value of the DEB control file
  • --linux-app-category category-value — the group value of the RPM /.spec file, or the section value of the DEB control file
  • --linux-shortcut — creates a shortcut for the application. slay 🦋

🍎 macOS platform options (available only when running on macOS)

  • --mac-dmg-content additional-content[,additional-content...] — include all the referenced content in the dmg. You can use this option more than once, so go off 👑

🔥 JPACKAGE EXAMPLES

Generate an application package suitable for the host system:

For a modular application:

jpackage -n name -p modulePath -m moduleName/className

For a non-modular application:

jpackage -i inputDir -n name \
    --main-class className --main-jar myJar.jar

From a pre-built application image:

jpackage -n name --app-image appImageDir

Generate an application image ✨

For a modular application:

jpackage --type app-image -n name -p modulePath \
    -m moduleName/className

For a non-modular application:

jpackage --type app-image -i inputDir -n name \
    --main-class className --main-jar myJar.jar

To provide your own options to jlink, run jlink separately:

jlink --output appRuntimeImage -p modulePath \
    --add-modules moduleName \
    --no-header-files [<additional jlink options>...]
jpackage --type app-image -n name \
    -m moduleName/className --runtime-image appRuntimeImage

Generate a Java runtime package:

jpackage -n name --runtime-image <runtime-image>

Sign the predefined application image (on macOS):

jpackage --type app-image --app-image <app-image> \
    --mac-sign [<additional signing options>...]
Note: the only additional options that are permitted in this mode are: the set of additional mac signing options and --verbose 💀 don't try to sneak anything else in, bestie.

🎀 JPACKAGE RESOURCE DIRECTORY

Icons, template files and other resources of jpackage can be overridden by dropping replacement resources into this directory. jpackage looks files up by very specific names in the resource directory, so the names matter, fr fr 🙈

🐧 Resource directory files considered only when running on Linux

  • <launcher-name>.png — the application launcher icon. Default resource is JavaApp.png
  • <launcher-name>.desktop — a desktop file to be used with the xdg-desktop-menu command. Considered with application launchers registered for file associations and/or that have an icon. Default resource is template.desktop

📦 Resource directory files considered only when building Linux DEB/RPM installer

  • <package-name>-<launcher-name>.service — systemd unit file for an application launcher registered as a background service-type application. Default resource is unit-template.service

🔴 Resource directory files considered only when building Linux RPM installer

  • <package-name>.spec — RPM spec file. Default resource is template.spec

🟣 Resource directory files considered only when building Linux DEB installer

  • control — control file. Default resource is template.control
  • copyright — copyright file. Default resource is template.copyright
  • preinstall — pre-install shell script. Default resource is template.preinstall
  • prerm — pre-remove shell script. Default resource is template.prerm
  • postinstall — post-install shell script. Default resource is template.postinstall
  • postrm — post-remove shell script. Default resource is template.postrm

🪟 Resource directory files considered only when running on Windows

  • <launcher-name>.ico — application launcher icon. Default resource is JavaApp.ico
  • <launcher-name>.properties — properties file for the application launcher executable. Default resource is WinLauncher.template

💠 Resource directory files considered only when building Windows MSI/EXE installer

  • <application-name>-post-image.wsf — a Windows Script File (WSF) to run after building the application image
  • main.wxs — main WiX project file. Default resource is main.wxs
  • overrides.wxi — overrides WiX project file. Default resource is overrides.wxi
  • service-installer.exe — service installer executable. Considered if some application launchers are registered as background service-type applications
  • <launcher-name>-service-install.wxi — service installer WiX project file. Considered if some application launchers are registered as background service-type applications. Default resource is service-install.wxi
  • <launcher-name>-service-config.wxi — service installer WiX project file. Considered if some application launchers are registered as background service-type applications. Default resource is service-config.wxi
  • InstallDirNotEmptyDlg.wxs — WiX project file for the installer UI dialog that checks the installation directory doesn't exist or is empty. Default resource is InstallDirNotEmptyDlg.wxs
  • ShortcutPromptDlg.wxs — WiX project file for the installer UI dialog that configures shortcuts. Default resource is ShortcutPromptDlg.wxs
  • bundle.wxf — WiX project file with the hierarchy of components of the application image
  • ui.wxf — WiX project file for installer UI

🧚 Resource directory files considered only when building Windows EXE installer

  • WinInstaller.properties — properties file for the installer executable. Default resource is WinInstaller.template
  • <package-name>-post-msi.wsf — a Windows Script File (WSF) to run after building the embedded MSI installer for the EXE installer

🌈 Resource directory files considered only when running on macOS

  • <launcher-name>.icns — application launcher icon. Default resource is JavaApp.icns
  • Info.plist — application property list file. Default resource is Info-lite.plist.template
  • Runtime-Info.plist — Java Runtime property list file. Default resource is Runtime-Info.plist.template
  • <application-name>.entitlements — signing entitlements property list file. Default resource is sandbox.plist

🍓 Resource directory files considered only when building macOS PKG/DMG installer

  • <package-name>-post-image.sh — shell script to run after building the application image

💜 Resource directory files considered only when building macOS PKG installer

  • uninstaller — uninstaller shell script. Considered if some application launchers are registered as background service-type applications. Default resource is uninstall.command.template
  • preinstall — pre-install shell script. Default resource is preinstall.template
  • postinstall — post-install shell script. Default resource is postinstall.template
  • services-preinstall — pre-install shell script for the services package. Considered if some application launchers are registered as background service-type applications. Default resource is services-preinstall.template
  • services-postinstall — post-install shell script for the services package. Considered if some application launchers are registered as background service-type applications. Default resource is services-postinstall.template
  • <package-name>-background.png — background image. Default resource is background_pkg.png
  • <package-name>-background-darkAqua.png — dark background image. Default resource is background_pkg.png
  • product-def.plist — package property list file. Default resource is product-def.plist
  • <package-name>-<launcher-name>.plist — launchd property list file for an application launcher registered as a background service-type application. Default resource is launchd.plist.template

🦋 Resource directory files considered only when building macOS DMG installer

  • <package-name>-dmg-setup.scpt — setup AppleScript script. Default resource is DMGsetup.scpt
  • <package-name>-license.plist — license property list file. Default resource is lic_template.plist
  • <package-name>-background.tiff — background image. Default resource is background_dmg.tiff
  • <package-name>-volume.icns — volume icon. Default resource is JavaApp.icns

and that's the whole page, bestie! 💖✨ This one's from the JDK 21 era, dated 2023, and it's the JPACKAGE(1) manual page — go forth and package something iconic 🎀🫶

📦 where this page comes from