After my previous post on creating EXE files in Windows it quickly became aware that first, the community is hungry for desktop integration tips, and second, installers are a topic people want to know about.

My original intention was to discuss the N ullsoft S criptable I nstall S ystem ; NSIS 2.0 provides a very modern and native-feeling installer for any open-source software package. However, Julien Ponge presented me with his project, IzPack . I may cover NSIS in a future release, but IzPack deserves attention in four areas where NSIS may not:

1. It is java-centric, which means it has considerations for Java-specific concerns


2. IzPack has Ant integration


3. Written in Java; not tied to Windows (A ready to run IzPack installer is an executable JAR file, but it can always be wrapped with JSmooth!!!)


4. I'm selfish, and want to learn a new installer

With that, I'll get started walking through some features of IzPack now; Julian, keep me honest - this is all new to me .

IzPack installers are based on an installation XML file conforming to the IzPack installation DTD (once you've installed IzPack, the DTD is available here: [installation folder]\src\dtd\installation.dtd ). For a perfect example, the IzPack installer is available here: [installation folder]\src\dist-files\IzPack-install.xml which is the actual installation XML file for IzPack itself - I HIGHLY recommend checking out the actual IzPack installation process as most of the advanced features are used in this installer. In addition a complete sample can be found in the [installation folder]\samples directory - more trivial, but easier to understand.

At any point if you want to try running an install, open a command prompt (or terminal) in the 'samples' directory mentioned above, and simply type '..\bin\compile install.xml' or if you are in the 'bin' folder, type: 'compile ..\sample\install.xml -b ..\sample'. Please note, on any OTHER platform, flip your backslashes to forward slashes.

Finally, PDF documentation ships with IzPack in the [installation folder]\doc\IzPack\pdf\ directory - for more detailed information, please look here.

These installation XML files always have a root 'installation' element, and each installation element consists of some high level concepts:

• info - The info tag contains the global application information (name, version, authors, url, etc.).
  
• variables - The variables tag allows you to declare values for variables that can be used in external resources and be replaced at the execution of the installer.


• guiprefs - The guiprefs tag is where you configure how the installer window will look (look and feel, size, is it resizable, etc.).


• locale - The locale tag represents all of the available languages for the installer, and is used to determine what languages will be available in the opening prompt.


• resources - The resources tag contains paths to resources used by various parts of the installer - the resources are linked by unique IDs to be used by certain panels (see below)


• panels - The panels tag defines the workflow of the installation wizard; this is where you define what panels the user will be confronted with through an installer (readme, license, installation folder, etc).


• packs - The packs of IzPack are the unique 'bundles' that need to be shipped with your application. Packs are tied to a particular panel (the PacksPanel) and represent the checkboxes that a user can choose to check/uncheck.


• native - Use this to declare the usage of a native library in the installer. Currently IzPack only ships with one, ShellLink.dll which I will explain later, but you can also write your own installer extensions and if they are native, you would declare those here as well.
• 
  
• jar - The JAR element allows you to bundle your custom extensions to IzPack alongside the IzPack code in the final installation JAR to your application (so you can have custom panels, and integration)

Info
The info tag is used throughout the installer for various verbiage, but is primarily used on the first page as seen here (from the sample):



Here is the corresponding XML:

<info>

  <appname>Sample Installation</appname>

  <authors>

    <author name="JPz" email="jpz at superman dot org"/>

    <author name="Hidden Man" email="hidden at hisdomain dot com"/>

  </authors>

  <url>http://www.anotherworld-inspace-website.net/</url>

</info>

Variables
Variables are a very intersting (and very powerful) construct that I, at first, didn't understand. Variables can be used in certain definitions such as target references for packs, but are also meant to be referred to in external resources so that, at installation time, they can be replaced with values that are relevant to the particular platform. There are a huge number of built-in variables, and you can also declare your own. The detailed list of variables available through IzPack is defined in the PDF, but suffice it to say it contains values such as $APP_NAME , $USER_HOME and $INSTALL_PATH .

Parsing can be done primarily on two items in an installation: resources and parsable elements in a pack. Typically, resources are items used inside panels (such as the license file for the LicensePanel, or the readme for the InfoPanel), and parsable elements are files that are included in a certain 'pack' (such as a startup script or a platform-specific property file).

There are four 'types' of parsing: plain, javaprop, xml, and shell script. Each parse type is designed to ensure that replacing the final value doesn't make the resulting file malformed (in the case of XML files, angle brackets would be properly accounted for, in the case of java property files, carriage returns are handled carefully, and in the case of shell scripts the searched for variable declaration is allowed to start with % as opposed to $ which is already used by shell scripts). For a detailed explanation of each parse type, please see the IzPack documentation.

Keep in mind that built-in variables can only be used inside the XML file itself and in the pack files (e.g. not in resources); because the text replacement on resources occurs at the construction of the installer, the built-in variables (which are unique to the execution of the installer) are only available as references in the XML file and in the post-user selection environment of installing packs. Please be sure to check the documentation for where built-in variables can be used - a good example is the path for the target of pack files.

User defined variables look like this:

    <variables>

    	<variable name="MY_VAR" value="MY_VAR value"/>

    </variables>

... and given a readme file with this definition (that is marked to be parsed - see the below sections):

A readme file ... $MY_VAR

The final result looks like this:



GUI Preferences
The guiprefs tag has appearance implications, and is thoroughly documented in the PDF. Essentially, with this tag you define the default size of the install window, if it is resizable, and what look and feel should be used.

IzPack comes shipped with the ability to use JGoodies Looks, Kunststoff, Metuoia, or any of the J2SE shipped L&F features (system, metal, Motif, etc).
What is most interesting is the way it can make platform decisions for you in the new release. Here is an example that sets up metuoia for Unix, and Looks for all Windows variants:

  <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>

Locale
The locale element allows you to bundle new langpack s with your installation. A langpack is essentially meant to control what language is used for pre-built verbiage on the various pages (titles, hello page, buttons, etc). Here is the locale selector:



You have access to the selected langpack , however, and can use it to properly externalize readme files, license files, etc so that they are unique per language selection. All that is required is extending the resource id with the ISO3 locale code for the language pack the resource belongs to. So, for instance, the readme for the InfoPanel (a text file) should have the id InfoPanel.info , so to refer to a special French version, you could type InfoPanel.info_fra - IzPack handles this localization automatically.

Resources
Resources, as I mentioned above, are links to files that are then used by certain panels. The linking occurs by using unique IDs. Here is an example of providing the readme file for the InfoPanel:

    <resources>

        <res id="InfoPanel.info" src="Readme.txt"/>

    </resources>    

In the variables section above I mentioned that resources could be 'parsed' by the installer to keep them externalized - here is how you define a resource to be parsed:

    <resources>

        <res id="InfoPanel.info" src="Readme.txt" parse="yes" type="plain"/>

    </resources>    

I also discussed above how to refer to a resource for a specific locale, here is the same example taking that into account:

    <resources>

        <res id="InfoPanel.info" src="Readme.txt" parse="yes" type="plain"/>

        <res id="InfoPanel.info_fra" src="Readme_fra.txt" parse="yes" type="plain"/>

    </resources>   

Panels

Ahh, now the good stuff. Panels are the visual organization of the installer. IzPack defines many panels that are already ready to be used, or you can supply your own using the extension abilities of IzPack. Here is a basic panel definition:

    <panels>

        <panel classname="HelloPanel"/>

        <panel classname="InfoPanel"/>

        <panel classname="LicencePanel"/>

        <panel classname="TargetPanel"/> 

        <panel classname="PacksPanel"/>

        <panel classname="InstallPanel"/>

        <panel classname="SimpleFinishPanel"/>

    </panels>

I won't bother going in to each panel in detail here (they are well defined in the IzPack documentation), but let me give you a quick overview. The HelloPanel is seen above in the first screenshot, and is essentially a summary of the application and the authors of that application. The InfoPanel (and the counterpart HtmlInfoPanel) show a quick read-through with no additional prompts - the former are expecting a text file, the latter expects a file containing HTML markup.



The LicensePanel (and HtmlLicencePanel) are the same, but also provide an accept/reject prompt.



The Target panel allows the user to select the installation folder.



The PacksPanel (and ImgPacksPanel) provide the users with the ability to select and deselect various parts of the application (such as documentation and source code).



The InstallPanel is a special panel that fires off the installation process.



Finally, the SimpleFinishPanel just supplies the 'way out' of the installation process after the installation has completed (the FinishPanel counterpart also offers further steps for automated installation).



Suffice it to say that each panel has different requirements that should be fulfilled through the installation file - see the documentation for what each one needs. One common panel (the ShortcutPanel) requires that you include the ShellLink.dll file as a native resource. The detailed steps required are covered in Section 4 of the IzPack documentation. Here is a screenshot of the ShortuctPanel (from the actual IzPack installation program):





Packs

Packs have been referred to umpteen times already in this tip, but they are essentially unique bundles of files that can be included/excluded by the user. Each pack can be marked as required or optional, and can be selected or unselected by default. Each pack and each file can be controlled based on which OS the user is on (using the OS child element as seen above on the guiprefs element). Finally, there are five ways to refer to files under a pack - the file tag (which refers to files and directories), the singlefile tag which allows for single file renaming, the fileset tag (which as far as I can tell only differs from the file tag by allowing Ant style syntax), the parsable tag (which represents any file that should have user and built-in variables substituted in post-installation), and executable tags (which are used for a.) executing a file at installation time and b.) marking a file as executable on Unix systems). Here is an example pack:

 	<pack name="Base" required="yes" preselected="yes">

            <description>The base files</description>

            <file src="Readme.txt" targetdir="$INSTALL_PATH"/>

            <file src="Licence.txt" targetdir="$INSTALL_PATH"/>

            <file src="script.bat" targetdir="$INSTALL_PATH"/>

            <parsable targetfile="$INSTALL_PATH/script.bat"/> <!-- The file will be parsed -->

	    <executable src="some_executable.exe" targetdir="$INSTALL_PATH"/>

        </pack>

And the rest...

The jar and native tags are probably best covered in a more advanced tip session; for now it is best to understand they are meant to include various libraries that extend the feature set of IzPack. As mentioned above, to get the shortcut panel to work, you have to have the native ShellLink.dll file included in your installation XML file.

Here is the supporting native line:

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

... but what about Ant?!
I promised that IzPack was capable of Ant integration, and since this tip is already running incredibly long, let me give you the quick tour. There are many options, but I personally like to use the standalone JAR file that doesn't require an IzPack installation as it makes it easy to integrate with an existing build process:

<!-- Allows us to use the IzPack Ant task -->

<taskdef name="izpack" classpath="${basedir}/lib/standalone-compiler.jar"

classname="com.izforge.izpack.ant.IzPackTask"/>

Once the task is declared (and the standalone-compiler jar is on your Ant classpath), here is how you can use it:

<izpack input="[installation XML file]" output="[output JAR file]" basedir="[base directory to execute from]"/>

Wintegrating IzPack - Smooth it out
Another step I (very) briefly glossed over was integrating JSmooth with your IzPack installer. As mentioned before, IzPack produces an executable JAR file for the installer - and as I also mentioned in the JSmooth entry , executable JAR files are a little unpolished for some users. It is a very short trip to make IzPack installer JAR files into SmoothJ EXE files. Simply go through the standard steps as detailed in the JSmooth tip using a GUI skeleton, putting the installer JAR in your classpath, and using com.izforge.izpack.installer.Installer as the main class to execute. Finally, set your installer JAR as an embedded JAR (as seen on the 'Application' tab). That should be all that is required!

Further Reading
IzPack is really quite powerful - in addition to the above features, IzPack supports web installation, automated installers, and a versatile extension API. I hope to cover some of these features in the future, but I highly recommend you read for yourself everything that is possible by downloading IzPack and the documentation.