Excelsior JET Getting Started Tutorial

The Excelsior JET build process principally consists of two steps: compilation and packaging.

During compilation, the Java class files of your application get transformed into optimized native code. The result is a conventional binary executable.

That executable, however, can only run on the same system where Excelsior JET is installed. You need to package it together with the required Excelsior JET Runtime files for deployment to other systems. The result can be a zip archive, an installer, or simply a directory that can be processed further with a third-party setup generator.

Below please find step-by-step instructions for compiling and packaging a simple plain Java application with Excelsior JET using:

It is assumed that the bin/ subdirectory of your Excelsior JET installation has been added to the PATH environment variable. Version for Windows does that automatically, on macOS and Linux you need to do that yourself.

The official Excelsior JET Maven Plugin, available on Maven Central, enables you to add support for native builds to your existing Maven projects with ease. Here is how you would use it in a simple project:

  1. Copy and paste the following configuration into the <plugins> section of your pom.xml file:

    <plugin>
        <groupId>com.excelsiorjet</groupId>
        <artifactId>excelsior-jet-maven-plugin</artifactId>
        <version>1.1.3</version>
        <configuration>
            <mainClass></mainClass>
        </configuration>
    </plugin>
  2. Correct the plugin version number if needed.

  3. Enter the main class name into the <mainClass> parameter.

  4. Run Maven with the jet:build goal:

    mvn jet:build

See also Optional Pre-Build Steps below.

Run

The plugin will place your natively compiled Java application along with the required pieces of Excelsior JET Runtime in the target/jet/app subdirectory of your Maven project. You can run it directly or by issuing the command

mvn jet:run

Packaging

Packaging is automatic. You will find a zip archive named ${project.build.finalName}.zip in the root of your Maven project, ready for copying to other systems.

Optional Pre-Build Steps

It is recommended to conduct a Test Run before the build, for you to make sure your project is configured correctly and for Excelsior JET to collect some information about your application that will be useful during the build.

mvn jet:testrun

Notice During a Test Run, your application will start and work much slower than usual. That is normal behavior.

To take advantage of Profile-Guided Optimization, profile your application before the build:

mvn jet:profile

For further instructions, refer to the official plugin documentation.

The official Excelsior JET Gradle plugin, available on Maven Central, enables you to add support for native builds to your existing Gradle projects with ease. Here is how you would use it in a simple project:

  1. Add the plugin dependency to the buildscript{} configuration of the build.gradle file:

    buildscript {
        ext.jetPluginVersion = '1.1.3'
        repositories {
            mavenCentral()
        }
        dependencies {
            classpath "com.excelsiorjet:excelsior-jet-gradle-plugin:$jetPluginVersion"
        }
    }
  2. Correct the plugin version number if needed.

  3. Apply and configure the excelsiorJet plugin as follows:

    apply plugin: 'excelsiorJet'
    excelsiorJet {
        mainClass = ''
    }
  4. Set the mainClass parameter and use the following command line to build the application:

    gradlew jetBuild

See also Optional Pre-Build Steps below.

Run

The plugin will place your natively compiled Java application along with the required pieces of Excelsior JET Runtime in the target/jet/app subdirectory of your Gradle project. You can run it directly or by issuing the command

gradlew jetRun

Packaging

Packaging is automatic. You will find a zip archive named <artifactName>.zip in the root of your Gradle project, ready for copying to other systems.

Optional Pre-Build Steps

It is recommended to conduct a Test Run before the build, for you to make sure your project is configured correctly and for Excelsior JET to collect some information about your application that will be useful during the build.

gradlew jetTestRun

Notice During a Test Run, your application will start and work much slower than usual. That is normal behavior.

To take advantage of Profile-Guided Optimization, profile your application before the build:

gradlew jetProfile

For further instructions, refer to the official plugin documentation.

Compilation

  1. Invoke the JET Control Panel:

    • Windows: select JET Control Panel from the Excelsior JET Start Menu.
    • OS X/Linux: type jetcp at the command prompt and press Enter.

  2. On the welcome screen, click Plain Java SE application under Create New Project for. The Start Page shall display.

  3. Specify the full pathname of the directory containing the jar file of your application in the Application Working Directory field.

  4. Enter the java launcher command line used to start your application into the Command Line field and click Parse. This will populate fields in the right column: Classpath, Application Main Class, and Java System Properties.

  5. Click the Next button in the bottom right corner or select Test Run in the sidebar.

  6. On the Test Run page, click Run. This will launch your application on the Excelsior JET JVM, enabling it to collect certain run time information useful for optimization.

    Notice The application will start and work much slower than usual during a Test Run. That is normal behavior.

  7. If your application appears to launch and work normally, albeit slowly, close it and proceed directly to the Compile page.

  8. On the Compile page, click Build. The JET Control Panel will prompt you to save the project. Save it under the name of your choice. The compilation progress window shall appear.

    Notice Before exiting, the compiler will launch the resulting binary executable to gather its startup profile, terminate it automatically 20 seconds later, and patch for optimal startup.

  9. Upon successful compilation, a dialog will pop up. Click the Package button. This will close the JET Control Panel and launch the packaging tool, JetPackII.

Packaging

  1. The application binary and the rt directory containing the required Excelsior JET Runtime files get added to the project automatically. Click the Trial Run button in the sidebar.

  2. On the Trial Run page, click Run. JetPackII will copy package contents into an empty directory and run the application binary with a miminal set of environment variables, simulating deployment to a system that does not have Java or Excelsior JET installed.

    If the application works as expected, close it and proceed to the Backend page.

  3. On the Backend page, select the Self-Contained Directory option and go to the Finish page.

  4. On the Finish page, enter the full pathname of the output directory in the Installation Package field, or click Browse to select it using a file dialog. Then click Create!.

Upon completion, JetPackII will display information about the location of the resulting package, along with instructions for its deployment and unattended packaging.

If you have previsouly used the Excelsior JET GUI tools to compile and package your application, you can repeat those processes in unattended mode using the command-line compiler (jc) and packager (xpack) as follows:

jc =p project-name.prj
xpack -clean-target project-name.jpn

You can also feed a jar file that has the Main‑Class: header set in its manifest* directly to jc:

jc app.jar

This command will compile your jar into a native binary with the same base name that you can then package using xpack. For instance, the following command will create a zip file MyApp.zip with the native executable app.exe located in its root and the runtime files in the rt subdirectory:

xpack -add-file app.exe / -target MyApp -clean-target -zip-only

Now you can unpack MyApp.zip on another system and launch app.exe.

* The Class-Path: header, if present, gets picked up as well, so you can compile multi-jar apps this way.