The
...
<packs> Element
Packs in IzPack are bundles of files grouped under a certain package ID. Each file or set of files in a pack can be given certain attributes, which tell the compiler
...
Each pack can be selected or deselected by default or by the user except is marked hidden or mandatory.
...
Packs Reference
There are the following possible root elements to define packs:
...
which might embed a couple of possible nested elements describing the pack.
<pack>
Attributes
Attribute | Usage |
---|
name
id |
unique id for the pack to be used for internationalization via packsLang.xml file | |
| the user-friendly name that will be displayed during the installation |
|
yes
or no
and specifies whether the pack must be installed ( | |
| optional. Lets you make the pack targeted to a specific operating system, |
see OS Restrictions. | |
| optional. Lets you choose whether the pack is selected for installation by default or not. Possible values are yes and no. A pack which is not preselected needs to be explicitly selected by the user during installation to get installed |
|
optional. Indicates that the files are not located in the installer Jar. The possible values are true or false, the default being false. |
For example, your application could be distributed on a CD so that the users could run it directly from |
the CD. In order to install the software |
locally without duplicating the files in a jar, you can set |
the CD rather than from the installer jar. Please make sure that your relative |
file paths are correct! |
id
this attribute is used to give a unique id to the pack to be used for internationalization via packsLang.xml file
packImgId
When using | |
| optional. reference to a resource that defines the pack's image for the ImgPacksPanel. The resource should be defined in the <resources> element of the installation XML using the same value for the |
|
optional. ID of a condition which has to be |
fulfilled to |
enable this package |
hidden
takes true or false and specifies whether the pack shall be shown in the packs panel. The size of a hidden pack will be used to calculate the required space, but the pack itself won't be shown. A hidden pack can be preselected or selected conditionally. For the latter, you have to specify a condition
. The default for this attribute is false.
Nested Elements
<description>
- pack description
The contents of the <description>
tag describe the pack contents. This description is displayed if the user highlights the pack during installation.
<depends>
- pack dependencies
This can be used to make this pack selectable only to be installed only if some other is selected to be installed. The pack can depend on more than one by specifying more than one <depends>
elements. Circular depedencies are not supported and the compiler reports an error if one occurs.
This tag takes the following attribute:
| The name of the pack that this one depends on |
<os>
- OS restrictions
It is possible to restrict a pack to a certain list of operating systems. This tag takes the following attributes:
| unix, windows or mac |
| the exact OS name (ie Windows, Linux, ...) |
| the exact OS version (see the JVM os.version property) |
| the machine architecture (see the JVM os.arch property) |
<updatecheck>
This feature can update an already installed package, therefore removing superfluous files after installation. Here's how this feature's author (Tino Schwarze) described it on the IzPack development mailing-list:
Each pack can now specify an <updatecheck>
tag. It supports a subset of ant fileset syntax, e.g.:
...
<updatecheck>
<include name="lib/**" />
<exclude name="config/local/** />
</updatecheck>
If the paths are relative, they will be matched relative to $INSTALL_PATH
. Update checks are only enabled if at least one <include>
is specified. See {{com.izforge.izpack.installer.Unpacker
for details.
<file>
- add files and/or directories
The <file>
tag specifies a single file (a directory is a file, too!) to include into the pack.
...
Attributes
...
Attribute
...
Description
...
Required
...
Values
(Default)
...
src
...
the file location (relative path) - if this is a directory its content will be added recursively. It may contain previously defined static variables (see <variables>
).
...
yes
...
...
targetdir
...
the destination directory, could be something like $INSTALL_PATH/subdirX
...
yes
...
...
os
...
Limit installation of this particular file only to the given target OS type.
...
no
...
"unix" | "windows" | "mac"
...
override
...
Whether to overwrite existing files.
Use asktrue
or askfalse
if the user should be interactively asked what to do and supply default value for non-interactive use. Another possible value is update. It means that the new file is only installed if it's modification time is newer than the modification time of the already existing file (note that this is not a reliable mechanism for updates - you cannot detect whether a file was altered after installation this way.)
...
no
...
"true" | "false" | "asktrue" | "askfalse" | "update"
("update")
...
overrideRenameTo
...
no
...
String - valid globmapper target expression
...
blockable
...
no
...
"none"
| "auto"
| "force"
("none")
...
unpack
...
if true and the file is an archive then its content will be unpacked and added as individual files
...
no
...
"true" | "false"
("false")
...
condition
...
Limit installation of this particular file to the given condition, which must be true during the file installation.
...
no
...
String - a valid condition ID
...
casesensitive
...
Whether to treat the file name case-sensitive.
...
no
...
"true" | "false"
("true")
...
defaultExcludes
...
Whether to use global default excludes.
Implicit default exclude patterns are typically:
Code Block |
---|
*/~{}
*/##
*/.#
*/%%
*/._
**/CVS
*/CVS/*
**/.cvsignore
**/SCCS
*/SCCS/*
**/vssver.scc
**/.svn
*/.svn/*
**/.DS_Store |
Since IzPack 5.0
...
no
...
"true" | "false"
("true")
...
followSymLinks
...
Whether to follow symbolic links on target systems which support them.
...
no
...
"true" | "false"
("true")
...
Nested Elements
...
The following nested elements can be used in the <file> tag:
- <os>
Limit the installation of this file to conditions depending on the target OS, see below.
<singlefile>
- add a single file
Specifies a single file to include. The difference to <file>
is that this tag allows the file to be renamed, therefore it has a target attribute instead of targetdir
.
...
Attributes
...
Attribute
...
Description
...
Required
...
Values
(Default)
...
src
...
the file location (relative path). It may contain previously defined static variables (see <variables>
).
...
yes
...
...
target
...
the destination file name, could be something like $INSTALL_PATH/subdirX/fileY
...
yes
...
...
os
...
can optionally specify a target operating system (unix, windows, mac) - this means that the file will only be installed on its target operating system
...
no
...
"unix" | "windows" | "mac"
...
override
...
Whether to overwrite existing files.
Use asktrue
or askfalse
if the user should be interactively asked what to do and supply default value for non-interactive use. Another possible value is update. It means that the new file is only installed if it's modification time is newer than the modification time of the already existing file (note that this is not a reliable mechanism for updates - you cannot detect whether a file was altered after installation this way.)
...
no
...
"true" | "false" | "asktrue" | "askfalse" | "update"
("update")
...
overrideRenameTo
...
no
...
String - valid globmapper target expression
...
blockable
...
no
...
"none"
| "auto"
| "force"
("none")
...
condition
...
an id of a condition which has to be fullfilled to install this file
...
...
...
Nested Elements
...
The following nested elements can be used in the <singlefile> tag:
- <os>
Limit the installation of this file to conditions depending on the target OS, see below. <additionaldata>
Add customizing data, see below.
<fileset>
- add a fileset
The <fileset>
tag allows files to be specified similar like in Apache Ant.
...
Attributes
...
Attribute
...
Description
...
Required
...
Values
(Default)
...
dir
...
A base directory for the fileset (relative paths are treaten against the compiler base directory)
...
yes
...
...
file
...
A single file to copy, can be relative to the directory specified in dir. If not given, the whole directory dir is recursively included, filtered by the include and exclude expressions below.
...
no
...
...
targetdir
...
the destination path, works like for <file>
...
yes
...
...
casesensitive
...
optionally lets you specify if the names are case- sensitive or not - takes yes or no
...
no
...
...
defaultExcludes
...
Whether to use global default excludes.
Implicit default exclude patterns are typically:
Code Block |
---|
*/~{}
*/##
*/.#
*/%%
*/._
**/CVS
*/CVS/*
**/.cvsignore
**/SCCS
*/SCCS/*
**/vssver.scc
**/.svn
*/.svn/*
**/.DS_Store |
Since IzPack 5.0
...
no
...
"true" | "false"
("true")
...
os
...
specifies the operating system, works like for <file>
...
no
...
"unix" | "windows" | "mac"
...
override
...
Whether to overwrite existing files.
Use asktrue
or askfalse
if the user should be interactively asked what to do and supply default value for non-interactive use. Another possible value is update. It means that the new file is only installed if it's modification time is newer than the modification time of the already existing file (note that this is not a reliable mechanism for updates - you cannot detect whether a file was altered after installation this way.)
...
no
...
"true" | "false" | "asktrue" | "askfalse" | "update"
("update")
...
overrideRenameTo
...
no
...
String - valid globmapper target expression
...
blockable
...
no
...
"none"
| "auto"
| "force"
("none")
...
includes
...
comma- or space-separated list of patterns of files that must be included; all files are included when omitted. This is an alternative for multiple include tags.
...
...
...
excludes
...
comma- or space-separated list of patterns of files that must be excluded; no files (except default excludes) are excluded when omitted. This is an alternative for multiple exclude tags.
...
...
...
condition
...
an id of a condition which has to be fulfilled to install the files in this fileset
...
...
...
Nested Elements
...
The following nested elements can be used in the <fileset> tag:
- <os>
Limit the installation of this file to conditions depending on the target OS, see below. <additionaldata>
Add customizing data, see below.- <include>
Explicitely include files by pattern, similar like Ant fileset patterns. For more information see the FileSet core type.
Note: There is currently no file name mapper support in pack filesets. - <exclude>
Explicitely exclude files by pattern, similar like Ant fileset patterns. For more information see the FileSet core type.
Note: There is currently no file name mapper support in pack filesets.
<parsable>
- parse a file after installation
Files specified by <parsable>
are parsed after installation and may have variables substituted.
| the file to parse, could be something like |
| specifies the type (same as for the resources) - the default is plain |
| specifies the file encoding |
| specifies the operating system, works like for |
| an id of a condition which has to be fullfilled to parse this file |
<executable>
- mark file as executable and optionally execute it
The <executable>
tag is a very useful thing if you need to execute something during the installation process. It can also be used to set the executable flag on Unix-like systems. Here are the attributes:
| the file to run, could be something like |
| If the executable is a jar file, this is the class to run for a Java program |
| |
| specifies when to launch :
|
| specifies what to do when an error occurs:
|
| specifies the operating system, works like for |
| takes |
| an id of a condition which has to be fullfilled to execute this file |
Takes an <args>
tag to pass one or more arguments (one <arg>
tag per argument) to the executable.
<arg>
passes the argument specified in the value
attribute. Slashes are handled special (see attribute targetfile of tag <parsable>
.
...
<os>
- make a file OS-dependent
The <os>
tag can be used inside the <file>
, <fileset>
, <singlefile>
, <parsable>
, <executable>
tags to restrict it's effect to a specific operating system family, architecture or version using the following attributes:
Attribute | Description |
---|---|
| unix, windows, mac to specify the operating system family |
| the operating system name |
| the operating system version |
| the operating system architecture (for instance the Linux kernel can run on i386, sparc, and so on) |
Example
...
<packs>
(...)
<pack name="Core" required="yes">
(...)
<executable targetfile="$INSTALL_PATH/bin/compile" stage="never">
<os family="unix"/>
</executable>
(...)
</pack>
(...)
</packs>
<additionaldata>
- Adding Customizing Data
This tag can also be specified in order to pass additional data related to a file tag for customizing.
Attribute | Description |
---|---|
| key to identify the data |
| value which can be used by a custom action |
<refpack>
The <refpack>
takes only one attribute file
, which contains the relative path (from the installation compiler) to an externally defined packs-definition. This external packs definition is a regular IzPack installation XML. However the only elements that are used from that XML file are the <packs> and the <resources> elements.
This enables a model in which a single developer is responsible for maintaining the packs and resources (e.g. separate packsLang.xml_xyz files providing internationalization; see Internationalization of the PacksPanel) related to the development-package assigned to him. The main install XML references these xml-files to avoid synchronization efforts between the central installation XML and the developer-maintained installer XMLs.
Attributes
Attribute | Description |
---|---|
| Relative path during compile-time to an externally defined packs-definition |
<refpackset>
The <refpackset>
tag can be used in situations were there is no predefined set of <refpack>
files, but a given directory should be scanned for <refpack>
files to be included instead. This element takes the following parameters:
Attribute | Description |
---|---|
| Relative base directory during compile-time for the refpackset |
| Pattern of files in |
Example:
Code Block |
---|
<refpackset dir="" includes="**/refpack.xml" /> |
Internationalization of the PacksPanel
In order to provide internationalization for the PacksPanel, so that your users can be presented with a different name and description for each language you support, you have to create a file named packsLang.xml_xyz where xyz is the ISO3 code of the language in lowercase. Please be aware that case is significant. This file has to be inserted in the resources section of `` install.xml`` with the id and src attributes set at the name of the file. The format of these files is identical with the distribution langpack files located at `` $IZPACK_HOME/bin/langpacks/installer``. For the name of the panel you just use the pack id as the txt id. For the description you use the pack id suffixed with .description.
An example:
...
<resources>
<res id="packsLang.xml_eng" src="i18n/myPacksLang.xml_eng"/>
</resources>
The packsLang.xml_eng file:
...
<langpack>
<str id="myApplication" txt="Main Application"/>
<str id="myApplication.description" txt="A description of my main application"/>
[...]
</langpack>
| override
| Whether to overwrite existing files.
Use asktrue
or askfalse
if the user should be interactively asked what to do and supply default value for non-interactive use. Another possible value is update. It means that the new file is only installed if it's modification time is newer than the modification time of the already existing file (note that this is not a reliable mechanism for updates - you cannot detect whether a file was altered after installation this way.) | no
| "true" | "false" | "asktrue" | "askfalse" | "update"
("update")
|
overrideRenameTo
Since IzPack 5.0
no
String - valid globmapper target expression
blockable
Defines whether and how blocked target files on Windows should be recognized. This might result in pending file operations which require a system reboot. The reboot behavior at the end of an installation for pending file operations can be set using the nested rebootaction in the
info
element. See above for possible reboot options. Notes:
Using
blockable
does not necessarily force you to limit such files on Windows systems. For multi-platform installations there is a compiler warning shown that blockable
will be ignored on non-Windows systems. The native library
WinSetupAPI
must be explicitely included using this feature. Possible values:
"none"
: No recognition of blocked target files will be done at all, this is the default behavior of previous IzPack versions.
"auto"
: Automatic recognition of a blocked target file by the operating system, resulting in leaving a pending file operation to be finished after system reboot. Using
auto
this applies only for files that are really blocked, the other files are copied normally, which can result in mixed, old and new target files at the end of the installation, unless the system won't be really rebooted. "force"
: Forces target file to be always assumed a blocked, resulting in leaving a pending file operation to be finished after system reboot. Using
force
this applies for each file, regardless whether it is really blocked during installation. This makes sense if you don't want to mix files old and new files at the end of the installation to not disturbing a running process, but having the complete set of target files installed after system reboot. Since IzPack 5.0
no
"none"
| "auto"
| "force"
("none")
to be selected by the user. If the condition evaluates to false the package will be "greyed out" in the PacksPanel user view. The condition interacts with required in the following way:
Notice: if a package condition evaluates to false but it is marked | |||||||||
| optional. takes true or false and specifies whether the pack shall be shown in the packs panel. The size of a hidden pack will be used to calculate the required space, but the pack itself won't be shown. A hidden pack can be preselected or selected conditionally. For the latter, you have to specify a | ||||||||
size | optional. Specifies the size of the pack, in bytes. If not specified, the size will default to the sum of all file lengths in the pack. Since 5.0 | ||||||||
installGroups | optional. A comma separated list of groups, see InstallationGroupPanel for using them. | ||||||||
uninstall | optional. If "true ", the pack gets into the uninstaller's list of files to be uninstalled. This attribute has effect just in case of <uninstaller write="true"/> . Default: true |
Nested Elements
<singlefile>
- Adding/renaming a Single Pack File
See Adding or renaming a single file for more details.
<file>
- Adding a Set Of Files
See Adding or unpacking a single file to a target directory for more details.
<fileset>
- Adding a Set Of Files With Filtering
See Adding a set of files for more details.
<description>
- Adding a Description
The contents of the <description>
tag describe the pack contents. This description is displayed if the user highlights the pack during installation.
<depends>
- Defining Dependencies
This can be used to specify that this pack is to be evaluated for installation only if some other pack is selected to be installed. If the dependency is not going to be installed based on condition, then this pack can not be installed.The pack can depend on more than one by specifying more than one <depends>
elements. Circular dependencies will be detected and reported as an error if one is found.
This tag takes the following attribute:
| The name of the pack that this one depends on |
<onSelect>
- Select/Deselect a pack when this pack is selected
<onDeselect>
- Select/Deselect a pack when this pack is deselected
Gives you the ability to select or deselect other packs upon selection or deselection of this pack.
Allows for flexible pack management.
These tags take may take the following attributes:
| Required. |
condition | Optional. |
<parsable>
- mark text files for variable replacement
See Marking files for variable replacement for more details.
<executable>
- mark files for execution
See Marking files for execution for more details.
<updatecheck>
- Cleaning up on updates
See Cleaning up unwanted files after updates for details.
<refpack>
The <refpack>
takes only one attribute file
, which contains the relative path (from the installation compiler) to an externally defined packs-definition. This external packs definition is a regular IzPack installation XML. However the only elements that are used from that XML file are the <packs> and the <resources> elements.
This enables a model in which a single developer is responsible for maintaining the packs and resources (e.g. separate packsLang.xml_xyz files providing internationalization; see Internationalization of the PacksPanel) related to the development-package assigned to him. The main install XML references these xml-files to avoid synchronization efforts between the central installation XML and the developer-maintained installer XMLs.
Attributes
Attribute | Description |
---|---|
| Relative path at compile-time to an externally defined packs-definition |
<refpackset>
The <refpackset>
tag can be used in situations were there is no predefined set of <refpack>
files, but a given directory should be scanned for <refpack>
files to be included instead. This element takes the following parameters:
Attribute | Description |
---|---|
| Relative base directory at compile-time for the refpackset |
| Pattern of files in |
Example:
Code Block |
---|
<refpackset dir="" includes="**/refpack.xml" /> |
Internationalization of the PacksPanel
In order to provide internationalization for the PacksPanel, so that your users can be presented with a different name and description for each language you support, you have to create a file named packsLang.xml_xyz where xyz is the ISO3 code of the language in lowercase. Please be aware that case is significant. This file has to be inserted in the resources section of install.xml with the id and src attributes set to the name of the file. The format of these files is identical to the distribution langpack files located at $IZPACK_HOME/bin/langpacks/installer. For the name of the panel you just use the pack id as the part of text id. For the description you use the pack id suffixed with .description.
Example:
Code Block | ||||
---|---|---|---|---|
| ||||
<resources>
<res id="packsLang.xml_eng" src="i18n/myPacksLang.xml_eng"/>
</resources>
|
The packsLang.xml_eng file:
Code Block | ||||
---|---|---|---|---|
| ||||
<izpack:langpack version="5.0" xmlns:izpack="http://izpack.org/schema/langpack" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://izpack.org/schema/langpack http://izpack.org/schema/5.0/izpack-langpack-5.0.xsd">
<str id="myApplication" txt="Main Application"/>
<str id="myApplication.description" txt="A description of my main application"/>
</izpack:langpack> |
Example
Code Block | ||
---|---|---|
| ||
<pack name="Core files" required="yes" id="pack.core" condition="Install">
<description>Core files</description>
<fileset dir="@{staging.dir}" override="true">
<exclude name="*.zip" />
<exclude name="conf/*.properties" />
<exclude name="conf/*.xml" />
</fileset>
<fileset dir="@{staging.dir}/config_files" targetdir="${INSTALL_PATH}/conf" override="true" overrideRenameTo="*.configbak">
<include name="*.properties" />
<include name="*.xml" />
<exclude name="special.xml" />
</fileset>
<parsable encoding="UTF-8">
<fileset targetdir="${INSTALL_PATH}/conf">
<include name="wrapper.conf" />
</fileset>
</parsable>
<parsable>
<fileset>
<include name="**/*.bat" />
<include name="**/*.cmd" />
</fileset>
</parsable>
<parsable type="shell">
<fileset>
<include name="**/*.sh" />
</fileset>
</parsable>
<executable>
<fileset>
<include name="**/*.sh" />
</fileset>
</executable>
</pack> |
Note: Previously dir might have appeared as an attribute to <fileset> nested in <executable> or <parsable>. This is no longer supported.