Go back to the documentation index
In order to write your XML installation files, you just need a plain text editor. Of course it's always easier to work with color coded text, so you might rather want to work with a text editor having such a feature. Here is a list of free editors that work well :
If you are a developer and tend to write your own patches, extension or features to IzPack sources, or, if you wish to debug your compilation, installation and uninstallation, we recommend these IDE:
For the first one, JetBrains has granted us an Open Source License. All project members can ask the Licence Key to one of the project manager.
The other ones are well know open source projects (Just like us :-)). We provide a tutorial on how to develop/debug IzPack using Eclipse in the chapter ''Getting Started > How to develop and debug IpPack using Eclipse''
Though you might not know much about XML, you have certainly heard about it. If you know XML you can skip this subsection as we will briefly present how to use XML.
XML is a markup language, really close to HTML. If you've ever worked with HTML the transition will be fast. However there are a few little things to know. The markups used in XML have the following form : <markup>. Each markup has to be closed somewhere with its ending tag : </markup>. Each tag can contain text and other markups. If a markup does not contain anything, it is just reported once : <markup/>. A markup can contain attributes like : <markup attr1="123" attr2="hello !"/>. Here is a sample of a valid XML structure :
<chapter title="Chapter 1">
<section name="Introduction">
<paragraph>
This is the text of the paragraph number 1. It is available
for the very low
price of <price currency="dollar">1 000 000</price>.
</paragraph>
</section>
<section name="xxx">
xxx
</section>
</chapter>
You should be aware of the following common mistakes :
Also, an XML file must start with the following header : <?xml version="1.0" encoding="iso-8859-1 standalone="yes" ?>. The only thing you should modify is the encoding (put here the one your text editor saves your files to). The `` standalone`` attribute is not very important for us.
This (brief !) introduction to XML was just meant to enable you to write your installation specification. For a better introduction there are plenty of books and articles/tutorials dealing with XML on the Internet, in book stores, in magazines and so on.
During the installation process IzPack can substitute variables in various places with real values. Obvious targets for variable substitution are resource files and launch scripts, however you will notice many more places where it is more powerful to use variables rather then hard coded values. Wherever variables can be used it will be explained in the documentation.
There are three types of variables:
You define your own variables in the installation XML file with the <variable> tag. How to do this is explained in detail later in this chapter.
Please note that when using variables they must always appear with a '$' sign as the first character, even though they are not defined this way.
The following variables are built-in :
Environment variables can be accessed via the syntax ${ENV[variable]}. The curly braces are mandatory. Note that variable names are case-sensitive and usually in UPPER CASE.
Example: To get the value of the OS environment variable "CATALINA_HOME", use ${ENV[CATALINA_HOME]}.
Dynamic variables can be defined in the installation XML with the <variable> tag inside the <dynamicvariables> element. The value of dynamic variables will be evaluated every time a panel is switched, i.e. between the panels. Dynamic variables can have a condition which will be evaluated first. If it's true, the value would be assigned, otherwise nothing happens to the variable.
Example: To change a certain directory based on user input, use the following <variable name="test" value="/test/${USER_INPUT}" condition="hasuserinput" /> The condition has userinput has to be specified in the condition section of installation XML.
Parse types apply only when replacing variables in text files. At places where it might be necessary to specify a parse type, the documentation will mention this. Depending on the parse type, IzPack will handle special cases -such as escaping control characters- correctly. The following parse types are available:
Unless using braces to surround variable's name (${variable} or %{variable}}, the variable name can contain following characters: letters, digits, dots, dashes (-), underbars (_). Example: $this.is-my_variable
If you want to have two variables separated by character that is allowed to appear in variable name, for example: $major-version.$minor-version, then you must use braces, and the above example should look like: ${major-version}.${minor-version}.
When writing your installer XML files, it's a good idea to have a look at the iZPACK installation DTD.
The root element of an installation is <installation>. It takes one required attribute : version. The attribute defines the version of the XML file layout and is used by the compiler to identify if it is compatible with the XML file. This should be set to 1.0 for the moment.
This element is used to specify some general information for the installer. It contains the following elements :
Here is an example of a typical <info> section :
<info>
<appname>Super extractor</appname>
<appversion>2.1 beta 6</appversion>
<appsubpath>myCompany/SExtractor</appsubpath>
<url>http://www.superextractor.com/</url>
<authors>
<author name="John John Doo" email="jjd@jjd-mail.com"/>
<author name="El Goyo" email="goyoman@mymail.org"/>
</authors>
<javaversion>1.2</javaversion>
</info>
This element allows to specify packaging options. If not specified, the default will be to create an all in one installer. This element will usually be used to create an installer which spans over multiple volumes, e.g. the output will be two CDs. The packaging-element contains the following elements:
<packager> : specifies options used by the packager. The packager tag has the class attribute, which specifys the class to use for packaging. Currently two implementations are available (com.izforge.izpack.compiler.Packager, com.izforge.izpack.compiler.MultiVolumePackager). The packager-element can contain the <options> element which can have different attributes for the different implementations of packagers. For the MultiVolumePackager, it can have the following attributes:
(com.izforge.izpack.compiler.UnPacker, com.izforge.izpack.compiler.MultiVolumeUnPacker).
Here's an example how to specify an installer which will create multiple volumes. In this example the volumes shall be CDs with 650 megabytes. There will be an additional free space of 150 megabytes on the first volume. This will result in the creation of an installer.jar and multiple installer.pak* files. The installer.jar plus installer.pak plus the additional resources have to be copied on the first volume, each installer.pak.<number> on several volumes.
<packaging>
<packager class="com.izforge.izpack.compiler.MultiVolumePackager">
<!-- 650 MB volumes, 150 MB space on the first volume -->
<options volumesize="681574400" firstvolumefreespace="157286400"/>
</packager>
<unpacker class="com.izforge.izpack.installer.MultiVolumeUnpacker" />
</packaging>
This element allows you to define variables for the variables substitution system. Some variables are built-in, such as $INSTALL_PATH (which is the installation path chosen by the user). When you define a set of variables, you just have to place as many <variable> tags in the file as needed. If you define a variable named VERSION you need to type $VERSION in the files to parse. The variable substitutor will then replace it with the correct value. One <variable> tag take the following attributes :
Here's a sample <variables> section :
<variables> <variable name="app-version" value="1.4"/> <variable name="released-on" value="08/03/2002"/> </variables>
Here's a precise sample on how to use desktopshortcutcheckboxenabled and InstallerFrame.logfilePath variables:
<variables>
<variable name="InstallerFrame.logfilePath" value="$INSTALL_PATH
/My-install.log"/>
<!-- This means that the log name will be My-install and that
it will be stored at the root of the installation. -->
<!-- Any path is fine. If value is set to "Default" then
"$INSTALL_PATH/uninstall/install.log" is used. -->
<!-- And if variable isn't defined then no log is written. -->
<variable name="desktopshortcutcheckboxenabled" value="true"/>
<!-- This automatically checks the "Create Desktop Shortcuts"
button. Default value is "False". -->
</variables>
This element allows you to define dynamic variables for the variables substitution system. In contrast to the static <variables, dynamic variables will be evaluated every time, a panel switch is done.
When you define a set of variables, you just have to place as many <variable> tags in the file as needed. Normally you would use the condition attribute to specify, when a certain value will be set.
One <variable> tag take the following attributes :
Here's a sample <dynamicvariables> section :
<dynamicvariables> <variable name="app-version" value="1.4" condition="mycondition1" /> <variable name="app-version" value="1.4b" condition="!mycondition1" /> <variable name="released-on" value="08/03/2002" /> </dynamicvariables>
This element allows you to define conditions which can be used to dynamically change the installer, e.g. the panels shown, the variables set, files parsed, files executed and much more. When you define a condition it will get a type and an id. The id has to be unique. Conditions can be referenced based on this id (e.g. with the RefCondition).
There are several built-in types of conditions. At the time of writing this, Izpack has the following built-in types:
There are also boolean types to combine more than one condition:
When you define a set of conditions, you just have to write as many <condition> tags as you like. A condition can take the following attributes:
name without condition appended (variable,packselection,java, ...). Custom condition types should be referenced by the full qualified class name, e.g. de.dr.rules.MyCoolCondition.
id: the id of the condition. This will be used to refer to this conditions in other elements
The condition element can have several child elements depending on the type of this conditions. E.g. the VariableCondition has a name and value child element to specify, which variable should have a certain value to fullfil this condition.
This is an example which defines four conditions, two VariableConditions, a JavaCondition and a AndCondition which will refer to two of the first conditions.
<conditions>
<condition type="variable" id="standardinstallation">
<name>setup.type</name>
<value>standard</name>
</condition>
<condition type="variable" id="expertinstallation">
<name>setup.type</name>
<value>expert</name>
</condition>
<condition type="java" id="installonwindows">
<java>
<class>com.izforge.izpack.util.OsVersion</class>
<field>IS_WINDOWS</field>
</java>
<returnvalue type="boolean">true</returnvalue>
</condition>
<condition type="and" id="standardinstallation.onwindows">
<condition type="ref" refid="standardinstallation"/>
<condition type="ref" refid="installonwindows" />
</condition>
</condition>
Note, from IzPack 3.11 on normally, you don't have to define the compound conditions because you can use a simple expression language. The language has the following operators:
Neverthless if you define really complex conditions it's much easier to define them using the xml structure.
More types of conditions can be defined by inheriting com.izforge.izpack.Condition class.
This element allows you to set the behavior of your installer GUI. This information will not have any effect on the command-line installers that will be available in future versions of IzPack. The arguments to specify are :
Here's a sample :
<guiprefs resizable="no" width="800" height="600"/>
Starting from IzPack 3.6, the look and feel can be specified in this section on a per-OS basis. For instance you can use the native look and feels on Win32 and OS X but use a third-party one on Unix-like platforms. To do that, you have to add some children to the guiprefs tag:
The available look and feels are:
If you don't specify a look and feel for a particular operating system, then the default native one will be used: Windows on Windows, Aqua on Mac OS X and Metal on the Unix-like variants.
The Liquid Look and Feel supports the following parameters:
The JGoodies Looks look and feel can be specified by using the variant parameters. The values can be one of:
Here is a small sample:
<guiprefs height="600" resizable="yes" width="800">
<laf name="metouia">
<os family="unix" />
</laf>
<laf name="looks">
<os family="windows" />
<param name="variant" value="extwin" />
</laf>
</guiprefs>
The Substance look and feel toned-down themes can be specified using the variant parameter, with the value being one of: business, business- blue, business-black, creme, sahara, moderate, officesilver. We have reduced the choice to the toned-down themes since they are the only ones to actually look decent (the other families colors are way too saturated). Please consult https://substance.dev.java.net/docs/skins/toneddown.html for a gallery of the different toned-down themes.
Starting from IzPack 3.7, some characteristics can be customized with the <modifier> tag. There is a separate description in the Advanced Features chapter paragraph Modifying the GUI.
This element is used to specify the language packs (langpacks) that you want to use for your installer. You must set one <langpack> markup per language. This markup takes the `` iso3`` parameter which specifies the iso3 language code.
Here's a sample :
<locale> <langpack iso3="eng"/> <langpack iso3="fra"/> <langpack iso3="spa"/> </locale>
The supported ISO3 codes are :
| ISO3 code | Language |
|---|---|
| cat | Catalunyan |
| chn | Chinese |
| cze | Czech |
| dan | Danish |
| glg | Galician |
| deu | German |
| eng | English |
| fin | Finnish |
| fra | French |
| hun | Hungarian |
| ita | Italian |
| jpn | Japanese |
| mys | Malaysian |
| ned | Nederlands |
| nor | Norwegian |
| pol | Polnish |
| por | Portuguese (Brazilian) |
| rom | Romanian |
| rus | Russian |
| scg | Serbian |
| spa | Spanish |
| svk | Slovakian |
| swe | Swedish |
| ukr | Ukrainian |
Several panels, such as the license panel and the shortcut panel, require additional data to perform their task. This data is supplied in the form of resources. This section describes how to specify them. Take a look at each panel description to see if it might need any resources. Currently, no checks are made to ensure resources needed by any panel have been included. The `` <resources>`` element is not required, and no <res> elements are required within. The <resources> element is the only element besides the <packs> element that is taken into consideration in referenced pack-files (see `<packs> element`_ for more info)
You have to set one <res> markup for each resource. Here are the attributes to specify :
Here's a sample :
<resources> <res id="InfoPanel.info" src="doc/readme.txt" parse="yes"/> <res id="LicencePanel.licence" src="legal/License.txt"/> </resources>
Here you tell the compiler which panels you want to use. They will appear in the installer in the order in which they are listed in your XML installation file. Take a look at the different panels in order to find the ones you need. The <panel> markup takes the following attributes:
Here's a sample :
<panels> <panel classname="HelloPanel"/> <panel classname="LicencePanel"/> <panel classname="TargetPanel"/> <panel classname="InstallPanel"/> <panel classname="UserInputPanel" id="myuserinput" condition="pack2selected" /> <panel classname="FinishPanel"/> </panels>
This is a crucial section as it is used to specify the files that need to be installed. The <packs> section consists of several <pack> and <refpack> tags.
The <pack> takes the following attributes :
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 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.
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.
The following sections describe the tags available for a <pack> section.
The contents of the <description> tag describe the pack contents. This description is displayed if the user highlights the pack during installation.
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:
It is possible to restrict a panel to a certain list of operating systems. This tag takes the following attributes:
This feature can update an already installed package, therefore removing superfluous files after installation. Here's how this feature 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.
The <file> tag specifies a file (a directory is a file too) to include into the pack. It takes the following attributes:
This tag can also be specified in order to pass additional data related to a file tag for customizing.
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``.
A <additionaldata> tag can also be specified for customizing.
The <fileset> tag allows files to be specified using the powerful Jakarta Ant set syntax. It takes the following parameters:
You specify the files with <include> and <exclude> tags that take the name parameter to specify the Ant-like pattern :
Here are some examples of Ant patterns :
There area set of definitions that are excluded by default file-sets, just as in Ant. IzPack defaults to the Ant list of default excludes. There is currently no equivalent to the <defaultexcludes> task. Default excludes are:
**/*\~{}
**/\#*\#
**/.\#*
**/%*%
**/.\_*
**/CVS
**/CVS/**
**/.cvsignore
**/SCCS
**/SCCS/**
**/vssver.scc
**/.svn
**/.svn/**
**/.DS\_Store
A <additionaldata> tag can also be specified for customizing.
Files specified by <parsable> are parsed after installation and may have variables substituted.
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 :
A <args> tag can also be specified in order to pass arguments to the executable:
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:
Here's an example installation file :
<packs>
<!-- The core files -->
<pack name="Core" required="yes">
<description>The IzPack core files.</description>
<file targetdir="$INSTALL_PATH" src="bin"/>
<file targetdir="$INSTALL_PATH" src="lib"/>
<file targetdir="$INSTALL_PATH" src="legal"/>
<file targetdir="$INSTALL_PATH" src="Readme.txt"/>
<file targetdir="$INSTALL_PATH" src="Versions.txt"/>
<file targetdir="$INSTALL_PATH" src="Thanks.txt"/>
<parsable targetfile="$INSTALL_PATH/bin/izpack-fe"/>
<parsable targetfile="$INSTALL_PATH/bin/izpack-
fe.bat"/>
<parsable targetfile="$INSTALL_PATH/bin/compile"/>
<parsable
targetfile="$INSTALL_PATH/bin/compile.bat"/>
<executable targetfile="$INSTALL_PATH/bin/compile"
stage="never"/>
<executable targetfile="$INSTALL_PATH/bin/izpack-fe"
stage="never"/>
</pack>
<!-- The documentation (1 directory) -->
<pack name="Documentation" required="no">
<description>The IzPack documentation (HTML and
PDF).</description>
<file targetdir="$INSTALL_PATH" src="doc"/>
</pack>
</packs>
Use this if you want to use a feature that requires a native library. The native libraries are placed under bin/native/... There are 2 kinds of native libraries : the iZPACK libraries and the third-party ones. The IzPack libraries are located at bin/native/izpack, you can place your own libraries at `` bin/native/3rdparty``. It is possible to place a native library also into the uninstaller. It is useable from CustomActions. If one or more are referenced for it, the needed support classes are automatically placed into the uninstaller. To place it only on operating systems for which they are build, it is possible to define an OS restriction. This restriction will only be performed for the uninstaller. The markup takes the following attributes :
The <os> tag can be used to restrict the inclusion into the uninstaller to a specific operating system family, architecture or version. The inclusion into the installer will be always done.
Here's a sample :
<native type="izpack" name="ShellLink.dll"/>
If you adapt iZPACK for your own needs, you might need to merge the content of another jar file into the jar installer. For instance, this could be a library that you need to merge. The <jar> markup allows you to merge the raw content of another jar file into the installer and the uninstaller. It is necessary that the paths in the jars are unique because only the contained files of the jar are added to the installer jar, not the jar file self. The attributes are:
A sample :
<jar src="../nicelibrary.jar"/>
The xinclude element is used to include xml or text documents in your configuration files.
The xinclude element can be used anywhere in pretty much any of the xml files used by IzPack. It is based on the XInclude recomendation produced by the W3C (http://www.w3.org/TR/xinclude/) and should be able to be used as decribed in that document. Note that as namespaces are not supported in IzPack the elements specified by the w3c have been prefixed with 'x' so 'xsi:include' becomes 'xinclude' and 'xsi:fallback' becomes 'xfallback'.
The xinclude element has the following attributes:
The xfallback element is used to provide a fallback if the xinclude element fails. It can be empty or can contain a CDATA section containing valid xml (no document fragments allowed). If it is empty then a failure to include the specified document is supressed. If it contains a CDATA section then a failure to include the specified document causes the xml specified in the CDATA is parsed (evaluating nested xinclude elements) and inserted into the document in its place.
For example the following use of xinclude
<?xml version="1.0" encoding="iso-8859-1" standalone="yes" ?>
<installation version="1.0" xmlns:xi="http://www.izforge.com/izpack/include">
<xinclude href="does-not-exist.xml">
<xfallback>
<![CDATA[<bbb>hello</bbb>]]>
</xfallback>
</xinclude>
</installation>
will result in
<installation version="1.0" xmlns:xi="http://www.izforge.com/izpack/include">
<bbb>hello</bbb>]]>
</installation>
if the file 'does-not-exist.xml' does indeed not exist.
The xfragment element allows document fragments (xml documents without a single top level element) to be included. Simply use the xfragment as the top level element in the included document. It will be removed when the document is included.
e.g. If I want to use xinclude to include a file containing the following fragments:
<ffff>
<gggg>hello</gggg>
</ffff>
<hhhh>
<iiii>there</iiii>
</hhhh>
I could use the xfragment element to enable it
<?xml version="1.0" encoding="iso-8859-1" standalone="yes" ?>
<xfragment>
<ffff>
<gggg>hello</gggg>
</ffff>
<hhhh>
<iiii>there</iiii>
</hhhh>
</xfragment>
Go back to the documentation index