Dynamic Variables

Dynamic variables behave like "normal" static variables defined by the <variable> tag, except that they are evaluated on each panel change. They are maintained as normal variables in an installation process, but in comparison to them dynamic variables have been enhanced by many more facilities. You can set dynamic variables values from the following sources on the target computer:

plain values
environment variables
INI files
option/property files (key-value pairs)
XML files (using XPath-like queries)
INI/option/XML files from within an ZIP or JAR file
Windows registry
output of a command execution

and filter them optionally using regular expressions. A particular dynamic variable can be evaluated based on a certain condition.

Other variables and dynamic variables can be used withing ${ and } to be replaced in the assignment expressions below.

The attribute checkonce[ = "true"|"false"] might be added to assign a dynamic variable only one time at the beginning of the installation process, which makes it behave as a normal variable, although with enhanced capabilities to gather a value.

The attribute ignorefailure[ = "true"|"false"] might be used to allow the installation to continue or abort if an error occurred during gathering the value for a certain dynamic variable.

The assignment of a dynamic variable itself can be made dependent on a certain condition, using the condition attribute, which refers to the ID of condition defined in the installer description elsewhere.

Types of Dynamic Variable Assignments

Plain Values

The simpliest way to assign a value to a dynamic variable is a plain value.

Example:

Assigning a plain value to a dynamic variable

<dynamicvariables>
    <variable name="previous.version" value="4.3.3"/>
</dynamicvariable>

The above example is functionally equivalent to

<variables>
    <variable name="previous.version" value="4.3.3"/>
</variable>

since there are no replacements used which might be refreshed on a panel change.

Plain Values as Embedded Text

In another addition to normal variables, the value of a variable can be also defined using a nested value element embedding plain text

Example:

To comment out something in a xml file if a certain pack with the ID "mycoolfeature" is not activated, you might alternate between one and the same variable name, which gets assigned different values in different conditions.

<dynamicvariables>

    <variable name="XML_Comment_Start" condition="\!izpack.selected.mycoolfeature">
        <value><\!\[CDATA[<!--]\]></value>
    </variable>
    <variable name="XML_Comment_End" condition="\!izpack.selected.mycoolfeature">
        <value><\!\[CDATA[-->]\]></value>
    </variable>

    <variable name="XML_Comment_Start" value="" condition="izpack.selected.mycoolfeature" />
    <variable name="XML_Comment_End" value="" condition="izpack.selected.mycoolfeature" />

</dynamicvariables>

The condition "izpack.selected.mycoolfeature" is generated automatically when a pack with the ID "mycoolfeature" was specified. You could now use ${XML_Comment_Start} and ${XML_Comment_End} in a file which should be parsed.

Values from Environment Variables

Assigning the value of an environment variable to a dynamic variable

<dynamicvariables>
    <variable name="search.path" environment="PATH"/>
</dynamicvariables>

The above example is functionally equivalent to

<variables>
    <variable name="search.path" value="${ENV[PATH]}"/>
</variable>

since there are no replacements used which might be refreshed on a panel change and the environment variable PATH won't change during the runtime of an installation process.

Values from Property/Option Files

Dynamic variables can be also assigned from a value in configuration files with key-value pairs, as property files.

The attribute type="options" is to be used to make this file parsed as an option file. Separators between the key and value might be for instance '=', ':' including their escaped variants '\=', '\:', where leading and trailing whitespaces are trimmed off.

Example:

Assigning a dynamic variable from properties/option files

<dynamicvariables>

    <variable name="option.1" checkonce="true"
              file="${INSTALL_PATH}/../old_installation/test.properties" type="options"
              key="first.setting"/>

    <variable name="option.2" checkonce="true"
              file="${INSTALL_PATH}/../old_installation/test.conf" type="options"
              key="work.dir"/>

</dynamicvariables>

Values from INI Files

It's also possible to assign Windows INI file values to IzPack dynamic variables. INI files are 3-dimensional configuration files with key-value pairs which are divided into several sections, following a certain syntax.

Example:

Assigning a dynamic variable from an INI file value

<dynamicvariables>
    <variable name="ini.1" checkonce="true"
              file="C:/Program Files/freesshd/FreeSSHDService.ini" type="ini"
              section="SSH server" key="SSHCMD"/>
</dynamicvariables>

Values from XML Files

Another facility of dynamic variable assignments is reading values from XML files using XPath queries. For the syntax of XPath see XML Path Language (XPath) for more information.

Example:

Dynamic variable assignment from XML file contents

<dynamicvariables>

    <variable name="XMLReadTest.1" checkonce="true" ignorefailure="false"
              file="${INSTALL_PATH}/../old_installation/test.xml" type="xml"
              key="/installations/installation[path='/usr/local']/title[@lang='en']/text()"/>

    <variable name="XMLReadTest.2" checkonce="true" ignorefailure="false"
              file="${INSTALL_PATH}/../old_installation/test.xml" type="xml"
              key="//title[@lang='en']/text()"/>

</dynamicvariables>

Values From Configuration Files in an Archive (JAR/ZIP)

All of the above variants of reading a dynamic variable value from a configuration file can be also applied if that configuration files is packaged as an entry into a ZIP or JAR file.

Example:

Assigning a dynamic variable from an configuration entry in a JAR/ZIP file

<dynamicvariables>

    <variable name="previous.version" jarfile="${INSTALL_PATH}/${INSTALL_SUBPATH}/libs/config.jar"
              entry="release.properties" type="options"
              key="release.version"
              checkonce="false" ignorefailure="true">
    </variable>

    <variable name="other.stuff" zipfile="${INSTALL_PATH}/${INSTALL_SUBPATH}/libs/misc.zip"
              entry="app.ini" type="ini"
              section="Global Settings" key="AUTOSTART"
              checkonce="true" ignorefailure="true">
    </variable>

</dynamicvariables>

Values from the Windows Registry

Dynamic variable values can be also gathered from Windows registry data.

Example:

Assigning a dynamic variable value from the Windows registry

<dynamicvariables>
    <variable name="RegistryReadTest" checkonce="true"
              regkey="HKLM\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment"
              regvalue="Path"/>
</dynamicvariables>

Values from the Output of a Command Execution

Last but not least, a dynamic variable value can be assigned from the output of an external command execution.

Using a dynamic variable assignment from command output is recognized by using the attribute executable in the variable definition.

Specific attributes:

executable
Absolute or relative path to the command to be launched. If the "dir" attribute is used, than relative paths are computed against the mentioned directory. The characters '.' and '..' inside the command path are resolved to a canonical path according to the operating system.
type := "process" | "shell" (optional, defaults to "process")
"process" - launch the command directly without an underlying shell invocation
"shell" - launch the command over the system shell, assuming it to be a shell script
dir (optional)
Absolute or relative path to a work directory, from where the command should be launched. The characters '.' and '..' inside the directory path are resolved to a canonical path according to the operating system.
stderr := "true" | "false" (optional, defaults to "false")
Whether the standard error output of the command should be used instead of the standard output.
This can be useful for some commands which deliver certain information only as error, for instance 'java -version'..

Example 1:

Assigning a dynamic variable value from the output of a command execution

<dynamicvariables>

    <variable name="hostname" checkonce="true"
              executable="hostname"
              type="process"/>

    <variable name="result.value" checkonce="true"
              executable="${INSTALL_PATH}/bin/init.sh"
              type="shell"/>

</dynamicvariables>

Example 2:

Assigning a dynamic variable value from the output of a command execution

<dynamicvariables>

    <variable name="previous.java.version" checkonce="true"
              dir="${INSTALL_PATH}"
              executable="jre/bin/java" stderr="true"
              type="process" ignorefailure="true"
              condition="haveInstallPath+isUpgrade">
      <arg>-version</arg>
      <regex regexp="java version[^\d]+([\d\._]+)" select="\1"/>
    </variable>

</dynamicvariables>

Filtering Values Using Regular Expressions

Each dynamic variable assignment can be filtered using a Java regular expression. This is done by the nested regex element.

Example:

Filtering dynamic variable assignments using regular expressions

<dynamicvariables>

    <variable name="previous.version" jarfile="${INSTALL_PATH}/${INSTALL_SUBPATH}/libs/config.jar"
              entry="release.properties" type="options"
              key="release.version"
              checkonce="false" ignorefailure="true" condition="upgradecheck">
      <regex regexp="([0-9]+(\.[0-9]+){2})" select="\1" defaultvalue="none"/>
    </variable>

    <variable name="RegExTest.Select.Windows" checkonce="true"
              regkey="HKLM\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment"
              regvalue="Path">
      <regex regexp="([^;]*)(.*)"
             select="\1"
             defaultValue="(unmatched)"
             casesensitive="false"/>
    </variable>

    <variable name="RegExTest.ReplaceFirst.Windows" checkonce="true"
              regkey="HKLM\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment"
              regvalue="Path">
      <regex regexp="([^;]*)"
             replace="+++ \1 +++"
             defaultValue="(unmatched)"
             casesensitive="false"
             global="false"/>
    </variable>

    <variable name="RegExTest.ReplaceAll.Windows" checkonce="true"
              regkey="HKLM\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment"
              regvalue="Path">
      <regex regexp="([^;]*)"
             replace="+++ \1 +++"
             defaultValue="(unmatched)"
             casesensitive="false"
             global="true"/>
    </variable>

</dynamicvariables>