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.
Comment: Simplified and corrected English. Removed version information except where backward compaibility is supported since this is version 5 docs Removed rc2 since no one should be running that now

...

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

To define a set of variables, you place as many  <variable> 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 valuevalue that you specified in the  <variables> or <dynamicvariables> element with the name VERSION.

Each <variable> tag take takes the following attributes :

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

Note that variable names are case-sensitive.

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

Static variables can be are defined by the user using the <variables> element. They

Static variables are evaluated on launching when an installation starts and won't will not alter during the installation process. Static variables can assigned from an system environment variable on launching an IzPack installations

Environment variables

System environment variables that are defined when the IzPack installation is launched, can be used without a  <variables> element definition.

Environment variables

...

can be accessed directly using the syntax ${ENV[variable]}. The curly braces are mandatory.

...

Environment variable names

...

are usually in UPPER CASE. For example, to get the value of the OS environment variable ANT_HOME, use ${ENV[ANT_HOME]}

...

to substitute the

...

definition of ANT_HOME.

Dynamic variables

The value of dynamic variables will be evaluated every time a panel is switched. This makes them useful for passing information between panels during the installation.

Dynamic variables

...

Dynamic variables can be defined by the user using the <dynamicvariables> 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.

Dynamic variables are handled like other variable types for variable substitution.

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.


Built-In variables

There is are a couple of "hard-coded" variables implemented in IzPack. The value of several  

The following variables are built-in variables might alter depending on local conditions on and have values set by IzPack  depending on the target system where the installation is launched.

The following variables are built-in :

or information supplied by the user during the installation.

  • $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 applies to 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
  • $TargetPanel.dir.<platform>
    For setting <platform>, see also: Use Cases.
    the fully qualified target installation directory for the target platform. IzPack choses the most closely matching directory according to the current platform..

The following variables are defined but can have values redefined by the installation procedure: 

  • $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.
    the fully qualified target installation directory for the target platform. IzPack choses the most closely matching directory according to the current platform..

Variable Substitution

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

...

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 '_'. No substitution happens in this case, if the according system variable cannot be found in the execution environment. This means that for example the string ${SYSTEM_java_version} gets inserted into the output as a literal string, instead of replacing it by an environment value.

Examples:

...

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


${SYSTEM[variable.name]}

Example:

If "-Dfeature.Enabled=true" is on the command line that launched the installer, the command line argument can be used as follows:

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>


The format used in IzPack 4 and earlier is supported in IzPack 5.0 for backward compatibility:


${SYSTEM_variable_name}

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

Examples

If "-Dfeature.Enabled=true" is on the command line that launched the installer, the command line argument can be used as follows:

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>