Upgrading from IzPack 4.3 to 5.0

Upgrading installation files 

IzPack installation files try to preserve backwards compatibility as much as possible yet version 5.0 introduced some incompatible changes - mostly for consistency:

Native elements 

The <native> elements must now be contained in a <natives> wrapping element under 5.0. See the section on Native Libraries.

Panel action param elements

The optional <param> element in a panel <action> element now uses name and value attributes instead of key and value child elements. The following examples illustrate the change between the two versions.

<panel classname="TargetPanel" id="target.win">
  <os family="windows" />
  <actions>
    <action stage="preactivate" classname="com.opentext.installer.actions.RegistryReaderAction">
      <param>
        <key>ConfigurationFile</key>
        <value>RegistryReaderConfiguration.xml</value>
      </param>
    </action>
  </actions>
</panel>

<panel classname="TargetPanel" id="target.win">
  <os family="windows" />
  <actions>
    <action stage="preactivate" classname="com.opentext.installer.actions.RegistryReaderAction">
      <param name="ConfigurationFile" value="RegistryReaderConfiguration.xml"/>
    </action>
  </actions>
</panel>

See the section on Panel Actions.

Panel configuration param elements

The optional <configuration> section in a <panel> element permits nested <param> elements. Previously, the <param> element was specified using child elements <key> and <value>. This has now been changed to name and value attributes - see Panel action param elements, above, and the Panels section.

LateShortcutInstallListener 

Due to refactoring and improvement to the internal workings of IzPack, LateShortcutInstallListener is no longer available. Instead, use the new <lateShortcutInstall/> option in shortcutSpec.xml. See Shortcut Specification for details. 

Default installation directories in TargetPanel.dir.*

IZPACK-798 changed TargetPanel.dir.* etc to be variables, rather than resources.

In 4.3.5, the default directory displayed in TargetPanel may be configured in a text file named:

• TargetPanel.dir.<os name>
• TargetPanel.dir

In the <os name> form, the os name is one of:

• System.getProperty("os.name").replace(' ', '_')
• "windows"
• "mac"
• "unix"

For 4.3.6, IZPACK-798 changed the above to use variables instead of text files, following the same naming convention.
For 5.0 a better approach would be to use Platform to determine the appropriate variable (see IZPACK-829).
The variable could be derived from:

• Platform.getSymbolicName(), if the current platform has one, E.g. TargetPanel.dir.windows_7
• Platform.getName() E.g., TargetPanel.dir.windows
• The parent platform, if there is no directory specified for getSymbolicName() or getName(). E.g. if current platform is FEDORA_LINUX and there is no TargetPanel.dir.fedora_linux, fall back to TargetPanel.dir.linux. Failing that, fall back to TargetPanel.dir.unix

If no variable is specified for the current platform, it would use TargetPanel.dir.

For example, change the resources to variables:

<res id="TargetPanel.dir.windows" src="@{izpack.dir.app}/installpath.windows.txt"/>
<res id="TargetPanel.dir.unix" src="@{izpack.dir.app}/installpath.unix.txt"/>

to

<variable name="TargetPanel.dir.windows" value="C:/MyApp"/>
<variable name="TargetPanel.dir.unix" value="/usr/local/myapp"/> 

This uses the following variable search order to determine the default directory to display:

1. TargetPanel.dir.<platform symbolic name> e.g. TargetPanel.dir.windows_7
2. TargetPanel.dir.<platform name> e.g. TargetPanel.dir.windows
3. TargetPanel.dir.<parent platform> e.g. given platform "FEDORA_LINUX" looks for TargetPanel.dir.linux, followed by TargetPanel.dir.unix
4. TargetPanel.dir
5. DEFAULT_INSTALL_PATH
6. SYSTEM_user_dir corresponds to the system property "user.dir"

Available platforms can be found in the class Platforms. The names are the lowercase versions of those defined.
Allowed names include:

• aix
• debian_linux
• fedora_linux
• freebsd
• hp_ux
• linux
• mac
• mac_osx
• mandrake_linux
• mandriva_linux
• os_2
• red_hat_linux
• sunos
• sunos_x86
• sunos_sparc
• suse_linux
• unix
• ubuntu_linux
• windows
• windows_7
• windows_xp
• windows_2003
• windows_vista

Differences from 4.3.5

In 4.3.5, resources were used rather than variables. Resources were searched for with the following names

• "TargetPanel.dir." + lower case version of System.getProperty("os.name"), with any spaces replace with underscores
• "TargetPanel.dir." + <platform> where platform is one of ("windows", "macosx", "unix")
• "TargetPanel.dir"

Upgrading customizations

Prepare to detect some internal refactorings when providing customizations: e.g. the class com.izforge.izpack.util.AbstractUIProcessHandler can now be found under com.izforge.izpack.api.handler.AbstractUIProcessHandler

Using the IzPack Maven Plugin

Release 5.0 of IzPack introduces a new implementation of the izpack-maven-plugin currently found at http://izpack.codehaus.org/izpack-maven-plugin/. In contrast to the documentation there, an explicit dependency to the izpack-standalone-compiler is no longer needed.

Please note that also the configuration parameters and their default values have drastically changed, so in case you want to port your current maven build script you should consult the mojo class from the source tree for the current paramaters until a new Maven Plugin site has been published.