We need you!

Icon

The IzPack documentation needs work, and you are invited to edit it!

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

This element allows you to define variables for the variables substitution system. Some variables are built-in, such as $INSTALL_PATH (which is the installation path chosen by the user). When you

To define a set of variables, you just have to place as many <variable> tags in the file as needed. elements as needed inside a <variables> or <dynamicvariables> element which are in turn children of the <installation> element.

If you define a variable named VERSION you need to type $VERSION in the files to parse. The variable substitutor will then replace it with the correct value. One

Each <variable> tag take the following attributes :

  • name : the variable name
  • value : the variable value

Here's a sample <variables> section :

 

Code Block
languagehtml/xml
<variables>
  <variable name="app-version" value="1.4"/>
  <variable name="released-on" value="08/03/2002"/>
</variables>

Types of Variables

...

Static variables can be defined by the user using the <variables> tag in the installation description element.
They are evaluated on launching an installation and won't alter during the installation process. Static variables can assigned from an system environment variable on launching an IzPack installations.

...

Environment variables can be accessed using the syntax ${ENV[variable]}. The curly braces are mandatory. Note that variable names are case-sensitive and usually in UPPER CASE. For example, to get the value of the OS environment variable ANT_HOME, use ${ENV[ANT_HOME]} in the resource you want to substitute the according value during an installation.

...

Dynamic variables can be defined by the user using the <dynamicvariables> tag element in the installation description.
Dynamic variables are the most powerful facility of saving and gathering values on a target system where the installation is launched. The value of dynamic variables will be evaluated every time a panel is switched. Furthermore, beginning with IzPack 5.0, dynamic variables can be also assigned from several configuration and archive files, the Windows registry, the output of a command execution and dynamically filtered using Java regular expressions. See Dynamic Variables for more information and some examples how this can be achieved.
Dynamic variables can be handled like other variable types for variable substitution.

...

  • $INSTALL_PATH: the installation path on the target system, as chosen by the user
  • $INSTALL_DRIVE: the drive letter part of the installation path on the target system, set on Windows systems, only
  • $APPLICATIONS_DEFAULT_ROOT: the default path for applications
  • $JAVA_HOME: the JavaTM virtual machine home path
  • $CLASS_PATH: the Class Path used mainly for Java Applications
  • $USER_HOME: the user's home directory path
  • $USER_NAME: the user name
  • $APP_NAME: the application name
  • $APP_URL: the application URL
  • $APP_VER: the application version
  • $ISO2_LANG: the ISO2 language code of the selected langpack.
  • $ISO3_LANG: the ISO3 language code of the selected langpack.
  • $IP_ADDRESS: the IP Address of the local machine.
  • $HOST_NAME: the HostName of the local machine.
  • $FILE_SEPARATOR: the file separator on the installation system
  • $DesktopShortcutCheckboxEnabled: When set to true, it automatically checks the "Create Desktop Shortcuts" button. To see how to use it, go to `The Variables Element <variables> Be careful this variable is case sensitve !
  • $InstallerFrame.logfilePath: The path to the install log. This file contains the paths of all installed files. If set to "default" then the "$INSTALL_PATH/Uninstaller/install.log" path will be used. To see how to use it, go to `The Variables Element <variables>. If this variable is not set, no install.log will be created.
  • $TargetPanel.dir.<platform>
    For setting <platform>, see also: Use Cases.
    Defines the fully qualified target installation directory per for the target platform. IzPack choses the most closely matching one directory according to the current platform from the list during an installation..

Variable Substitution

References to variables enclosed in certain placeholder begin and end marks (for example ${ and }) can be used to substitute the according specified placeholders in

  • attribute values and embedded text in the installation description from which an IzPack setup is created
  • resource files of an installation
  • installed text files and shell scripts in several formats using the <parsable> tag

Substitute Variables in the Installer Descriptor

Additionally In additional to properties, static variables defined by the <variables> tag can be used to be substituted in the installer descriptor (install.xml) itself, where they have been defined.

...

Variables can be also substituted in resource files declared by the <resources> tag.

This is limited to static and built-in variables. It is not possible to substitute dynamic variables here, because they are refreshed and evaluated during the installation as soon as a panel is activated or changed, not at compilation time, and resource files are static files.

...

Substitute Variables in Installed Files

For replacing To replace variable references in installed textfiles by their current variable values those files must be tagged as parsable.

For this purpose, apply specify the <parsable> tag on a file previously included in the installation. Files marked parsable are parsed during the installation on the fly, references to existing variables are substituted, and the file is saved with substituted variable values.

See the <packs> element documentation for more information on how to use the <parsable> tag.

Using System Properties As Variables

System properties given on the command line can be directly included as IzPack variables when using the SYSTEM_ prefix followed by the system property name in the variable name, and substituting alls occurences of '.' by '_'. System properties with null values are not substituted.

Examples:

  • $SYSTEM_java_version
  • $SYSTEM_os_name

 are directly assigned to variables using the following syntax, provided the system property is variable.name:


IzPack 5.0 and later:

${SYSTEM[variable.name]}

More examples, provided -Dfeature.Enabled=true is added to launching the installer on the command line:

Code Block
titleExample 1
languagexml
<variables>
  <variable name="featureEnabled" value="${SYSTEM[feature.Enabled]}" />
</variables>

<conditions>
  <condition type="variable" id="isFeatureEnabled">
    <name>featureEnabled</name>
    <value>true</value>
  </condition>
</conditions>

 is equivalent to:

Code Block
titleExample 2
languagexml
<conditions>
  <condition type="variable" id="isFeatureEnabled">
    <name>SYSTEM[feature.Enabled]</name>
    <value>true</value>
  </condition>
</conditions>


IzPack 4 and earlier (obsolete handling in IzPack 5.0 for backward compatibility):


${SYSTEM_variable_name}

If the variable name contains '.' characters they got to be replaced by '_' here.

More examples, provided -Dfeature.Enabled=true is added to launching the installer on the command line:

Code Block
titleExample 1
languagexml
<variables>
  <variable name="featureEnabled" value="${SYSTEM_feature_Enabled}" />
</variables>

<conditions>
  <condition type="variable" id="isFeatureEnabled">
    <name>featureEnabled</name>
    <value>true</value>
  </condition>
</conditions>

 is equivalent to:

Code Block
titleExample 2
languagexml
<conditions>
  <condition type="variable" id="isFeatureEnabled">
    <name>SYSTEM_feature_Enabled</name>
    <value>true</value>
  </condition>
</conditions>

For Izpack before 5.0.0-rc2, no real substitution on demand happens but all system properties known to the JVM are added as IzPack variables by default when the installer starts.