Super Prev Next

Deployment automation


Super Prev Next

Intro

Excelsior JET comes with an Installation Toolkit, a complete solution for the deployment of applications which contain binary components (executables, shared libraries) produced by the JET Optimizer.

The toolkit includes:

It empowers 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 to CD, or transferred to a USB stick or flash memory card.

Using the toolkit, you can create 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

JetPackII

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, type

    JetPackII

at the command prompt and press Enter. 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, except for JIT Cache files. Possible operations on system files are described in sections Step 3: Configuring the JET Runtime and Installation into multiple directories.


Super Prev Next

Controls

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 package a Tomcat or 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

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 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 (executable or shared library) 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.

If the added executable has an associated JIT cache, it can be automatically added to the installation as well(see Packaging JIT cache.)

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

Packaging JIT cache

Note: packaging JIT cache is a deprected feature. For details, see Appendix Deprecated features.

If JetPackII detects that the added executable has an associated JIT cache, a dialog is displayed asking whether you want to add that cache to the package. Normally, you would only add optimized caches.

An important example of such executable is a custom launcher created by the xjava utility in the -Xcompile operation mode.

Note: Packaging JIT cache only allows you to automatically add the cache descriptor and shared libraries that contain the cached code. You still have to ensure that the original class files will be available to the JIT compiler on the target system.

If the dynamically compiled classes are contained in jar files and/or directories not listed in the classpath, you simply add them to the installation. Note that you should place the class containers at appropriate location to enable the used custom classloaders to find the classes.

If the jar files and/or directories are classpath entries, you can do one of the following:

You can enable or disable automatic inclusion of JIT cache for any executable later by selecting Options/Packaging JIT Cache menu item.


Super Prev Next

Caching of JITed classes on end user system

When deployed application runs on end user system, it may occasionally require JIT compilation to handle dynamically loaded classes.

If you added a JIT cache to the project, the JET Runtime automatically enables the caching mode — each time a new class is JITed on end user system, its compiled code is saved to the JIT cache directory, and reused on the next run, thus improving overall application performance.

But for certain types of applications, JIT caching makes no sense. Consider an application that constantly generates new classes, e.g. Hibernate thunks. Caching these classes is useless, because storing classes in the cache takes time and disk space but they are never reused.

There is an easy way to detect if your application belongs to this type. Run the application several times, and check the JIT cache directory size after each run. If the directory size keeps growing and does not stabilize after several run sessions, then new classes are continuously generated, and disabling the caching of JITed classes may improve application performance.

You can disable the JIT caching on end user system by removing the runtime property jet.jit.cache on Step 2.


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 ), Once there are no more unassigned classpath entires in the installation package, 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

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

          my.app.files.dir=$(Root)/AppFiles

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 my.app.files.dir 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

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

Selecting detached components

Excelsior JET features Java Runtime Slim-Down, a new deployment model that enables you to significantly reduce the download size of your Java applications.

The key idea is to select the components of the Java SE API that are not used by the application, and exclude them from the installation. Such components are called detached. For example, if your application does not use any of Swing, AWT, CORBA or, say, JNDI, you can exclude them from the installation package.

The detached components should be placed on a Web server so that the JET Runtime could download them if the deployed application attempts to use any of them at run time. You may find a detailed description of Java Runtime Slim-Down deployment in Chapter Java Runtime Slim-Down.

Note that detaching Java SE components is possible only if the executable(s) added to the installation have been compiled with the Global Optimizer enabled.

The Detached components pane of the Runtime page displays the names of the components that you have excluded from the installation. By default, however, all Java SE components are included. Click Configure to open a dialog for selecting the components you wish to exclude (detach).


Super Prev Next

Detached components configuration

The left pane of the dialog displays a tree of all Java SE components that can be detached. The tree branches have checkboxes displayed to the left of the components’ names. Enable the checkboxes of those components you want to exclude from the installation package.

When building an installation that has detached components, JetPackII creates two packages:

The detached package should be placed on a Web server so that the JET Runtime could download and unpack it if the deployed application tries to use some of the excluded components during execution.

You should specify the desired base URL for the detached package in the Base URL pane on the right. You will choose the filename of the detached package when creating the installation on the Final page (see Step 8: Creating The Installation Package).

Note: download from the server will occur if and only if the application accesses any of the detached components at run time.


Super Prev Next

How to identify unused components

Each detachable Java SE component comprises one or more Java packages and, in some cases, native method libraries and resource files. You may inspect the contents of a detachable component by expanding the respective tree node.

JetPackII helps you identify the Java SE components which are not used by your application. Each component name appears with a color tag displayed to the right. The tags indicate if classes from the component are referenced by your application or by third-party libraries it uses. The tags mean the following:

component is unused. Such components can be detached.
component is (partially) used. In general, it is not recommended to detach such components.

Under certain circumstances, you may detach a component marked with the red tag. When you try to exclude a used component, JetPackII opens a warning dialog. Click Details to see the list of classes and/or native method libraries which your application references. As JetPackII always places the referenced items into the main installation package, only the remaining part is actually detached.

However, care must be taken. If the application references lots of classes from a component, the remaining (unreferenced) classes may also be used implicitly, e.g. via the Reflection API. Placing them to the detached package may result in its downloading at run time. For more details, see Chapter Java Runtime Slim-Down.

To ensure that the downloading of the detached package will not occur at run time, simply run and test your application on the page Trial run (see Step 4: Performing a Trial Run). Upon application exit, JetPackII will display a warning if the detached package has been accessed during execution.


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

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

Troubleshooting

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 standard output.
  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 package and to rename or move the uninstaller executable that is automatically added if you select Excelsior Installer as the back-end.

The next sections describe the types of installations that you can create using JetPackII.


Super Prev Next

Excelsior Installer setup

Use the Excelsior Installer setup option to rapidly create an installer executable ready for distribution. The installer executable displays your end-user license agreement, lets user choose the installation folder, and then unpacks the software and JET runtime to the specified folder. It can optionally run your application right after the installation.

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 compressing level on the final Step (see Step 8: Creating The Installation Package.)

By default, the installer runs as a command-line tool that guides the user through the installation process step by step. Unattended (batch mode) installation/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 simple utilities such as tar+gzip or supply it as input to any third-party installation tool.


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

Installation directory

The installation wizard of Excelsior Installer displays a command prompt 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 default installation directory

If you need to set the 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

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 are sure the international characters in the directory name do not affect your software behavior 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

Installer appearance

On the Installer appearance tab you can set the language of the installer interface and the end-user license agreement that the installer will display.


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

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 or ANSI encoding. You can set the encoding by selecting the respective radiobutton below the field.


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 shared libraries that export functions which the installer will invoke before and after installation and uninstallation processes. Both techniques enables you to add extra functionality to the resulting installer/uninstaller.


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 after all installation procedures are completed.

Note: You should not rely on 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.


Super Prev Next

Callback shared libraries

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 libraries see Callback shared libraries.


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

Step 7: Specifying Installation Settings Of Windows Services

This step is needed only if the installation includes Windows services, so it is always skipped on Linux.


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 which is made of the project name and location.

Detached package — specify an absolute path and filename of the detached package. Note that this field appears only if you use Java Runtime Slim-Down model and your installation has detached Java SE components (see Selecting detached components).

Back-end — a text label that shows the back-end type you chose on Step 7. If you opted for Excelsior Installer, this field is a combobox that displays the back-end name and a desired strength of the compression algorithm to be used by the installer. The available options are trade-off between the size of the resulting installer and the time to build it.

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

Packaging native method libraries

In most cases, Java native methods are placed in native methods libraries (shared libraries) 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

     java.library.path=$(Root)/myLibs

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

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 /home/user/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.

Notes:

  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

Deployment Utilities


Super Prev Next

xpack

The xpack utility is used to re-build an installation package in the batch mode (from the command line or build scripts). After you have created an installation package using JetPackII and saved its 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) or the target directory (for self-contained directory or multiple roots package). If the option is omitted, the name shown 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.

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

The xpack utility can also help if you want to use a third-party license manager to protect your installation packages. 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

xbind

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:

    $(root-name)=root-location

For example,

    $(Root)=/usr/home/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 along with other files.


Super Prev Next

Installer

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 shared libraries are no longer looked for along LD_LIBRARY_PATH so 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 shared library 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

Uninstaller

An Excelsior Installer package may include an uninstaller executable, which removes installed package files on user request.

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 shared libraries

The install callback shared library should export the two functions:

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

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

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

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