Installer variables are an important concept in InstallBuilder. They allow you to store user input, temporary values, establish flags and use
that information at different points during the build and installation processes. There are a number of built-in variables and you are also able
to create them directly. The basic way of creating or changing the value of a variable in InstallBuilder is using the <setInstallerVariable>
action:
<setInstallerVariable name="foo" value="bar"/>
The action above will store the value bar
in the variable foo
. Once you have defined the variable, its value can be accessed in any other part of the project as ${foo}
. If you require a variable that you are creating at install time to be also available in the uninstallation steps, you have to set the optional persist
attribute to 1
:
<setInstallerVariable name="foo" value="bar" persist="1"/>
At uninstallation time, this variables will contain the value of the last assignment using the persist
property.
Variable names must not contain characters other than digits, letters, dashes and underscores. There is only one exception to this rule: it is possible to use a variable as part of the name of another variable (as long as it is a valid one).
For example, if you have a variable foo
with a value of bar
, then:
<setInstallerVariable name="${foo}" value="Hello"/>
will be equivalent to:
<setInstallerVariable name="bar" value="Hello"/>
In addition to regular variables, parameters can also be accessed as variables. One good example is the well-known installdir
variable
which is in reality a <directoryParameter>
:
<runProgram program="${installdir}/myApplication.run" programArguments="--install"/>
Some additional information to take into account when working with variables is:
$foo
is used instead of ${foo}
, it will not be resolved but treated as a literal string.
bar
, the value will be set to ***unknown variable bar***
${variablename},
${VariableName}
or ${VARIABLENAME}
and obtain the same value in all cases.
When accessing a variable, some operations can be specified through the usage of special suffixes:
${installdir.dos}
: If the variable contains a path, this modifier returns the DOS-style name for it. This will only take effect if the file exists and the platform is Windows. This is particularly useful when the value of the variable may contain spaces and you need to pass it as an argument to a program. Using the .dos
suffix will remove the need of quoting the path as spaces will be removed. Take into account that using .dos
over a path with forward slashes won’t convert them to backslashes.
${installdir.unix}
: If the variable contains a path, it will be converted to a Unix-style path and all of the backslashes will be translated into forward slashes. This will only take effect if the platform is Windows.
${myPassword.password}
: The .password suffix is used to mark a variable as a password to be hidden in the logs. This way, you can use a password as an argument in a <runProgram>
action and log the execution without showing the plain text password. For example, the following action:
<setInstallerVariable name="pass" value="myhiddenpassword!"/> <runProgram> <program>mysql</program> <programArguments>-u root --password=${pass.password}</programArguments> </runProgram>
will be logged as:
Executing mysql -u root --password=**** Script exit code: 0
Please note this suffix is only considered when resolving variables that will be used when writing to the installation log or in the error messages thrown by the <runProgram>
and <setInstallerVariableFromScriptOutput>
actions. For example, <logMessage>
will interpret the suffix when logging its information but <writeFile>
will ignore it.
${myVariable.escape_backslashes}
: This will escape all of the backslashes in the text stored in the variable. It is especially useful for substitution of values in Java property files.
${installdir.dos.unix.escape_backslashes}
: The modifiers can be combined.
The below table summarizes all the suffixes:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
![]() | Convert forward slashes to backslashes |
---|---|
InstallBuilder does not have a modifier suffix to convert forward slashes to backslashes the same way as the <setInstallerVariableFromRegEx> <name>backslash_path</name> <pattern>/</pattern> <substitution>\</substitution> <text>${forwardslash_path}</text> </setInstallerVariableFromRegEx> The above will store the backslash-version of the Unix-like |
It is possible to access any environment variable using the ${env(varname)}
construct, where
varname is the name of an environment variable. For example, on Windows you can refer to the system drive with
${env(SYSTEMDRIVE)}
and, on Linux, Mac OS X and other Unix systems to the user home directory with
${env(HOME)}
To get a list of the environment variables on your system that will be available to the installer you can execute:
set
env
Both commands will print a list of the defined environment variables. However, you must take into account that some of these variables could vary from one machine to another.
Almost all of the elements of an InstallBuilder project can be accessed and modified as variables. This makes InstallBuilder a very versatile tool because it allows installers to customize themselves at runtime, based on the environment or on end user feedback. The three basic elements which can be accessed are:
All of the project properties such as <version>
, <shortName>
, <installerFilename>
and so on, can be referenced using the notation ${project.property}
. For example, ${project.shortName}
for the <shortName>
. Similarly to regular variables, you can use any capitalization when referencing an element. Using ${PrOjEct.InstallerFilename}
is equivalent to using ${project.installerFilename}
.
The below example changes the <installationType>
at runtime to perform an upgrade if the previous installed version, stored in an environment variable, is lower than the current one:
<project> ... <shortName>myProduct</shortName> <installationType>normal</installationType> ... <initializationActionList> <setInstallerVariable> <name>project.installationType</name> <value>upgrade</value> <ruleList> <!-- Check that the env variable exists --> <compareText> <text>${env(MYPRODUCT_VERSION)}</text> <logic>does_not_equal</logic> <value></value> </compareText> <!-- Compare the versions --> <compareVersions> <version1>${project.version}</version1> <logic>greater</logic> <version2>${env(MYPRODUCT_VERSION)}</version2> </compareVersions> </ruleList> </setInstallerVariable> </initializationActionList> ... </project>
You can refer to the Project Properties appendix for the complete list of properties.
Using this notation you can also modify component settings:
${project.component(default).selected}
${project.component(mysql).show}
This allows, for example, disabling components at runtime when the user does not provide a license key:
<stringParameter> <name>licenseKey</name> <description>Please provide a license key. If you leave the field empty you just will be able to test the basic functionality</description> <insertBefore>components</insertBefore> <postShowPageActionList> <actionGroup> <actionList> <setInstallerVariable> <name>project.component(premiumComponent).selected</name> <value>0</value> </setInstallerVariable> <setInstallerVariable> <name>project.component(premiumComponent).canBeEdited</name> <value>0</value> </setInstallerVariable> </actionList> <ruleList> <compareText> <text>${licenseKey}</text> <logic>equals</logic> <value></value> </compareText> </ruleList> </actionGroup> </postShowPageActionList> </stringParameter>
You can refer to the Components appendix for the complete list of properties.
Using the advanced syntax on parameters will allow you to modify not only their values but their entire set of properties such as <description>
, <explanation>
and the especially useful <ask>
. The basic usage is:
${project.parameter(nameOfTheParameter).propertyName}
For example:
${project.parameter(installdir).value}
${project.parameter(tomcat).description}
${project.parameter(mySQL).default}
If the parameter to access is a child of a <parameterGroup>
, the parent must also be specified. For example, the port
parameter in the below code:
<project> ... <parameterList> <parameterGroup> <name>mysqlConfiguration</name> <parameterList> <stringParameter name="port" description="MySQL port" value="3306"/> <passwordParameter name="password" description="MySQL root password" value=""/> ... </parameterList> </parameterGroup> </parameterList> ... </project>
Can be accessed using:
${project.parameter(mysqlConfiguration).parameter(port).value}
If the parameters are also included inside a component, instead of directly under the <project>
<parameterList>
, it must be also specified. For example, reusing the above example:
<project> ... <componentList> <component> <name>mySQL</name> <parameterList> <parameterGroup> <name>mysqlConfiguration</name> <parameterList> <stringParameter name="port" description="MySQL port" value="3306"/> <passwordParameter name="password" description="MySQL root password" value=""/> ... </parameterList> </parameterGroup> </parameterList> </component> </componentList> ... </project>
The parameter should now be accessed using:
${project.component(mysql).parameter(mysqlConfiguration).parameter(port).value}
You can use this functionality to disable pages or parameters at runtime based on the user input:
<project> ... <componentList> <component> <name>mySQL</name> <parameterList> <booleanParameter> <name>enableAdvanced</name> <description>Do you want to enable the advanced configuration?</description> <postShowPageActionList> <!-- Enable the page, which is disabled by default --> <setInstallerVariable> <name>project.component(mySQL).parameter(mysqlAdvanced).ask</name> <value>1</value> <ruleList> <isTrue value="${project.component(mySQL).parameter(enableAdvanced).value}"/> </ruleList> </setInstallerVariable> </postShowPageActionList> </booleanParameter> <parameterGroup> <name>mysqlAdvanced</name> <parameterList> <stringParameter name="mysqlPort" description="MySQL port" value="3306"/> <passwordParameter name="mysqlPassword" description="MySQL root password" value=""/> ... </parameterList> </parameterGroup> </parameterList> </component> </componentList> ... </project>
Parameters are also handy when you want to preserve variables defined at build time. Accessing a variable defined in the <preBuildActionList>
at runtime will result in an ***unknown variable varName***
error. To workaround this issue, you could use a hidden parameter (setting ask="0"
), that won’t be displayed in the help menu nor the installer pages. For example, to pass a random generated key for each of the built installers you could use the below code:
<project> ... <parameterList> ... <stringParameter name="build_identifier" value="" ask="0"/> ... </parameterList> <preBuildActionList> <!-- Create random identifier for the build --> <generateRandomValue> <variable>build_identifier</variable> </generateRandomValue> <!-- Date of the build --> <createTimeStamp> <variable>timestamp</variable> </createTimeStamp> <!-- Register the build information in a local file --> <addTextToFile> <file>${build_project_directory}/builds</file> <text>${build_identifier} - Product Version: ${project.version} - IB Version: ${installer_builder_version} - Built On: ${timestamp}</text> </addTextToFile> </preBuildActionList> ... </project>
As you are using a hidden parameter, the ${build_identifier}
will be available at runtime and you could, for example, send it to your server using an <httpPost>
action to register the installations for each release:
<postInstallationActionList> ... <httpPost url="http://www.example.com/register.php" filename="${installdir}/activationUrl"> <queryParameterList> <queryParameter name="build_identifier" value="${build_identifier}"/> <queryParameter name="version" value="${project.version}"/> </queryParameterList> </httpPost> </postInstallationActionList>
![]() | Accessing a parameter as a regular variable |
---|---|
If you try to access a parameter as if it were a regular variable, it will give you its value. That is, using The advantage of using the long notation is that it provides a very descriptive path to the element you are modifying. For example, if you are working with a very big project that is maintained by multiple developers and divided into multiple files using the <throwError text="You have selected strict password checking and your password is too short" > <ruleList> <isTrue value="${enableStrictChecking}"/> <compareTextLength> <text>${password}</text> <logic>less</logic> <length>${minLength}</length> </compareTextLength> </ruleList> </throwError> Where using the long location will point you directly to where they are defined (assuming the included files are named according to the component names, for example): <throwError text="You have selected strict password checking and your password is too short" > <ruleList> <isTrue value="${project.component(settings).parameter(basicConfiguration).parameter(enableStrictChecking).value}"/> <compareTextLength> <text>${password}</text> <logic>less</logic> <length>${project.component(settings).parameter(defaultPasswordSettings).parameter(minLength).value}</length> </compareTextLength> </ruleList> </throwError> |
In addition to the above-mentioned elements, any other tag in the XML project with a unique identifier can be referenced. For example, is possible to reference a folder in a component to get its destination:
`<showInfo text="${project.component(mysql).folder(mysqlConfig).destination}"/>`
But not a file in its <distributionFileList>
because files do not have a unique name.
You can also access language strings, either built-in or user-defined (check the Languages section for more details), using the special notation ${msg(stringKey)}
. It will be resolved to the localized string identified by the key stringKey
in the current installation language:
<showInfo text="${msg(hello.world)}"/>
If you have defined the hello.world
localized string in the <customLanguageFileList>
, depending on the installation language you will get results such as Hello world!
, Hola Mundo!
or Hallo Welt
.
In some cases, for example when modifying shell scripts programmatically, you may need a literal ${foo}
instead of the contents of the foo
variable (which may result in an ***unknown variable foo***
). For these cases, InstallBuilder implements a special notation to specify that you want the text treated literally, without trying to be resolved: ${'${variableName}'}
.
For example, ${'${foo}'}
will be resolved to: ${foo}
. More complex text can be escaped as shown in the snippet below:
<writeFile> <path>~/.bashrc</path> <text>${' PATH=${PATH}:/some/path Foo=${bar} '}</text> </writeFile>
It will write:
PATH=${PATH}:/some/path Foo=${bar}
As shown in the example, it accepts line breaks in the text to escape. The only limitation is that it cannot contain the characters '}
in the text to escape or it will be interpreted as the end of the escaped reference.
Nested variables are also allowed. They will be evaluated from the most inner reference:
<showInfo> <text>${text_${foo-${i}}_${bar}}</text> </showInfo>
This feature is especially useful when iterating using a <foreach>
action. For example, if you have a list of component names and you want to create a list with those that are selected:
<setInstallerVariable name="selectedComponents" value=""/> <foreach variables="component" values="componentA componentB componentC componentD"> <actionList> <setInstallerVariable name="slectedComponents" value="${selectedComponents} ${component}" > <ruleList> <isTrue value="${project.component(${component}).selected"/> </ruleList> </setInstallerVariable> </actionList> </foreach>
InstallBuilder also provides a list of built-in variables containing information about the installer or the environment in which it is executed:
HTTP
installer_http_code: Contains the HTTP status code of the last httpGet or httpPost action.
Java
java_autodetected: Whether or not a valid Java was autodetected
java_bitness: Autodetected Java bitness
java_executable: Location of the autodetected Java executable
java_vendor: Autodetected Java vendor
java_version: Autodetected Java version
java_version_full: Autodetected Java full version
java_version_major: Autodetected Java major version
javaw_executable: Autodetected javaw executable path
javaws_executable: Location of the autodetected Java Web Start executable
User Interface
installer_interactivity: The level of interactivity of the installation mode
installer_ui: The mode in which the installer is run
installer_ui_detail: The detailed mode in which the installer is run
.NET Framework
dotnet_autodetected: Whether or not a valid .NET framework was autodetected
dotnet_framework_type: .NET framework type
dotnet_version: .NET framework version
Installer
installation_aborted_by_user: Whether or not installation was manually aborted by user
installation_finished: Whether or not the installation finished successfully
installation_guid: Unique installation ID
installation_language_code: Language code of the installation
installer_builder_timestamp: Timestamp of the InstallBuilder used to build the installer
installer_builder_version: Version of InstallBuilder used to build the installer
installer_command_line_arguments: Command line arguments as passed to installer
installer_error_message: Contains the error of the last failed action, possibly masked by its <customErrorMessage>
installer_error_message_original: Contains the original error of the last failed action
installer_installation_log: The location of the installer log
installer_is_root_install: Whether or not the current user has root privileges
installer_package_format: Type of installer
installer_pid: PID of the running installer or uninstaller
program_exit_code: Exit code from program; set by runProgram and setInstallerVariableFromScriptOutput actions
program_stderr: Program’s error output; set by runProgram and setInstallerVariableFromScriptOutput actions
program_stdout: Program’s output; set by runProgram and setInstallerVariableFromScriptOutput actions
required_diskspace: Required disk space to install the application in Kilobytes
Windows Folders
windows_folder_program_files: Directory for program files
windows_folder_program_files_common: Directory for components shared across applications
windows_folder_system: Windows system directory
windows_folder_systemroot: Windows root directory
windows_folder_windows: Windows root directory
Windows Folders - System Scope
windows_folder_common_admintools: Directory that stores administrator tools for all users
windows_folder_common_appdata: Directory that stores common application-specific data
windows_folder_common_desktopdirectory: Directory that stores common desktop files
windows_folder_common_documents: Directory that stores common document files
windows_folder_common_favorites: Directory that stores common favorite items
windows_folder_common_music: Directory that stores common music files
windows_folder_common_pictures: Directory that stores common picture files
windows_folder_common_programs: Directory that stores common program groups in start menu
windows_folder_common_startmenu: Directory that stores common start menu items
windows_folder_common_startup: Directory that stores common Startup program group
windows_folder_common_templates: Directory that stores common templates
windows_folder_common_video: Directory that stores common video files
Cross-platform Folders
installdir: The installation directory
installer_directory: The directory location of the installer binary
installer_pathname: The full path of the installer binary
platform_install_prefix: The platform specific default installation path
system_temp_directory: Path to the system’s temporary directory
user_home_directory: Path to the home directory of the user who is running the installer
Build-time Variables
build_project_directory: Directory containing the XML project used to generate the installer.
installbuilder_install_root: Installation directory of InstallBuilder. This variable is available only at build time, as it does not make sense to access this information at runtime
installbuilder_output_directory: InstallBuilder output directory. This variable is available only at build time, as it does not make sense to access this information at runtime
installbuilder_output_filename: Location of the generated installer. This variable is available only at build time, as it does not make sense to access this information at runtime
installbuilder_ui: The mode in which the builder is run
Windows Folders - User Scope
windows_folder_admintools: Directory that stores administrator tools for individual user
windows_folder_appdata: Directory that stores user application-specific data
windows_folder_cookies: Directory that stores user cookies
windows_folder_desktopdirectory: Directory that stores user desktop files
windows_folder_favorites: Directory that stores user favorite items
windows_folder_history: Directory that stores user Internet history items
windows_folder_internet_cache: Directory that stores user temporary internet files
windows_folder_local_appdata: Directory that stores user local (non-roaming) repository for application-specific data
windows_folder_mymusic: Directory that stores user music files
windows_folder_mypictures: Directory that stores user picture files
windows_folder_myvideo: Directory that stores user video files
windows_folder_nethood: Directory that stores user network shortcuts
windows_folder_personal: Directory that stores user document files
windows_folder_printhood: Directory that stores printer shortcuts
windows_folder_profile: Directory that stores user profile
windows_folder_programs: Directory that stores user program groups in start menu
windows_folder_recent: Directory that stores shortcuts to user’s recently used documents
windows_folder_sendto: Directory that stores user Send To menu items
windows_folder_startmenu: Directory that stores user start menu items
windows_folder_startup: Directory that stores user Startup program group
windows_folder_templates: Directory that stores user templates
Linux Specific
linux_distribution: Type of Linux distribution
linux_distribution_description: Linux distribution description (based on Linux Standard Base tool: lsb_release)
linux_distribution_fullname: Linux distribution fullname
linux_distribution_id: Linux distribution distributor’s ID (based on Linux Standard Base tool: lsb_release)
linux_distribution_release: Linux distribution release number(based on Linux Standard Base tool: lsb_release)
linux_distribution_shortname: Linux distribution shortname
linux_distribution_version: Linux distribution mayor version
OSX Specific
osx_major_version: OSX major version number
osx_version: OSX version number
Windows Specific
windows_os_family: Type of Windows OS
windows_os_family_shortname: Windows OS family shortname
windows_os_flavor: Flavor of Windows OS
windows_os_name: Windows OS name
windows_os_service_pack: Windows OS Service Pack version number
windows_os_uac_enabled: Whether or not UAC is enabled
windows_os_version_number: Windows OS version number
System Configuration
machine_cpu_count: Number of CPUs in the machine
machine_cpu_speed: The machine’s CPU speed in MHZ
machine_fqdn: The machine’s fully qualified domain name
machine_hostname: The machine’s hostname
machine_ipaddr: The machine’s IP address
machine_swap_memory: The machine’s swap memory in MB
machine_total_memory: The machine’s total physical memory in MB
platform_exec_suffix: The platform specific binary suffix
platform_has_smp: Whether or not the machine has multiple processors
platform_name: At build-time, it contains the target build platform. At runtime, the platform in which the installer is running
platform_path_separator: The platform specific path separator
system_locale: Current system locale
system_username: Name of the user who is running the installer