HOWTO: Use third-party tools to create setup packages for JET-compiled applications

Article ID: 000026
Last Revised On: 03-Oct-2005

PDF Version: 000026.pdf

The information in this article applies to:

• Excelsior JET 4.0 and above

The similar article for Excelsior JET 3.7 and below can be found here 000017.

SUMMARY

Excelsior JET for Windows includes Excelsior Installer, which you may use to deploy your JET-compiled Java applications. However, the capabilities of Excelsior Installer are limited to very basic operations, such as file copying and creation of Start Menu shortcuts. For more sophisticated setups and for the distribution of your application on Linux you may use a third-party setup generator.

This article describes creation of setup packages for JET-compiled applications using third-party tools. The example section contains step-by-step instructions for creating a setup package with NSIS (Nullsoft Scriptable Install System.)

Control files for this article may be found here.

MORE INFORMATION

Introduction

After you have created an executable using Excelsior JET, you need to make a setup package for further distribution of the compiled application to your end users. Note, however, that the compiled executable cannot be simply copied into another system as it requires the JET Runtime components, that include Java 2 platform API.

Applications compiled by Excelsior JET do not require the Sun JRE to be bundled into the installation package or preinstalled on the target system.

The JetPackII tool that comes with Excelsior JET will help you to create an image of the installation: the self-contained directory with your application’s executable along with JET Runtime components. After that, the created image can be used as a source for the third-party setup generator.

To summarize, the packaging of your application using third-party tools consists of the following steps:

• Using the JetPackII utility, create the installation image of your application along with the JET Runtime.
• Create the installer using a third-party setup generator. The resulting installer should copy (unpack) the installation image to end user systems.

Typical Scenario: Single Root Placement

A root directory is an abstract destination directory for some or all of the installation package files. The actual pathname for each root, such as C:\Program Files\My App, is usually assigned at install time.

Excelsior JET allows you to define one or more root directories / Multiple root directories can be defined in Excelsior JET, Professional Edition only./ . The setup with one destination directory is suitable for most applications. During such setup all files are copied into one destination directory and its subdirectories on the end user system.

To create an image of the single root package, select the Third-party installer, single root placement on the step Backend in JetPackII.

On the final page in JetPackII, specify the location where to put the files prepared for the distribution (the image), for example C:\MyAppImage, and then click Create.

When JetPackII finishes creating the image you will find the set of files ready for distribution in the C:\MyAppImage directory.

All the installer has to do is copy the contents of the image directory to the target computer, preserving the subdirectory structure.

Example

This example shows how to create a single root installation for the hello application using NSIS (Nullsoft Scriptable Install System). To create the installer, do the following:

1. Go to the samples\Hello subdirectory of your JET installation.
2. Compile hello.java to hello.exe by running the build.bat script.
3. Run JetPackII and add hello.exe into the package. The JET Runtime components should be added automatically by JetPackII. The contents of the package should look as follows:

       $(Root)
           xjre
           hello.exe
   

4. Perform trial run.
5. Choose "Third-party installer, single root placement" back-end.
6. On the final step, choose image location and create an image. Exit from JetPackII.
7. Unzip this file into some directory. The following files should be created:
       hello.nsi
       pack.bat
   In the pack.bat file set the path to the created image and run the batch file to create a setup package with NSIS.

Advanced Scenario: Multiple Roots Placement

For the most applications, one root directory is enough, but in some cases it is useful to copy application files into several locations on the end user system. In this case, the JET Runtime must be "informed" about the locations of application’s components on the target system. This is done through the special post-processing (patching) of the executables.

To create an image with multiple roots, select the Third-party installer, multiple roots placement on the step Backend in JetPackII.

After JetPackII has created the image, you find the following content at the specified image location:

    C:\MyAppImage\Root1\
    C:\MyAppImage\Root2\
       .  .  .
    C:\MyAppImage\RootN\
    C:\MyAppImage\xbind.exe
    C:\MyAppImage\xbind.script

where the C:\MyAppImage\RootX directories contain directory structures and files you defined in JetPackII for the respective roots.

After creation of the image, JetPackII displays an information dialog to indicate that the extra post-processing of the executables is required.

To make the application work on the target system, the installation program should perform the following steps:

1. Copy the contents of all RootX directories to desired locations on the target systems (let’s call them Root1-Location, Root2-Location, and so on.)
2. Copy xbind.exe and xbind.script to the target system. Since these files are only needed at install time, you may copy them to a temporary directory, e.g. C:\tmp.
3. Create a redirection file (let it be C:\tmp\xbind.red). It should be a text file with the following contents:

       Root1="Root1-Location"
       Root2="Root2-Location"
          .  .  .
       RootN="RootN-Location"

   Note that quotes around the pathnames are required.

4. Run the following command line:

       C:\tmp\xbind.exe C:\tmp\xbind.script C:\tmp\xbind.red

   If xbind returns zero error code, the utility succeeded and the JET-compiled executables are ready to work. After that, the installer can remove the files created in the temporary directory.

REFERENCES

1. JET User’s Guide http://www.excelsior-usa.com/doc/jc.html, chapter “Deployment Automation”.
2. Nullsoft Scriptable Install System http://nsis.sourceforge.net
3. Inno Setup http://www.jrsoftware.org/isinfo.htm

Copyright © 2003-2006 Excelsior LLC. All rights reserved.