Variables

## Variables |

### 1. Introduction

With variables you can customize many aspects of install4j. They can be used in all text fields and text properties in the install4j IDE as well as from the install4j API. The general variable syntax is

        ${prefix:variableName}

where prefix denotes the functionality scope of the variable and is one of

- compiler
  Compiler variables are replaced by the install4j compiler when the project is built.
- installer
  Installer variables are evaluated when the installer or uninstaller is running.
- launcher
  Launcher variables are evaluated when a generated application launcher is started.
- i18n
  Custom localization keys are evaluated at runtime and depend on the chosen installer language.
- (no prefix)
  Variables with no prefix resolve to environment variables when used in the launcher configuration.

Text fields in the install4j IDE where you can use variables have a variable selector next to them. The variable selection dialog shows all known variables that can be used in the current context.

The above dialog, for example, is shown when clicking on the button in a text property of an installer element or form component. There, you can use compiler variables, installer variables and custom localization keys, but not launcher variables.

For both compiler and installer variables install4j offers a fixed set of "system variables". These variables are prefixed with "sys.". These variables are not writable and it is discouraged to use this prefix for your own variables.

### 2. Compiler variables

Compiler variables are written as

        ${compiler:variableName}

The value of a compiler variable is a string that is known and replaced at compile time. The installer runtime or the generated launchers do not see this variable, but just the value that was substituted at runtime.

You can use compiler variables for various purposes. The most common usage of a compiler variable is the possibility to define a string in one place and use it in many other places. You can then change the string in one place instead of having to look up all its usages. An example of this is the pre-defined "sys.version" variable that contains the value of the text field where you enter the application version. Another usage for compiler variables is to override certain project settings on a per-media file basis. For example, if you want to include one directory in the distribution tree for Windows but another one for Mac OS X, you can use a compiler variable for that directory and override it in the media file wizard. Finally, compiler variables can be overridden from the command line compiler and the ant task.

When you use a compiler variable in your project that is not a system variable, it must be defined in on the Compiler Variables tab of the General Settings step. If an unknown variable is encountered, the build will fail. You can use other variables in the value of a variable. Recursive definitions are detected and lead to a failure of the build. It is not possible to define compiler variables with the name of a system variable.

install4j provides a number of system compiler variables. They include:

- sys.version
  The application version as entered on the Application Info tab.
- sys.shortName
  The short name of the application as entered on the Application Info tab.
- sys.fullName
  The full name of the application as entered on the Application Info tab.
- sys.setName
  The name of the media file definition. If the default name of the media set is not suitable, you can rename the media set.
- sys.platform
  A short identifier for the platform (windows, linux, unix, macos). The value of this variable depends on your choice in the platform step of the media file wizard.
- sys.languageId
  The 2-letter ISO 639 code (see http://www.w3.org/WAI/ER/IG/ert/iso639.htm) for the principal language of the installer. This variable can be overidden on the command line or the ant task which is useful if you build different installers for different languages.
- sys.withJre
  A variable that contains "_with_jre" if a JRE is statically bundled with a media file and the empty string if not. This is useful if media files with and without JRE are built.
- sys.date
  The current date in the format `YYYYMMDD` (e.g. "20060910")
- sys.javaMinVersion
  The minimum Java version as entered on the Java Version tab.
- sys.javaMaxVersion
  The maximum Java version as entered on the Java Version tab.
- sys.install4jHome
  The installation directory of the install4j IDE.
- sys.applicationId
  The application ID as entered on the Update Options tab.

You can access environment variables on the build machine with the syntax

        ${compiler:env.environmentVariableName}

where "environmentVariableName" is the name of an environment variable. This only works if no compiler variable with the same name is defined on the Compiler Variables tab. This is resolved at build time, not at run time.

In order to debug problems with compiler variables, you can switch on the `extra verbose output` flag in the Build step. All variable replacements will be printed to the build console.

### 3. Installer variables

Installer variables are written as

        ${installer:variableName}

The value of an installer variable is an arbitrary object that is not known at compile time. Installer variables are evaluated when requested in the installer or uninstaller. Installer variables are not pre-defined in the install4j IDE like compiler variables, however, they have to be set before they are actually used at runtime. I.e., if you use an installer variable in an action, you have to make sure that the installer variable is defined before the action is executed.

Installer variables are used to wire together actions, screens and form components at runtime. The user input in screens is saved to variables, which can be used in the properties of certain actions. Furthermore, variables are routinely used in condition and validation expressions. Some examples are given in the help topic on form screens. In expression/script properties, you retrieve variables by invoking

        context.getVariable(String variableName)

Variable value can be set with the installer API by invoking

        context.setVariable(String variableName, Object variableValue)

A common scenario is the need to calculate a variable value at runtime with some custom code and use the result as the initial value of a component in a screen. To achieve this you can add a "Set a variable" action to the startup screen and set its "Variable name" property to some variable name. In contexts where a variable name is expected by install4j, you must not use the `${installer:variableName}` syntax but specify `variableName` only. The return value of the "Script" property is written to the variable. If, for example, the variable represents the initial directory that is displayed for a customizable "Directory selection" screen, you then set the "Initial Directory" property of that screen to `${installer:variableName}`. In this way you have wired an action with a screen.

Another important use of installer variables is for the locations of custom installation roots. In most cases a custom installation root contains an installer variable that is resolved at runtime. Often, one of the system installer variables that represent a "magic" folder can be used, such as the Windows `system32` directory.

Installer variables can be passed to the installer or uninstaller from the command line prefixed with -V (for example -VmyVar=test). Alternatively, you can specify a property file containing installer variables with -varfile (for example -varfile myfile.prop). The variables will be String objects.

install4j provides a number of system installer variables. They include:

- sys.installationDir
  The installation directory for the current installation as a string. The value of this variable can change in the installer as the user selects an installation directory in the "Installation directory" screen or the installation directory is set via `context.setInstallationDirectory(File installationDirectory)`.
- sys.userDir
  The user home directory as a string, typically something like `C:\Documents and Settings\$USER` on Windows or `/home/$USER` on Unix platforms.
- sys.windowsDir
  The Windows installation directory as a string, typically `C:\WINDOWS`.
- sys.system32Dir
  The system32 directory of your Windows installation as a string, typically `C:\WINDOWS\system32`.
- sys.programFilesDir
  The directory in your Windows installation where programs are installed as a string, typically something like `c:\Program Files`.
- sys.programGroupDir
  The directory of the program group that will be or was created by the "Create standard program group" action as a string. If this action is not present, the value will be `null`. The value of this variable can change in the installer as the user selects a program group on the "Create program group" screen.
- sys.mediaFile
  The path of your media file as a string. Not available for uninstallers.
- sys.mediaDirectory
  The path of the directory where your media file is located as a string. Not available for uninstallers.
- sys.preferredJre
  The home directory of the JRE that will be used by the installed launchers. This variable will only be set after the "Install files" action has run. It will be the same as `System.getProperty("java.home")` unless a bundled JRE (shared or non-shared) has been installed.

### 4. Launcher variables

Launcher variables are written as

        ${launcher:variableName}

The value of a launcher variable is a string that is not known at compile time. Launcher variables are evaluated when a generated application launcher is started. Launcher variables can only be used in the VM parameters text field of the launcher wizard. No user-defined launcher variables exist, the available system launcher variables include:

- sys.launcherDirectory
  The directory in which your launcher is located.
- sys.jvmHome
  The home directory of the JVM that your launcher is running with. This is useful to put JAR files from the JRE into your boot classpath.
- sys.pathlistSeparator
  The platform-dependent separator for lists of directories. On Window, this is a semicolon (";"), on Unix a colon (":").

### 5. Custom localization keys

Custom localization keys are written as

        ${i18n:keyName}

The value of a custom localization key depends on the language that is selected for the installer. You can use this facility to localize messages in your installers if they support multiple languages. You can supply key value pairs for internationalization in the custom localization file. The variable selection dialog shows all keys in the custom localization file for the principal language of your project.

All standard messages displayed by install4j can be referenced with this syntax as well. You can locate the key name in one of the `message_*.utf8` files in the `$INSTALL4J_HOME/resource/messages` directory and use it anywhere in your project. The standard messages can be overwritten by your custom localization files.

### 6. Using variables your own applications

Many times there is a need in the installed applications to access user input that was made in the installer. The install4j API provides the helper class `com.install4j.api.launcher.Variables` to access the values of installer variables.

There are two ways that installer variables can be persisted in the installer: First, installer variables are saved to the default response file `.install4j/response.varfile` that is created when the installer exits or if a "Create response file" action is executed. Only response file variables are saved to that file. Please see the help topic on response files for more information. Second, selected installer variables can be saved to the Java preference store. The `com.install4j.api.launcher.Variables` helper class offers methods to load variables from both sources.

Saving to the Java preference store is interesting if you want to modify those variable values in your applications and save back the modified values. The Java preference store is available on a per-user basis so that it is possible to modify settings even if the user does not have write permissions for the installation directory. The `com.install4j.api.launcher.Variables` helper class has methods for loading and saving the entire map of installer variables that way saved by the installer. Also, it is possible to specify an arbitrary package to which the installer variables are saved, so that communication of settings between installers is made possible.

Lastly, it is useful to access compiler variables in your own applications. For example, the version number configured in the install4j IDE can be accessed in your own application through the `com.install4j.api.launcher.Variables` helper class.