3 Support Application Requirements
The packaging tool provides support for application requirements such as default arguments, JVM options, file associations, multiple launchers, and signing.
Set Default Command-Line Arguments
If your application accepts command-line arguments, use the --arguments
option to define default values. Users can override these values when they start the application.
If you package your application with default command-line arguments, these values
are passed to the main class when the user starts your application without providing
arguments. The [ArgOptions]
section of the app-name.cfg
file in the
/app
directory of the application image generated by
jpackage
shows any default arguments that are defined. You can check
this file to ensure that the values are defined correctly.
The following examples show some of the ways to set up default arguments:
Set JVM Options
If you want options passed to the JVM when your application is started, use the --java-options
option when you package your application. Users can't provide JVM options to the application.
To set up the JVM as needed to run your application, define the JVM options to pass when a user starts your application. Use the $APPDIR
macro to reference resources included with the application. The resource file must be in the input directory when the application is packaged.
The [JavaOptions] section of the app-name.cfg
file in the /app
directory of the application image generated by jpackage
shows any default arguments that are defined. You can check this file to ensure that the values are defined correctly.
The following examples show some of the ways to pass JVM options to your application:
Set Class and Module Paths
By default, the jpackage
tool generates a
default class path that contains the path to each JAR file that's specified in the
--input
option. However, a class path that you specify with the
-cp
, -classpath
, or -Djava.class.path
option through the --java-options
option overrides the default class
path.
If you're using --java-options
to specify the class path, then
ensure that you include the path to each of your input JAR files in it. For example, if
your application contains only one JAR file, myapp.jar
but you want
to include the classes in the classes
subdirectory in the class path,
then add the following to the jpackage
command:
--java-options "-cp \$APPDIR/myapp.jar:\$APPDIR/classes"
For a modular application, the default module path that
jpackage
generates is $APPDIR/mods
. However, if
you specify a module path with the --module-path
option through
--java-options
, then your module path is appended after the
default module path; it doesn't replace the default one.
Set File Associations
If you want your application to be started when a user opens a specific type of file, use the --file-associations
option when you package your application.
To have your application started when a user opens a file that your application can handle, define the file associations that you want created when the application is installed. Associations are defined in properties files that are passed to jpackage
. For each association, a separate file and a separate instance of the --file-associations
option is required. The following properties define an association, which must include either mime-type
or extension
:
-
mime-type
- MIME type for files that your application can process. -
extension
- File extension for files that your application can process. -
icon
- Icon to use for the type of files that your application can process. The icon must be in the input directory when the application is packaged. If no icon is specified, the default icon is used. -
description
- Short description of the association.
To set up file associations, first create the properties files. The following two files set up an association for JavaScript files and for Groovy files.
FAjavascript.properties:
mime-type=text/javascript
extension=js
description=JavaScript Source
FAgroovy.properties:
mime-type=text/x-groovy
extension=groovy
description=Groovy Source
The following command packages the application FADemo and sets up file associations using the properties files just created. When a user opens a .js
or .groovy
file, FADemo is started.
jpackage --name FADemo --input FADemo \
--main-jar ScriptRunnerApplication.jar \
--file-associations FAjavascript.properties \
--file-associations FAgroovy.properties
Add Launchers
If you have more than one way start your application, use the --add-launcher
option to describe the additional launchers that you want created.
You might want an additional launcher if your application has different default values for arguments or can run with or without the Windows console, or if you package multiple apps together to share a runtime. The format for the option is --add-launcher launcher-name=properties-file
, where launcher-name is the named used for the additional launcher. Use quotes if the name contains spaces.
The launchers are defined in properties files that are passed to jpackage
. For each launcher, a separate file and a separate instance of the --add-launcher
option is required. The following properties define a launcher, at least one option must be set:
-
module
- Name of the module that contains the main class for the launcher. If the main module does not identify the main class, include it in the formatmodule=main-module/class
. -
main-jar
- Name of the JAR file that contains the main class for the launcher. -
main-class
- Name of the main class. -
arguments
- Default arguments, separated by spaces. If an argument contains spaces, enclose the argument in quotes, for example,arguments=arg1 "arg 2" arg3
-
app-version
- Version number. -
java-options
- Options to pass to the JVM, separated by spaces. If an argument contains spaces, enclose the argument in quotes. -
icon
- Icon used for the additional launcher -
win-console
- Set totrue
to start the console with the application.
To define additional launchers, first create the properties files. The following examples show some of the ways to set up a launcher:
Sign the Application Package (macOS)
For an application that runs on macOS, use the --mac-sign
and supporting options when you package your application. A disk image
(.dmg
) or package (.pkg
) that contains a signed
application image (.app
) can be notarized.
The required jpackage
options depend on whether or not
you want to distribute your application though the Mac App Store.
Required Certificates
If you want to distribute your application outside the Mac App Store, then you'll need the certificates "Developer ID Application: <user or team name>" and "Developer ID Installer: <user or team name>".
If you want to deploy your application through the Mac App Store, then you'll need the certificates "3rd Party Mac Developer Application: <user or team name>" and "3rd Party Mac Developer Installer: <user or team name>".
Options for Signing macOS Application Package
To sign a macOS application package, include the following
jpackage
options:
-
--mac-sign
: Requests that the bundle be signed for macOS. -
--mac-signing-key-user-name user_or_team_name
: The key user or team name, which is the name portion in Apple signing identities' names.
In addition, you may require the following options
-
--mac-package-signing-prefix prefix
: When signing the application bundle, this value is prefixed to all components that need to be signed that don't have an existing bundle identifier. If you don't specify this option, then the prefix is the (unqualified) main class name followed by a period (.
). -
--mac-signing-keychain keychain_name
: If a keychain other than the standard keychain is used, then specify the name of the keychain as show in the Keychain Access app. The name should end in.keychain
. -
--type type
: If you want to create an application image (.app
), specifyapp-image
; if you want to create a package (.pkg
), specifypkg
. If you don't specify this option, then this option creates a disk image (.dmg
). -
--mac-entitlements path
: Path to the file containing entitlements to use when signing executables and libraries in the bundle.If you don't specify the
--mac-entitlements
option nor the--mac-app-store
option, thenjpackage
uses the entitlements filedefault.plist
, which is a built-in resource (see Resources Used in Packaging). It contains entitlements that enable your signed application to run the JDK.
The following command generates a disk image
(.dmg
) containing an application image signed with
the "Developer ID Application: developer.example.com" certificate. The disk
image is generated with the prefix
com.example.developer.OurApp.
and the team name
developer.example.com.
jpackage --name DynamicTreeDemo --input myApps --main-jar DynamicTree.jar \
--mac-sign --mac-package-signing-prefix com.example.developer.OurApp. \
--mac-signing-key-user-name "developer.example.com"
The following command generates a package (.pkg
)
containing an application image signed with the "Developer ID Installer:
developer.example.com" certificate. The package is generated with the prefix
com.example.developer.OurApp.
and the team name
developer.example.com.
jpackage --type pkg --name DynamicTreeDemo --input myApps \
--main-jar DynamicTree.jar --mac-sign --mac-package-signing-prefix com.example.developer.OurApp. \
--mac-signing-key-user-name "developer.example.com"
Options for Signing Application Package for Mac App Store
To sign an application package for the Mac App Store, also include
the following jpackage
options:
-
--mac-app-store
: Indicates that thejpackage
output is intended for the Mac App Store. -
--mac-entitlements path
: Path to file containing entitlements to use when signing executables and libraries in the bundle. This file should enable the App Sandbox Entitlement, which restricts your application to system resources and user data. It's required for applications distributed through the Mac App Store.If you don't specify the
--mac-entitlements
option but specify the--mac-app-store
option, thenjpackage
uses the entitlements filesandbox.plist
, which is a built-in resource (see Resources Used in Packaging). It contains<key>com.apple.security.app-sandbox</key><true/>
, which enables the App Sandbox Entitlement. -
--mac-app-category category
: Specifies the category that best describes your application package for the Mac App Store. Thejpackage
tool sets the value of LSApplicationCategoryType to the value of this option in your application's.plist
file. The default value of this option isutilities
. See LSApplicationCategoryType in Apple Developer Documentation for a list of valid categories.