We need you!

Icon

The IzPack documentation needs work, and you are invited to edit it!

Skip to end of metadata
Go to start of metadata

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.

Packs Reference

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, see OS Restrictions.

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.

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

installGroupsoptional. A comma separated list of groups, see InstallationGroupPanel for using them.
uninstalloptional. If set "true", the according 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 Pack SingleFile for more details.

<file> - Adding a Set Of Files

See Pack File for more details.

<fileset> - Adding a Set Of Files With Filtering

See Pack Fileset 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 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 dependencies 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

<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:

name

Required.
A comma separated list of pack names.
Pack names per-appended with an exclamation mark '!', will be deselected when this pack is selected.
Pack names that are not per-appended with an exclamation mark will be selected when this pack is selected.

condition

Optional.
When the specified condition is true the onSelect action will work as normal.
When the specified condition is false the onSelect action will have no effect.

<updatecheck> - Cleaning Up After Updates

This feature can update an already installed package, therefore removing superfluous files after an installation.

Each pack can now specify an <updatecheck> tag. Includes and excludes can be defined as filesets, but no file name mappers can be used. If no include or exclude pattern is given all files are deleted in $INSTALL_Path on the target system, which were not part of the setup.

Be careful with this facility to not delete 3rd-party files coming from other installations, for instance plugins to a base application.

Example::

$INSTALL_PATH is treated as the base path for include/exclude patterns with relative paths.

<parsable> - Mark Text Files For Parsing / Substituting Variables

Pack files marked <parsable> are parsed after copying them to the target system and substitute IzPack variables. Those variables can be defined in a syntax according to their file format, the default for plain files is ${<variable_name>} or $variable_name.

Files must be first added to the pack using <singlefile>, <file> or <fileset> before they can be marked parsable.

Attributes

Attribute

Description

Required

Values
(Default)

targetfile

Relative or absolute target path of a pack file added before, where variables should be resolved in place.

May contain IzPack variables resolved during installation.

Example: $INSTALL_PATH/conf/app.properties

(required, if no nested fileset is used) 

File path

type

Specifies the text file type:

  • plain - use for plain text files, where the variable definition syntax cannot conflict with the original file's syntax.
    Example of a variable definition in a text file in plain style: ${MY_VAR} or $MY_VAR.
  • javaprop - use for Java properties file.
  • java - use in Java source files.
  • xml - use for XML files.
  • shell - use for shell scripts.
    Example of a variable definition in a shell script%MY_VAR or %{MY_VAR}.
  • at
    Example: @MY_VAR.
  • ant - use in Ant files, where the plain style for IzPack conflicts with the syntax of Ant property substitutions.
    Example: {MY_VAR}

no

"plain" | "javaprop" (Properties) | "xml" | "java" | "shell" | "at" | "ant" (Ant buildfile)
("plain")

encoding

The file encoding

no

A valid Java encoding string
("ISO-8859-1" for type="javaprop",
"UTF-8" for type="xml", otherwise the Java default charset is assumed as encoding)

os

Limits this action on a particular OS, works like for <file>

no

 

condition

Limits this action on a particular condition with the specified ID which has to be fulfilled

no

 

Nested Elements
  • <os> - restrict parsing depending on the target operating system, see the OS Restriction element
  • One or more <fileset> tags can be used to mark multiple files parsable at once. The <fileset> which can be used here has not the full number of attributes and nested tags like a Pack FileSet.
    <parsable> marks files parsable, which have been added using the <singlefile><file> or <fileset> tags before nested against the <pack> definition. There is no access to the filesystem for a <parsable> fileset, but just to files that are packed into the installer before.
    There can be filesets defined here without any attribute, but just one or more includes (targetDir defaults to "${INSTALL_PATH}" in that case.
    See the example below. 

<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.

Files must be first added to the pack using <singlefile><file> or <fileset> before they can be marked executable.

Attributes

Attribute

Description

Required

Values
(Default)

targetfile

Relative or absolute target path of a pack file added before, which should reeceive executable permissions or which should be executed.

May contain IzPack variables resolved during installation.

Example: $INSTALL_PATH/bin/launch-script.sh

no
(required, if no nested fileset is used) 

File path

type

bin or jar (the default is bin)

no

"bin" | "jar"
("bin")

class

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

no

A valid Java class within the jar file

stage

Specifies at which stage when to launch the executable:

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

no

"never" | "postinstall" | "uninstall"
("never")

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

no

"ask" | "abort" | "warn" | "ignore"
("ask")

os

specifies the operating system, works like for <file>

no

 

keep

Whether the file will be kept after execution

no

"true" | "false"
("false")

condition

ID of a condition which has to be fulfilled to execute this file

no

A valid condition ID

Nested Elements
  • <os> - restrict parsing depending on the target operating system, see the OS Restriction element
  • <args>
    Pass one or more arguments with nested <arg> tags  (one <arg> tag per argument) to the executable
    Attributes: value - the argument value
    Example:
    <args><arg value="-version"/></args>
    Slashes are handled special (see attribute targetfile of tag <parsable>.
  • One or more <fileset> tags can be used to mark multiple files executable at once. The <fileset> which can be used here has not the full number of attributes and nested tags like a Pack FileSet.
    <executable> marks files executable, which have been added using the <singlefile><file> or <fileset> tags before nested against the <pack> definition. There is no access to the filesystem for a <parsable> fileset, but just to files that are packed into the installer before.
    There can be filesets defined here without any attribute, but just one or more includes (targetDir defaults to "${INSTALL_PATH}" in that case.
    See the example below. 

<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:

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.

Example:

The packsLang.xml_eng file:

Example

 

The dir attribute should no longer been parsed in <fileset> nested to <executable>, <parsable> at all.

  • No labels