Given a JetPackII project file, you can build an installation package with the command:
xpack project-file [ options ]
You can use options to change package content and settings as described in Creating Installation Packages from Scratch. You can also save the resulting project using the -save-project or -save-project-as options (see Saving Projects).
xpack MyApp-slim.jpn -add-file samples / ^ -save-project-as MyApp-full.jpn
See also Re-building installation package.
During packaging, the Excelsior JET Installation Toolkit modifies the executables produced by JET Optimizer, binding them to the copy of the JET Runtime included in the package. You may then use a third-party license manager and/or native code protection tools that also modify the same executables. However, these modfications would come in a wrong order if you create an Excelsior Installer setup in one step.
In such a scenario, you should first invoke xpack to produce an intermediate image with modified executables in a temporary directory, then apply those third-party tools to the executables in that image, and then apply xpack to the post-processed image:
xpack project-file -make-image temp-directory
. . .
xpack project-file -from-image temp-directory -target target-file
See Installations protected by license managers for details.
Under certain circumstances, creating installation packages with the JetPackII graphical tool may be inconvenient. For instance, you may need to create a handful of similar packages for different editions of your application or for different markets. In such scenarios, you can use the xpack utility to create those packages without ever launching JetPackII.
In general, usage of xpack without a project file is as follows:
xpack config-options [-backend install-type ] -target target-file-or-dir
Valid values of the -backend option are excelsior-installer, multi-root, and self-contained-directory (default).
The -target option defines the pathname of the resulting file (for Excelsior Installer setups) or the target directory (for self-contained directory and multiple roots packages).
config-options, described below, define installation package contents and the behavior of the installation wizard (for Excelsior Installer setups).
The simplest way to package your optimized application into a self-contained directory is as follows:
xpack -source source-dir -target target-dir
where source-dir contains the executable(s) produced by JET and other files that you want to appear on the end user system, arranged in subdirectories as desired, and target-dir is the pathname of the resulting self-contained directory. xpack will automatically add the necessary JET Runtime files to the package.
In addition or as an alternative to using the -source option, you can explicitly list all package files and directories and specify their locations in the package. For that purpose, use the -add-file option that has two arguments: the pathname of a file or directory in the local file system that you want to add to the installation package and its desired location on the end user system relative to the installation directory, using the forward slash ("/") character as a separator. To denote the installation directory itself, use either a standalone forward slash ("/") or "$(Root)".
For example, the following option:
-add-file MyApp.exe /
tells xpack to add the MyApp executable to the root of the installation package.
If the specified relative path does not exist in the package yet, the respective directory structure will be automatically created.
For instance, the command
xpack -add-file MyApp.exe /bin other-options
will create the /bin directory in the package and add the MyApp executable to it.
You can specify the -add-file option as many times as required to fully define the package content.
If you need to add a directory containing many files to the package, but want some of them placed at alternative locations on the target system, use the -move-file option:
-move-file from-package-path to-package-path
For example, if the doc directory contains documentation for your application, including the license agreement, you can have the latter placed alongside the executable at the top level of the target directory as follows:
. . . -add-file doc / -move-file /doc/LICENSE / . . .
You can also use -move-file to rename and relocate installation package directories, including the JET Runtime directory (placed at /rt by default).
Finally, for multiple roots installations, you can add a new root to the package with the -add-root option:
and then prepend the package paths in arguments of the respective -add-file and -move-file options with $(root-name).
Multiple occurrences of -add-root in the command line are allowed. The name of the default root is "Root".
For example, the following response file excerpt:
. . . -add-root DATA -add-file Myapp.exe /bin -add-file doc $(DATA)/ -move-file $(DATA)/doc/LICENSE / . . .
makes xpack add the MyApp executable to the /bin subdirectory of the default root, add the doc directory to the root named DATA, and then move the license file from that directory to the top level of the default root.
Classpath entries you kept outside the compiled executables /Those compiled with the "Pack into exe" mode set to none./ should be added to the package with -add-file. In this case, the respective jar/zip files or directories will be automatically added to the application classpath. If you need to manually configure such classpath entries for some reason, use the -assign-resource option. It has three arguments: name of executable (short name or relative path in the package), classpath entry name (short or full file name), and its relative path in the package:
-assign-resource executable classpath-entry package-path
The -disable-resource option can be used to remove a non-packed entry from the classpath of a compiled executable, usually when you know for sure that it does not contain any resource files. The option has two arguments: name of executable (short name or relative path in the package) and classpath entry name (short or full file name):
-disable-resource executable classpath-entry
. . . -assign-resource MyApp.exe media.jar /data/media.jar -disable-resource MyApp.exe classesonly.jar . . .
You can specify system properties for each executable produced by Excelsior JET (see Editing Java system properties) using the option -assign-vm-properties:
-assign-vm-properties executable "vm-properties"
where executable is either the short name of a JET-compiled executable included in the package, or its package path, and vm-properties is a list of system properties enclosed in double quotes.
Note: You may refer to package root(s) using the $(root-name) syntax.
. . . -add-root DATA -add-file MyApp.exe /bin -assign-vm-properties /bin/MyApp.exe "-Ddata.dir=$(DATA)" . . .
Java SE 8 defines three subsets of the standard Platform API called compact profiles. Excelsior JET enables you to deploy your application with one of those subsets. See Compact Profiles for details.
By default, xpack includes the entire Java SE Platform API in the package. To specify a particular profile, use the -profile option:
-profile auto | compact1 | compact2 | compact3 | full
-profile auto forces xpack to detect which parts of the Java SE Platform API are referenced by the JET-compiled executable(s) added to the package and select the smallest compact profile that includes them all, or the entire Platform API if there is no such profile.
Additional locales and character encoding tables that may potentially be in use in the regions where you distribute your application can be added to the package with the help of options -add-locales and -remove-locales.
If you need your application to support locales and encodings other than US English and European, do one of the following:
where list is a comma-separated list of locale/charset IDs
where list is a comma-separated list of locale/charset IDs
The available locale/charset IDs are:
European (included by default), Indonesian, Malay, Hebrew, Arabic, Chinese, Japanese, Korean, Thai, Vietnamese, Hindi, Extended_Chinese, Extended_Japanese, Extended_Korean, Extended_Thai, Extended_IBM, Extended_Macintosh, Latin_3
. . . -add-locales all -remove-locales Extended_IBM,Extended_Macintosh . . .
To include optional JET Runtime components in the package, use the -add-opt-rt-files and -remove-opt-rt-files options.
where list is a comma-separated list of component IDs
where list is a comma-separated list of component IDs
The available optional components are:
runtime_utilities, fonts, jdk_tools, api_classes, jce, accessibility, javafx, javafx-webkit, javafx-swing, nashorn, cldr
Note: by default, xpack automatically includes the optional components which the compiler detected as used when building the executable(s) included in the package.
Note: Information in this section is not applicable to the Standard Edition of Excelsior JET.
Excelsior JET is capable of reducing the disk footprint of installed applications, if their executables were produced with the
Global Optimizer enabled.
The syntax of the respective xpack option is as follows:
where mode is one of the following:
See Disk footprint for details.
The Excelsior JET Deployment Toolkit includes several backends that produce packages of different types.
To select the desired backend, use the -backend option:
where backend is one of the following:
After producing a self-contained directory, xpack can also create a zip archive with a copy of the contents of that directory. The archive will have the same pathname as the directory, with the extension .zip added.
If you want xpack to keep the directory after creating the zip archive, specify the option -zip. If you only need the zip archive, specify the option -zip-only.
Make a self-contained directory MyApp-1.0, pack its contents into MyApp-1.0.zip, and remove the directory:
xpack -source build\native -target MyApp-1.0 -zip-only
Use the -company, -product, and -version options to supply meta information for the resulting installer. Apart from displaying that information to the end user, Excelsior Installer uses it to compose the path to the default installation directory and registry keys. Note that if this information is not set, it is taken from version information resources of the JET-compiled executable(s) added to the package. If such resources are not present, you must specify at least the options -company and -product.
. . . -company "My Company Name, Inc." -product "Pi Number Calculator" -version 3.14 . . .
You can customize installer and uninstaller appearance using the following options:
The image argument of each option is the pathname of the respecitve image file in BMP format.
. . . -splash installer\branding\splash.bmp -welcome-image installer\branding\install.bmp -installer-image installer\branding\installer-top.bmp -uninstaller-image installer\branding\uninstall.bmp . . .
Excelsior Installer can display its screens in multiple languages. By default, it selects the most appropriate language based on the locale settings of the target system. Use the option -language to force a specific language instead:
-language autodetect | language
Where language is one of the following:
english, french, german, japanese, russian,
polish, spanish, italian, brazilian
To have the installer prompt the end user to accept a license agreement before installation, use either the -eula or -unicode-eula option specifying the pathname of the license agreement file in the ANSI or Unicode (UTF-16LE) encoding, respectively.
You may configure installation directory defaults using the following options:
Sets the default installation directory.
If this option is not explicitly specified, its value is derived from the values of -company, -product and -version options as follows:
Always install in the directory \MyVeryImportantApp on the system drive:
. . . -installation-directory-type system-drive -installation-directory MyVeryImportantApp -installation-directory-fixed . . .
Install in Program Files\MyApp by default:
During installation, Excelsior Installer creates a registry key to store information required for the installation of update packages.
The key is located either in the HKEY_LOCAL_MACHINE/SOFTWARE/ or the HKEY_CURRENT_USER/SOFTWARE/ subtree, depending on whether Common or Personal installation type gets selected during installation. By default, the rest of the full name of the key is derived from the values of -company, -product and -version options as follows:
You can override the default using the -registry-key option:
You can make the installer create shortcuts at various locations using the -shortcut option:
-shortcut location target name icon work-dir arguments
location is either program-folder, desktop, start-menu or startup.
target is the location of the shortcut target within the package
name is the name of the shortcut, or an empty string to have the short name of the target used instead
icon is the pathname of the shortcut icon within the package, or an empty string if you want the default icon used.
work-dir is the pathname of the working directory of the shortcut target within the package, or an empty string, the latter meaning "the directory containing target".
arguments is a string containing the command line arguments for target, or an empty string.
You can also suppress the creation of the default shortcuts using the -no-default-shortcuts option.
Examples (second line broken down into three):
. . . -shortcut desktop /bin/MyApp.exe "My App" "" "" "" -shortcut program-folder /bin/MyApp.exe "Getting Started Tutorial" "" "/samples/tutorials" "getting-started.tut" . . .
You can make the installer create file associations using the -file-association option:
-file-association extension target assoc-desc target-desc icon arguments checked | unchecked
extension is a file name extension without the leading dot, such as myscript
target is the location within the package of the executable program being associated with extension
assoc-desc is a description of the file type, such as "MyApp Script", or an empty string ("")
target-desc is the string to be used in the prompt displayed by the Excelsior Installer wizard: "Associate *.extension files with target-desc", or an empty string ("")
icon is the location within the package of an icon file that should be used for files with names ending in extension, or an executable other than target to be used as the source of that icon. Specify an empty string ("") to use the default icon of the target executable.
arguments are the command-line arguments to be passed to target. Default is "%1" meaning the full pathname of the clicked file.
checked | unchecked is the initial state of the respective checkbox "Associate *.extension files with target-desc" in the Excelsior Installer wizard.
Example (broken down into two lines):
. . . -file-association myscript /bin/MyApp.exe "MyApp Script" "MyApp" "" "-script %1" checked . . .
Excelsior Installer can optionally run one of the executable files included in the package upon succesfull installation. Use the option -after-install-runnable to specify the executable and its arguments:
-after-install-runnable runnable arguments
where runnable is a path to the executable within the package, and arguments are its command-line arguments. If there is more than one argument, make sure to enclose arguments in quotes. Arguments may include references to the actual root installation directory in the form of $(Root).
-after-install-runnable /bin/init.exe "-home=$(Root)"
Note: Callback DLLs may also be used to perform additional acions after installation.
Upon successful installation, Excelsior Installer can optionally display to the user a list of checkboxes enabling various post-install actions, such as launching the installed application, viewing the readme file, restarting the system, and so on.
The default is to add a launch action for each JET-compiled executable in the package with the text "Start executable-name".
You can configure post-install actions using the following options:
target is the location of the executable within the package
work-dir is the pathname of the working directory for target within the package
arguments is a (possibly empty) string containing the command line arguments for target.
The last argument of all options that add post-install actions, [un]checked, indicates whether the action checkbox has to be checked by default.
Excelsior JET includes a Java API that enables you to create Windows service executables (see Chapter Windows services for details). If your package includes such executables, you need to specify additional options.
To set command line arguments, display name, and description for the given Windows Service executable, use the -service option:
-service executable arguments display-name description
To specify service startup settings , use the -service-startup option:
-service-startup executable logon mode [no-]start-after-install
logon is either system, system-desktop or user, meaning respectively the built-in system account, built-in system account with desktop interaction, and user account.
mode is the service startup mode, one of auto, manual, or disabled.
[no-]start-after-install specifes whether the service has to be started immediately upon succesful installation.
To specify service dependencies, use the -service-dependencies option:
-service-dependencies executable dependencies
where dependencies is a comma separated list of names of dependent services for the given Windows Service executable.
Example (each line broken down into two):
. . . -service /bin/server.exe start "MyApp Service" "My Application Background Processing Service" -service-startup /bin/server.exe system auto start-after-install . . .
Excelsior Installer support three compression levels: fast, medium (default) and high (slow). You can select the desired level using the -compression-level option:
-compression-level ( fast | medium | high )
To have the Excelsior Installer wizard prompt the user to specify the Tomcat HTTP port during installation, use the option -allow-user-to-change-tomcat-port.
By default, the installer registers the Tomcat executable as a Windows service The option -no-tomcat-service-install disables that behavior.
By default, the uninstaller only removes those files and directories from the installation directory that the original applicaion installer, and possibly update installers, had created. If any files and directories were created by a post-install runnnable, callback DLL, installed and/or third-party applications, the uninstaller will leave them in place and report to the user that it was unable to remove the installation directory due to their presence.
The option -cleanup-after-uninstall forces the uninstaller to remove all files from the installation directory:
You can add an install-time callback DLL to the project using the option -install-callback:
where install-callback-DLL points to the location of the callback DLL on the host system. The DLL is added to the package implicitly and gets removed upon successful installation.
An uninstall callback DLL has to be present on the end user system at the time of uninstall, so you need to add it to the project as you would add any other file and then use the option -uninstall-callback:
where uninstall-callback-DLL points to the location of the uninstall callback DLL within the package.
. . . -add-file uninstall.dll /utils -uninstall-callback /utils/uninstall.dll . . .
Disable printing of log messages to the standard output.
Save the project under the same name. Only works if a project file was specified. Any modifications made to the project by other options will be saved, so next time you can run xpack against the project without specifying those options.
Save the project under a different name and/or location, or create a new project file if invoked without a project file.
Save the project as updatable at the given pathname.
Add a copy of the JET Runtime to the update project (see Updating JET Runtime for details).
As an alternative to receiving all the options as command line arguments, xpack accepts response files using either of the following syntaxes:
xpack @response-file xpack -arg-file response-file
where response-file is the pathname of a plain text file that contains xpack options, one per line.
You can specify some options on the command line, for instance, if you need to create slightly different variants of a package:
xpack @common.xpack -target lean xpack @common.xpack -add-file samples /samples -target full