| --- | |
| # Copyright (c) 2018, 2025, Oracle and/or its affiliates. All rights reserved. | |
| # DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. | |
| # | |
| # This code is free software; you can redistribute it and/or modify it | |
| # under the terms of the GNU General Public License version 2 only, as | |
| # published by the Free Software Foundation. | |
| # | |
| # This code is distributed in the hope that it will be useful, but WITHOUT | |
| # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
| # FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
| # version 2 for more details (a copy is included in the LICENSE file that | |
| # accompanied this code). | |
| # | |
| # You should have received a copy of the GNU General Public License version | |
| # 2 along with this work; if not, write to the Free Software Foundation, | |
| # Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. | |
| # | |
| # Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA | |
| # or visit www.oracle.com if you need additional information or have any | |
| # questions. | |
| # | |
| title: 'JPACKAGE(1) JDK @@VERSION_SHORT@@ | JDK Commands' | |
| date: @@COPYRIGHT_YEAR@@ | |
| lang: en | |
| --- | |
| ## Name | |
| jpackage - tool for packaging self-contained Java applications. | |
| ## Synopsis | |
| `jpackage` \[*options*\] | |
| *options* | |
| : Command-line options separated by spaces. See [jpackage Options]. | |
| ## Description | |
| The `jpackage` tool will take as input a Java application and a Java run-time image, and produce a Java application image that includes all the necessary dependencies. It will be able to produce a native package in a platform-specific format, such as an exe on Windows or a dmg on macOS. Each format must be built on the platform it runs on, there is no cross-platform support. The tool will have options that allow packaged applications to be customized in various ways. | |
| ## jpackage Options | |
| ### Generic Options: | |
| `@`*filename* | |
| : Read options from a file. | |
| This option can be used multiple times. | |
| <a id="option-type">`--type` or `-t` *type*</a> | |
| : 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. | |
| <a id="option-app-version">`--app-version` *version*</a> | |
| : Version of the application and/or package | |
| <a id="option-copyright">`--copyright` *copyright*</a> | |
| : Copyright for the application | |
| <a id="option-description">`--description` *description*</a> | |
| : Description of the application | |
| <a id="option-help">`--help` or `-h`</a> | |
| : Print the usage text with a list and description of each valid | |
| option for the current platform to the output stream, and exit. | |
| <a id="option-icon">`--icon` *path*</a> | |
| : Path of the icon of the application package | |
| (absolute path or relative to the current directory) | |
| <a id="option-name">`--name` or `-n` *name*</a> | |
| : Name of the application and/or package | |
| <a id="option-dest">`--dest` or `-d` *destination*</a> | |
| : Path where generated output file is placed | |
| (absolute path or relative to the current directory). | |
| Defaults to the current working directory. | |
| <a id="option-resource-dir">`--resource-dir` *path*</a> | |
| : 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. | |
| <a id="option-temp">`--temp` *directory*</a> | |
| : 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 the task | |
| completion and must be removed manually. | |
| If not specified, a temporary directory will be created and | |
| removed upon the task completion. | |
| <a id="option-vendor">`--vendor` *vendor*</a> | |
| : Vendor of the application | |
| <a id="option-verbose">`--verbose`</a> | |
| : Enables verbose output. | |
| <a id="option-version">`--version`</a> | |
| : Print the product version to the output stream and exit. | |
| ### Options for creating the runtime image: | |
| <a id="option-add-modules">`--add-modules` *module-name* \[`,`*module-name*...\]</a> | |
| : 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. | |
| <a id="option-module-path">`--module-path` or `-p` *module-path* \[`,`*module-path*...\]</a> | |
| : 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. | |
| <a id="option-jlink-options">`--jlink-options` *options*</a> | |
| : 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. | |
| <a id="option-runtime-image">`--runtime-image` *directory*</a> | |
| : 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. | |
| ### Options for creating the application image: | |
| <a id="option-input">`--input` or `-i` *directory*</a> | |
| : 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. | |
| <a id="option-app-content">`--app-content` *additional-content* \[`,`*additional-content*...\]</a> | |
| : 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. | |
| ### Options for creating the application launcher(s): | |
| <a id="option-add-launcher">`--add-launcher` *name*=*path*</a> | |
| : 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", "icon", "launcher-as-service", | |
| "win-console", "win-shortcut", "win-menu", 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. | |
| <a id="option-arguments">`--arguments` *arguments*</a> | |
| : 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. | |
| Value can contain substrings that will be expanded at runtime. | |
| Two types of such substrings are supported: environment variables | |
| and "APPDIR", "BINDIR", and "ROOTDIR" tokens. | |
| An expandable substring should be enclosed between the dollar | |
| sign character ($) and the first following non-alphanumeric | |
| character. Alternatively, it can be enclosed between "${" and "}" | |
| substrings. | |
| Expandable substrings are case-sensitive on Unix and | |
| case-insensitive on Windows. No string expansion occurs if the | |
| referenced environment variable is undefined. | |
| Environment variables with names "APPDIR", "BINDIR", and "ROOTDIR" | |
| will be ignored, and these expandable substrings will be | |
| replaced by values calculated by the app launcher. | |
| Prefix the dollar sign character with the backslash character (\\) | |
| to prevent substring expansion. | |
| <a id="option-java-options">`--java-options` *options*</a> | |
| : Options to pass to the Java runtime | |
| This option can be used multiple times. | |
| Value can contain substrings that will be substituted at runtime, | |
| such as for the --arguments option. | |
| <a id="option-main-class">`--main-class` *class-name*</a> | |
| : Qualified name of the application main class to execute | |
| This option can only be used if --main-jar is specified. | |
| <a id="option-main-jar">`--main-jar` *main-jar*</a> | |
| : 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. | |
| <a id="option-module">`--module` or `-m` *module-name*[/*main-class*]</a> | |
| : 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. | |
| ### Platform dependent options for creating the application launcher: | |
| #### Windows platform options (available only when running on Windows): | |
| <a id="option-win-console">`--win-console`</a> | |
| : Creates a console launcher for the application, should be | |
| specified for application which requires console interactions | |
| #### macOS platform options (available only when running on macOS): | |
| <a id="option-mac-package-identifier">`--mac-package-identifier` *identifier*</a> | |
| : 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. | |
| <a id="option-mac-package-name">`--mac-package-name` *name*</a> | |
| : 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. | |
| <a id="option-mac-package-signing-prefix">`--mac-package-signing-prefix` *prefix*</a> | |
| : 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. | |
| <a id="option-mac-sign">`--mac-sign`</a> | |
| : Request that the package or the predefined application image be signed. | |
| <a id="option-mac-signing-keychain">`--mac-signing-keychain` *keychain-name*</a> | |
| : Name of the keychain to search for the signing identity | |
| If not specified, the standard keychains are used. | |
| <a id="option-mac-signing-key-user-name">`--mac-signing-key-user-name` *name*</a> | |
| : Team or user name portion in Apple signing identities | |
| <a id="option-mac-app-store">`--mac-app-store`</a> | |
| : Indicates that the jpackage output is intended for the Mac App Store. | |
| <a id="option-mac-entitlements">`--mac-entitlements` *path*</a> | |
| : Path to file containing entitlements to use when signing executables and libraries in the bundle | |
| <a id="option-mac-app-category">`--mac-app-category` *category*</a> | |
| : String used to construct LSApplicationCategoryType in application plist | |
| The default value is "utilities". | |
| ### Options for creating the application package: | |
| <a id="option-about-url">`--about-url` *url*</a> | |
| : URL of the application's home page | |
| <a id="option-app-image">`--app-image` *directory*</a> | |
| : 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) | |
| <a id="option-file-associations">`--file-associations` *path*</a> | |
| : Path to a Properties file that contains 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. | |
| <a id="option-install-dir">`--install-dir` *path*</a> | |
| : 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) | |
| <a id="option-license-file">`--license-file` *path*</a> | |
| : Path to the license file | |
| (absolute path or relative to the current directory) | |
| <a id="option-application-package-runtime-image">`--runtime-image` *path*</a> | |
| : Path of the predefined runtime image to install | |
| (absolute path or relative to the current directory) | |
| Option is required when creating a runtime installer. | |
| <a id="option-launcher-as-service">`--launcher-as-service`</a> | |
| : Request to create an installer that will register the main | |
| application launcher as a background service-type application. | |
| ### Platform dependent options for creating the application package: | |
| #### Windows platform options (available only when running on Windows): | |
| <a id="option-win-dir-chooser">`--win-dir-chooser`</a> | |
| : Adds a dialog to enable the user to choose a directory in which | |
| the product is installed. | |
| <a id="option-win-help-url">`--win-help-url` *url*</a> | |
| : URL where user can obtain further information or technical support | |
| <a id="option-win-menu">`--win-menu`</a> | |
| : Request to add a Start Menu shortcut for this application | |
| <a id="option-win-menu-group">`--win-menu-group` *menu-group-name*</a> | |
| : Start Menu group this application is placed in | |
| <a id="option-win-per-user-install">`--win-per-user-install`</a> | |
| : Request to perform an install on a per-user basis | |
| <a id="option-win-shortcut">`--win-shortcut`</a> | |
| : Request to create a desktop shortcut for this application | |
| <a id="option-win-shortcut-prompt">`--win-shortcut-prompt`</a> | |
| : Adds a dialog to enable the user to choose if shortcuts will be created by installer | |
| <a id="option-win-update-url">`--win-update-url` *url*</a> | |
| : URL of available application update information | |
| <a id="option-win-upgrade-uuid">`--win-upgrade-uuid` *id*</a> | |
| : UUID associated with upgrades for this package | |
| #### Linux platform options (available only when running on Linux): | |
| <a id="option-linux-package-name">`--linux-package-name` *name*</a> | |
| : Name for Linux package | |
| Defaults to the application name. | |
| <a id="option-linux-deb-maintainer">`--linux-deb-maintainer` *email-address*</a> | |
| : Maintainer for .deb bundle | |
| <a id="option-linux-menu-group">`--linux-menu-group` *menu-group-name*</a> | |
| : Menu group this application is placed in | |
| <a id="option-linux-package-deps">`--linux-package-deps` *package-dep-string*</a> | |
| : Required packages or capabilities for the application | |
| <a id="option-linux-rpm-license-type">`--linux-rpm-license-type` *type*</a> | |
| : Type of the license ("License: *value*" of the RPM .spec) | |
| <a id="option-linux-app-release">`--linux-app-release` *release*</a> | |
| : Release value of the RPM \<name\>.spec file or | |
| Debian revision value of the DEB control file | |
| <a id="option-linux-app-category">`--linux-app-category` *category-value*</a> | |
| : Group value of the RPM \<name\>.spec file or | |
| Section value of DEB control file | |
| <a id="option-linux-shortcut">`--linux-shortcut`</a> | |
| : Creates a shortcut for the application. | |
| #### macOS platform options (available only when running on macOS): | |
| <a id="option-mac-dmg-content">`--mac-dmg-content` *additional-content* \[`,`*additional-content*...\]</a> | |
| : Include all the referenced content in the dmg. | |
| This option can be used more than once. | |
| ## 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 | |
| ## jpackage and jlink | |
| jpackage will use jlink to create Java Runtime unless the `--runtime-image` option is used. | |
| The created Java Runtime image on Windows will include MS runtime libraries bundled with the JDK. | |
| If MS runtime libraries of a different version are needed for the application, the user will need | |
| to add/replace those themselves. | |
| ## jpackage resource directory | |
| Icons, template files, and other resources of jpackage can be over-ridden by | |
| adding replacement resources to this directory. | |
| jpackage will lookup files by specific names in the resource directory. | |
| ### Resource directory files considered only when running on Linux: | |
| `<launcher-name>.png` | |
| : Application launcher icon | |
| Default resource is *JavaApp.png* | |
| `<launcher-name>.desktop` | |
| : A desktop file to be used with `xdg-desktop-menu` command | |
| Considered with application launchers registered for file associations and/or 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 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 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 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 installer UI dialog checking installation directory doesn't exist or is empty | |
| Default resource is *InstallDirNotEmptyDlg.wxs* | |
| `ShortcutPromptDlg.wxs` | |
| : WiX project file for installer UI dialog configuring shortcuts | |
| Default resource is *ShortcutPromptDlg.wxs* | |
| `bundle.wxf` | |
| : WiX project file with the hierarchy of components of application image | |
| `ui.wxf` | |
| : WiX project file for installer UI | |
| `os-condition.wxf` | |
| : WiX project file with the condition to block installation on older versions of Windows | |
| Default resource is *os-condition.wxf* | |
| `wix-conv.xsl` | |
| : WiX source code converter. Used for converting WiX sources from WiX v3 to v4 schema when WiX v4 or newer is used | |
| Default resource is *wix3-to-wix4-conv.xsl* | |
| #### 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 embedded MSI installer for EXE installer | |
| `installer.exe` | |
| : Executable wrapper for MSI installer | |
| Default resource is *msiwrapper.exe* | |
| ### 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 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 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 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 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* |