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, installaiton of the Java Runtime Environment (JRE) on target systems is not required.
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.
You can start JetPackII as a standalone application or launch it from within JetBrains’ IntelliJ IDEA. You can find the IDEA Integration plug-in in the ideplugins/IDEA subdirectory of your Excelsior JET installation. For more information, visit
http://www.excelsior-usa.com/jetplugin.html
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.
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.
Suppose you have compiled your application with JET and the compiled version has successfully passed the QA-analysis on your system. Now you need to prepare it for distribution to end users without changing its behavior.
Ideally, you should write down the answers to the following questions before launching 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, three buttons are displayed:
Figure 2. Excelsior JetPackII
Just alike 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 at the left edge, 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.
A JetPackII project consists of a project configuration and a set of files, which together fully determine the installation. A project defines:
Note: The pathnames of the actual installation directories may be substitited into the property values during installation. See e.g. Packaging native method libraries for the possible use of this feature.
This information is stored in a JetPackII project file that you create as described later in this chapter. JetPackII project files have extensions “.jpn” (for new installations) and “.jpu” (for updates).
You may create a new JetPackII project by clicking the New button on the JetPackII splash screen or by clicking the New sidebar button or by selecting the File/New menu item. This brings up the New page. If there is already an opened project, JetPackII will prompt you to save it first.
You may open a previously created project right on JetPackII startup by clicking the Open button on the JetPackII splash screen or later 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 using the File/Reopen menu item.
You can 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” is added to the file name automatically.
You can 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.
The left part of JetPackII pages Files and Resources is occupied by the package files panel. 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 |
 |
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 4: Configuring the JET Runtime and Installation into multiple directories.
The following buttons appear above the tree view of the installation package files:
 |
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.
On this page you choose the type of the installation package that you want to prepare — either a new installation or an update to already existing one.
Click the New installation button on the New page to start preparing a complete installation package for your application. The Files page will display immediately.
Using JetPackII, you may update the existing installations of your product with upgrades or patches.
To create such an update, you need a project file for the original package that was saved as "updatable". Those project files have extension “.jpu”. Click the Update package button on the New page of JetPackII and select the desired updatable project file using a conventional file dialog.
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 JET Runtime Updates.
On this step you can add application files to your installation package.
The page displays the package files panel on the left and a host file chooser on the right. The package files panel represents the structure of the installation on a target machine. The host 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.
To add file(s) to the installation, do the following:
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 4./ . 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 JIT cache packaging.)
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.
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 appear:
| |
|
“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:
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.
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 saving classes to the cache takes time, and they are never reloaded from the cache.
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 runs, 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 3.
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.
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.
To assign a classpath entry the respective jar/zip file or directory from the package, do the following:
 |
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.
It may happen that the package does not contain the required item because you have forgotten to add it on Step 2. 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:
 |
Assign by adding to package |
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.
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:
 |
Disable classpath entry |
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 )
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:
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.
On this page, you may:
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.
The list of optional components displayed in the left panel and their meaning are as follows:
By selecting the Additional locales and charsets checkbox, you add all locales at once. Note that inclusion of all locales increases the size of the installation.
Note that a violation of this requirement will result in throwing java.awt.HeadlessException at run time.
New in JET 5.0:
Since version 5.0, 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).
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:
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 9: 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.
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 5: Performing a Trial Run). Upon application exit, JetPackII will display a warning if the detached package has been accessed during execution.
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.
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 run-time components that were involved during the trial run are automatically added to the project. You may inspect them on the JET runtime page.
The trial run directory is a directory where all files are copied into before a trial run. It can be thought of as an "installation directory" for a trial run. It may be selected by clicking the Browse button. The directory selected should be empty (and you are warned if it is not), and the respective drive must have enough free space to accommodate the installed version of your application.
If your installation package contains multiple JET-compiled executables, 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.
A 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.
Trial run configurations are enumerated in a list. The color of a configuration reflects its status. A trial run colored in 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 suitable for trial run. Select an executable to be run and click the OK button. |
 |
Remove the selected trial run configuration. |
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 file name in the target form (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 the executable to run.
The Start in field shows the working directory of the executable.
To select a working directory from the package, do the following:
The selected trial run can be performed using the Run button. After you click it, a dialog proposing to save the project may appear if you haven’t saved the project yet. 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. If it is a console application, its console will remain open after the execution is over (you may safely close it then).
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.
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 9: 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.
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.
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.
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.
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.
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.
If you need to set a default installation directory, select the desired option from the Installation directory radiobutton group. The following options are available:
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.
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.
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.
To set the language of the installation wizard, select the desired option from the Language combobox. Currently, English, French, German, Spanish, Polish, Japanese, and Russian are supported. The default value "Auto-detect" means automatic selection of the language at install time depending on the system locale settings.
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.
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.
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.
If your product needs to accommodate to a specific target environment, you can use one of the following customization facilities:
To do that, click Browse next to the Install callback shared library and select the library using a conventional file dialog.
To do that, click Select next to the Uninstall callback shared library and select the library from the package files.
For more information on the programming of the callback libraries see Callback shared libraries.
This step is needed only if the installation includes Windows services, so it is always skipped on Linux.
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 6. 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 a "third-party" back-end), 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 the Update package button on Step 1.
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.
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 3 (see Editing Java system properties.) As a result, the appropriate search path for the application will be automatically set on the target system.
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.
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.
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.
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 file rather than to create a new project 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) the new environment. Ideal case for packaging would be just copying the project file (.jpn) to the new location and rebuilding the package in the batch mode. The problem, however, is that placement of the package files in the file system may be changed during relocation so the existing project cannot be reused directly.
JetPackII automatically detects if the project was relocated, and attempts to find all package files, using paths relative to the new placement of the project file. If some of the files are not found this way, JetPackII lets you either supply the files, or remove them from the project.
The following procedure helps you easily relocate an existing JetPackII project.
), fix them as follows:
Enable the Show full path checkbox 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, such as system properties (see Step 3: Configuring Resources And System Properties) will be lost.
At last, implemented in 6.4:
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.
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).
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 the Update Package button on the New page 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:
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.
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
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.
Excelsior JET includes an installation tool which helps you to compose a setup that contains JET-compiled applications along with other files.
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:
The interactive installation consists of several steps:
To launch an installation in such unattended mode, specify the /batch option to the installer executable. Other command-line options specify installation settings, such as destination folder, etc. The installation process then runs on its own, no user input is required.
The following command-line options are recognized:
/dest "full-path" - defines the destination folder pathname. If it is not specified, the application will be installed into the default folder. The default folder value could be specified with JetPackII (see Installation directory.)
/primary "full-path" - defines the path to the installation being updated. This option makes sense only for update packages. If it is not specified, the setup will ask user for proper path.
/force - forces the setup to override an already installed package instance. If it is not specified and if another instance is detected, the setup will not proceed.
/no-aftrun - suppresses invocation of after-install runnables
/? - shows a brief help page.
Note: Both - and / are recognized as option starting characters, so /no-aftrun is equal to -no-aftrun.
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.
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.
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.