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.
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.
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 | a string | no |
environment | Creates property values from all existing environment variables and uses the value of the environment attribute as a prefix. A " For example, if you specify the attribute | 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".
<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.
<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.
<properties> <property environment="env"/> </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:
<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:
They are handled different in the Maven plugin:
|
The attributes file, prefix and environment have been broken in 5.0 at the beginning, they are fixed in IzPack 5.1.0. |
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
Example:
<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> |