Understanding Properties

IzPack properties are key-value pairs that can be used for substitution during the compilation phase, only. The scope makes the difference to variables, which are evaluated and can be seen also during the installation phase. IzPack properties will not be visible during the execution of the compiled installer. Properties have been thought to be a clearly visible compile-time "variable" in IzPack XML descriptors with a different notation.

Properties cannot be re-defined and once a property is created, it will not be overwritten.

Properties can be used to set up an installer build in the source code.

Using Properties

Properties can be explicitely set in the installer descriptor.

IzPack sets a couple of built-in properties automatically depending on how the compilation is launched.

WIthin a Maven build environment, there are automatically visible Maven user properties defined in the POM.

Setting Properties

Explicit Properties

Explicit properties can be defined by the user using the <properties> element as a child of the <installation> element.

The <properties> element accepts the following attributes:

Attribute	Description	Value Range	Required
*name*	The name of the property to set.	a string	yes
*value*	The static value of the property.	a string	yes unless file or environment has been specified
*file*	Alternatively, the properties file to load all values from	a valid path	yes, if value or environment has not been specified)
*prefix*	The prefix to be added to the properties names read from a file. Only valid if the file attribute is specified. A "." is appended to the prefix value if the prefix doesn't already end with ".". For example, if you set the attribute `<property prefix="install"/>` and the property file specified in `<property file="company.properties"/>` includes an property named COMPANY_NAME, then the property created will be named install.COMPANY_NAME rather than COMPANY_NAME.	a string	no
*environment*	Creates property values from all existing environment variables and uses the value of the environment attribute as a prefix. A "`.`" is appended to the end of the prefix specified by the environment attribute. For example, if you specify the attribute `<property environment="env"/>` and the system has an environment variable named PATH, a property named env.PATH will be created.	a string	yes if value or file has not been specified)

Example:

This sets the values of the properties "info.appName", "info.appsubpath", info.url", "info.company.name" and "info.company.email".

install.xml

<properties>
  <property name="info.appName" value="My Application"/>
  <property name="info.appsubpath" value="my-company/my-app"/>
  <property name="info.url" value="http://www.my-company.com"/>
  <property name="info.company.name" value="My Company Name"/>
  <property name="info.company.email" value="info@my-company.com"/>
</properties>

Example:

This creates properties based on the values of the properties specified.in the "install.properties" file. The names of the properties are the names specified in the file with "install." added to the beginning of the name.

install.xml

<properties>
  <property file="install.properties"/>
  <property prefix="install"/>
</properties>

Example:

This creates properties based on the values of all of the system variables available to the installer. The names of the properties are the names of the system variables with "env." added to the beginning of the name.

install.xml

<properties>
    <property environment="env"/>
</properties>

Maven Properties

When launching the compilation using the IzPack Maven plugin, all Maven project properties are available as properties in IzPack.

Maven properties have priority over explicit properties, since they are set during instantiation of the IzPack compiler, before the IzPack compilation starts so they can not be replaced by later specifications from the <properties> element.

This behavior of defining implicit properties is similar to setting implicit Ant project properties in IzPack 4.X.

Example:

POM

<properties>
  <!-- Installer variables -->
  <info.appName>My Application</info.appName>
  <info.appsubpath>my-company/my-app</info.appsubpath>
  <info.url>www.my-company.com</info.url>
  <info.company.name>My Company Name</info.company.name>
  <info.company.email>info@my-company.com</info.company.email>
</properties>

There are two ways to define a property in Maven:

Defining <properties> inside pom.xml like in the example above.
Setting a user property on the commandline with "-Dproperty=value".

They are handled different in the Maven plugin:

In IzPack 5.0 only the definitions in pom.xml are recognized by the installer.
Starting with version 5.0.9 these static properties can be overwritten with the value given as user property on the command line:
IZPACK-1400 - Getting issue details... STATUS
Properties defined as user property only without a definition in pom.xml are not available to the installer. This is discussed in JIRA, because it could break existing installers:
IZPACK-1402 - Getting issue details... STATUS

The attributes file, prefix and environment have been broken in 5.0 at the beginning, they are fixed in IzPack 5.1.0.

Reading/Substituting Properties

IzPack properties can be referenced in the installation specification by a leading 'at' placeholder followed by the property name (for example @my.prop.name).

Optionally, when embedding property substitution into text which continues without a whitespace character, the key can be embedded in braces opening after the 'at' (for example @{my.prop.name}).

IzPack properties are substituted when their definition is found in the installation descriptor XML inside of

element attribute values,
embedded (enclosed) content.

Example:

install.xml

<info>
  <appname>@{info.appName}</appname>
  <appsubpath>@{info.appsubpath}</appsubpath>
  <appversion>@{project.version}</appversion>
  <authors>
    <author name="@{info.company.name}" email="@{info.company.email}"/>
  </authors>
  <url>@{info.url}</url>
  ...
</info>