Copy Page

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account. You can also Sign Up for a new account.

<h1>Writing Installation XML Files</h1>

<h3>Your editor</h3>

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

<ul>
	<li>Jext : <a href="http://www.jext.org/">http://www.jext.org/</a></li>
	<li>JEdit : <a href="http://www.jedit.org/">http://www.jedit.org/</a></li>
	<li>classics like Vim and (X)Emacs.</li>
</ul>

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

<ul>
	<li>IntelliJ IDEA : <a href="http://www.jetbrains.com/idea/">http://www.jetbrains.com/idea/</a></li>
	<li>Eclipse : <a href="http://www.eclipse.org/">http://www.eclipse.org/</a></li>
	<li>Netbeans : <a href="http://www.netbeans.org/">http://www.netbeans.org/</a></li>
</ul>

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

<p>The other ones are well know open source projects (Just like us <img class="emoticon emoticon-smile" data-emoticon-name="smile" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/smile.png" alt="(smile)" title="(smile)" /> ). We provide a tutorial on how to develop/debug IzPack using Eclipse in the chapter <em>Getting Started &gt; How to develop and debug IpPack using Eclipse</em></p>

<h3>Writing XML</h3>

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

<p>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 : <code>&lt;markup&gt;</code>. Each markup has to be closed somewhere with its ending tag : <code>&lt;/markup&gt;</code>. Each tag can contain text and other markups. If a markup does not contain anything, it is just reported once : <code>&lt;markup/&gt;</code>. A markup can contain attributes like : <code>&lt;markup attr1=&quot;123&quot; attr2=&quot;hello !&quot;/&gt;</code>. Here is a sample of a valid XML structure :</p>

<table class="wysiwyg-macro" data-macro-name="panel" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e3BhbmVsfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body">
<p> <strong>markups*are</strong> case sensitive : <code>&lt;markup&gt;</code> is different from <code>&lt;Markup&gt;</code>.<br />
<strong>you*must</strong> close the markups in the same order as you create them : <code>&lt;m1&gt;&lt;m2&gt;(...)&lt;/m2&gt;&lt;/m1&gt;</code> is right but <code>&lt;m1&gt;&lt;m2&gt;(...)&lt;/m1&gt;&lt;/m2&gt;</code> is not.</p></td></tr></table>

<p>Also, an XML file must start with the following header : <code>&lt;?xml version=&quot;1.0&quot; encoding=&quot;iso-8859-1 standalone=&quot;yes&quot; ?&gt;</code>. The only thing you should modify is the encoding (put here the one your text editor saves your files to). The <code>standalone</code> attribute is not very important for us.</p>

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

<h2>Variable Substitution</h2>

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

<p>There are three types of variables:</p>

<ul>
	<li>Built-In variables. These are implemented in IzPack and are all dynamic in nature. This means that the value of each variable depends on local conditions on the target system.</li>
	<li>Environment variables. These are provided by the operating system the installer is run on.</li>
	<li>Variables that you can define. You also define the value, which is fixed for a given installation file.</li>
</ul>

<p>You define your own variables in the installation XML file with the <code>&lt;variable&gt;</code> tag. How to do this is explained in detail later in this chapter.</p>

<p><strong>Please note</strong> that when using variables they must always appear with a '<code>$</code>' sign as the first character, even though they are not defined this way.</p>

<h2>The Built-In Variables</h2>

<p>The following variables are built-in :</p>

<ul>
	<li><code>$INSTALL_PATH</code> : the installation path on the target system, as chosen by the user</li>
	<li><code>$INSTALL_DRIVE</code> : the drive letter part of the installation path on the target system, set on Windows systems, only (for instance <code>C:</code>)</li>
	<li><code>$APPLICATIONS_DEFAULT_ROOT</code> : the default path for applications</li>
	<li><code>$JAVA_HOME</code> : the JavaTM virtual machine home path</li>
	<li><code>$CLASS_PATH</code> : the Class Path used mainly for Java Applications</li>
	<li><code>$USER_HOME</code> : the user's home directory path</li>
	<li><code>$USER_NAME</code> : the user name</li>
	<li><code>$APP_NAME</code> : the application name</li>
	<li><code>$APP_URL</code> : the application URL</li>
	<li><code>$APP_VER</code> : the application version</li>
	<li><code>$ISO3_LANG</code> : the ISO3 language code of the selected langpack.</li>
	<li><code>$IP_ADDRESS</code> : the IP Address of the local machine.</li>
	<li><code>$HOST_NAME</code> : the HostName of the local machine.</li>
	<li><code>$FILE_SEPARATOR</code> : the file separator on the installation system</li>
	<li><code>$DesktopShortcutCheckboxEnabled</code> : When set to true, it automatically checks the &quot;Create Desktop Shortcuts&quot; button. To see how to use it, go to `The Variables Element <code>&lt;variables&gt;</code> Be careful this variable is case sensitve !</li>
	<li><code>$InstallerFrame.logfilePath</code> : The path to the install log. This file contains the paths of all installed files. If set to &quot;default&quot; then the &quot;$INSTALL_PATH/Uninstaller/install.log&quot; path will be used. To see how to use it, go to `The Variables Element <code>&lt;variables&gt;</code>. If this variable is not set, no install.log will be created.</li>
</ul>

<h2>Environment Variables</h2>

<p>Environment variables can be accessed via the syntax <code>${ENV</code><code><a class="confluence-link unresolved" data-content-title="variable" data-linked-resource-default-alias="variable" href="#">variable</a></code><code>}</code>. The curly braces are mandatory. Note that variable names are case-sensitive and usually in UPPER CASE.</p>

<p>Example: To get the value of the OS environment variable &quot;CATALINA_HOME&quot;, use <code>${ENV</code><code><a class="confluence-link unresolved" data-content-title="CATALINA_HOME" data-linked-resource-default-alias="CATALINA_HOME" href="#">CATALINA_HOME</a></code><code>}</code>.</p>

<h2>Dynamic Variables</h2>

<p>Dynamic variables can be defined in the installation XML with the <code>&lt;variable&gt;</code> tag inside the <code>&lt;dynamicvariables&gt;</code> 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.</p>

<p>As and addition to normal variables, the value of a variable can either be defined by using the value attribute or by using a child element called value.</p>

<p>Example1: To change a certain directory based on user input, use the following <code>&lt;variable name=&quot;test&quot; value=&quot;/test/${USER_INPUT}&quot; condition=&quot;hasuserinput&quot; /&gt;</code> The condition has userinput has to be specified in the condition section of installation XML.</p>

<p>Example2: To comment out something in a xml file if a certain pack with id mycoolfeature is not activated, you could use &quot;two&quot; dynamic variables to create a xml comment or not.</p>

<h2>Parse Types</h2>

<p>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 <span style="text-decoration: line-through;">such as escaping control characters</span> correctly. The following parse types are available:</p>

<ul>
	<li><code>plain</code> - use this type for plain text files, where no special substitution rules apply. All variables will be replaced with their respective values as is.</li>
	<li><code>javaprop</code> - use this type if the substitution happens in a Java properties file. Individual variables might be modified to function properly within the context of Java property files.</li>
	<li><code>java</code> - use this type for Java files.</li>
	<li><code>xml</code> - use this type if the substitution happens in a XML file. Individual variables might be modified to function properly within the context of XML files.</li>
	<li><code>shell</code> - use this type if the substitution happens in a shell script. Because shell scripts use <code>$variable</code> themselves, an alternative variable marker is used: <code>%variable</code> or <code>%{variable</code>}.</li>
	<li><code>at</code> - use this type if the substitution must occure on files where paramters are marked with leading AT characters. The example: <code>@variable</code>.</li>
	<li><code>ant</code> - use this type if the substitution must occure on files where parameters are surrounded with AT characters (similar to ANT filters, hence the type name). The example: <code> </code><code>(variable)</code>.</li>
</ul>

<p>Unless using braces to surround variable's name (<code>${variable</code>} or <code>%{variable</code>}}, the variable name can contain following characters: letters, digits, dots, dashes <img class="emoticon emoticon-minus" data-emoticon-name="minus" border="0" src="/s/en_GB/3278/15/_/images/icons/emoticons/forbidden.png" alt="(minus)" title="(minus)" /> , underbars (_). Example: <code>$this.is-my_variable</code></p>

<p>If you want to have two variables separated by character that is allowed to appear in variable name, for example: <code>$major-version.$minor-version</code>, then you must use braces, and the above example should look like: <code>${major-version}.${minor-version</code>}.</p>

<h2>The IzPack Elements</h2>

<p><em>When writing your installer XML files, it's a good idea to have a look at the iZPACK installation DTD</em>.</p>

<h3>The Root Element <code>&lt;installation&gt;</code></h3>

<p>The root element of an installation is <code>&lt;installation&gt;</code>. It takes one required attribute : <code>version</code>. 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 <strong>1.0</strong> for the moment.</p>

<h3>The Information Element <code>&lt;info&gt;</code></h3>

<p>This element is used to specify some general information for the installer. It contains the following elements :</p>

<ul>
	<li><code>&lt;appname&gt;</code> : the application name</li>
	<li><code>&lt;appversion&gt;</code> : the application version</li>
	<li><code>&lt;appsubpath&gt;</code> : the subpath for the default of the installation path. A variable substitution and a maskable slash-backslash conversion will be done. If this tag is not defined, the application name will be used instead.</li>
	<li><code>&lt;url&gt;</code> : the application official website url</li>
	<li><code>&lt;authors&gt;</code> : specifies the author(s) of the application. It must contain at least one <code>&lt;author&gt;</code> element whose attributes are :
	<ul>
		<li><code>name</code> : the author's name</li>
		<li><code>email</code> : the author's email</li>
	</ul>
	</li>
</ul>

<ul>
	<li><code>&lt;uninstaller&gt;</code> : specifies whether to create an uninstaller after installation, and which name to use for it. This tag has the <code>write</code> attribute, with default value <code>yes</code>. If this tag is not specified, the uninstaller will still be written. The <code>name</code> attribute can be used to change the default name of the generated uninstaller, <em>i.e.</em> <code>uninstaller.jar</code>. The <code>condition</code> attribute can be used to specify a condition which has to be fullfilled for creating the uninstaller. The <code>path</code> attribute can be used to define the destination path where the uninstaller is written to, <em>i.e.</em> <code>${INSTALL_PATH}/Uninstaller</code>.</li>
	<li><code>&lt;javaversion&gt;</code> : specifies the minimum version of Java required to install your program. Values can be <code>1.2</code>, <code>1.2.2</code>, <code>1.4</code>, etc. The test is a lexical comparison against the <code>java.version</code> System property on the install machine.</li>
	<li><code>&lt;requiresjdk&gt;</code>: (yes or no) specifies wether a JDK is required for the software to be installed and executed. If not, then the user will be informed and given the option to still proceed with the installation process or not.</li>
	<li><code>&lt;webdir&gt;</code> : Causes a <em>web installer</em> to be created, and specifies the URL packages are retrieved from at install time. The content of the tag must be a properly formed URL.</li>
	<li><code>&lt;summarylogfilepath&gt;</code> : specifies the path for the logfile of the `SummaryLoggerInstallerListener`.</li>
	<li><code>&lt;writeinstallationinformation&gt;</code> : (yes or no) specifies if the file .installinformation should be written which includes the information about installed packs. The default if not specified is yes.</li>
	<li><code>&lt;pack200/&gt;</code>: adding this element will cause every JAR file that you will add to your packs to be compressed using Pack200 (see <a href="http://java.sun.com/j2se/1.5.0/docs/guide/deployment/deployment-guide/pack200.html).">http://java.sun.com/j2se/1.5.0/docs/guide/deployment/deployment-guide/pack200.html).</a> As a special exception, signed JARs are not compressed using Pack200, as it would invalidate the signatures. This makes the compilation process a little bit longer, but it usually results in drasticaly smaller installer files. The decompression is relatively fast. Please note that Pack200 compression is destructive, i.e., after decompression a JAR won't be identical to its original version (yet the code in the class files remains semantically equivalent).</li>
	<li><code>&lt;run-privileged/&gt;</code>: adding this element will make the installer attempt to launch itself with administrator permissions. Il also supports a <code>condition</code> attribute to reference a condition id so that the elevation is not always attempted (e.g., you may want to activate it only for Windows Vista). This is not supported on all platforms, in which case a message will be provided to the user before continuing the installation. You can disable this feature for the uninstaller by specifying <code>uninstaller=&quot;yes&quot;</code> as an attribute. Only use this feature if you really need to be an administrator as part of your installation process.</li>
</ul>

<ul>
	<li><code>&lt;rebootaction&gt;</code>: defines what to do if there were pending file operations left which require a reboot; otherwise any of the options below will be ignored. Possible values are:
	<ul>
		<li><code>ignore</code> (default): Doesn't reboot at all even if there are pending operations. Pending operations can be recognized only on the installer command line output (for all options).</li>
		<li><code>notice</code>: Doesn't reboot, but notices the user interactively at the end of an installation, which must be confirmed. Notification works only for interactive installation types (no auto-installation).</li>
		<li><code>ask</code>: Reboots only if the user confirms it interactively at the end of an installation.</li>
		<li><code>always</code>: Reboots always without any confirmation at the end of an installation.<br />
Notes:</li>
	</ul>
	</li>
</ul>

<ul>
	<li>
	<ol>
		<li>The usage of <code>&lt;rebootaction&gt;</code> is bound to using the attribute blockable_ with the values <code>auto</code> or <code>force</code> at least in one of the elements <code>&lt;file&gt;</code>, <code>&lt;singlefile&gt;</code> or <code>&lt;fileset&gt;</code>, for being able to recognize blocked files before IzPack tries to overwrite them (which would result in a failing installation of the file). See the documentation of these elements later.</li>
		<li><code>&lt;rebootaction&gt;</code> works and makes sense only on Windows, where target files (as device drivers, EXE or DLL files) might be blocked during an installation. On other platforms than Windows the <code>&lt;rebootaction&gt;</code> element will be ignored.</li>
		<li><code>&lt;rebootaction&gt;</code> supports the <code>condition</code> attribute to limit reboot processing on particular conditions.</li>
		<li>Without setting at least one attribute blockable = <code>auto</code> or blockable = <code>force</code> rebootaction will not have any effect.<br />
See also the description of the blockable_ attribute.<br />
For getting more information see the chapter <em>Advanced features</em>.</li>
	</ol>
	</li>
</ul>

<p>Here is an example of a typical <code>&lt;info&gt;</code> section :</p>

<h3>The Packaging Element <code>&lt;packaging&gt;</code></h3>

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

<ul>
	<li><code>&lt;packager&gt;</code> : specifies options used by the packager. The packager tag has the <code>class</code> attribute, which specifys the class to use for packaging. Currently two implementations are available (com.izforge.izpack.compiler.packager.impl.Packager, com.izforge.izpack.compiler.packager.impl.MultiVolumePackager). The packager-element can contain the <code>&lt;options&gt;</code> element which can have different attributes for the different implementations of packagers. For the MultiVolumePackager, it can have the following attributes:
	<ul>
		<li><code>volumesize</code>: the size of the volumes</li>
		<li><code>firstvolumefreespace</code>: free space on the first volume used for the installer jar and additional resources like readme-files etc.</li>
	</ul>
	</li>
</ul>

<ul>
	<li><code>&lt;unpacker&gt;</code> : specifies which unpacker class should be used. Currently there are two unpacker implementations (com.izforge.izpack.compiler.UnPacker, com.izforge.izpack.compiler.MultiVolumeUnPacker).</li>
</ul>

<p>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.&lt;number&gt; on several volumes.</p>

<h3>The Variables Element <code>&lt;variables&gt;</code></h3>

<p>This element allows you to define variables for the variables substitution system. Some variables are built-in, such as <code>$INSTALL_PATH</code> (which is the installation path chosen by the user). When you define a set of variables, you just have to place as many <code>&lt;variable&gt;</code> tags in the file as needed. If you define a variable named <code>VERSION</code> you need to type $VERSION in the files to parse. The variable substitutor will then replace it with the correct value. One <code>&lt;variable&gt;</code> tag take the following attributes :</p>

<ul>
	<li><code>name</code> : the variable name</li>
	<li><code>value</code> : the variable value</li>
</ul>

<p>Here's a sample <code>&lt;variables&gt;</code> section :</p>

<h3>The dynamic Variables Element <code>&lt;dynamicvariables&gt;</code></h3>

<p>This element allows you to define dynamic variables for the variables substitution system. In contrast to the static <code>&lt;variables</code>, dynamic variables will be evaluated every time, a panel switch is done.</p>

<p>When you define a set of variables, you just have to place as many <code>&lt;variable&gt;</code> tags in the file as needed. Normally you would use the condition attribute to specify, when a certain value will be set.</p>

<p>One <code>&lt;variable&gt;</code> tag take the following attributes :</p>

<ul>
	<li><code>name</code> : the variable name</li>
	<li><code>value</code> : the variable value</li>
	<li><code>condition</code> : a condition for this variable, which has to be true to set the value</li>
</ul>

<p>Here's a sample <code>&lt;dynamicvariables&gt;</code> section :</p>

<h3>The Conditions Element <code>&lt;conditions&gt;</code></h3>

<p>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 <code>RefCondition</code>).</p>

<p>There are several built-in types of conditions. At the time of writing this, Izpack has the following built-in types:</p>

<ul>
	<li><code>VariableCondition</code>: a condition based on the value of a certain variable</li>
	<li><code>PackSelectionCondition</code>: a condition based on a pack selected for installation</li>
	<li><code>JavaCondition</code>: a condition based on a static java field or method.</li>
	<li><code>CompareNumericsCondition</code>: a condition based on the comparison of a certain variable with a given value and operator.</li>
</ul>

<p>There are also boolean types to combine more than one condition:</p>

<ul>
	<li><code>AndCondition</code>: both conditions have to be true</li>
	<li><code>OrCondition</code>: only one of both conditions has to be true</li>
	<li><code>XOrCondition</code>: one condition has to be true, the other one has to be false</li>
	<li><code>NotCondition</code>: the condition has to be false</li>
</ul>

<p>When you define a set of conditions, you just have to write as many <code>&lt;condition&gt;</code> tags as you like. A condition can take the following attributes:</p>

<table class="wysiwyg-macro" data-macro-name="panel" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e3BhbmVsfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body">
<p>**; <code>type</code>: the type of the condition. For built-in types, this is the lowercase portion of the condition class</p></td></tr></table>
<ul>
	<li>: 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.</li>
</ul>

<ul>
	<li><code>id</code>: the id of the condition. This will be used to refer to this conditions in other elements</li>
</ul>

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

<p>This is an example which defines four conditions, two VariableConditions, a JavaCondition and a AndCondition which will refer to two of the first conditions.</p>

<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>&lt;conditions>
   &lt;condition type="variable" id="standardinstallation">
      &lt;name>setup.type&lt;/name>
      &lt;value>standard&lt;/value>
   &lt;/condition>
   &lt;condition type="variable" id="expertinstallation">
      &lt;name>setup.type&lt;/name>
      &lt;value>expert&lt;/value>
   &lt;/condition>
   &lt;condition type="java" id="installonwindows">
 &lt;java>
   &lt;class>com.izforge.izpack.util.OsVersion&lt;/class>
   &lt;field>IS_WINDOWS&lt;/field>
 &lt;/java>
 &lt;returnvalue type="boolean">true&lt;/returnvalue>
 &lt;/condition>
 &lt;condition type="and" id="standardinstallation.onwindows">
   &lt;condition type="ref" refid="standardinstallation"/>
   &lt;condition type="ref" refid="installonwindows" />
 &lt;/condition>
&lt;/conditions></pre></td></tr></table>
<p>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:</p>

<ul>
	<li>{+}: an operator for the Andcondition</li>
	<li><code>|</code>: an operator for the OrCondition</li>
	<li>{{}}: an operator for the XOrCondition</li>
	<li><code>!</code>: an operator for the NotCondition</li>
</ul>

<p>Neverthless if you define really complex conditions it's much easier to define them using the xml structure.</p>

<p>More types of conditions can be defined by inheriting com.izforge.izpack.Condition class.</p>

<h3>Built-in conditions</h3>

<p>A number of built-in condition IDs are available for you.</p>
<table class="confluenceTable"><tbody>
<tr>
<th class="confluenceTh"><p> Name </p></th>
<th class="confluenceTh"><p> Condition </p></th>
</tr>
<tr>
<td class="confluenceTd"><p> izpack.windowsinstall </p></td>
<td class="confluenceTd"><p> The OS is Windows (any variant) </p></td>
</tr>
<tr>
<td class="confluenceTd"><p> izpack.windowsinstall.xp </p></td>
<td class="confluenceTd"><p> The OS is Windows XP </p></td>
</tr>
<tr>
<td class="confluenceTd"><p> izpack.windowsinstall.2003 </p></td>
<td class="confluenceTd"><p> The OS is Windows Server 2003 </p></td>
</tr>
<tr>
<td class="confluenceTd"><p> izpack.windowsinstall.vista </p></td>
<td class="confluenceTd"><p> The OS is Windows Vista </p></td>
</tr>
<tr>
<td class="confluenceTd"><p> izpack.windowsinstall.7 </p></td>
<td class="confluenceTd"><p> The OS is Windows 7 </p></td>
</tr>
<tr>
<td class="confluenceTd"><p> izpack.linuxinstall </p></td>
<td class="confluenceTd"><p> The OS is Linux (any variant) </p></td>
</tr>
<tr>
<td class="confluenceTd"><p> izpack.solarisinstall </p></td>
<td class="confluenceTd"><p> The OS is Solaris (any variant) </p></td>
</tr>
<tr>
<td class="confluenceTd"><p> izpack.solarisinstall.x86 </p></td>
<td class="confluenceTd"><p> The OS is Solaris (any x86 variant) </p></td>
</tr>
<tr>
<td class="confluenceTd"><p> izpack.solarisinstall.sparc </p></td>
<td class="confluenceTd"><p> The OS is Solaris (any Sparc variant) </p></td>
</tr>
</tbody></table>

<h4>The Installer Requirements Element <code>&lt;installerrequirements&gt;</code></h4>

<p>This element allows to specify requirements for running the installation. This will be done based on conditions defined in the conditions section.</p>

<p>An installer requirement consists of a condition and a message which will be shown if the condition is not fulfilled. If so, the installer will show the message and exit after that.</p>

<ul>
	<li><code>installerrequirement</code>: specifies a single installer requirement. You can define an unlimited number of them.</li>
</ul>

<p>Installerrequirements have the following attributes: - <code>condition</code>: an id of a condition defined in the conditions section - <code>message</code>: a message text or a langpack key defining which message should be shown before exiting the installer in case of a missing requirement.</p>

<h3>The GUI Preferences Element <code>&lt;guiprefs&gt;</code></h3>

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

<ul>
	<li><code>resizable</code> : takes <code>yes</code> or <code>no</code> and indicates whether the window size can be changed or not.</li>
	<li><code>width</code> : sets the initial window width</li>
	<li><code>height</code> : sets the initial window height.</li>
</ul>

<p>Here's a sample :</p>

<ul>
	<li><code>laf</code>: the tag that specifies a look and feel. It has a <code>name</code> parameter that defines the look and feel name.</li>
	<li>Each <code>laf</code> element needs at least one <code>os</code> tag, specified like in the other parts of the specification that support this tag.</li>
	<li>Like you can add <code>os</code> elements, you can add any number of <code>param</code> elements to customize a look and feel. A <code>param</code> elements has two attribues: <code>name</code> and <code>value</code>.</li>
</ul>

<p>The available look and feels are:</p>

<ul>
	<li>Kunststoff: <code>kunststoff</code></li>
	<li>Liquid: <code>liquid</code></li>
	<li>Metouia: <code>metouia</code></li>
	<li>JGoodies Looks: <code>looks</code></li>
	<li>Substance: <code>substance</code></li>
</ul>

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

<p>The <em>Liquid Look and Feel</em> supports the following parameters:</p>

<ul>
	<li><code>decorate.frames</code>: <code>yes</code> means that it will render the frames in Liquid style</li>
	<li><code>decorate.dialogs</code>: <code>yes</code> means that it will render the dialogs in Liquid style</li>
</ul>

<p>The <em>JGoodies Looks</em> look and feel can be specified by using the <code>variant</code> parameters. The values can be one of:</p>

<ul>
	<li><code>windows</code>: use the Windows look</li>
	<li><code>plastic</code>: use the basic Plastic look</li>
	<li><code>plastic3D</code>: use the Plastic 3D look</li>
	<li><code>plasticXP</code>: use the Plastic XP look (default).</li>
</ul>

<p>Here is a small sample:</p>

<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>&lt;guiprefs height="600" resizable="yes" width="800">
    &lt;laf name="metouia">
        &lt;os family="unix" />
    &lt;/laf>
    &lt;laf name="looks">
        &lt;os family="windows" />
        &lt;param name="variant" value="extwin" />
    &lt;/laf>
&lt;/guiprefs></pre></td></tr></table>
<p>The <em>Substance</em> look and feel <em>toned-down</em> themes can be specified using the <code>variant</code> parameter, with the value being one of: <code>business, business- blue, business-black, creme, sahara, moderate, officesilver</code>. 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 <a href="https://substance.dev.java.net/docs/skins/toneddown.html">https://substance.dev.java.net/docs/skins/toneddown.html</a> for a gallery of the different toned-down themes.</p>

<p>Starting from IzPack 3.7, some characteristics can be customized with the <code>&lt;modifier&gt;</code> tag. There is a separate description in the `Advanced Features` chapter paragraph `Modifying the GUI`.</p>

<h3>The Localization Element <code>&lt;locale&gt;</code></h3>

<p>This element is used to specify the language packs (langpacks) that you want to use for your installer. You must set one <code>&lt;langpack&gt;</code> markup per language. This markup takes the <code>iso3</code> parameter which specifies the iso3 language code.</p>

<p>Here's a sample :</p>

<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>&lt;locale>
  &lt;langpack iso3="eng"/>
  &lt;langpack iso3="fra"/>
  &lt;langpack iso3="spa"/>
&lt;/locale></pre></td></tr></table>
<p>The supported ISO3 codes are :h3. h4. h4. h4. h2. ISO3 code Language h4. h4. h4. cat Catalunyan chn Chinese cze Czech dan Danish glg Galician deu German eng English eus Basque fin Finnish fra French hun Hungarian ita Italian jpn Japanese mys Malaysian ned Nederlands nor Norwegian pol Polnish por Portuguese (Brazilian) prt Portuguese (European) rom Romanian rus Russian scg Serbian spa Spanish svk Slovakian swe Swedish ukr Ukrainianh3. h4. h4.h3.  The Resources Element <code>&lt;resources&gt;</code> h3. 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 <code>&lt;resources&gt;</code> element is not required, and no <code>&lt;res&gt;</code> elements are required within. The <code>&lt;resources&gt;</code> element is the only element besides the <code>&lt;packs&gt;</code> element that is taken into consideration in referenced pack-files (see <code>`&lt;packs&gt;</code> element`_ for more info)</p>

<p>You have to set one <code>&lt;res&gt;</code> markup for each resource. Here are the attributes to specify :</p>

<ul>
	<li><code>src</code> : the path to the resource file which can be named freely of course (for instance <code>my-picture.jpg</code>).</li>
	<li><code>id</code> : the resource id, depending on the needs of a particular panel</li>
	<li><code>parse</code> : takes <code>yes</code> or <code>no</code> (default is <code>no</code>) - used to specify whether the resource must be parsed at the installer compilation time. For instance you could set the application version in a readme file used by <code>InfoPanel</code>.</li>
	<li><code>type</code> : specifies the parse type. This makes sense only for a text resource - the default is <code>plain</code>, other values are <code>javaprop, xml, plain, java, shell, at, ant</code> (Java properties file and XML files)</li>
	<li><code>encoding</code> : specifies the resource encoding if the receiver needs to know. This makes sense only for a text resource.</li>
</ul>

<p>Here's a sample :</p>

<p>You can define bundles of resources by using <code>&lt;bundle&gt;</code> You have to set a unique id for the bundle <code>id</code>. One bundle can be marked to be default: <code>default=&quot;true&quot;</code></p>

<p>You need to define a variable to set the name of the SystemProperty: <code>resource.bundle.system.property</code></p>

<p>Here's a sample:</p>

<p>; &lt;variables&gt;</p>
<table class="wysiwyg-macro" data-macro-name="panel" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e3BhbmVsfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body">
<p>... &lt;variable name=&quot;resource.bundle.system.property&quot; value=&quot;BUNDLE_NAME&quot; /&gt;</p></td></tr></table>

<p>&lt;/variables&gt; ... &lt;resources&gt; &lt; <table class="wysiwyg-macro" data-macro-name="unmigrated-wiki-markup" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e3VubWlncmF0ZWQtd2lraS1tYXJrdXB9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>!-- bundle 1 --> &lt;bundle id="bundle1" default="yes"> &lt;res id="Heading.image" src="path1/HeadingImage.png" /> &lt;res id="installer.langsel.img" src="path1/langselImage.png" /> &lt;/bundle> &lt;!</pre></td></tr></table>-- bundle 2 -<span style="text-decoration: line-through;">&gt; &lt;bundle id=&quot;bundle2&quot;&gt; &lt;res id=&quot;Heading.image&quot; src=&quot;path2/HeadingImage.png&quot; /&gt; &lt;res id=&quot;installer.langsel.img&quot; src=&quot;path2/langselImage.png&quot; /&gt; &lt;/bundle&gt; &lt;!</span>- common resources --&gt; &lt;res id=&quot;resource.id&quot; src=&quot;path.to.resource&quot; /&gt; ...</p>

<p>Resources will be then be loaded in the following order:</p>

<ul>
	<li><code>classname</code>: which is the classname of the panel.</li>
	<li><code>id</code>: an identifier for a panel which can be used e.g. for referencing in userinput panel definitions.</li>
	<li><code>condition</code>: an id of a condition which has to be fullfilled to show this panel</li>
	<li><code>jar</code>: jar file where the classes for this panel can be found. This attribute is optional. If it is empty (jar=&quot;&quot;) the classes for this panel must be murged using the &lt;jar&gt; tag.</li>
</ul>

<p>Here is a sample :</p>

<p>The <code>&lt;help&gt;</code> takes the following attributes :</p>

<ul>
	<li><code>iso3</code>: iso3 representation of the language the help is written</li>
	<li><code>src</code>: path to the help file to display</li>
</ul>

<p>Here's a sample :</p>

<p>The <code>&lt;validator&gt;</code> takes the following attributes :</p>

<ul>
	<li><code>classname</code>: The class implementing com.izforge.izpack.api.installer.DataValidator</li>
</ul>

<p>Here's a sample :</p>

<p>The <code>&lt;actions&gt;</code> tag has no attributes but has <code>&lt;action&gt;</code> markups with the following attributes :</p>

<ul>
	<li><code>stage</code>: The stage when the action should be triggered. Possible values are <code>preconstruct</code>, <code>preactivate</code>, <code>prevalidate</code> or <code>postvalidate</code>.</li>
	<li><code>classname</code>: The class implementing com.izforge.izpack.installer.PanelAction</li>
</ul>

<p>Here's a sample :</p>

<p>The <code>&lt;pack&gt;</code> takes the following attributes :</p>

<ul>
	<li><code>name</code>: the pack name</li>
	<li><code>required</code>: takes <code>yes</code> or <code>no</code> and specifies whether the pack is optional or not.</li>
	<li><code>os</code>: optional attribute that lets you make the pack targeted to a specific <em>operating system</em>, for instance <code>unix</code>, <code>mac</code> and so on.</li>
	<li><code>preselected</code>: optional attribute that lets you choose whether the pack is by default selected for installation or not. Possible values are <code>yes</code> and <code>no</code>. A pack which is not preselected needs to be explicitly selected by the user during installation to get installed.</li>
	<li><code>loose</code>: can be used so that the files are not located in the installer Jar. The possible values are <code>true</code> or <code>false</code>, the default beeing <code>false</code>. 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. <em>Please make sure that your relative files paths are correct !</em></li>
	<li><code>id</code>: this attribute is used to give a unique id to the pack to be used for internationalization via <code>packsLang.xml</code> file.</li>
	<li><code>packImgId</code>: 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 <code>&lt;resources&gt;</code> element of the installation XML using the same value for the <code>id</code> attribute of the <code>&lt;res&gt;</code> element.</li>
	<li><code>condition</code>: an id of a condition which has to be fullfilled to install this package.</li>
	<li><code>hidden</code>: takes <code>true</code> or <code>false</code> and specifies whether the pack shall be shown in the packs panel. The bytes of such a hidden pack will be used to calculate the required space, but the pack itself won't be shown. A hidden pack can be selected conditionally. So you have to specify a condition to enable it for installation. The default for this attribute is <code>false</code></li>
</ul>

<p>The <code>&lt;refpack&gt;</code> takes only one attribute <code>file</code>, 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 <code>&lt;packs&gt;</code> and the <code>&lt;resources&gt;</code> elements. This enables a model in which a single developer is responsible for maintaining the packs and resources (e.g. separate <code>packsLang.xml_xyz</code> 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.</p>

<p>The <code>&lt;refpackset&gt;</code> tag can be used in situations were there is no predefined set of <code>&lt;refpack&gt;</code> files, but a given directory should be scanned for <code>&lt;refpack&gt;</code> files to be included instead. This element takes the following parameters:</p>

<ul>
	<li><code>dir</code>: the base directory for the refpackset (relative path)</li>
	<li><code>includes</code>: a pattern of files in <code>&lt;refpack&gt;</code> format that must be included</li>
</ul>

<p>An example:</p>

<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>&lt;refpackset dir="" includes="**/refpack.xml" /></pre></td></tr></table>
<p> Internationalization of the PacksPanel h3. 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 <code>packsLang.xml_xyz</code> where <code>xyz</code> 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 <code>install.xml</code> with the <code>id</code> and <code>src</code> attributes set at the name of the file. The format of these files is identical with the distribution langpack files located at <code>$IZPACK_HOME/bin/langpacks/installer</code>. For the name of the panel you just use the pack <code>id</code> as the txt <code>id</code>. For the description you use the pack <code>id</code> suffixed with <code>.description</code>.</p>

<p>An example:</p>

<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>&lt;langpack>
    &lt;str id="myApplication" txt="Main Application"/>
    &lt;str id="myApplication.description" txt="A description of my main application"/>
    [...]
&lt;/langpack></pre></td></tr></table>
<p>The following sections describe the tags available for a <code>&lt;pack&gt;</code> section. <code>&lt;description&gt;</code> - pack description h3. The contents of the <code>&lt;description&gt;</code> tag describe the pack contents. This description is displayed if the user highlights the pack during installation. <code>&lt;depends&gt;</code> - pack dependencies h3. 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 <code>&lt;depends&gt;</code> elements. Circular depedencies are not supported and the compiler reports an error if one occurs.</p>

<p>This tag takes the following attribute:</p>

<ul>
	<li><code>packname</code>: The name of the pack that it depends on <code>&lt;os&gt;</code> - OS restrictions h3. It is possible to restrict a panel to a certain list of operating systems. This tag takes the following attributes:</li>
</ul>

<ul>
	<li><code>family</code>: unix, windows or mac</li>
	<li><code>name</code>: the exact OS name (ie Windows, Linux, ...)</li>
	<li><code>version</code>: the exact OS version (see the JVM <code>os.version</code> property)</li>
	<li><code>arch</code>: the machine architecture (see the JVM <code>os.arch</code> property). <code>&lt;updatecheck&gt;</code> h3. 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:</li>
</ul>

<p>&gt; Each pack can now specify an <code>&lt;updatecheck&gt;</code> tag. It supports a subset of ant fileset syntax, e.g.:</p>

<ul>
	<li><code>src</code>: the file location (relative path) - if this is a directory its content will be added recursively. It may contain previously defined static variables (see <code>&lt;variables&gt;</code>).</li>
	<li><code>targetdir</code>: the destination directory, could be something like <code>$INSTALL_PATH/subdirX</code></li>
	<li><code>os</code>: can optionally specify a target operating system (<code>unix, windows, mac</code>) - this means that the file will only be installed on its target operating system</li>
	<li><code>override</code>: if <code>true</code> then if the file is already installed, it will be overwritten (use <code>false</code> otherwise). Alternative values: <code>asktrue</code> and <code>askfalse</code> -ask the user what to do and supply default value for non-interactive use. Another possible values is <code>update</code>. 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.) By default it is set to <code>update</code>.</li>
</ul>

<ul>
	<li><code>blockable</code> : 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 <code>info</code> element. See above for possible reboot options. Possible values:
	<ul>
		<li><code>none</code> (default): No recognition of blocked target files will be done at all, this is the default behavior of previous IzPack versions.</li>
		<li><code>auto</code>: 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 <code>auto</code> 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.</li>
		<li><code>force</code>: Forces target file to be always assumed a blocked, resulting in leaving a pending file operation to be finished after system reboot. Using <code>force</code> 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.<br />
Notes:</li>
	</ul>
	</li>
</ul>

<ul>
	<li>
	<ol>
		<li>Using <code>blockable</code> does not necessarily force you to limit such files on Windows systems. For multi-platform installations there is a compiler warning thrown that <code>blockable</code> will be ignored on non-Windows systems.</li>
		<li>The native library <code>WinSetupAPI</code> must be explicitely included using this feature.<br />
For setting up the according reboot behaviour see the rebootaction_ element.<br />
For getting more information see the chapter <em>Advanced features</em>.</li>
	</ol>
	</li>
	<li><code>unpack</code>: if <code>true</code> and the file is an archive then its content will be unpacked and added as individual files</li>
	<li><code>condition</code>: an id of a condition which has to be fullfilled to install this file <code>&lt;additionaldata&gt;</code> h3. This tag can also be specified in order to pass additional data related to a file tag for customizing.</li>
</ul>

<ul>
	<li><code>&lt;key&gt;</code>: key to identify the data</li>
	<li><code>&lt;value&gt;</code>: value which can be used by a custom action <code>&lt;singlefile&gt;</code> - add a single file h3. Specifies a single file to include. The difference to <code>&lt;file&gt;</code> is that this tag allows the file to be renamed, therefore it has a <code>target</code> attribute instead of <code>targetdir</code>.</li>
</ul>

<ul>
	<li><code>src</code>: the file location (relative path). It may contain previously defined static variables (see <code>&lt;variables&gt;</code>).</li>
	<li><code>target</code>: the destination file name, could be something like <code>$INSTALL_PATH/subdirX/fileY</code></li>
	<li><code>os</code>: can optionally specify a target operating system (<code>unix, windows, mac</code>) - this means that the file will only be installed on its target operating system</li>
	<li><code>override</code>: see <code>&lt;file&gt;</code> for description</li>
	<li><code>blockable</code>: see <code>&lt;file&gt;</code> for description</li>
	<li><code>condition</code>: an id of a condition which has to be fullfilled to install this file</li>
</ul>

<p>A <code>&lt;additionaldata&gt;</code> tag can also be specified for customizing. <code>&lt;fileset&gt;</code>: add a fileset h3. The <code>&lt;fileset&gt;</code> tag allows files to be specified using the powerful Jakarta Ant set syntax. It takes the following parameters:</p>

<ul>
	<li><code>dir</code>: the base directory for the fileset (relative path)</li>
	<li><code>targetdir</code>: the destination path, works like for <code>&lt;file&gt;</code></li>
	<li><code>casesensitive</code>: optionally lets you specify if the names are case-sensitive or not - takes <code>yes</code> or <code>no</code></li>
	<li><code>defaultexcludes</code>: optionally lets you specify if the default excludes will be used - takes <code>yes</code> or <code>no</code>.</li>
	<li><code>os</code>: specifies the operating system, works like for <code>&lt;file&gt;</code></li>
	<li><code>override</code>: see <code>&lt;file&gt;</code> for description</li>
	<li><code>blockable</code>: see <code>&lt;file&gt;</code> for description (applied for all files in the fileset)</li>
	<li><code>includes</code>: 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.</li>
	<li><code>excludes</code>: 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.</li>
	<li><code>condition</code>: an id of a condition which has to be fullfilled to install the files in this fileset</li>
</ul>

<p>You specify the files with <code>&lt;include&gt;</code> and <code>&lt;exclude&gt;</code> tags that take the <code>name</code> parameter to specify the Ant-like pattern :</p>

<p>Here are some examples of Ant patterns :</p>

<ul>
	<li><code>&lt;include name=&quot;lib&quot;/&gt;</code> : will include <code>lib</code> and the subdirectories of <code>lib</code>
<table class="wysiwyg-macro" data-macro-name="panel" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e3BhbmVsfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body">
<p> <code><strong>&lt;exclude name=&quot;</strong></code><code><strong>/</strong></code><code>.java&quot;/&gt;</code> : will exclude any file in any directory starting from the base path ending by <code>.java</code><br />
<code><strong>&lt;include name=&quot;lib/</strong></code><code>.jar&quot;/&gt;</code> : will include all the files ending by <code>.jar</code> in <code>lib</code><br />
<code><strong>&lt;exclude name=&quot;lib/</strong></code><code>*/</code><code><strong>FOO</strong></code><code>&quot;/&gt;</code> : will exclude any file in any subdirectory starting from <code>lib</code> whose name contains <code>FOO</code>.</p></td></tr></table></li>
</ul>

<p>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 &lt;defaultexcludes&gt; task. Default excludes are:</p>

<ul>
	<li><code>targetfile</code> : the file to parse, could be something like <code>$INSTALL_PATH/bin/launch-script.sh</code> 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. No longer mandatory as a fileset of files can be used.</li>
	<li><code>type</code> : specifies the type (same as for the resources) - the default is <code>plain</code></li>
	<li><code>encoding</code> : specifies the file encoding</li>
	<li><code>os</code>: specifies the operating system, works like for <code>&lt;file&gt;</code></li>
	<li><code>condition</code>: an id of a condition which has to be fullfilled to parse this file</li>
</ul>

<p>One or more fileset tags can be used inside parsable to specify multiple files at once. <code>&lt;executable&gt;</code> - mark file executable or execute it h3. The <code>&lt;executable&gt;</code> 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 :</p>

<ul>
	<li><code>targetfile</code> : the file to run, could be something like <code>$INSTALL_PATH/bin/launch-script.sh</code> Slashes are handled special (see attribute <code>targetfile</code> of tag <code>&lt;parsable&gt;</code>).</li>
	<li><code>class</code> : If the executable is a jar file, this is the class to run for a JavaTM program</li>
	<li><code>type</code> : <code>bin</code> or <code>jar</code> (the default is <code>bin</code>)</li>
	<li><code>stage</code> : specifies when to launch : <code>postinstall</code> is just after the installation is done, <code>never</code> will never launch it (useful to set the +x flag on Unix). <code>uninstall</code> will launch the executable when the application is uninstalled. The executable is executed before any files are deleted. <code>never</code> is the default value.</li>
	<li><code>failure</code> : specifies what to do when an error occurs : <code>abort</code> will abort the installation process, <code>ask</code> (default) will ask the user what to do and <code>warn</code> will just tell the user that something is wrong</li>
	<li><code>os</code>: specifies the operating system, works like for <code>&lt;file&gt;</code></li>
	<li><code>keep</code> : specifies whether the file will be kept after execution. The default is to delete the file after is has been executed. This can be changed by specifying <code>keep=&quot;true&quot;</code>.</li>
	<li><code>condition</code>: an id of a condition which has to be fullfilled to execute this file</li>
</ul>

<p>A <code>&lt;args&gt;</code> tag can also be specified in order to pass arguments to the executable:</p>

<ul>
	<li><code>&lt;arg&gt;</code>: passes the argument specified in the <code>value</code> attribute. Slashes are handled special (see attribute <code>targetfile</code> of tag <code>&lt;parsable&gt;</code>. <code>&lt;os&gt;</code> - make a file OS-dependent h3. The <code>&lt;os&gt;</code> tag can be used inside the <code>&lt;file&gt;</code>, <code>&lt;fileset&gt;</code>, <code>&lt;singlefile&gt;</code>, <code>&lt;parsable&gt;</code>, <code>&lt;executable&gt;</code> tags to restrict it's effect to a specific operating system family, architecture or version using the following attributes:</li>
</ul>

<ul>
	<li><code>family</code>: <code>unix, windows, mac</code> to specify the operating system family</li>
	<li><code>name</code>: the operating system name</li>
	<li><code>version</code>: the operating system version</li>
	<li><code>arch</code>: the operating system architecture (for instance the Linux kernel can run on i386, sparc, and so on)</li>
</ul>

<p>Here's an example installation file fragment:</p>

(...)

&lt;pack name="Core" required="yes">

(...)

&lt;executable targetfile="$INSTALL_PATH/bin/compile" stage="never">
            &lt;os family="unix"/>
        &lt;/executable>

(...)

&lt;/pack>

(...)

&lt;/packs></pre></td></tr></table>
<p> The Native Element <code>&lt;native&gt;</code> h3. Use this if you want to use a feature that requires a native library. The native libraries are placed under <code>bin/native/..</code>. There are 2 kinds of native libraries : the iZPACK libraries and the third-party ones. The IzPack libraries are located at <code>bin/native/izpack</code>, you can place your own libraries at <code>bin/native/3rdparty</code>. It is possible to place a native library also into the uninstaller.</p>

<p>It is usable 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 :</p>

<ul>
	<li><code>type</code> : <code>izpack</code> or <code>3rdparty</code></li>
	<li><code>name</code> : the library filename</li>
	<li><code>stage</code>: stage where to use the library (install|uninstall|both)</li>
	<li><code>src</code> : source directory where to find the library to build the installer</li>
</ul>

<p>Note for developers: <code>com.izforge.izpack.util.Librarian.loadLibrary()</code> must be used to load custom native libraries, as it performs some housekeeping. <code>&lt;os&gt;</code> - make a library OS-dependent h3. The <code>&lt;os&gt;</code> 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.</p>

<p>Here's a sample :</p>

<ul>
	<li><code>src</code> : the path at compile time</li>
	<li><code>stage</code>: stage where to use the contents of the additional jar file (install|uninstall|both)</li>
</ul>

<p>A sample :</p>

<h2>XInclude-style constructs</h2>

<p>The xi:include element is used to include xml or text documents in your configuration files.</p>

<p>The xi:include element can be used anywhere in pretty much any of the xml files used by IzPack. It is supported by the javax DocumentBuilder. It follows the XInclude recommandation produced by the W3C (<a href="http://www.w3.org/TR/xinclude/">http://www.w3.org/TR/xinclude/</a>) and should be able to be used as decribed in that document.</p>

<p>To use the xi:include, you have to specify the namespace xmlns:xi=&quot;http://www.w3.org/2001/XInclude&quot; in your xml.</p>

<p>If a logical error appear in an included file, the line number shown will indicate the xinclude element in the main xml file.</p>

<p>The xi:include element has the following attributes:</p>

<ul>
	<li>href<br />
The location of the file to include. If this is a relative path (e.g. href='../bob.xml') then the file is resolved relative to the document that includes the xinclude element. The href element can be a remote url (e.g. href='http://example.com/file.txt') but this is not recommended.</li>
	<li>parse<br />
Indicates that the included file should be treated as xml, forcing the included file to be parsed (which results in all xinclude elements in the included file to also be included), or as text which includes the specified file as a text node. It can have a value of 'xml' or 'text' and defaults to 'xml' if ommitted.</li>
	<li>xpointer<br />
In case in parse=&quot;xml&quot;, you can use xpointer to get a part of the included xml. The details of the xpointer framework can be found <a href="http://www.w3.org/TR/2003/REC-xptr-framework-20030325/.">http://www.w3.org/TR/2003/REC-xptr-framework-20030325/.</a></li>
	<li>encoding<br />
This is used when the parse attribute is 'text' to specify the character encoding of the included text document. It has no effect if parse is 'xml'.</li>
	<li>accept<br />
Used if the href attribute specifies a url accessible via HTTP. The value of this attribute will be added as the accpet header on the HTTP request. The fallback element h3. The xi:fallback element is used to provide a fallback if the xi:include element fails. It can be empty or can contain a valid xml. If it is empty then a failure to include the specified document is supressed. If it contains a xml then a failure to include the specified document causes the xml specified in the fallback is parsed (evaluating nested xinclude elements) and inserted into the document in its place.</li>
</ul>

<p>For example the following use of xi:include</p>

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

<p>e.g. If I want to use xi:include to include a file containing the following fragments:</p>