Excelsior Installer Configurations

The plugin supports the creation of Excelsior Installer setups - conventional installer GUIs for Windows or self-extracting archives with command-line interface for Linux.

To create an Excelsior Installer setup, add the following configuration into the excelsiorJet{} plugin extension:

packaging = 'excelsior-installer'

Note: if you use the same build.gradle for all three supported platforms (Windows, OS X, and Linux), it is recommended to use another configuration:

packaging = 'native-bundle'

to create Excelsior Installer setups on Windows and Linux and an application bundle and installer on OS X.

Excelsior Installer setup, in turn, has the following configurations:

• product = product-name - default is <project.name>

• vendor = vendor-name - default is <project.group>

• version = product-version - default is <project.version>

The above parameters are also used by Windows Version Information and OS X bundle configurations.

To further configure the Excelsior Installer setup, you need to add the following configuration section:

excelsiorInstaller {
}

that has the following configuration parameters:

• eula = end-user-license-agreement-file - default is <project.projectDir>/src/main/jetresources/eula.txt

• eulaEncoding = eula-file-encoding - default is autodetect. Supported encodings are US-ASCII (plain text) and UTF16-LE

• installerSplash = installer-splash-screen-image - default is <project.projectDir>/src/main/jetresources/installerSplash.bmp

The following parameters are only available for Excelsior JET 11.3 and above:

• language = setup-language - force the installer to display its messages in a particular language. Available languages: autodetect (default), english, french, german, japanese, russian, polish, spanish, italian, and brazilian.

• cleanupAfterUninstall = true - remove all files from the installation folder on uninstall

• After-install runnable configuration sections of the form:

  afterInstallRunnable {
      target = ""
      arguments = []
  }

  where target is the location of the after-install runnable within the package, and arguments contains its command-line arguments.

• compressionLevel = setup-compression-level - available values: fast, medium, high

• Installation directory configuration section:

  installationDirectory {
      type = ""
      path = ""
      fixed =
  }

  where:

  • type is either program-files (default on Windows, Windows only), system-drive (Windows only, default for Tomcat web applications on Windows), absolute-path, current-directory (default on Linux), or user-home (Linux only)
  • path - the default pathname of the installation directory
  • fixed - if set to true, prohibits changes of the path value at install time

• registryKey = registry-key - Windows registry key for installation.

• List of Windows shortcuts to create during installation, e.g. in the Start Menu:

  shortcuts {
      shortcut {
          location = ""
          target = ""
          name = ""
          icon {
              path = new File("")
              packagePath = ""
          }
          workingDirectory = ""
          arguments = []
      }
         .  .  .
  }

  where:

  • location - either program-folder, desktop, start-menu, or startup

  • target - location of the shortcut target within the package

  • name - shortcut name. If not set, the filename of the target will be used, without extension

  • icon - location of the shortcut icon. If no icon is set for the shortcut, the default icon will be used.

    If the package already contains the desired icon file, configure the packagePath parameter to point to its location within the package. Otherwise, set the path parameter to the pathname of an icon file on the host system, and, optionally, packagePath to the location of the folder within the package in which that icon file should be placed (root folder by default).

  • workingDirectory - pathname of the working directory of the shortcut target within the package. If not set, the directory containing the target will be used.

  • arguments - command-line arguments that shall be passed to the target

• noDefaultPostInstallActions = true - if you do not want to add the default post-install actions, e.g. prompting the user to run your main executable after installation.

• Windows post-install actions that will be shown to the user as a set of checkboxes at the end of installation:

  postInstallCheckboxes {
      postInstallCheckbox {
          type = ""
          target = ""
          workingDirectory = ""
          arguments = []
          checked =
      }
         .  .  .
  }

  where:

  • type - run (default), open, or restart
  • target - location of the target within the package (not valid for restart)
  • workingDirectory - pathname of the working directory of the target within the package. If not set, the directory containing the target will be used. Valid for the run type only.
  • arguments - command-line arguments that shall be passed to the target. Valid for the run type only.
  • checked - whether the checkbox should be checked by default (true or false)

• List of Windows file associations in the form:

  fileAssociations {
      fileAssociation {
          extension = ""
          target = ""
          description = ""
          targetDescription = ""
          icon {
              path = ""
              packagePath = ""
          }
          arguments = []
          checked =
      }
         .  .  .
  }

  where:

  • extension - file name extension without the leading dot

  • target - location within the package of the executable program being associated with extension

  • description - description of the file type. For example, the description of .mp3 files is "MP3 Format Sound".

  • targetDescription - string to be used in the prompt displayed by the Excelsior Installer wizard: "Associate *.extension files with targetDescription".

  • icon - the location of the association icon. If not set, the default icon will be used (e.g. the icon associated with the executable target).

    If the package already contains the desired icon file, configure the packagePath parameter to point to its location within the package. Otherwise, set the path parameter to the pathname of an icon file on the host system, and, optionally, packagePath to the location of the folder within the package in which that icon file should be placed (root folder by default).

  • arguments - command-line arguments that shall be passed to the target

  • checked - initial state of the respective checkbox "Associate *.extension files with targetDescription" in the Excelsior Installer wizard. Default value is true.

• installCallback = dynamic-library - install callback dynamic library. Default is <project.projectDir>/src/main/jetresources/install.dll|libinstall.so

• Uninstall callback dynamic library:

  uninstallCallback {
      path = new File("")
      packagePath = ""
  }

  If packageFilesDir or packageFiles add a library to the package, you need to configure packagePath parameter of uninstallCallback locating the library in the package, else set path parameter locating the library on the host system and packagePath specifying a folder within the package where the library should be placed (root folder by default). Default value for path is <project.projectDir>/src/main/jetresources/uninstall.dll|libuninstall.so

• welcomeImage = welcome-image - (Windows) image to display on the first screen of the installation wizard. Recommended size: 177*314px. Default is <project.projectDir>/src/main/jetresources/welcomeImage.bmp.

• installerImage = installer-image - (Windows) image to display in the upper-right corner on subsequent Excelsior Installer screens. Recommended size: 109*59px. Default is <project.projectDir>/src/main/jetresources/installerImage.bmp.

• uninstallerImage = uninstaller-image - (Windows) Image to display on the first screen of the uninstall wizard. Recommended size: 177*314px. Default is <project.projectDir>/src/main/jetresources/uninstallerImage.bmp.