Super Prev Next

Deployment automation

Super Prev Next


Excelsior JET comes with an Installation Toolkit, a complete solution for the deployment of applications which contain binary components (EXEs, DLLs, Windows services) produced by the JET Optimizer.

The toolkit includes:

It enables you to create new installations and updates, and deploy them using either Excelsior Installer or a third-party setup authoring tool. You may also create a self-contained directory that includes your application’s files and can be simply copied to the target systems without any setup actions, burned onto a CD, or written to a USB stick or flash memory card.

The toolkit creates complete installations without deployment dependencies. In particular, installation of the Java Runtime Environment (JRE) on target systems is not required.

Super Prev Next

Excelsior deployment technology

Super Prev Next


The JetPackII graphical tool, designed in the spirit of the JET Control Panel, is responsible for all stages of creating new installations and updates. Its wizard-like interface guides you through the process of preparing the installation package step by step.

When creating a new package, you define the set of JET-compiled executables and auxiliary files (resources, documentation, samples, etc.) which your application needs to work. For each executable, you may configure the classpath and Java system properties to be set during installation. As a result, your end users receive self-installing archives that always create clickable executables on target machines. This way, the need to use shell scripts for application startup is greatly reduced.

You can also create updates to previously created installations. This feature allows you to issue upgrades and patches for your products. JetPackII assists you in tracking the differences between the original and new packages for the update package to include only added and modified files.

Then, you may perform a trial run before packaging your application. That is a testing procedure that ensures the completeness of your package. It simulates execution of your application deployed to a target system. The package contents are copied to a trial run directory, and the applications are run as if Excelsior JET was not installed on your computer.

In the end, you get either a self-extracting Excelsior Installer archive, a self-contained directory, or a set of files and instructions to create an installation package using a third-party tool.

Super Prev Next

Excelsior Installation Toolkit

Excelsior Installation Toolkit is a part of Excelsior JET that enables you to create self-extracting installation packages without using any third-party tools.

Excelsior Installation Toolkit is a set of utilities seamlessly integrated with the JetPackII wizard. Using it, you immediately get installation packages ready for deployment on the final step of JetPackII.

Here is the list of features available in Excelsior Installation Toolkit:

Note: Not all features are available in the Standard Edition.

Super Prev Next

Before You Begin

Suppose you have compiled your application with Excelsior JET and the compiled version has successfully passed the QA on your system. Now you need to prepare it for distribution to end users.

Ideally, you should write down the answers to the following questions before launching JetPackII:

What resource files your application needs?

Resource files are image files, text property files, HTML files, etc., that applications load from the classpath by means of java.lang.Class.getResource() and similar methods.
Are the resources included in the jar files you compiled?

Resources from the jar files were automatically packed into the executable at compilation time so you need to do nothing to make them available to the applications deployed to end user systems. "Standalone" resources located in directories in the local file system should be added to the package manually when creating the installation as described in Step 1: Adding files to package.
What other files have to be distributed along with your application?

These may be native method libraries, configuration files, samples, manuals, non-Java executables, etc.
What is the desired directory structure of your installation package?

Super Prev Next

Starting JetPackII

To launch JetPackII, select the JetPackII item from the Excelsior JET Start Menu. A splash screen with a “Loading...” progress indicator shall appear. When loading is over, the Welcome Screen is displayed.

In the middle column, click:

Super Prev Next

JetPackII Overview

Figure 2. Excelsior JetPackII

Like the JET Control Panel, JetPackII user interface is built as a series of “pages”, each representing one logical step in the process of your installation package creation. As can be seen on the Figure 2. Excelsior JetPackII, most of page space is occupied by page-specific controls; but there are also some common controls: the sidebar on the left, the main menu at the top, and help/navigation buttons in the lower right corner.

You can navigate through the pages either sequentially, by using the Next Page / Previous Page buttons, or directly, by clicking the respective sidebar button or by selecting a page in the Page menu. Depending on the context, some pages may be unavailable, with their respective sidebar buttons and main menu items disabled.

Online help is available to assist you at any point. To display help information for the current page, click the Page Help button. To get a help on a particular control, click the Context Help button. The mouse cursor will change its shape to an arrow with a question-mark — click the control you wish to learn about, and the respective portion of the online help will be displayed.

Super Prev Next

Working With Projects

A JetPackII project consists of a project configuration and a set of files, which together fully determine the installation. A project defines:

This information is stored in a JetPackII project file that you create as described later in this chapter. JetPackII project files have extensions .jpn.

Super Prev Next

Creating a new project

You may create a new JetPackII project by clicking New Installation (New Tomcat Installation or New Eclipse RCP Installation) on the Welcome Screen or by selecting those options in the File/New Project menu. If there is already an opened project, JetPackII will prompt you to save it first.

Super Prev Next

Opening a project

You may open a previously created project by clicking the Open icon on the Welcome Screen or by selecting the File/Open menu item. A conventional file dialog will appear; use it to browse for the JetPackII project file you want to open or select the desired project in the File name combo box.

Later you may quickly open an existing project by selecting it in the Recent Projects column of the Welcome Screen or using the File/Reopen menu item.

Super Prev Next

Saving a project

You may save a project by selecting the File/Save item from the main menu. When you save a just created project for the first time, a conventional file dialog is displayed; use it to specify the desired pathname for your project file. The default extension .jpn will be added to the file name automatically.

Super Prev Next

Saving a project under a different name

You may save the current project with a different name or in another directory by selecting the File/Save As item from the main menu. A conventional file dialog is displayed; use it to specify a new directory and/or a new name for your project file.

Super Prev Next

Closing a project

You may close the current project by selecting the File/Close Project item from the main menu. This brings up the JetPackII Welcome Screen. If the current project has been modified, JetPackII will prompt you to save it first.

Super Prev Next

Package Files Panel

The left part of JetPackII pages Files and Resources is occupied by the package files panel /If you are preparing a Tomcat or Eclipse RCP installation, the panel is displayed in the cenral area of the page Files/ . The panel displays the installation package you are working on as a tree. Leaf nodes represent the files included in the package. Non-leaf nodes represent the directory structure of the installation. Top-level nodes represent abstract root directories. Each root directory is a destination directory for the installation (typically installations will have a single root, but you may need to have multiple root directories in certain circumstances.) The actual location of root directories in the end user’s file system becomes known only at install time. Each root has a special symbolic name that starts with $, e.g. $(Root). A root directory may be referenced by its name from various places, such as command line arguments for trial runs and shortcuts,values of Java system properties, etc.

An installation package contains one or more system nodes, added automatically by JetPackII. Only a restricted set of operations can be performed on system nodes.

In a complete installation package, directories and files have the respective icons displayed before their names. See also System files.

In an update package, the set of icons is richer:

“new”: directories and files that were not present in the original package; they will be created and copied during installation of the update;
“updated”: directories and files that were present in the original package and will be changed during installation of the update, that is, directories containing new or changed files, and files that were changed and will be replaced during update installation.
“identical”: directories and files that were parts of the original package, but were not altered since the original package was created; they are not included into the update package;

The following icon may also appear next to the name of a non-root node:

“absent”: marks files that no longer exist or may not be used, and directories that contain such files

Super Prev Next

System files

A thin red border surrounding a node icon indicates that the respective file or directory is “system”, i.e. was automatically added to the package by JetPackII.

There are the following types of system files:

You may not remove any of the system files from the package. Possible operations on system files are described in sections Step 3: Configuring the JET Runtime and Installation into multiple directories.

Super Prev Next


The following buttons appear above the tree view of the installation package files /The buttons are not displayed if you are packaging a Tomcat or Eclipse RCP application. In this case, all the necessary files are added to the package automatically and the content cannot modified from within JetPackII/ :

Create a new directory in the installation package.
Remove the selected node from the installation.
Rename the selected node.
Create a new root in the installation. This button is available only if the Multiple roots option is turned on via the Options item from the main menu.

Note: Multiple root installations can be created only using a third-party installer and are not supported in the Standard Edition.

You may also control the view using the following checkboxes:

The Show all files check box can be used to toggle the filtering of installation elements unnecessary for the current step.

The Show full path check box can be used to show the locations of the files included into installation on your system.

Super Prev Next

Selecting installation type

On this step you choose the type of the installation package that you want to prepare — either a new installation or an update to already existing one.

Super Prev Next

Creating a new installation

Click New Installation on the Welcome Screen to start preparing a complete installation package for your application. If you are packaging a Tomcat Web application or an Eclipse RCP application /For more information on deployment of Tomcat and Eclipse RCP applications, refer to Chapters Tomcat Web applications and Eclipse RCP, respectively./ compiled with Excelsior JET, click New Tomcat Installation or New Eclipse RCP Installation, resprectively.

The Files page will display immediately.

Super Prev Next

Creating an update

Using JetPackII, you may create updates or patches for the existing installations of your product.

To create such an update, you need the project file for the original package that was saved as "updatable". The project file has the extension .jpu. Click Update Package on the Welcome Screen of JetPackII and select the updatable project file using a conventional file dialog. You may also quickly select the desired updatable project among those displayed in the middle column of the Welcome Screen.

JetPackII then assists you in tracking differences between the original installation package and the files currently available on your system to include only added and modified files in the update. See Adding files using the Difference Tracker for details.

See also Updating JET Runtime.

Super Prev Next

Command line interface

From the command line, you can save a project as updatable using the -save-as-updatable option of the xpack utility.

Super Prev Next

Step 1: Adding files to package

On this step you can add application files to your installation package.

Note: If you are preparing a Tomcat or Eclipse RCP application installation, refer to sections Files to package or Files to package, respectively.

The page displays the package files panel on the left and the embedded file chooser on the right. The package files panel represents the structure of the installation on a target machine. The embedded file chooser allows you to select the files to be added to the installation. You must add at least one JET-compiled component (EXE or DLL) to create an installation.

Super Prev Next

Adding files using filechooser

To add file(s) to the installation, do the following:

  1. Select file(s) in the embedded file chooser on the right.
  2. Drag selected file(s) to the package files panel or click button.

Note that files are not actually copied — the project being created contains just links to file locations. You can check that all referenced files do actually exist on disk by selecting the File/Refresh menu item. In general, you should avoid physical deletion of files already added to the installation.

Adding a directory results in inclusion of its entire contents with subdirectories and respective (sub)directories are created in the package files panel. Note that adding large directories may take a while.

To create an empty directory in the installation, use button.

When you add a JET-compiled executable to the package, JetPackII recognizes it and automatically adds a system folder named rt. The folder contains the JET Runtime components required by the added executable /You may also add some optional components of the JET Runtime on Step 3./ . You may rename the JET Runtime folder or move it within the tree using drag-n-drop.

The restrictions on what files are allowed within a single installation are as follows:

When creating an update package, you can replace files included in the previous installation by dropping a newer file version over the older one. Such files will be added to the package to replace the previous copies of the files when updating a client installation of the application.

Super Prev Next

Adding files using the Difference Tracker

Another way to include files in an update package is using the Difference Tracker, which enables you to:

The Difference Tracker dialog is invoked automatically when you start preparing an update package. You may also invoke it manually later by selecting the Options/View and commit changes item of the main menu.

The dialog contains the Summary of changes panel that displays files and directories similarly to the Packages Files panel.

The tree highlights the differences between the content of the original package and files/directories located on the disk. To the left of each node element, one of the following icons appears:

“new”: files and directories not included in the original package;
“changed”: modified files and directories that contain new and/or modified files.
“identical”: files and directories identical to those included in the original package;

Note that the Difference Tracker treats files as identical if they have the same name and size, and meet either comparison criteria:

Comparison by date works faster but it is less accurate. You may select the desired comparison method by selecting the radio button in the Comparison method panel on the right.

The tree nodes displayed in the Summary of changes panel have checkboxes. Select the checkbox to mark the respective the file or directory (including all its content) as "to be added" to the update package.

Once you have selected the desired files and/or directories, click Ok at the bottom of the dialog to commit the selection and include the items in the update. For your convenience, the checkboxes of the changed files and directories have the selected state by default so you may add them at once by simply clicking Ok.

The checkboxes may have one of the following states:

Super Prev Next

Command line interface

From the command line, you can add files and folders to the package using the -source, -add-file and -move-file options of the xpack utility.

Super Prev Next

Step 2: Configuring Resources And System Properties

Note: if you are preparing a Tomcat or Eclipse RCP installation, this step is not required and the respective page of JetPackII is not available.

Each JET-compiled executable added to the installation has an associated classpath, that is, a list of directories and jar/zip files where the running application will look for resources, such as images, media, property files, etc. On this step you set up the classpath for each executable so that the classpath entries refer to directories and jar/zip files from the installation package, not from the local file system. Additionally, you may edit Java system properties for the executable(s) /Note that when creating an update package, you can set up the classpath and properties only for the files that are either “new” or “updated”. These setting cannot be edited for files marked as “identical” ./ .

The left side of this page contains the Package files panel that shows the contents of the installation being prepared. The Classpath panel to the right displays the list of the executables and their classpath entries that are shown as subitems of the executable names.

Each classpath entry name appears with a small icon displayed to the left. The icons indicate if the entry needs to be assigned, that is, if you should assign a directory or jar/zip file from the package to the entry. The following icons are used:

the entry needs to be assigned. The full path to the respective directory or jar/zip file on your system is displayed as the entry’s name.
the entry has been assigned. The path relative to a package root is displayed as the entry’s name.
the entry was packed into the executable during compilation. Such entries are also considered assigned and displayed just for reference.
the entry is disabled (by the user) because it does not contain any resource files

If all classpath entries appear to be assigned or disabled (in other words, no entry has the icon ), you may proceed to the next step. You may also wish to define additional Java system properties before leaving the Resources page.

Super Prev Next

Setting the classpath entries

First of all, the list of classpath entries specified when compiling the executable cannot be changed in JetPackII. That is, you cannot reorder the existing entries or add a new entry to the list. What you can do, (in fact, what you must do), is specify a particular directory or jar/zip file from the installation package for each entry marked as unassigned. Another option is to disable such an entry if you are sure that it does not contain any resources.

Super Prev Next

Selecting an item from the package

To assign a classpath entry the respective jar/zip file or directory from the package, do the following:

  1. Right-click the entry name and choose Assign by selecting from package from the pop-up menu; or, alternatively, select the entry name and click the button

    Assign by selecting from package

    A dialog displaying a package files tree will appear. Note that it contains only items of the appropriate type. For example, if the classpath entry is a directory, only directories from the package will be displayed.

  2. Select the desired item from the package and click Ok

Super Prev Next

Adding an item to the package

It may happen that the package does not contain the required item because you forgot to add it on Step 1. If so, you can add such an item to the package and assign its classpath entry at once without going back to the previous page. For that, do one of the following:

Note: If the classpath entry is a directory, it will be added to the package as whole, including all contained files and subdirectories. That is why JetPackII displays a message box with a request for confirmation when adding a directory. After you have added a directory, it is recommended to inspect its contents using the Package files panel to the left and remove unnecessary files, if any.

Super Prev Next

Disabling a classpath entry

Finally, if you are sure that certain classpath entries do not contain any resources, you can disable such entries. That is the case, for example, if the entry contains only class files that were all compiled into the executable.

To disable a classpath entry, do one of the following:

If you want to correct the classpath settings, you can re-assign or disable any classpath entry except for those packed into the executable (displayed with the icon )

Super Prev Next

Command line interface

From the command line, you can manipulate the classpath entries of an executable using the -assign-resource and -disable-resource options of the xpack utility.

Super Prev Next

Editing Java system properties

In the lower right panel you can edit the system properties for each Java application added to the installation package. The properties will receive their values upon application startup /As you know, a Java application can use the java.lang.System.getProperty() method to access Java system properties./ .

To set a Java system property for an executable added to the package, do the following:

  1. Select the desired executable from the list of executables above.
  2. Type in a name and, optionally, a value of a property in the lower right panel as

    property-name [ = property-value ]

Property names and values may contain references to root directories from the package files in the form $(root-name). For example, suppose the package contains a root directory called $(Root) that includes a subdirectory AppFiles. You may define the following property


Then you prepare a package and install it into a directory on the target system. Upon application startup, the JET Runtime replaces $(Root) with the absolute path of the installation directory. Thus, when the installed application inquires the value of the property, it gets the full path to the AppFiles directory on the target system.

Note: The java.class.path system property is set by JetPackII automatically. Its value cannot be edited manually and is displayed at the top of the property list for reference.

Super Prev Next

Command line interface

From the command line, you can set the system properties of an executable(s) using the -assign-vm-properties option of the xpack utility.

Super Prev Next

Step 3: Configuring the JET Runtime

On this page, you may:

Super Prev Next

Selecting optional components

The upper left panel displays a tree of the JET Runtime components that may be optionally excluded from the installation package without compromising compatibility.

The tree branches and certain components have checkboxes displayed to the left of their names. The checkbox on a tree branch allows you to include all its components at once, while the checkbox on a particular component controls inclusion of that component only. A checkbox has one of the following states:

The number that appears next to a component’s name is the amount of disk space (in KBytes or MBytes) occupied by the component’s files on end user systems.

Inclusion of optional components also increases the size of the installation bundle though the download size overhead will be typically smaller due to compression implemented in the used installer.

Super Prev Next

Optional components

The list of optional components displayed in the left panel and their meaning are as follows:

Super Prev Next

Command line interface

From the command line, you can specify additional locales using the -add-locales and -remove-locales options of the xpack utility.

From the command line, you can specify optional runtime components using the -add-opt-rt-files and -remove-opt-rt-files options of the xpack utility.

Super Prev Next

Compact Profiles

Excelsior JET supports Java SE 8 compact profiles.

Below is an excerpt from the official Java SE 8 documentation:

Compact profiles, introduced in Java SE 8, define subsets of the Java SE Platform API that can reduce the static size of the Java runtime on devices that have limited storage capacity.


A compact profile (or simply profile) is a subset of the full Java SE Platform API. Because they have smaller storage footprints, profiles can enable many Java applications to run on resource-constrained devices. Choosing a profile that closely matches an application’s functional needs minimizes the storage devoted to unused functions.

Compact profiles address API choices only; they are unrelated to the Java virtual machine, the language proper, or tools.

There are three profiles, compact1, compact2, and compact3. Each profile includes the APIs of the lower-numbered profiles (compact2 is a superset of compact1). The full SE API is a superset of the compact3 profile. The following table shows the high-level composition of each:

  Preferences Accessibility IDL
  RMI-IIOP CORBA Print Service
  Sound Swing Java 2D
  AWT Drag and Drop Input Methods
  Image I/O
compact3 Security1 JMX
  XML JAXP2 Management Instrumentation
compact1 Core (java.lang.*) Security Serialization
  Networking Ref Objects Regular Expressions
  Date and Time Input/Output Collections
  Logging Concurrency Reflection
  JAR ZIP Versioning
  Internationalization JNDI Override Mechanism
  Extension Mechanism Scripting
1Adds kerberos, acl, and sasl to compact1 Security.
2Adds crypto to compact2 XML JAXP.

Excelsior JET enables you to deploy your optimized application with a compact profile instead of the full Java SE Platform API, provided of course that the application does not use any parts of the API that are not present in that profile. For instance, a Swing app needs the Full SE API, whereas a JavaFX-only app can possibly do with the compact2 profile (you may need to remove the "JavaFX Bridge to Java2D/Swing" optional component as described in Selecting optional components).

Note: The javac compiler has the -profile option. Specifying -profile profile directs the compiler to flag usage of an API not present in profile.

When you add your compiled application to the project JetPackII automatically determines whether it can be deployed with a compact profile. If the answer turns out to be positive, and the project contains no other applications requiring an enclosing profile or the full Java SE API, JetPackII prompts you to let it automatically select the appropriate compact profile for your project.

The Compact Profile pane on the Runtime page displays the currently selected compact profile in a combo box. You can change it if you wish, though JetPackII won’t let you select a "smaller" profile than the minimum required by the applications that the project currently contains.

Super Prev Next

Command line interface

From the command line, you can select the desired compact profile using the -profile option of the xpack utility.

Super Prev Next

Enabling disk footprint reduction

You enable disk footprint reduction if you need the client installation of your application to occupy less disk space. It is important, for example, when the application files should be burned onto a CD full of other applications and/or data or the application will run off a USB flash drive.

Note that the reduction of disk footprint is possible only if the executable(s) added to the installation have been compiled with the Global Optimizer enabled. That is necessary to detect the parts of the JET Runtime that will unlikely be used during execution and compress them, thus minimizing the required disk space.

To enable disk footprint reduction, select "MEDIUM REDUCTION" or "HIGH REDUCTION" radio button in the Disk footprint panel. If you opt for the high reduction, you can also select an on-demand decompression method. Two options are available:

Note that on-demand decompression does not necessarily occur at application run time. For a detailed description of the reduction technique and available options, see Disk footprint.

Using the disk footprint reduction methods may negatively impact application start-up time and performance. If the disk space occupied by the application files is not an issue, you can disable the reduction by selecting the "NO REDUCTION" radio button in the Disk footprint panel.

Note: disk footprint reduction is not available in Standard Edition of Excelsior JET.

Super Prev Next

Command line interface

From the command line, you can configure disk foorprint reduction using the -reduce-disk-footprint option of the xpack utility.

Super Prev Next

Step 4: Performing a Trial Run

On this step you can perform a trial run of the application to be deployed.

A trial run is a testing procedure that ensures completeness of your package. It simulates execution of your application deployed to a target system. The package contents are copied to the specified trial run directory exactly if it was an installation to an end-user system. The fact that Excelsior JET is installed on your computer does not affect the correctness of trial run results.

The main purpose of the trial run is to ensure that the application would behave correctly if installed to a typical target system. At this step you can check if all files required by the application are actually included into the package.

Performing trial runs is optional and may be skipped. However, it is strongly recommended to perform a trial run of each JET-compiled executable at least once after you have added it to the installation package.

During a trial run, all files are copied into target directories corresponding to the installation roots, the post-installation processing is performed and the selected executable is started. Note that the system environment is reduced for the running executable, simulating installation on a “clean” target machine.

When you feel testing is over, close your program in a usual way (of course, you should do nothing special if your program stops automatically, e.g. if it is a number-crunching application).

After the program execution has finished, all JET Runtime components that were involved during the trial run are automatically added to the project. You may inspect them on the Runtime page (see Step 3: Configuring the JET Runtime).

Super Prev Next

Selecting a trial run directory

Trial run directory is the directory in which JetPackII copies all files from the package before a trial run is executed. You may consider it as a test "installation directory" for the package. It may be selected by clicking the Browse button. Note that the directory should be empty (you will be warned if it is not), and the respective drive must have enough free space to accommodate the installed version of your application.

Super Prev Next

Working with trial run configurations

If your installation package contains more than one JET-compiled executable, each of them should be run at least once. Moreover, if your application behaves essentially differently depending on command line arguments and/or user input, you may wish to run the application several times using different scenarios.

Trial run configuration is a “scenario” for a trial run. It specifies what executable is to be run, its working directory and command line arguments. By default, JetPackII creates one trial run configuration for each executable that you add to the package. You can create more configurations, e.g. for running your application with different command line arguments or with a shell script that defines additional settings.

Trial run configurations are enumerated in a list. The color of a configuration reflects its status. A trial run colored red is not performed yet. A trial run colored green is already performed. Certain changes in the project (such as adding/removing files, including a component into the JET Runtime ) switch trial run status to “red”.

You can add/remove trial run configurations using buttons on the left of the trial runs list:

Add a trial run configuration. After clicking this button, a dialog is displayed showing the list of executables and script files, suitable for trial run. Select a file to be run and click the OK button.
Remove the selected trial run configuration.

Super Prev Next

Configuring a trial run

The selected trial run configuration can be edited using the options panel to the right of the trial run list.

The Executable text field shows the executable or script file name in target form, that is, with its name relative to the root directory. It cannot be changed after the trial run configuration is created.

The Arguments text field shows command-line parameters that will be passed to this executable or script.

The Start in field shows the working directory of the executable or script.

To select a working directory from the package, do the following:

  1. Click the Select button. A dialog that shows the directory structure of your installation, will appear.
  2. Select a directory and click the OK button.

The selected trial run can be performed using the Run button. After you click it, JetPackII may prompt you to save the current project unless you haven’t saved it earlier. Also, if the trial run directory is not empty, you may be prompted to clear its contents before simulating installation. After copying files, JetPackII starts the executable or script specified in the selected trial run configuration. If it is a console application, its console will remain open after the execution is over and you may safely close it then.

Super Prev Next

Performing all trial runs

After certain changes in the project you may wish to perform all trial runs. The Run All button can be used to perform all trial runs, one by one.

Super Prev Next


If the tested executable exits with a non-zero return code, the trial run fails. JetPackII displays the respective error message that includes the executable or script name and return code. You may cope with it as follows:
  1. Check that your application always exits with zero return code in the case of normal termination.
  2. Make sure the package files are complete, that is, all auxiliary files necessary for your application were added to the package. Often, applications throw an uncaught exception when some files are missing. You may check it in the application’s console. /If your application was compiled with the console window suppressed (see Console window), you may check the problem without recompilation. For that, use the utility named gui that comes with Excelsior JET. Just issue the command “gui - executable-name” at the command prompt. Then you may run it manually and check the output in the console window./
  3. If your application requires a special environment to run, e.g. some environment variables should be set, you have to prepare a script file that makes the necessary settings and invokes the JET-compiled executable. Then, add the script to the package files and create a trial run configuration specifying the script in the Executable field.

Super Prev Next

Skipping trial runs

If you do not wish to perform trial runs, you may just skip them by checking the Skip Trial Run box. Note, however, that it is not recommended. You cannot proceed to any of the subsequent steps until you either perform all trial runs or check the box.

Super Prev Next

Step 5: Selecting a Back-End

On this step you choose the back-end, or, in other words, the type of the installation you wish to create.

You choose a back-end using the radio buttons displayed on the right side of the page. Note that when creating an update package, you cannot change the back-end because it should be identical to that selected for the original package.

The left side of the page contains the package files panel. It can be used to review the packageand to rename or move the uninstaller executable that is automatically added if you select Excelsior Installer as the back-end.

Sections describe the types of installations that you can create using JetPackII.

Super Prev Next

Command line interface

From the command line, you can specify the back-end using the -backend option of the xpack utility.

Super Prev Next

Excelsior Installer setup

Use the Excelsior Installer setup option to rapidly create an installer executable ready for distribution. Excelsior Installer provides typical installation facilities, such as displaying a splash screen and end-user license agreement, creating shortcuts, setting up file type associations, installing Windows services, creating registry keys, etc. The functionality of the installer is extensible so you can add extra actions to customize both installation and uninstallation procedures.

Note: Excelsior Installer setups have much smaller size as compared with other back-end options, if you select the best compression level on the final Step (see Step 8: Creating The Installation Package.)

By default, the installer runs a GUI installation wizard that guides the user through the installation process step by step. Unattended (batch mode) installation and uninstallation are also supported. The Excelsior Installer back-end is suitable for most packages /If you opt for Excelsior Installer, the client installation will be placed into one directory (or its subdirectories.) You therefore may not use multiple roots placement with Excelsior Installer./ .

Note that the uninstaller executable is automatically added to the package on selection of the Excelsior Installer back-end. However, the executable can be renamed or removed, if necessary.

Super Prev Next

Self-contained directory

Select this option to have JetPackII simply copy the installation package files into a newly created directory on your system on the last step. Before copying the JET-compiled executables, JetPackII “binds” them to the JET Runtime included in the package, so they will run without any extra settings, such as PATH, and from any location, provided that the directory is deployed "as is" and in whole.

In this mode, the basic installation procedure for new packages and updates to client installations is reduced to simply copying the directory to the target system. It effectively means that you may burn the resulting directory to a CD or copy it to a removable drive, package it using a simple utility such as WinZip, or supply it as input to any third-party installation tool.

JetPackII can also create a zip archive with a copy of the contents of the self-contained directory. See Step 8: Creating The Installation Package for details.

Super Prev Next

Installation into multiple directories

Note: Information in this section is not applicable to the Standard Edition of Excelsior JET.

Choose this back-end if you need the application files to be placed into multiple installation directories on the target system /That is, the directories which have not a common root directory. For example, they may be placed on different disk partitions./ . For instance, suppose your distribute several products sharing some common files. In such case, you may wish to divide each installation into two parts: common files and files specific to a particular product. In the Windows environment, common files are typically placed in a subdirectory of

  system-drive:\Program Files\Common Files\

directory whereas the location of product-specific files may be selected by the user during installation. Therefore, the application files will be actually installed in two directories on the target system.

If you choose this back-end, the button

Create new root

will appear at the top of the package files panel. Use it to create a new root directory that corresponds to a separate installation directory on the target machine. Then, you can reorganize package files by placing them under different roots to compose a package that consists of several parts.

On the last step, JetPackII will create a separate directory for each part of the installation. Note that after the directories have been created, locations of the files inside them must not be changed and each directory must be copied to the target system as a whole.

Excelsior Installer does not support installation into multiple directories, so you need to use a third-party setup generator to create the resulting installer. In addition to copying the application files, the installer will have to copy and invoke the xbind utility from the Excelsior Installation Toolkit. It is necessary to hard-wire the pathnames of the actual installation directories into the compiled executables. On the last step, JetPackII will display an instruction describing the required post-install action in details.

Super Prev Next

Step 6: Specifying Installation Settings

This step is intended to describe the appearance and behavior of the resulting installer. Note that this page is accessible only if you opted for using Excelsior Installer on the previous step.

Super Prev Next

Vendor information

First of all, you should specify a company name, a product name and a product version. For that, use the respective entry fields from the Vendor information pane at the top. As you type the values, JetPackII automatically fills the default values for other settings such as the registry keys and installation directory which you may change later, if necessary.

In addition, the values entered in the fields Product Name and Product Version are used to compose the product identifier that will be displayed in the resulting installer.

Super Prev Next

Command line interface

From the command line, you can specify vendor information using the -company, -product, -version’ options of the xpack utility.

Super Prev Next

Registry keys

Excelsior Installer creates two keys in the system registry solely for managing the installation. One key is created to make the installed program appear in the Add/Remove Programs applet of the Windows Control Panel.

The other key is created to store the necessary information, such as the installation directory, that will be used by the installer when installing updates. According to the Windows programming guidelines, the default pathname of the key ends with SOFTWARE/company-name/product-name/product-version and the key is placed in the respective part of the system registry /The registry subtree HKEY_LOCAL_MACHINE or HKEY_CURRENT_USER is used depending on the Common or Personal installation type that the user selects during installation./ . You may change the tail of the pathname by entering another value in the Registry key field.

If your application needs to create and manage additional registry keys on its own, you should extend the functionality of Excelsior Installer by providing install/uninstall callback DLLs as described in section Extra facilities.

Super Prev Next

Command line interface

From the command line, you can set the name of the registry key the -registry-key option of the xpack utility.

Super Prev Next

Installation directory

The installation wizard of Excelsior Installer displays a dialog where the user selects an installation directory for the application. In JetPackII, you can specify a default value for the installation directory or force installation into a particular location, not allowing the end user to change it.

Super Prev Next

Specifying a default installation directory

If you need to set a default installation directory, select the desired option from the Installation directory radiobutton group. The following options are available:

Super Prev Next

Fixing the installation directory

If you do not want the user to change the default directory when installing the application, uncheck the respective checkbox displayed below the entry field.

Super Prev Next

Command line interface

From the command line, you can control the installation directory settings using the -installation-directory, -installation-directory-fixed, and -installation-directory-type options of the xpack utility.

Super Prev Next

Pathnames with international characters

If the pathname of the installation directory contains non-ASCII characters, your program may function improperly due to defects in the internationalization facilities existing in certain versions of the Java platform. If you enter such a character in the installation directory field, JetPackII shall display a warning message when you attempt to leave this page.

Click Check to change the Trial Run directory pathname so that it matches the default installation directory pathname and repeat the trial run procedure.

Click Ignore if you already have international characters in the trial run directory pathname or if you normally skip trial runs.

Click Cancel to return to the Installation Settings page and correct the pathname so that it contains only ASCII characters.

Super Prev Next

Changing the default Tomcat port

You can allow the user to change default HTTP port when installing your Tomcat application. In this case the installation wizard of Excelsior Installer displays an additional dialog prompting the user to select the HTTP port for the application. This option is not available by default, because of explicit setting of HTTP port in tomcat configuration files.

To make this option available, you should set HTTP port via a VM property in the Tomcat configuration file "conf\server.xml".

Example of an explicit port setting:

    <Connector port="8080"

You should change it to:

    <Connector port="${}"

In this example, the VM property is used to set the Tomcat port. It can be initialized in "conf\".

For example:


If you do not want the user to change the default Tomcat HTTP port when installing the application, uncheck the respective checkbox.

Super Prev Next

Command line interface

From the command line, you can enable the user to set a HTTP port for Tomcat using the -allow-user-to-change-tomcat-port option of the xpack utility.

Super Prev Next


On the Shortcuts tab you can specify shortcuts which the resulting installer will create on the desktop and in the Start Menu. There are three places where shortcuts can be created:

These options appear as the top-level nodes of the shortcut tree displayed on the left side of the tab.

Super Prev Next

Adding a shortcut

You specify a new shortcut as follows.

  1. Add a shortcut to the shortcut tree by doing one the following:
  2. Type the shortcut’s name and press Enter.

  3. Select the file from the package for which you want to create the shortcut: click Select next to the Target field. A dialog showing the package files will display. Choose the file and click Ok.

Super Prev Next

Shortcut’s icon

By default, a shortcut reuses the icon of its target file /If you want to assign an icon to a JET-compiled executable, use JET Control Panel (see Icon.)/ but you may change the icon. For that, select the shortcut in the shortcut tree, click Select next to the Icon field and choose the desired .ico file from the package.

Super Prev Next

Working directory and arguments of shortcut’s target

You may also specify a working directory and command line arguments for the program that runs when the user clicks the shortcut. To do that, click Select next to the Start in field and select the required directory from the package. To specify arguments, type them in the Arguments entry field.

Super Prev Next

Command line interface

From the command line, you can add shortcuts using the -shortcut option of the xpack utility.

Super Prev Next

Installer appearance

On the Installer appearance tab you can set the language of the installation wizard interface, the end-user license agreement that the installer will display, and a splash screen that the installer will show when unpacking and copying package files.

Super Prev Next

Installation language

To set the language of the installation wizard, select the desired option from the Language combobox. Currently, English, French, German, Spanish, Polish, Russian, Japanese, Italian, and Brazilian Portuguese are supported. The default value "Auto-detect" means automatic selection of the language at install time depending on the system locale settings.

Super Prev Next

Command line interface

From the command line, you can control the installation language setting using the -language option of the xpack utility.

Super Prev Next

License agreement

To add the license agreement dialog to the resulting installer, type the full path to the desired text file in the License agreement field, or click Browse to select it using a conventional file dialog.

The license agreement must be a plain text file in either Unicode (UTF-16LE) or ANSI encoding. You can set the encoding by selecting the respective radiobutton below the field.

Super Prev Next

Command line interface

From the command line, you can specify the license agreement using either the -eula or the -unicode-eula option of the xpack utility.

Super Prev Next

Splash screen

If you want the resulting installer to display a splash screen when unpacking and copying package files, type full path to the desired bitmap image (.bmp file) in the Installation splash screen field or click Browse next to the field and select the image using a conventional file dialog.

Super Prev Next

Command line interface

From the command line, you can specify the splash screen image using the -splash option of the xpack utility.

Super Prev Next

Installer branding

The Branding button invokes the respective dialog that lets you further customize the installer and uninstaller, fitting them to the style of your application.

With the dialog, you can provide your own wordings, company and product logos to be shown during the installation process.

The branding information consists of three images and several text strings. Using the dialog, you can replace all images and text messages with your own ones, and then easily test the appearance of the installer dialogs.

Super Prev Next


The are three images you can replace with your own ones:

You can specify your own bitmap (.bmp) files to be used, or leave these fields blank, so default images will be shown. If an image is larger than the recommended size, it is clipped, so its upper left part is shown. If an image is smaller than the recommended size, it is centered in the display area. Images are never scaled.

Super Prev Next

Command line interface

From the command line, you can specify the installer branding images using the -welcome-image, -installer-image, and -uninstaller-image options of the xpack utility.

Super Prev Next

Text messages

The branding dialog lets you edit the most important text messages — the window title, window caption, and the welcome message.

The $(PRODUCT_NAME) macro

In every message, the string $(PRODUCT_NAME) is replaced by the product name you entered at the Vendor Information dialog.


As of version 15.3, the Excelsior Installer supports nine languages. Depending on the settings you specified at the Installer Appearance tab, the installer either detects the proper language automatically, or always sticks to the language of your choice.

The branding dialog lets you customize text messages for each supported language. Select the respective language from the combobox, edit the messages, and then proceed to the next language.

Note: There are other messages that Excelsior Installer may show to the user. They are pure technical in nature, and they do not contain any company or product names.

Reset values

At any moment, you can reset the text messages to the default state, using the Reset button. It affects the messages for the currently chosen language only.

Super Prev Next

Preview branding dialogs

Bottom part of the dialog contains three preview buttons: Welcome, Main and UnInstall. Using them, you can quickly test the changes you have done to the installer images and messages. These buttons invoke the installer and show the respective installer dialogs exactly as they would look like on the end user’s machine, using the images, text messages and language you just selected.

Note: If you provided your own text messages for several languages, do not forget to preview the installer dialogs for each of them.

Super Prev Next

Branding in update packages

When you create an update package, the branding information of the original package is partially reused:

Welcome screen image, Dialog screen image and Window caption text remain the same as you specified in the original package. You can keep them unchanged or set new values.

Welcome screen caption and Welcome screen text are not reused, they are replaced with the default values provided by Excelsior. This is because the respective messages differ in the original and update packages — the former tells the user that new software will be installed, while the latter tells the user that already installed software will be updated.

So, if you have edited the respective messages in the original package, you should correct them in the update package as well.

Uninstaller screen image is not editable. As update packages cannot be uninstalled by their own /Update packages are installed on top of a previously installed package. Uninstallation removes both the original package and all updates/ , you cannot provide the uninstall dialog image.

Super Prev Next

File associations

Note: Information in this section is not applicable to the Standard Edition of Excelsior JET.

On the File associations tab, you can specify a program that opens files of a certain type depending on the file name extension. The setting will take effect on the end user system after installing the package being prepared. For example, if you develop and distribute a program that works with files of some proprietary format, you can associate the file type with the program.

Super Prev Next

Adding a file association

You set up a new file association as follows.

  1. Specify the filename extension by doing one the following:
  2. Type the extension name and press Enter.

  3. Select the program that you want to associate with the file type: click Select next to the Associated program field. A dialog showing the package files will display. Choose the executable and click Ok.

Super Prev Next

Arguments of the associated program

Under the covers, the file association mechanism is quite simple. When the user double-clicks a file, the operating system recognizes the file type and invokes the associated program supplying the file name as a command line argument to the program.

In the Arguments field, that argument is shown as %1. If you need to specify additional arguments for the associated program, e.g. certain command line switches, type them in this field.

Super Prev Next

Icon of the file type

After registration of a file association in the system, files with the specified extension will be displayed with the icon of the associated program. If necessary, you may change the icon as follows.

On the right to the Icon field, click Select and select the desired .ico file from the package. Alternatively, you may select .exe file, not necessary that of the associated program, and the executable’s icon will be used when displaying files of this type.

Super Prev Next

Description of the file type

In the Description field, you may give a short description of the file type. The operating system will display it in some dialogs, such as File Properties. For example, the description of .mp3 files is "MP3 Format Sound".

Super Prev Next

Installer appearance

In the pane To appear in the installer as, you tune the appearance of the installer dialog where the user is prompted to set file associations. In the dialog, each association is displayed on a separate line which includes a checkbox to enable/disable installing the association, followed by the text Associate *.ext files with program-description, where ext is the extension name you specified in the File name extensions pane.

In the entry field, type a short description of the associated program that the installer will display for program-description on the dialog. You may also set the default state of the checkbox that enables installing the association.

Super Prev Next

Command line interface

From the command line, you can configure file associations using the -file-association option of the xpack utility.

Super Prev Next

Post-install actions

Note: Information in this section is not applicable to the Standard Edition of Excelsior JET.

On the Post-install actions tab, you may specify a list of typical post-install actions that the user can select on the last page of the Excelsior Installer GUI wizard. Examples are launching the application just installed, viewing the readme file, restarting the system, and the like.

Super Prev Next

Adding a post-install action

You set up a post-install action as follows:

  1. A post-install action configuration dialog will appear.

  2. Select the action type using the Type combobox. The following action types are available:

  3. If you are specifying a Run or Open action, click Select next to the Target field. A dialog showing the package files will display. Choose the desired file and click Ok.

  4. If you are specifying a Run action, you may also set:

Super Prev Next

Installer appearance

In the pane To appear in the installer as, you tune the appearance of the installer dialog prompting the user to execute the post-install actions after finishing the installation process.

In the dialog, each action is displayed on a separate line which includes a checkbox to enable/disable the action, followed by the text you type in the entry field of the pane. If you ship a localized version of the installer, you may select the desired language in the combobox on the right and type the respective localized text that describes the action.

You may also set the default state of the checkbox that triggers the execution of each post-install action.

Super Prev Next

Command line interface

From the command line, you can configure post-install actions using the -no-default-post-install-actions, -post-install-checkbox-run, -post-install-checkbox-open, and -post-install-checkbox-restart options of the xpack utility.

Super Prev Next

Extra facilities

On the Extra facilities tab you can specify a runnable file that will be executed just after the end of the installation process. Another available facility is adding your own callback DLLs that export functions which the installer will invoke before and after installation and uninstallation. These techniques enable you to add extra functionality to the resulting installer/uninstaller. Finally, on this tab you can select a clean-up policy for installation folders upon uninstall.

Super Prev Next

After-install runnable

To specify the runnable file, click Select in the After-install runnable pane and select the desired file from the package. If you need to specify command line arguments to the runnable, type them in the Arguments field. Values of the arguments may contain references to root directories from the package in the form $(root-name). For example, if you specify an argument $(Root)\MyFiles\InstallStuff, the installer will expand $(Root) to the absolute path of the installation directory on the target system.

The selected runnable file will be started when the user presses the Finish button on the last dialog of the installation wizard.

Note: You should not rely on the fact that the runnable starts in a particular working directory. If it needs to access the package files, you can specify the necessary arguments for the runnable as described above.

If you want to remove the run of the selected file from the installation process, click on the Name field and press the Delete key.

Super Prev Next

Callback DLLs

If your product needs to accommodate to a specific target environment, you can use one of the following customization facilities:

For more information on the programming of the callback DLLs see Callback DLLs.

Super Prev Next

Deleting all files from installation folders

By default, Excelsior unInstaller removes only the files copied to the installation folder(s) during installation.

You can configure the uninstaller to remove all files from the installation folders if, for example, your application creates some temporary files in the folders.

To enable this option, check the box at the bottom of the Extra facilities tab.

Super Prev Next

Installation settings for updates

When you create an update package, you can change the following settings:

You may also add new shortcuts to the files included in the update.

Other settings make no sense for updates, so the respective fields are read-only.

Super Prev Next

Step 7: Specifying Installation Settings Of Windows Services

A Windows service is a special long-running process that may be launched during an operating system bootstrap. See Chapter Windows services for more information on the creation of Windows services using Excelsior JET.

If you opted for the Excelsior Installer setup on Step 5 and your installation includes Windows service executables, this page is accessible to specify installation settings for the services. Attributes of each included service are displayed under a separate tab. You can edit the most attributes, if necessary. For example, you may type a service description to be shown during installation or when inspecting the service’s settings through Windows Administrative Tools.

Super Prev Next

General settings

The following attributes are displayed on each service’s tab:

Super Prev Next

Startup properties

Using the controls from the Startup properties pane, you specify how and under which account the service should start.

To specify an account to be used by the service, select either radio button from the Log on as group:

You specify how to start the service by selecting one of the following options from the Startup type combobox:

If you want the service to be started immediately after installation, check the Start service after installation box.

Super Prev Next


In the Dependencies pane, you may specify other services on which the service depends. To do that, click the Add button to the left and type in the system name of a service to include it in the dependency list.

Super Prev Next

Command line interface

From the command line, you can configure settings for Windows services using the -service, -service-startup, and -service-dependencies options of the xpack utility.

Super Prev Next

Step 8: Creating The Installation Package

This is the final step of creating the installation. This page contains the following fields.

Installation package — specify the location of the installation package here. If you use the Excelsior Installer back-end, it must be a single file, while for other back-ends the installation package is created as a directory. If you have already saved the project, this field contains the default value derived from project name and location.

Back-end — a text label that shows the back-end type you chose on Step 7.

If you opted for the Excelsior Installer backend this field is a combobox that displays the back-end name and the desired strength of the compression algorithm to be used by the installer. The available options are essentially trade-offs between the size of the resulting installer and the time required to build it.

If you have selected the Self-contained directory backend the Back-end field also turns into a combo box, with three options:

Create! button — click it after specifying the package location. If your project is not saved yet, you are prompted to save it.

Then a progress window is displayed and, as the process is over, the creation of your installation package is completed. If you have chosen "Excelsior Installer" or"Self-contained directory", you now have a package ready for installation or CD burn. Otherwise (for "multiple roots" installations), detailed instructions are displayed. They explain how to integrate the generated image into a third-party installer.

You are recommended to test your newly created package by installing it to several machines with different operation systems, hardware configurations, etc. before starting distribution.

Save as updatable button — click to save the project file as updatable. It may be used later to create update packages, from minor version updates and hot-fixes to major upgrades.

To prepare an update package, create a new project and click Update package on the Welcome Screen (see Saving a project).

After the successful creation of an update package, you can save the modified project as updatable, thus building a chain of updates.

Note: If you plan to issue minor updates to your application, it makes sense to write down the version of Excelsior JET, the current profile and the exact configuration of JET updates you used to compile and deploy your application, so as to avoid JET Runtime updates.

Super Prev Next

Command line interface

From the command line, you can control the creation of a zip archive for a self-contained directory using the -zip and -zip-only options of the xpack utility.

You can also set the compression level for Excelsior Installer using the -compression-level option of the xpack utility.

Super Prev Next

Packaging native method libraries

In most cases, Java native methods are placed in native methods libraries (DLLs) which the application loads on demand at run time. If your application’s classes contain native methods or the application uses a third-party component that includes native libraries, you need to add them to the installation.

Problems may arise when the installed application loads such a library unless you specify the appropriate search path /A Java runtime throws UnsatisfiedLinkError exception if it fails to load a native library./ . Fortunately, the Java platform provides an OS-neutral way of lookup of the native libraries through setting the java.library.path system property.

You can set the search path using JetPackII as follows. Suppose your installation contains a native library placed in the $(Root)/myLibs directory. Specify the property


on Step 2 (see Editing Java system properties.) As a result, the appropriate search path for the application will be automatically set on the target system.

Super Prev Next

Installations protected by license managers

Excelsior JET Optimizer protects your proprietary code from reverse engineering thus improving IP protection. However, it does not provide copy protection, that is, preventing unauthorized copying or use of the program. To resolve the issue, you can employ complementary protection mechanisms such as software license managers or hardware keys.

License managers typically encrypt the executable file and then add a wrapper around it. However, that does not allow JetPackII to work with such executables because it needs to read from the executable some information necessary for creating the installation. Therefore, you should use such copy protection tools after the installation is created.

That is not a problem if your installation type is self-contained directory: you may encrypt the executable(s) after JetPackII has creates the directory.

However, if you use Excelsior Installer, JetPackII directly creates a self-extracting setup so there is no intermediate step when the encrypting tools could work. The problem can be easily resolved using the xpack utility from Excelsior Installation Toolkit (see xpack.)

The procedure of creating an Excelsior Installer setup that includes encrypted executables is as follows.

  1. Create the Excelsior Installer setup in JetPackII and install the package on a test machine to make sure that the application works as expected if encryption is not used. On this step you have a project file which you saved on the last page of JetPackII. Let us call it MyPackage.jpn
  2. Create an empty directory for temporary use.
  3. Execute the command

       xpack project -make-image temp-directory

    supplying the JetPackII project name and the temporary directory as arguments. In this example, the exact command line would be

       xpack MyPackage.jpn -make-image C:\ENCRYPT

    In the specified directory, the xpack utility will create the installation which is not yet wrapped into the Excelsior Installer setup.

  4. Encrypt the executable(s) in the temporary directory
  5. Run the encrypted executable(s) to make sure that the application works as expected
  6. Execute the command

        xpack project -from-image temp-directory -target target-file

    supplying the same arguments for project and temp-directory. As a result, the xpack utility will create the Excelsior Installer setup that includes the encrypted executables. The resulting installer package name is target-file.

Now you can safely deploy the installation package to target systems.

Note: Copy protection mechanisms that involve encrypting executables cannot be used for multiple root installations. This limitation will be removed in future versions of Excelsior Installation Toolkit.

Super Prev Next

Relocation of JetPackII projects

In some cases, you may need to create the resulting package in an environment different from where the project was created, for example, on another machine / For that, you have to install JET on that machine and create an identical profile./ or on the same computer with the placement of package files changed. In such scenario, it would be reasonable to reuse the existing project rather than to create a new one from scratch. JetPackII can help you update the existing project so that all settings and properties you specified in it are retained.

Suppose that the package files were copied to (or built in) a new environment. Ideal case for packaging would be just copying the project file (.jpn) along with other files to the new location and rebuilding the package in the batch mode.

Note that a JetPackII project uses paths relative to its own location to reference the files included in the package. Therefore, if the overall file structure remains unchanged and the files are still available through the same relative paths, you have to do nothing to enable building the project in the new environment.

If some of the package files are not found this way, JetPackII automatically detects that the project has been relocated and lets you either supply the files, or remove them from the project. The following procedure helps you relocate an existing JetPackII project.

  1. Start JetPackII in the new environment and open the project file copied. JetPackII detects that the project was relocated and issues a warning. Click OK to display the Package files panel and check the package for completeness.
  2. If any package files are marked as absent (displayed with the icon ), fix them as follows:

    Check the Show full path box on the bottom pane to see where JetPackII expects to find the missing files. Then, either copy or move the files to the appropriate location or remove them from the project and add such files again from their present locations using the Filechooser pane on the right. Note that in the latter case, file-specific settings, for example user-defined system properties (see Step 2: Configuring Resources And System Properties) referencing the removed files, will be lost.

  3. Perform the Trial Run for safety.
  4. Go to the Finish page and click the Create! button. As the creation of the package finishes, the displayed information will contain instructions on how to build the package in the batch mode.

Super Prev Next

Updating JET Runtime

As you know, an installation package created with JetPackII includes JET Runtime files When you include a new version of a certain executable into an update package, it may turn out that it was compiled for a different version of the JET Runtime. JetPackII is capable of updating the JET Runtime files automatically in such situations.

Super Prev Next

When a JET Runtime update is necessary

A JET Runtime update is required if you have done one of the following since the creation of the original installation package:

Note: Even if you only intend to update files other than JET-compiled executables, JetPackII forces the JET Runtime into the update package under the following circumstances:

Tip: To avoid inclusion of the JET Runtime into the minor updates of your applications, make sure to enable reproduction of the respective build environments (see Reproducing the build environment).

Super Prev Next

JET Runtime Update dialog

When you initiate the creation of an update package, JetPackII automatically determines whether the JET Runtime included in the original package also needs an update, as described in When a JET Runtime update is necessary.

If there is a need to force a JET Runtime update, the respective dialog is displayed immediately after you click Update Package on the Welcome Screen. Otherwise, the Difference Tracker is displayed as usual and you may select the files that you want to include in the update package as described in Adding files using the Difference Tracker. Then, if you have included in the update any executables created by JET Optimizer, JetPackII checks them for compatibility with the JET Runtime included in the original package. If JetPackII has determined that a JET Runtime update is necessary, it displays the JET Runtime Update dialog.

The dialog prompts you to choose a new profile for the update package. The profile used when building the original package is marked as <ORIGINAL>, and the recommended profile is marked as <RECOMMENDED>. Select the desired profile and click OK. The respective version of the JET Runtime will be included in the update package.


  1. The current version of JetPackII includes all JET Runtime files into an update package, even if some of them were not changed. This will be improved in future versions.
  2. JetPackII further ensures that there is only one version of the JET Runtime in any actual installation. So if your update package includes a new version of the JET Runtime for any of the reasons listed in When a JET Runtime update is necessary, you must recompile all executables that were part of the original package, so as to make them work with that new version of the JET Runtime, and include them in the update package.

Super Prev Next

Command line interface

From the command line, you can include an updated JET Runtime in the package using the -update-rt option of the xpack utility.

Super Prev Next

Deployment Utilities

Super Prev Next


The xpack utility xpack is essentially a command-line driver for the same engine that powers JetPackII. You can use it to create or re-build installation packages from the command line or a build script.

Super Prev Next

Re-building installation package

Once you have created an installation package using JetPackII and saved the project file, you can build the package with the command:

  xpack JetPackII-project-file [-target target-file] [-version version]

The -target option specifies the name of the target file (for Excelsior Installer setups) orthe target directory (for self-contained directory or multiple roots package). If the option is omitted, the name specified on the last page of JetPackII is used.

The -version option may be used for changing the product version displayed by the installation wizard of Excelsior Installer. It takes no effect for other back-ends.

The -quiet option disables printing the log to the standard output.

Re-building installation packages with JetPackII existing projects is useful for minor updates, e.g. when only particular files are modified, provided that the overall structure of the project and installation settings were not changed.

Super Prev Next

Processing installation image with third-party tools

The xpack utility can also help if you want to use a third-party license manager to protect your installation packages created with Excelsior Installer back-end. The following command line prepares intermediate installation image for post-processing by a license manager or by other binary encryption utilities:

  xpack JetPackII-project-file -make-image image-dir

After the post-processing is done, the following command line creates an installation from the post-processed image:

  xpack JetPackII-project-file -from-image image-dir  [-target target-file]

Refer to Installations protected by license managers for details.

Super Prev Next

Creating a new installation package

Nearly all JetPackII capabilities are now accessible from the command line.

xpack also enables you to create a new installation package without a JetPackII project file. In the basic scenario, you simply specify a directory containing the compiled executable(s) and other package files /Except JET Runtime files/ , the desired backend, and the pathname of the resultingsetup executable ordirectory as follows:

  xpack -source src-dir -backend install-type -target target-file-or-dir

If you are packaging a compiled Eclipse RCP application, specify its root as src-dir; for Tomcat Web applications, supply the Tomcat directory. You can specify excelsior-installer or self-contained-directory as backend.

For more details and advanced scenarios of creating installations from command line, consult Creating Installation Packages from Scratch.

Super Prev Next


The xbind utility is used to perform post-installation processing of JET-compiled executables. You would normally use it in multiple root installations created with third-party installers.

xbind takes two files as input: a script file and a redirection file.

JetPackII prepares an xbind script file when creating the installation image. You do not need to edit that file.

An xbind redirection file should be prepared by the installer after the destination directory for each package root is defined. A redirection file is a plain text file, with each line specifying a root directory location on the target machine, in the following format:


For example,

    $(Root)=C:\Program Files\MyApp

Post-installation processing can then be performed via the command:

    xbind xbind-script xbind-redirection [-unicode-redirection]

xbind recognizes redirection files in the Unicode character set. The default encoding is ANSI. Use the -unicode-redirection option to specify that the redirection file is a Unicode text file.

Super Prev Next

Excelsior Installer

Excelsior JET includes an installation tool which helps you to compose a setup that contains JET-compiled applications and Windows services along with other files.

Super Prev Next


The Installer automatically binds installed JET-compiled executables to JET Runtime components. This technique guarantees that installed applications will use exactly the same versions of files that were used during testing on the developer’s machine. As a result, the behavior of deployed applications will be identical to that on the developer’s machine during a Trial Run. Besides, the location of standalone resources will be automatically added to the classpath making all executables clickable (no need in launching scripts).

Binding also helps avoid so called "DLL Hell" because DLLs are no longer looked for along the PATHso all import between components is unambiguously resolved independently on the target system environment variables.

There are two possible ways of installation:

If a project contains an installation callback DLL or a post-installation runnable, or both, they are invoked in the following order:

For the functions above, the return value of integer type means: zero — no error, installation may proceed, any non-zero value — there is an error, installation must be aborted.

Super Prev Next


An Excelsior Installer package may include an uninstaller executable, which removes installed package files , shortcuts and registry keys on user request. If the user runs the executable, e.g. via the shortcut placed in Program Folder of Start Menu, GUI uninstallation wizard appears.

The uninstallation acts as follows:

To perform uninstallation in the unattended mode, the user should specify the /batch option on the command line of the uninstaller executable.

Uninstallation is cumulative, that is, it removes the initially installed package along with all updates that were possibly installed later.

Super Prev Next

Callback DLLs

The install callback DLL should export the two functions:

 int __stdcall PreInstall (char* installation_folder_name)  int __stdcall PostInstall (char* installation_folder_name)

where the installation_folder_name parameter is the absolute pathname of the installation directory. The uninstall callback DLL should export the function

 int __stdcall PreUninstall (void)

Return value of the functions is a return code. If they return a non-zero value, the (un)installation process will be terminated and a dialog displaying the respective message and the return code, will appear. The installer/uninstaller invokes the functions in the order described in sections Installer and Uninstaller.

Though the declarations are given in the notation of the C language, you can create the DLLs using another programming language provided that it has equivalent types and its implementation supports the __stdcall calling convention.

Note: when building the DLLs, enable the static linking mode so that they do not depend on any other DLLs except those implementing the system API.