IzPack – Open Source Java installer engine

Old post from Feb 11th, 2010

—————

Recently we faced the need for an installer for a Java tool. Nothing too refined, just select the path, select the packages to install and create some shortcuts.

First I googled for the obvious query and found many alternatives, some free and some commercial, and then we do a preliminary testing to some of them (OpenInstaller, Advanced Installer, install4j) and finally we knew of IzPack.

In this post I would to highlight some of the characteristics of IzPack and why we decided to use it, and then show you how to make a simple yet powerful installer.

Highlights

These are the things that I highlight of IzPack:

– Open Source, Apache Software License – do what you want, free to use, modify, distribute (of course always in the terms of the ASL).

– Cross-platform (one installer to rull them all).

– Decent, although limited, support for OS dependant features (i.e. Windows shortcuts on Stat Menu or read/write actions over Windows Registry).

– Easy to install (of course) and to start with. You can have your installer ready in 5 minutes.

– API available to extend the installer features.

– Automation automation automation. It can be easily integrated with Ant.

– And many, many more.

Creating an installer

Creating an installer is easy – you only need to write a simple XML file where you define the packages (files and modules, mandatory and optional) and the panels (both dialog steps and actions to do).

As IzPack comes with a lot of panels available, most probably all your installer needs will be covered by them, although you can always write you own panels or extend existing ones.

XML: Basic info

When we create the XML installer definition we start by providing the basic information about our application:

<?xml version="1.0" encoding="iso-8859-1" standalone="yes" ?>
<installation version="1.0">
    <info>
        <appname>My Tool</appname>
        <appversion>1.0</appversion>
        <appsubpath>My Tool Folder</appsubpath>
        <javaversion>1.6</javaversion>
    </info>

Explanation is pretty straightforward: the application name and version, default folder for the installation (i.e. in Windows would be C:\Program Files\My Tool Folder) and required Java version.

XML: Definition of installer packages

Then we need to define the installer packages. Each package will be a collection of files that can be independently selected by the user. Some of the packages will be mandatory and some optional.

Our example will have three packages: tool executable, documentation and examples. For each package we will define the files included (all paths are defined relative to the definition file actual location and a folder can be selected) and where to install them:

    <packs>
        <pack name="Tool executable" required="yes">
            <description>The tool executable file</description>
            <file src="readme.txt" targetdir="$INSTALL_PATH"/>
            <file src="../../deliverables/mytool-1.0.jar" targetdir="$INSTALL_PATH"/>
        </pack>
        <pack name="Tool documentation" required="no">
            <description>The tool documentation. It includes the installation guide and the user's manual</description>
            <file src="../manual" targetdir="$INSTALL_PATH"/>
        </pack>
        <pack name="Examples" required="no">
            <description>Tool examples</description>
            <file src="../examples" targetdir="$INSTALL_PATH"/>
        </pack>
    </packs>

XML: Defining panels (installer steps)

The behavior of the installer itself is defined through a consecutive list of panels. Each panel is both a presentation and actions. For example, a license panel will request for acknowledgement of your license terms while an install panel will show you the progress of the installation while copying files to their target folder.

For our example we will use 6 steps:

    <panels>
        <panel classname="HTMLHelloPanel"/>
        <panel classname="HTMLLicencePanel"/>
        <panel classname="TargetPanel"/>
        <panel classname="PacksPanel"/>
        <panel classname="InstallPanel"/>
        <panel classname="SimpleFinishPanel"/>
    </panels>

Some of the panels need some external resources. For example the hello panel needs a file to present to the user and the license panel needs the license file, of course. These resources are defined using predefined keys in the XML file:

    <resources>
        <res id="company-logo.jpg" src="company-logo.jpg"/>
        <res id="HTMLHelloPanel.info" src="panel-hello.html"/>
        <res id="HTMLLicencePanel.licence" src="panel-license.html"/>
    </resources>
</installation>

The file company-logo.jpg is included because it is referenced in the provided HTML files.

Running the installer creation

Now that we have our installer definition created, we need to actually create the installer file. It can be created using a command line tool, but in this post I will go directly for the Ant task. This Ant target will do the work:

    <target name="installer" depends="deliverables">
        <taskdef name="IzPack"
                 classpath="${tools.izpack.classpath}"
                 classname="com.izforge.izpack.ant.IzPackTask"/>
        <mkdir dir="${project.deliverables}"/>
        <IzPack basedir="${project.installer.home}"
                input="${project.installer.definition}"
                output="${project.deliverables}/${project.artifact}-${project.version}-installer.jar"
                installerType="standard"
                IzPackDir="${tools.izpack.home}"/>
    </target>

Refining the installer

Now that we know the basics, let me introduce some advanced features of IzPack that will help you to give your installer a more professional look.

Adding images to the panels

You can easily add an image to the left of each panel. To do that we only need to add some resources linking to the image for a given panel. The resource keys are always the same with the panel index starting at 0:

        <res id="Installer.image.0" src="panel-hello.png" />
        <res id="Installer.image.1" src="panel-license.png" />
        <res id="Installer.image.2" src="panel-target.png" />
        <res id="Installer.image.3" src="panel-packs.png" />
        <res id="Installer.image.4" src="panel-install.png" />
        <res id="Installer.image.5" src="panel-finish.png" />

Using Look & Feels

Another easy to configure effect is to select Look & Feels for your installer. IzPack documentation will let you know what are supported, but let’s add Substance to our installer but only for Windows (yes, you can also customize some behaviors for a given OS):

    <guiprefs width="640" height="480" resizable="no">
        <laf name="substance">
            <os family="windows"/>
            <param name="variant" value="creme"/>
        </laf>
    </guiprefs>

Creating Shortcuts

The last feature we are going to introduce is about creating shortcuts in the Windows Start Menu. To do that we need to modify our installer definition file in three sections:

Adding the shortcut selection/creation panel. In the panels section we add a new panel just before the finish panel:

<panel classname="ShortcutPanel"/>

Adding the DLL that provides support for creating the shortcuts. This library is included in a native element:

<native type="izpack" name="ShellLink.dll"/>

Adding a shortcut specification XML file and panel image. In the resource section we add something like:

    <res id="Installer.image.5" src="panel-shortcut.png" />
    <res id="shortcutSpec.xml" src="shortcut-definition.xml"/>

The shortcut specification XML file is easy to understand without further explanations:

<?xml version="1.0" encoding="iso-8859-1" standalone="yes" ?>
<shortcuts>
    <skipIfNotSupported />
    <programGroup defaultName="My Tool" location="startMenu" />
    <shortcut name="Uninstall My Tool"
              target="$INSTALL_PATH\Uninstaller\uninstaller.jar"
              commandLine=""
              workingDirectory="$INSTALL_PATH\Uninstaller"
              description="My Tool uninstaller"
              initialState="normal"
              programGroup="yes"
              desktop="no"
              applications="no"
              startMenu="no"
              startup="no">
        <createForPack name="Tool executable" />
    </shortcut>
    <shortcut name="Readme"
              target="$INSTALL_PATH\readme.txt"
              commandLine=""
              workingDirectory="$INSTALL_PATH"
              description="My Tool readme"
              initialState="normal"
              programGroup="yes"
              desktop="no"
              applications="no"
              startMenu="no"
              startup="no">
        <createForPack name="Tool executable" />
    </shortcut>
    <shortcut name="User's Manual"
              target="$INSTALL_PATH\manual\User's manual.docx"
              commandLine=""
              workingDirectory="$INSTALL_PATH\manual"
              description="My Tool User's manual"
              initialState="normal"
              programGroup="yes"
              desktop="no"
              applications="no"
              startMenu="no"
              startup="no">
        <createForPack name="Tool documentation" />
    </shortcut>
    ...
</shortcuts>

And that’s all! You have your installer ready to be created and full of neat features. Moreover, it is integrated with Ant so you can launch it as part of your release process.

Happy installers!

Author: deors

senior technology architect in accenture, with a passion for technology related stuff, celtic music and the best sci-fi, among other thousand things!

1 thought on “IzPack – Open Source Java installer engine”

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s