Excelsior JET comes with an Installation Toolkit, a complete solution for the deployment of applications which contain binary components (EXEs, DLLs, Windows services) produced by the JET Optimizer.
The toolkit includes:
It 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 EXE or Windows service, 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, select the JetPackII item from the Excelsior JET Start Menu. 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 (EXE or DLL) 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 DLLs 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.
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.
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 a GUI installation wizard that guides the user through the installation process step by step. Unattended (batch mode) installation and uninstallation are also supported. The Excelsior Installer back-end is suitable for most packages /If you opt for Excelsior Installer, the client installation will be placed into one directory (or its subdirectories.) You therefore may not use multiple roots placement with Excelsior Installer./ .
Note that the uninstaller executable is automatically added to the package on selection of the Excelsior Installer back-end. However, the executable can be renamed or removed, if necessary.
Select this option to have JetPackII simply copy the installation package files into a newly created directory on your system on the last step. Before copying the JET-compiled executables, JetPackII “binds” them to the JET Runtime included in the package, so they will run without any extra settings, such as PATH, and from any location, provided that the directory is deployed "as is" and in whole.
In this mode, the basic installation procedure for new packages and updates to client installations is reduced to simply copying the directory to the target system. It effectively means that you may burn the resulting directory to a CD or copy it to a removable drive, package it using a simple utility such as WinZip, or supply it as input to any third-party installation tool.
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 other settings such as the registry keys and installation directory which you may change later, if necessary.
In addition, the values entered in the fields Product Name and Product Version are used to compose the product identifier that will be displayed in the resulting installer.
Excelsior Installer creates two keys in the system registry solely for managing the installation. One key is created to make the installed program appear in the Add/Remove Programs applet of the Windows Control Panel.
The other key is created to store the necessary information, such as the installation directory, that will be used by the installer when installing updates. According to the Windows programming guidelines, the default pathname of the key ends with SOFTWARE/company-name/product-name/product-version and the key is placed in the respective part of the system registry /The registry subtree HKEY_LOCAL_MACHINE or HKEY_CURRENT_USER is used depending on the Common or Personal installation type that the user selects during installation./ . You may change the tail of the pathname by entering another value in the Registry key field.
If your application needs to create and manage additional registry keys on its own, you should extend the functionality of Excelsior Installer by providing install/uninstall callback DLLs as described in section Extra facilities.
The installation wizard of Excelsior Installer displays a dialog where the user selects an installation directory for the application. In JetPackII, you can specify a default value for the installation directory or force installation into a particular location, not allowing the end user to change it.
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 already have international characters in the trial run directory pathname or if you normally skip trial runs.
Click Cancel to return to the Installation Settings page and correct the pathname so that it contains only ASCII characters.
On the Shortcuts tab you can specify shortcuts which the resulting installer will create on the desktop and in the Start Menu. There are three places where shortcuts can be created:
These options appear as the top-level nodes of the shortcut tree displayed on the left side of the tab.
You specify a new shortcut as follows.
| |
Add shortcut |
displayed to the left; or
Type the shortcut’s name and press Enter.
Select the file from the package for which you want to create the shortcut: click Select next to the Target field. A dialog showing the package files will display. Choose the file and click Ok.
By default, a shortcut reuses the icon of its target file /If you want to assign an icon to a JET-compiled executable, use JET Control Panel (see Icon.)/ but you may change the icon. For that, select the shortcut in the shortcut tree, click Select next to the Icon field and choose the desired .ico file from the package.
You may also specify a working directory and command line arguments for the program that runs when the user clicks the shortcut. To do that, click Select next to the Start in field and select the required directory from the package. To specify arguments, type them in the Arguments entry field.
On the Installer appearance tab you can set the language of the installation wizard interface, the end-user license agreement that the installer will display, and a splash screen that the installer will show when unpacking and copying package files.
To set the language of the installation wizard, select the desired option from the Language combobox. Currently, English, French, German, Japanese, Spanish, Polish, 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.
If you want the resulting installer to display a splash screen when unpacking and copying package files, type full path to the desired bitmap image (.bmp file) in the Installation splash screen field or click Browse next to the field and select the image using a conventional file dialog.
The Branding button invokes the respective dialog that lets you further customize the installer and uninstaller, fitting them to the style of your application.
With the dialog, you can provide your own wordings, company and product logos to be shown during the installation process.
The branding information consists of three images and several text strings. Using the dialog, you can replace all images and text messages with your own ones, and then easily test the appearance of the installer dialogs.
The are three images you can replace with your own ones:
You can specify your own bitmap (.bmp) files to be used, or leave these fields blank, so default images will be shown. If an image is larger than the recommended size, it is clipped, so its upper left part is shown. If an image is smaller than the recommended size, it is centered in the display area. Images are never scaled.
The branding dialog lets you edit the most important text messages — the window title, window caption, and the welcome message.
The $(PRODUCT_NAME) macro
In every message, the string $(PRODUCT_NAME) is replaced by the product name you entered at the Vendor Information dialog.
Language
As of version 6.4, the Excelsior Installer supports seven languages. Depending on the settings you specified at the Installer Appearance tab, the installer either detects the proper language automatically, or always sticks to the language of your choice.
The branding dialog lets you customize text messages for each supported language. Select the respective language from the combobox, edit the messages, and then proceed to the next language.
Note: There are other messages that Excelsior Installer may show to the user. They are pure technical in nature, and they do not contain any company or product names.
Reset values
At any moment, you can reset the text messages to the default state, using the Reset button. It affects the messages for the currently chosen language only.
Bottom part of the dialog contains three preview buttons: Welcome, Main and UnInstall. Using them, you can quickly test the changes you have done to the installer images and messages. These buttons invoke the installer and show the respective installer dialogs exactly as they would look like on the end user’s machine, using the images, text messages and language you just selected.
Note: If you provided your own text messages for several languages, do not forget to preview the installer dialogs for each of them.
When you create an update package, the branding information of the original package is partially reused:
Welcome screen image, Dialog screen image and Window caption text remain the same as you specified in the original package. You can keep them unchanged or set new values.
Welcome screen caption and Welcome screen text are not reused, they are replaced with the default values provided by Excelsior. This is because the respective messages differ in the original and update packages — the former tells the user that new software will be installed, while the latter tells the user that already installed software will be updated.
So, if you have edited the respective messages in the original package, you should correct them in the update package as well.
Uninstaller screen image is not editable. As update packages can not be uninstalled by their own /Update packages are installed on top of a previously installed package. Uninstallation removes both the original package and all updates/ , you can not provide the uninstall dialog image.
Note: information in this section is not applicable to the Standard Edition of Excelsior JET.
On the File associations tab, you can specify a program that opens files of a certain type depending on the file name extension. The setting will take effect on the end user system after installing the package being prepared. For example, if you develop and distribute a program that works with files of some proprietary format, you can associate the file type with the program.
You set up a new file association as follows.
| |
Add association |
displayed to the left of the File name extensions pane; or
Type the extension name and press Enter.
Select the program that you want to associate with the file type: click Select next to the Associated program field. A dialog showing the package files will display. Choose the executable and click Ok.
Under the covers, the file association mechanism is quite simple. When the user double-clicks a file, the operating system recognizes the file type and invokes the associated program supplying the file name as a command line argument to the program.
In the Arguments field, that argument is shown as %1. If you need to specify additional arguments for the associated program, e.g. certain command line switches, type them in this field.
In the Description field, you may give a short description of the file type. The operating system will display it in some dialogs, such as File Properties. For example, the description of .mp3 files is "MP3 Format Sound".
In the pane To appear in the installer as, you tune the appearance of the installer dialog where the user is prompted to set file associations. In the dialog, each association is displayed on a separate line which includes a checkbox to enable/disable installing the association, followed by the text Associate *.ext files with program-description, where ext is the extension name you specified in the File name extensions pane.
In the entry field, type a short description of the associated program that the installer will display for program-description on the dialog. You may also set the default state of the checkbox that enables installing the association.
Note: information in this section is not applicable to the Standard Edition of Excelsior JET.
On the Post-install actions tab, you may specify a list of typical post-install actions that the user can select on the last page of the Excelsior Installer GUI wizard. Examples are launching the application just installed, viewing the readme file, restarting the system, and the like.
You set up a post-install action as follows:
| |
Add action |
displayed to the left of the panel within the tab; or
A post-install action configuration dialog will appear.
Select the action type using the Type combobox. The following action types are available:
If you are specifying a Run or Open action, click Select next to the Target field. A dialog showing the package files will display. Choose the desired file and click Ok.
If you are specifying a Run action, you may also set:
In the pane To appear in the installer as, you tune the appearance of the installer dialog prompting the user to execute the post-install actions after finishing the installation process.
In the dialog, each action is displayed on a separate line which includes a checkbox to enable/disable the action, followed by the text you type in the entry field of the pane. If you ship a localized version of the installer, you may select the desired language in the combobox on the right and type the respective localized text that describes the action.
You may also set the default state of the checkbox that triggers the execution of each post-install action.
On the Extra facilities tab you can specify a runnable file that will be executed just after the end of the installation process. Another available facility is adding your own callback DLLs that export functions which the installer will invoke before and after installation and uninstallation. These techniques enable you to add extra functionality to the resulting installer/uninstaller. Finally, on this tab you can select a clean-up policy for installation folders upon uninstall.
To specify the runnable file, click Select in the After-install runnable pane and select the desired file from the package. If you need to specify command line arguments to the runnable, type them in the Arguments field. Values of the arguments may contain references to root directories from the package in the form $(root-name). For example, if you specify an argument $(Root)\MyFiles\InstallStuff, the installer will expand $(Root) to the absolute path of the installation directory on the target system.
The selected runnable file will be started when the user presses the Finish button on the last dialog of the installation wizard.
Note: You should not rely on the fact that the runnable starts in a particular working directory. If it needs to access the package files, you can specify the necessary arguments for the runnable as described above.
If you want to remove the run of the selected file from the installation process, click on the Name field and press the Delete key.
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 DLL and select the DLL using a conventional file dialog.
To do that, click Select next to the Uninstall callback DLL and select the DLL from the package files.
For more information on the programming of the callback DLLs see Callback DLLs.
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.
When you create an update package, you can change the following settings:
You may also add new shortcuts to the files included in the update.
Other settings make no sense for updates, so the respective fields are read-only.
A Windows service, formerly known as NT service, is a special long-running process that may be launched during an operating system bootstrap. See Chapter Windows services for more information on the creation of Windows services using Excelsior JET.
If you opted for the Excelsior Installer setup on Step 6 and your installation includes Windows service executables, this page is accessible to specify installation settings for the services. Attributes of each included service are displayed under a separate tab. You can edit the most attributes, if necessary. For example, you may type a service description to be shown during installation or when inspecting the service’s settings through Windows Administrative Tools.
Service Name - the system name of the service. It is used to install, remove and otherwise manage the service. It can also be used to recognize messages from this service in the system event log. This name is set during the creation of the service executable. It is displayed for reference so you cannot edit it.
Arguments - the command line arguments passed to the service upon startup.
Display Name - the descriptive name of the service. It is shown in the Event Viewer system tool and in the Services applet of the Windows Control Panel. You must enter the Display Name before the installation package is created.
Description - the user description of the service. It must not exceed 1000 characters.
Note that this option is ignored on Windows NT 4.
Using the controls from the Startup properties pane, you specify how and under which account the service should start.
To specify an account to be used by the service, select either radio button from the Log on as group:
Enable the Allow service to interact with desktop checkbox, if the service needs to interact with the system desktop, e.g. open/close other windows, etc. This option is only available under the local system account.
When installing the package, the user will be prompted for an account name and password necessary to run the service.
You specify how to start the service by selecting one of the following options from the Startup type combobox:
In the Dependencies pane, you may specify other services on which the service depends. To do that, click the Add button to the left and type in the system name of a service to include it in the dependency list.
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 (DLLs) which the application loads on demand at run time. If your application’s classes contain native methods or the application uses a third-party component that includes native libraries, you need to add them to the installation.
Problems may arise when the installed application loads such a library unless you specify the appropriate search path /A Java runtime throws UnsatisfiedLinkError exception if it fails to load a native library./ . Fortunately, the Java platform provides an OS-neutral way of lookup of the native libraries through setting the java.library.path system property.
You can set the search path using JetPackII as follows. Suppose your installation contains a native library placed in the $(Root)/myLibs directory. Specify, the property
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&nbs