Skip to end of metadata
  • Created by Former user, last modified by Former user on Jul 23, 2010
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 10 Next »

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

  • from where to get files into the compiled setup
    and the installer
  • where to put the files
  • which files to directly execute (or just receive the executable permission)
  • which files to parse and replace variables in
  • whether to overwrite existing target files with the same path
  • whether to rename existing target files with the same path before they are overwritten

Each pack can be selected or deselected by default or by the user except is marked hidden or mandatory.

Using packs

There are the following possible root elements to define packs:

  • pack
  • refpack
  • refpackset

which might embed a couple of possible nested elements describing the pack.

<pack>

Attributes

Attribute

Usage

name

defines the pack name

required

takes yes or no and specifies whether the pack must be installed (yes) or is optional (no)

os

optional. Lets you make the pack targeted to a specific operating system, for instance unix, mac and so on

preselected

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

loose

can be used so that the files are not located in the installer Jar. The possible values are true or false, the default being false. The author of this feature needed to put his application on a CD so that the users could run it directly from this media. However, he also wanted to offer them the possibility to install the software localy. Enabling this feature will make IzPack take the files on disk instead of from the installer. Please make sure that your relative files 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

this attribute is used to reference a unique resource that represents 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 id attribute of the <res> element.

condition

an id of a condition which has to be fullfilled to install 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:

packname

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:

family

unix, windows or mac

name

the exact OS name (ie Windows, Linux, ...)

version

the exact OS version (see the JVM os.version property)

arch

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

Globmapper to rename a conflicting file to. This works similar like the <globmapper> in File Name Mappers, whereby the mapper's from attribute is set to "" and the to attribute exactly to the value given here. Example ".bak" will rename the target file by appending the suffix .bak before overwriting it. The override attribute must be set "true" to activate this feature.

Since IzPack 5.0

no

String - valid globmapper target expression

blockable

For Windows only, ignored on non-Windows systems:
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")

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: 

*/~{}
*/##
*/.#
*/%%
*/._
**/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

Globmapper to rename a conflicting file to. This works similar like the <globmapper> in File Name Mappers, whereby the mapper's from attribute is set to "" and the to attribute exactly to the value given here. Example ".bak" will rename the target file by appending the suffix .bak before overwriting it. The override attribute must be set "true" to activate this feature.

Since IzPack 5.0

no

String - valid globmapper target expression

blockable

For Windows only, ignored on non-Windows systems:
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")

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

the base directory for the fileset (relative path)

yes

 

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: 

*/~{}
*/##
*/.#
*/%%
*/._
**/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

Globmapper to rename a conflicting file to. This works similar like the <globmapper> in File Name Mappers, whereby the mapper's from attribute is set to "" and the to attribute exactly to the value given here. Example ".bak" will rename the target file by appending the suffix .bak before overwriting it. The override attribute must be set "true" to activate this feature.

Since IzPack 5.0

no

String - valid globmapper target expression

blockable

For Windows only, ignored on non-Windows systems:
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")

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 <singlefile> 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.
  • <exclude>
    Explicitely exclude files by pattern, similar like Ant fileset patterns. For more information see the FileSet core type.
<parsable> - parse a file after installation

Files specified by <parsable> are parsed after installation and may have variables substituted.

targetfile

the file to parse, could be something like $INSTALL_PATH/bin/launch-script.sh A slash will be changed to the system dependant path separator (e.g. to a backslash on Windows) only if no backslash masks the slash.

type

specifies the type (same as for the resources) - the default is plain

encoding

specifies the file encoding

os

specifies the operating system, works like for <file>

condition

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:

targetfile

the file to run, could be something like $INSTALL_PATH/bin/launch-script.sh Slashes are handled special (see attribute targetfile of tag <parsable>).

class

If the executable is a jar file, this is the class to run for a Java program

type

bin or jar (the default is bin)

stage

specifies when to launch :

  • never (default) will never launch it (useful to set the +x flag on Unix)
  • postinstall is just after the installation is done
  • uninstall will launch the executable when the application is uninstalled. The executable is executed before any files are deleted.

failure

specifies what to do when an error occurs:

  • ask (default) will ask the user what to do
  • abort will abort the installation process
  • warn will just tell the user that something is wrong
  • ignore don't tell the user, just continue

os

specifies the operating system, works like for <file>

keep

takes true or false (default for backward compatibility). specifies whether the file will be kept after execution.

condition

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

family

unix, windows, mac to specify the operating system family

name

the operating system name

version

the operating system version

arch

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>

key to identify the data

<value>

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

file

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

dir

Relative base directory during compile-time for the refpackset

includes

Pattern of files in <refpack> format that have to be included

Example:

<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

Globmapper to rename a conflicting file to. This works similar like the <globmapper> in File Name Mappers, whereby the mapper's from attribute is set to "" and the to attribute exactly to the value given here. Example ".bak" will rename the target file by appending the suffix .bak before overwriting it. The override attribute must be set "true" to activate this feature.

Since IzPack 5.0

no

String - valid globmapper target expression

blockable

For Windows only, ignored on non-Windows systems:
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")

  • No labels