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.
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:
- sys.version
The version of your application as configured under General Settings->Application Info.
- sys.shortName
The short name of your application as configured under General Settings->Application Info.
- sys.fullName
The full name of your application as configured under General Settings->Application Info.
- sys.publisher
The publisher of your application as configured under General Settings->Application Info.
- sys.publisherUrl
The publisher URL of your application as configured under General Settings->Application Info.
- sys.setName
The display name in the install4j IDE of the currently compiled media file as configured in the Media section. If the default name of the media file is not suitable, you can rename the media file.
- sys.platform
The platform descriptor of the currently compiled media file. One of "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.loc.gov/standards/iso639-2/php/code_list.php) for the principal language of the installer. This variable can be overridden 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. "20090910").The value is set at the start of a build and will not change during a single build.
- sys.time
The current time in the format HHMMSS (e.g. "153012") where HH is the hour in 24-hour format, MM is the minute and SS is the second. The value is set at the start of a build and will not change during a single build.
- sys.javaMinVersion
The minimum Java version as configured under General Settings->Java Version
- sys.javaMaxVersion
The maximum Java version as configured under General Settings->Java Version
- sys.install4jHome
The installation directory of the install4j IDE.
- sys.applicationId
The application ID as configured under Installer->Update Options
- sys.updatesUrl
The URL where auto updaters can download the update descriptor file updates.xml as configured under Installer->Auto-Update Options. This variable is usually used in the "Update descriptor URL" property of a "Check for update" action.
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.
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 can be predefined in the install4j IDE like compiler variables,
but this is not necessary.
Undefined installer variables come into existence the first time they are defined
at runtime.
However, it is an error to use an undefined variable. For example, 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)
You can analyze the bindings of an installer variable on the "Installer Variables"
tab of an
installer application configuration. It will show you a list of bound variables together
with all
bindings. In order to document and categorize bound installer variables, you can pre-define
them
and set a description for them, which will be displayed in the installer variable
selector in the
install4j IDE.
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:
- sys.installationDir [Source and Target]
The installation directory for the current installation. 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).Note that for single bundle installers on Mac OS X, the installation directory is usually just /Applications, not a separate subdirectory.
- sys.contentDir [Source and Target]
The directory that holds the installed files. On Windows, Linux and Unix, this is the same as the installation directory. For single bundle installers on Mac OS X, this is [Bundle name].app/Contents/Resources/app/. To reference an installed file in a cross-platform way, use this variable and not sys.installationDir.
- sys.mediaFile [Source and Target]
The path of your media file. Not available for uninstallers.On Windows and Unix this is the same as sys.installerFile. On Mac OS X, this is the path to the DMG file. If you want to reference the installer file, use sys.installerFile instead.
- sys.mediaDir [Source and Target]
The path of the directory where your installer file is located. Not available for uninstallers.On Windows and Unix this is the same as sys.installerDir. On Mac OS X, this is the directory where the DMG file is located. If you want to reference files inside the DMG file, use sys.installerDir instead.
- sys.installerFile [Source and Target]
The path of your installer file. Not available for uninstallers.On Windows and Unix this is the same as sys.mediaFile. On Mac OS X, this is the path to the installer inside the mounted DMG. If you want to reference the DMG file, use sys.mediaFile instead.
- sys.installerDir [Source and Target]
The path of the directory where your installer file is located. Not available for uninstallers.On Windows and Unix this is the same as sys.mediaDir. On Mac OS X, this is the path into the mounted DMG. If you want to reference files in the same directory as the DMG file, use sys.mediaDir instead.
- sys.resourceDir [Installer application state]
The directory where the resource files are present that have been configured on the Installer->Custom Code & Resources tab.
- sys.installationTypeId [Installer application state]
The ID of the selected installation type. This is only relevant if the "Installation Type" screen has been added to the installer. The value is null as long as no installation type has been selected.
- sys.version [Installer application state]
For installers, the version of your application as configured under General Settings->Application Info. In that case, the variable yields the same value as the compiler variable of the same name. For custom installer applications, the installed version,which might not be the same as the version for which the custom installer application was originally compiled.
- sys.logFile [Installer application state]
The full path to the currently used log file. This is a path in the TEMP directory. For installers, this changes after the "Install Files" action, when the log file is moved to a path in the installation directory.
- sys.responseFile [Installer application state]
If a response file is supplied with a -varfile command line argument, the full path to the response file. If no response file is used, the variable value is null.
- sys.preferredJre [Installer application state]
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") or the sys.javaHome installer variable unless a bundled JRE (shared or non-shared) has been installed. This variable is not available in the uninstaller or custom installer applications, use the sys.javaHome directory there.
- sys.languageId [Installer application state]
The 2-letter ISO 639 code (see http://www.loc.gov/standards/iso639-2/php/code_list.php) for the actual language of the installer. For fixed-language installers, this is the same as the compiler variable of the same name. For multi-language installers, the value is determined at runtime.
- sys.programGroupDisabled [Installer application state/Program group]
If the user has disabled program group creation on the "Standard program group" screen. This applies to both the Windows program group and the Linux/Unix launcher link directory selection. If no "Standard program group" screen is present, the variable value will be null.
- sys.programGroupName [Installer application state/Program group]
The name of the program group that user has selected on the "Standard program group" screen. If no program group has been selected, the variable value will be null. Only set in Windows installers.
- sys.programGroupDir [Installer application state/Program group]
The directory that has been selected as the program group. This is the full path to the actual location of the program group, not just the name of the program group. If no program group has been selected, the variable value will be null. Only set in Windows installers.
- sys.programGroupAllUsers [Installer application state/Program group]
If the user has selected to create menu entries for all users on the "Standard program group" screen. If no "Standard program group" screen is present, the variable value will be null. Only set in Windows installers.
- sys.symlinkDir [Installer application state/Program group]
The name of the directory for launcher links that user has selected on the "Standard program group" screen. If no program group has been selected, the variable value will be null. Only set in Linux/Unix installers.
- sys.fileSeparator [Cross-platform variables]
The platform-dependent separator for directories in a file path. On Windows, this is a backslash ("\"), on Unix a forward slash ("/").
- sys.pathlistSeparator [Cross-platform variables]
The platform-dependent separator for lists of directories. On Windows, this is a semicolon (";"), on Unix a colon (":").
- sys.userHome [Cross-platform variables]
The user home directory, typically something like C:\Documents and Settings\$USER on Windows or /home/$USER on Unix platforms.
- sys.userName [Cross-platform variables]
The user account name.
- sys.workingDir [Cross-platform variables]
The working directory. For the installer, this is the temporary directory that the installer was extracted to.
- sys.tempDir [Cross-platform variables]
The temporary directory of the operating system. On all supported platforms, this is the value of the TEMP environment variable.
- sys.javaHome [Cross-platform variables]
The Java home directory of the currently used JRE.
- sys.javaVersion [Cross-platform variables]
The Java version of the currently used JRE.
- sys.confirmedUpdateInstallation [Cross-platform variables]
If the user has confirmed an update installation on top of a previous installation. If a previous installation is detected, the "Welcome" screen asks the user whether to perform an update installation or choose another installation directory. The result of that question is saved to this variable. If the "Welcome screen is not shown, this variable is not set and Context#getBooleanVariable(...) returns false for this variable.
- sys.desktopDir [Cross-platform variables]
The directory used to physically store file objects on the desktop. A typical path is C:\Documents and Settings\[user name]\Desktop on Windows XP and earlier or C:\Users\[user name]\Desktop on Windows Vista and later. On Mac OS X, this is the ~/Desktop directory and on Unix the freedesktop.org setting for the XDG_DESKTOP_DIR directory is returned.
- sys.docsDir [Cross-platform variables]
The directory used to physically store a user's common repository of documents. A typical path is C:\Documents and Settings\[user name]\My Documents on Windows XP and earlier or C:\Users\[user name]\Documents on Windows Vista and later. On Mac OS X, this is the ~/Documents directory and on Unix the freedesktop.org setting for the XDG_DOCUMENTS_DIR directory is returned.
- sys.downloadsDir [Cross-platform variables]
The directory used to physically store a user's downloads. A typical path is C:\Users\[user name]\Downloads on Windows Vista and later. On Mac OS X, this is the ~/Downloads directory and on Unix the freedesktop.org setting for the XDG_DOWNLOAD_DIR directory is returned.
- sys.appdataDir [Platform-specific variables]
The directory that serves as a common repository for application-specific data. On Windows, a typical path is C:\Documents and Settings\[user name]\Application Data or C:\Users\[user name]\AppData\Roaming on Windows Vista and later. On Mac OS X, this is the ~/Library/Application Support directory.
- sys.localAppdataDir [Platform-specific variables]
The user-specific directory that serves local applications to store computed data. A typical path is C:\Documents and Settings\[user name]\Local Settings\Application Data on Windows XP and earlier or C:\Users\[user name]\AppData\Local on Windows Vista and later. On Mac OS X, this is the ~/Library/Caches directory.
- sys.windowsDir [Platform-specific variables]
The Windows installation directory, typically C:\Windows.
- sys.system32Dir [Platform-specific variables]
The system32 directory of your Windows installation, typically C:\Windows\system32.
- sys.commonDir [Platform-specific variables]
The common files directory of your Windows installation, typically C:\Program Files\Common Files.
- sys.programDataDir [Platform-specific variables]
The directory where applications can save data that is not specific to particular users. A typical path is C:\Documents and Settings\All Users\Application Data on Windows XP and earlier or
C:\ProgramData on Windows Vista and later.
- sys.startMenuDir [Platform-specific variables]
The directory containing Start menu items. A typical path is C:\Documents and Settings\[user name]\Start Menu on Windows XP and earlier or C:\Users\[user name]\AppData\Roaming\Microsoft\Windows\Start Menu on Windows Vista and later.
- sys.programsDir [Platform-specific variables]
The directory that contains the user's program groups. The groups are themselves file system directories. A typical path is C:\Documents and Settings\[user name]\Start Menu\Programs on Windows XP and earlier or C:\Users\[user name]\AppData\Roaming\Microsoft\Windows\Start Menu\Programs on Windows Vista and later.
- sys.startupDir [Platform-specific variables]
The directory that corresponds to the user's Startup program group. The system starts these programs whenever any user logs onto Windows NT or starts Windows 95. A typical path is C:\Documents and Settings\[user name]\Start Menu\Programs\Startup on Windows XP and earlier or C:\Users\[user name]\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup on Windows Vista and later.
- sys.sendToDir [Platform-specific variables]
The directory that contains Send To menu items. A typical path is C:\Documents and Settings\[user name]\SendTo on Windows XP and earlier or C:\Users\[user name]\AppData\Roaming\Microsoft\Windows\SendTo on Windows Vista and later.
- sys.templatesDir [Platform-specific variables]
The directory that serves as a common repository for document templates. A typical path is C:\Documents and Settings\[user name]\Templates on Windows XP and earlier or C:\Users\[user name]\AppData\Roaming\Microsoft\Windows\Templates on Windows Vista and later.
- sys.favoritesDir [Platform-specific variables]
The directory that serves as a common repository for the user's favorite items. A typical path is C:\Documents and Settings\[user name]\Favorites on Windows XP and earlier or C:\Users\[user name]\Favorites on Windows Vista and later.
- sys.programGroupDir [Platform-specific variables]
The directory of the program group that will be or was created by the "Create standard program group" action. 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.fontsDir [Platform-specific variables]
The folder that contains fonts. A typical path is C:\Windows\Fonts. On Mac OS X, the value is /Library/Fonts.
- sys.programFilesDir [Platform-specific variables]
The directory where programs are installed, typically something like C:\Program Files. On Mac OS X, the value is /Applications.
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
are:
- sys.launcherDirectory
The directory in which your launcher has been installed at runtime.
- 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. The "home directory" is the directory that contains the "bin" directory of the JRE.
- sys.pathlistSeparator
The platform-dependent separator for lists of directories. On Windows, this is a semicolon (";"), on Unix a colon (":").
- sys.tempDir
The temporary directory for the current user.
I18N messages
I18N messages are written as
${i18n:keyName}
The value of an I18N message 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 for I18N messages shows all system messages as well
as all messages
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.
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.