Support Application Requirements

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 the default value for a single argument.

The following command defines the value for a single argument for the MyApp application.
```
jpackage --name MyApp --input samples/myapp --main-jar MyApp.jar \
   --arguments arg1 
```
Set the default value for more than one argument.

Use a space to separate arguments and enclose the entire string in quotes, or use multiple instances of the --arguments option. The following commands show alternative ways to define three default command-line arguments for the MyApp application.
```
jpackage --name MyApp --input samples/myapp --main-jar MyApp.jar \
   --arguments "arg1 arg2 arg3" 

jpackage --name MyApp --input samples/myapp --main-jar MyApp.jar \
   --arguments arg1 --arguments "arg2 arg3" 

jpackage --name MyApp --input samples/myapp --main-jar MyApp.jar \
   --arguments arg1 --arguments arg2 --arguments arg3 
```
Set a default value that contains spaces.

If an argument contains a space, two sets of quotes are needed to ensure that jpackage treats the spaces as part of the value and not as delimiters between values. Enclose the argument in single quotes, or double quotes preceded by the escape character, then enclose the quoted string in quotes. The following commands show alternative ways to define two arguments that contain spaces.
```
jpackage --name MyApp --input samples/myapp --main-jar MyApp.jar \
   --arguments "\"String 1\" \"String 2\"" 

jpackage --name MyApp --input samples/myapp --main-jar MyApp.jar \
   --arguments "\"String 1\"" --arguments "\"String 2\"" 

jpackage --name MyApp --input samples/myapp --main-jar MyApp.jar \
   --arguments "'String 1'" --arguments "'String 2'" 
```

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 a single JVM option.

The following command sets the initial size of the heap for the MyApp application to 2 megabytes.
```
jpackage --name MyApp --input samples/myapp --main-jar MyApp.jar \
   --java-options Xms2m 
```
Set more than one JVM option.

To provide more than one JVM option, use a space to separate arguments and enclose the entire string in quotes, or use multiple instances of the --jvm-options option. The following commands show alternate ways to set the initial size and the maximum size for the heap.
```
jpackage --name MyApp --input samples/myapp --main-jar MyApp.jar \
   --java-options "Xms2m Xmx10m"

jpackage --name MyApp --input samples/myapp --main-jar MyApp.jar \
   --java-options Xms2m  --java-options Xmx10m
```
Set a JVM option that contains a space.

If a JVM option contains a space, two sets of quotes are needed to ensure that jpackage treats the spaces as part of the option and not as delimiters between options. Enclose the argument in single quotes, or double quotes preceded by the escape character, then enclose the quoted string in quotes. The following commands show alternate ways to define an option that contain spaces.
```
jpackage --name MyApp --input samples/myapp --main-jar MyApp.jar \
   --java-options "\"-DAppOption=text string\""

jpackage --name MyApp --input samples/myapp --main-jar MyApp.jar \
   --java-options "'-DAppOption=text string'"
```
Set a JVM option that contains quotes.

If a JVM option contains quotes, escape characters must be used for the quotes. The following command passes the JVM option -XX:OnError="userdump.exe %p" to jpackage.
```
jpackage --name MyApp --input samples/myapp --main-jar MyApp.jar \
   --java-options "-XX:OnError=\"\\\"userdump.exe %p\\\"\""
```
Use the $APPDIR macro with a JVM option.

To use the image myAppSplash.jpg from the application directory as the splash screen for your application, use the $APPDIR macro as shown in the following example. The image file must be in the input directory when the application is packaged. Note that in some shells the dollar sign needs to be escaped, for example, \$APPDIR.
```
jpackage --name MyApp --input samples/myapp --main-jar MyApp.jar \
   --java-options "-splash:\$APPDIR/myAppSplash.jpg"
```

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 format module=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 to true 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:

Add a launcher with different application arguments.

Create the following properties files that define different default arguments to use when the application is launched. The first file defines 3 arguments to pass. The second file defines two arguments to pass.
```
MLAppArgs1.properties:

arguments=arg1 arg2 arg3

MLAppArgs2.properties:

arguments="String 1" "String 2"
```
The following command packages the application MyApp with two additional launchers using the properties files just created.
```
jpackage --name MyApp --input samples/myapp --main-jar MyApp.jar \
   --add-launcher MyApp1=MLAppArgs1.properties \
   --add-launcher MyApp2=MLAppArgs2.properties
```
Add a launcher to start the Windows console.

To provide the user with the option of running your application with or without the console, create the following properties file that defines a launcher that uses the Windows console.
```
MLConsole.properties:

win-console=true
```
The following command packages the HelloWorld application with an additional launcher that runs the application with the Windows console.
```
jpackage --name HelloWorld --input helloworld \
   --main-jar HelloWorld.jar \
   --add-launcher HWConsole=MLConsole.properties 
```
Add a launcher for a second entry point.

When more than one application is included in the same package, each application can be started independently by adding additional launchers. If the FADemo and the Dynamic Tree applications are packaged together and the main launcher is for the FADemo application, create the following properties file to define an additional launcher for the Dynamic Tree application.
```
MLDynamicTree.properties

main-jar=DynamicTree.jar
main-class=webstartComponentArch.DynamicTreePanel
icon=DTDemo.ico
```
The following command packages the two applications together and sets up the additional launcher using the properties file just created.
```
jpackage --name MLDemo --input MLDemo \
   --main-jar ScriptRunnerApplication.jar \
   --add-launcher "Dynamic Tree"=MLDynamicTree.properties
```

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), specify app-image; if you want to create a package (.pkg), specify pkg. 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, then jpackage uses the entitlements file default.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 the jpackage 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, then jpackage uses the entitlements file sandbox.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. The jpackage tool sets the value of LSApplicationCategoryType to the value of this option in your application's .plist file. The default value of this option is utilities. See LSApplicationCategoryType in Apple Developer Documentation for a list of valid categories.