Info

<info>
    <appname>${project.name}</appname>
    <appversion>${project.version}</appversion>
    <appsubpath>Patrodyne/${project.artifactId}/${project.version}</appsubpath>
    <authors>
        <author name="Patrodyne" email="rick.osullivan@patrodyne.org"/>
    </authors>
    <url>${project.url}</url>
    <javaversion>1.6</javaversion>
    <requiresjdk>no</requiresjdk>
</info>

For the application name, we use the POM's project name. The name of our poject is Hello. It is an informal name that we use when speaking about our project in conversation. In contrast, the artifact name is more formal: patrodyne-site-hello.

The sub-path determines where our project will be installed, relative to the installation path. In other words, after the end-user selects the installation path, the sub-path is created in it. Our sub-path has three parts:

1. Patrodyne - our group name ensures that this project and all of our other fine projects are grouped together.
2. $project.artifactId - the artifact id, from the POM, provides a well-defined name for this project.
3. $project.version - a place for each version and each version in its own place!

Variables

<variables>
    <variable name="CFG_DIR" value="${cfgdir}"/>
    <variable name="EXT_DIR" value="${extdir}"/>
    <variable name="ICN_DIR" value="${icndir}"/>
    <variable name="LIB_DIR" value="${libdir}"/>
    <variable name="LOG_DIR" value="${logdir}"/>
    <variable name="FINAL_NAME" value="${project.build.finalName}"/>
</variables>

We define some IzPack variables here so we can use them in the Shortcut files.

Dynamic Variables

<dynamicvariables>
    <variable 
        name="JVM_CFG_LOG" 
        value="logback.configurationFile=${cfgdir}/logback.xml" 
        condition="LogbackSelected"
    />
    <variable
        name="JVM_CFG_LOG"
        value="log4j.configuration=file:${cfgdir}/log4j.xml"
        condition="Log4jSelected"
    />
    <variable
        name="JVM_CFG_LOG"
        value="java.util.logging.config.file=${cfgdir}/logging.properties"
        condition="JULSelected"
    />
</dynamicvariables>

Dynamic variables are cool. The value is determined based on conditions determined by the end-user's choices. For example, the Hello installation gives the user an option to choose one of three popular logging frameworks: logback, log4j or jul. The value of JVM_CFG_LOG will correspond to the selected logging framework.

Hint: You'll see JVM_CFG_LOG later when we declare the command line options for launching the Hello application.

Conditions

<conditions>
    <condition type="PackSelection" id="LogbackSelected">
        <packid>Logback</packid>
    </condition>
    <condition type="PackSelection" id="Log4jSelected">
        <packid>Log4j</packid>
    </condition>
    <condition type="PackSelection" id="JULSelected">
        <packid>JUL</packid>
    </condition>
    
    <condition type="not" id="LogbackIsSelectable">
        <condition type="or" id="LogbackIsNotSelectable">
            <condition type="ref" refid="Log4jSelected" />
            <condition type="ref" refid="JULSelected" />
        </condition>
    </condition>
    <condition type="not" id="Log4jIsSelectable">
        <condition type="or" id="Log4jIsNotSelectable">
            <condition type="ref" refid="LogbackSelected" />
            <condition type="ref" refid="JULSelected" />
        </condition>
    </condition>
    <condition type="not" id="JULIsSelectable">
        <condition type="or" id="JULIsNotSelectable">
            <condition type="ref" refid="LogbackSelected" />
            <condition type="ref" refid="Log4jSelected" />
        </condition>
    </condition>
</conditions>

In this installation, we use conditions to determine which one of three logging frameworks is selectable:

• LogbackIsSelectable - as the default, it will be preselected.
• Log4jIsSelectable - false until no other logger is selected.
• JULIsSelectable - false until no other logger is selected.

  We use this information to implement a set of radio buttons. First we set a condition to detect which pack is selected:

• LogbackSelected - true, when the Logback option is checkmarked.
• Log4jSelected - true, when the Log4j option is checkmarked.
• JULSelected - true, when the Java Utility Logger option is checkmarked.

  Next, we set a *IsNotSelectable condition when any of the other options is selected.

  Finally, we negate *IsNotSelectable to determine *IsSelectable.

  We'll use these conditions later in the Packs section.

GUI Preferences

<guiprefs width="800" height="500" resizable="no" />

In this element, we set the dimensions of the IzPack installer window to a nice rectangles and disable resizing, to keep things simple.

Nice rectangles have sides corresponding to consecutive Fibonacci numbers: 1, 1, 2, 3, 5, 8, 13, etc. In this case, we choose 5 and 8 (times 100).

Locale

<locale>
    <langpack iso3="eng" />
</locale>

Until we learn to translate "Hello" into other languages, this installation will only support English.

Resources

<resources>
    <res id="Installer.image"       src="InstallerLeft.png" />
    <res id="Unix_shortcutSpec.xml" src="linux_shortcuts.xml" />
    <res id="shortcutSpec.xml"      src="winos_shortcuts.xml" />
</resources>

To display a picture on the left side of the IzPack installer window, we define a resource with a magic id, Installer.image. Supported image formats are GIF, JPEG and PNG.

Another magic id, Unix_shortcutSpec.xml defines a resource for Linux desktop shortcuts.

And another magic id, shortcutSpec.xml defines a resource for Windows desktop shortcuts.

Panels

<panels>
    <panel classname="HelloPanel"/>
    <panel classname="TargetPanel"/>       
    <panel classname="TreePacksPanel"/>
    <panel classname="SummaryPanel"/>
    <panel classname="InstallPanel"/>           
    <panel classname="ShortcutPanel"/>
    <panel classname="FinishPanel"/>
</panels>

HelloPanel - This panel welcomes the user by displaying the project name, the version, the URL as well as the authors.

TargetPanel - This panel allows the user to select the installation path.

TreePacksPanel - Using a tree-like structure, this allows the user to select the packs s/he wants to install.

SummaryPanel - This panel gives a summary of all shown panels.

InstallPanel - This panel launches the installation process!

ShortcutPanel - This panel is used to create desktop shortcuts.

FinishPanel - A ending panel, able to write automated installer information.

For a complete list of available panels, see IzPack Panels.

Packs

<packs>
    <pack name="Core" required="yes">
        <description>Core installation files</description>
        <file src="README.html" targetdir="${INSTALL_PATH}"/>
        <file src="../${FINAL_NAME}.jar" targetdir="${INSTALL_PATH}"/>
        <fileset dir="${libdir}" targetdir="${INSTALL_PATH}/${libdir}">
            <include name="**"/>
        </fileset>
        <!-- Unix -->
        ...
        <!-- Windows -->
        ...
    </pack>
    <pack name="Logger" required="yes">
        ...
    </pack>
    <pack name="Logback" parent="Logger" required="no" 
        preselected="yes" condition="LogbackIsSelectable">
        ...
    </pack>
    <pack name="Log4j" parent="Logger" required="no" 
        preselected="no" condition="Log4jIsSelectable">
        ...
    </pack>
    <pack name="JUL" parent="Logger" required="no" 
        preselected="no" condition="JULIsSelectable">
        ...
    </pack>
</packs>

Packs contain our application and optional features. IzPack provides Ant-like actions to gather files, artifacts, libraries and other resources to create an installer package. The Hello installer defines five packs:

1. Core - The Hello application is comprised of a jar and additional libraries. We add a README.html to explain our cool app, too. This pack includes conditional actions depending of the target operating system.
2. Logger - A wrapper to group the logging options.
3. Logback - A pack containing the Logback libraries and settings file. This is preselected to be the default option.
4. Log4j - A pack containing the Log4j libraries and settings file.
5. JUL - A pack containing the Java Utility Logger libraries and settings file.

Note: We use the LogbackIsSelectable, Log4jIsSelectable, and JULIsSelectable conditions defined earlier to dynamically maintain the checkboxes as a set of radio buttons.

Native

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

<native type="izpack" name="ShellLink_x64.dll">
    <os family="windows"/>
</native>

These native libraries are used to create desktop shortcuts in Windows.

Linux Shortcuts

In Linux, shortcuts can be added to the desktop and to the application menu.

<shortcuts>
    <skipIfNotSupported/>
    <defaultCurrentUser/>
    <shortcut 
        ... Specification Attributes ...
        ... Control Attributes ...
        ... Linux Attributes ...
    >
        <createForPack name="Core"/>
    </shortcut>
</shortcuts>

name="${APP_NAME}"
description="Launch ${APP_NAME}"
target="java"
commandLine="-D${JVM_CFG_LOG} -Djava.ext.dirs=${EXT_DIR} 
    -jar "${INSTALL_PATH}/${FINAL_NAME}.jar""
workingDirectory="${INSTALL_PATH}"
iconFile="${INSTALL_PATH}/${ICN_DIR}/${APP_NAME}.png"
initialState="normal"

desktop="yes"
programGroup="yes"
applications="no"
startMenu="no"
startup="no"

categories="Application;Office;"
type="Application"
terminal="false"
encoding="UTF-8"

Windows Shortcuts

In Windows, shortcuts can be added to the desktop and grouped in the application menu.

<shortcuts>
    <skipIfNotSupported/>
    <programGroup defaultName="Patrodyne\${APP_NAME}"
        location="applications"/>
    <defaultCurrentUser/>
    <shortcut 
        ... Hello Launcher ...
    >
        <createForPack name="Core"/>
    </shortcut>

    <shortcut
        ... Uninstaller ...
    >
        <createForPack name="Core" />
    </shortcut>
</shortcuts>

name="${APP_NAME}"
description="Launch ${APP_NAME}"
target="java"
commandLine="-D${JVM_CFG_LOG} -Djava.ext.dirs=${EXT_DIR} 
    -jar "${INSTALL_PATH}/${FINAL_NAME}.jar""
workingDirectory="${INSTALL_PATH}"
iconFile="${INSTALL_PATH}/${ICN_DIR}/${APP_NAME}.ico"
iconIndex="0"
initialState="noShow"

desktop="yes"
programGroup="yes"
applications="no"
startMenu="no"
startup="no"

name="Uninstall ${APP_NAME}"
description="Launch uninstaller"
target="java"
commandLine="-jar 
    "${INSTALL_PATH}/Uninstaller/uninstaller.jar""
workingDirectory="${INSTALL_PATH}"
iconFile="${INSTALL_PATH}/${ICN_DIR}/uninstaller.ico"
iconIndex="0"
initialState="noShow"

desktop="no"
programGroup="yes"
applications="no"
startMenu="no"
startup="no"

Native Libraries

• native/izpack/ShellLink.dll - The native library required for 32 bit Windows operating systems.
• native/izpack/ShellLink_x64.dllcl - The native library required for 64 bit Windows operating systems.

Launch Scripts

• Hello - a shell script for Linux to launch the Hello application.
• Hello.cmd - a command script for Windows to launch the Hello application.
• Uninstall - a shell script for Linux to reverse the Hello installation.

#!/bin/sh
java -D%{JVM_CFG_LOG} -Djava.ext.dirs=%{EXT_DIR} \
    -jar "%{INSTALL_PATH}/%{FINAL_NAME}.jar"
# vi:set tabstop=4 hardtabs=4 shiftwidth=4:

@echo off
@start "%{APP_NAME}" /D"%{INSTALL_PATH}" javaw -D%{JVM_CFG_LOG} ^
    -Djava.ext.dirs=%{EXT_DIR} -jar "%{INSTALL_PATH}/%{FINAL_NAME}.jar"
@rem vi:set tabstop=4 hardtabs=4 shiftwidth=4:

#!/bin/sh
java -jar "%{INSTALL_PATH}/Uninstaller/uninstaller.jar"
# vi:set tabstop=4 hardtabs=4 shiftwidth=4: