Super Prev Next

xpack Reference


Super Prev Next

Unattended Packaging

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).

Example:

    xpack MyApp-slim.jpn -add-file samples / ^
        -save-project-as MyApp-full.jpn

See also Re-building installation package.


Super Prev Next

Two-Step Packaging

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.


Super Prev Next

Creating Installation Packages from Scratch

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.

Notes:

  1. When packaging an Eclipse RCP application, specify its root directory as source-dir; for Tomcat Web applications, specify the Tomcat directory.
  2. The target directory must either not exist or be empty. To force overwrite, use the -clean-target option.


Super Prev Next

Adding specific files and directories

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:

    -add-root root-name

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.


Super Prev Next

Assigning non-packed classpath entries

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

Example:

       .  .  .
    -assign-resource MyApp.exe media.jar /data/media.jar
    -disable-resource MyApp.exe classesonly.jar
       .  .  .


Super Prev Next

Assigning VM properties

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.

Example:

       .  .  .
    -add-root DATA
    -add-file MyApp.exe /bin
    -assign-vm-properties /bin/MyApp.exe "-Ddata.dir=$(DATA)"
       .  .  .


Super Prev Next

Selecting a Compact Profile

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.


Super Prev Next

Adding locales and charsets

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:

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

Example:

       .  .  .
    -add-locales all
    -remove-locales Extended_IBM,Extended_Macintosh
       .  .  .


Super Prev Next

Adding optional runtime components

To include optional JET Runtime components in the package, use the -add-opt-rt-files and -remove-opt-rt-files options.

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.

Example:

    -add-opt-rt-files jce,nashorn


Super Prev Next

Enabling disk footprint reduction

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:

    -reduce-disk-footprint mode

where mode is one of the following:

none

disables reduction
medium

default
high-disk

on demand decompression to disk
high-memory

on demand decompression to memory

See Disk footprint for details.


Super Prev Next

Backend selection

The Excelsior JET Deployment Toolkit includes several backends that produce packages of different types.

To select the desired backend, use the -backend option:

    -backend backend

where backend is one of the following:

self-contained-directory (default)

Produce a self-contained directory, which you may copy to target systems, possibly after using third-party tools to turn it into a (self-extracting) archive or a full-featured installation package. This backend recognizes a few extra options, described in subsection Self-contained directory: Zip archive generation.
multi-root

Produce a multi-root layout, supposed to be packaged by a third-party setup generator
excelsior-installer

Generate an Excelsior Installer setup. This backend recognizes a number of additional options, described in subsections Excelsior Installer: Product and Vendor Information to Excelsior Installer: Callback DLLs.


Super Prev Next

Self-contained directory: Zip archive generation

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.

Example:

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


Super Prev Next

Excelsior Installer: Product and Vendor Information

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.

Example:

       .  .  .
    -company "My Company Name, Inc."
    -product "Pi Number Calculator"
    -version 3.14
       .  .  .


Super Prev Next

Excelsior Installer: Appearance

You can customize installer and uninstaller appearance using the following options:

-splash image

Display a splash screen upon installer launch.
-welcome-image image

Set image to display on the first screen of the installation wizard. Recommended size: 177*314px.
-installer-image image

Set image to display in the upper-right corner on subsequent screens. Recommended size: 109*59px.
-uninstaller-image image

Set image to display on the first screen of the uninstall wizard. Recommended size: 177*314px.

The image argument of each option is the pathname of the respecitve image file in BMP format.

Example:

       .  .  .
    -splash installer\branding\splash.bmp
    -welcome-image installer\branding\install.bmp
    -installer-image installer\branding\installer-top.bmp
    -uninstaller-image installer\branding\uninstall.bmp
       .  .  .


Super Prev Next

Excelsior Installer: Enforcing Installer Language

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


Super Prev Next

Excelsior Installer: EULA Acceptance Screen

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.


Super Prev Next

Excelsior Installer: Installation Directory

You may configure installation directory defaults using the following options:

-installation-directory-type type

where type is either program-files (default), system-drive, or absolute-path. Specifies whether the default installation directory pathname is relative to the Program Files folder, is relative to the root of the system drive, or is an absolute path, respectively.
-installation-directory path

where path is the full or partial /Depending on installation directory type./ pathname of the desired installation directory.

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:

    "company-name\product-nameproduct-version]"

-installation-directory-fixed

Prohibits changes of the installation directory.

Examples:

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:

    -installation-directory MyApp


Super Prev Next

Excelsior Installer: Registry Key

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:

    company-name/product-name/product-version

You can override the default using the -registry-key option:

    -registry-key partial-key-name

Example:

    -registry-key MyApp/1.0


Super Prev Next

Excelsior Installer: Shortcuts

You can make the installer create shortcuts at various locations using the -shortcut option:

    -shortcut location target name icon work-dir arguments

where

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"
       .  .  .


Super Prev Next

Excelsior Installer: File Associations

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

where

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
       .  .  .


Super Prev Next

Excelsior Installer: Post-Install Runnable

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).

Example:

    -after-install-runnable /bin/init.exe "-home=$(Root)"

Note: Callback DLLs may also be used to perform additional acions after installation.


Super Prev Next

Excelsior Installer: Post-Install Actions

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:

-no-default-post-install-actions

Do not add the default post-install actions
-post-install-checkbox-run target work-dir arguments[un]checked

Add a post-install action checkbox for launching an executable, where

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.

-post-install-checkbox-open file [un]checked

Add a post-install action checkbox for opening the given installed file using file associations, whether pre-existing or created by the installer. file is the location of the file within the package
-post-install-checkbox-restart [un]checked

Add a post-install action checkbox for restarting Windows

The last argument of all options that add post-install actions, [un]checked, indicates whether the action checkbox has to be checked by default.


Super Prev Next

Excelsior Installer: Windows Services

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

where

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
       .  .  .


Super Prev Next

Excelsior Installer: Compression Level

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 )


Super Prev Next

Excelsior Installer: Tomcat-specific Options

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.


Super Prev Next

Excelsior Installer: Installation Directory Removal

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:

    -cleanup-after-uninstall


Super Prev Next

Excelsior Installer: Callback DLLs

You can add an install-time callback DLL to the project using the option -install-callback:

    -install-callback install-callback-DLL

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:

    -uninstall-callback uninstall-callback-DLL

where uninstall-callback-DLL points to the location of the uninstall callback DLL within the package.

Example:

       .  .  .
    -add-file uninstall.dll /utils
    -uninstall-callback /utils/uninstall.dll
       .  .  .


Super Prev Next

Miscellaneous features

    -quiet

Disable printing of log messages to the standard output.


Super Prev Next

Saving Projects

    -save-project

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-project-as pathname

Save the project under a different name and/or location, or create a new project file if invoked without a project file.

    -save-as-updatable pathname

Save the project as updatable at the given pathname.


Super Prev Next

Updating The JET Runtime

    -update-rt profile-name

Add a copy of the JET Runtime to the update project (see Updating JET Runtime for details).


Super Prev Next

Response Files

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