1. Introduction to InstallBuilder

InstallBuilder is a modern, fully-featured, cross-platform installation tool. It is designed to simplify the deployment of both desktop and server software, helping you reduce support costs related to installation and provide a positive end-user experience.

This document provides an overview of InstallBuilder capabilities and architecture, as well as in-depth coverage of common installation topics. A companion appendix provides detailed information on each one of the XML configuration options.

1.1. What Sets InstallBuilder Apart

To fully understand the architecture and capabilities of InstallBuilder, it is useful to consider the previous generation of cross-platform installers. These were built using the Java programming language. Java is a fine choice for multiple scenarios and indeed over half of your users use InstallBuilder to package Java-based applications. However, it has a set of major drawbacks when the goal is to create setup programs. For example, it requires a Java runtime environment to be present in the machine, which increases the chances of something going wrong if one is not present or the one present is not a suitable version. Alternatively, if the user decides to bundle a JRE with the installer in order to avoid these potential problems, it will increase significantly the footprint of the installation. Java-based installers also require a self-extraction step, in which the files are first unpacked to disk before installation can begin. For large installers, this can be a time-consuming step and another source of installation-related issues if the end-user runs out of disk space during this process. Finally, and although alternative toolkits like SWT finally emerged, Java GUI development has traditionally suffered from poor performance and lack of a truly native look-and-feel. End-users react much more favorably to setup applications that are responsive and provide a familiar native interface, even if the functionality is identical.

The above is not intended as a rant against Java-based installers, rather as an illustration of the challenges that a cross platform installation tool faces. So, how does InstallBuilder address these issues? Installers generated with InstallBuilder are native applications that do not require any runtime to be present in the system to run. This means that the overhead the installer introduces is very small, typically around 2 to 3 Mb, versus the 15 Mb to 20 Mb that a bundled JRE requires. In addition to this, the installers do not perform a self-extraction step, meaning that they start up instantaneously, whereas some Java-based installers can take up to minutes to initialize for large installers. Installers created with InstallBuilder use the underlying system libraries for displaying their GUI interfaces, so users get a native look and feel for each platform the installers run on, such as Windows and Mac OS X. On Linux and other Unix platforms, there is not a single standard look and feel. In those cases, InstallBuilder provides a choice between the most common toolkits, Qt and GTK, as well as a built-in fallback mode.

1.2. What’s New In InstallBuilder 17

InstallBuilder 17 provides a host of new features, including:

  • Multi-core installer creation: InstallBuilder can take advantage of multiple cores/threads in LZMA and LZMA Ultra compression

  • Multi-core decompression: Significantly faster file unpacking by using up to 8 cores/threads for LZMA and LZMA Ultra compressions

  • Installation time performance improvements: Multiple changes in file management provide up to 20% speed increase for large installers

  • Support for cross-platform installer signing: Signing installers for both Windows and Mac OS X can now be done from any platform

1.3. Features

InstallBuilder is a fully-featured tool capable of addressing multiple installation scenarios, from desktop games to engineering simulation tools to enterprise-level server software.

  • Multiplatform Support: BitRock installers are native binaries that can run on Windows, OS X and Linux and most other flavors of Unix, including FreeBSD, OpenBSD, AIX, OS/400, HP-UX and IRIX.

  • Desktop Integration: BitRock installers provide native look and feel and desktop integration for Windows, OS X and Linux (KDE and Gnome).

  • Optimized: BitRock installers are optimized in size and speed and do not require a self-extraction step, reducing download, startup and installation time. Built-in LZMA support provides great compression ratios.

  • No External Dependencies: BitRock installers are single-file, self-contained native executables with no external dependencies and minimal overhead. Unlike competing products, all BitRock installers are truly native code and do not require bundling a Java Runtime Environment.

  • Ease of Use: BitRock installers provide an intuitive and easy to use interface on all platforms, even for end users without previous Linux experience.

  • Ease of Development: InstallBuilder includes an easy to learn, easy to use GUI environment. Design, build and test installers with the click of a button.

  • Time Saving Functionality: For advanced users, a friendly XML project format supports source control integration, collaborative development and customizing projects both by hand and using external scripts. A command line interface allows you to automate and integrate the building process. QuickBuild functionality allows you to update installers in a few seconds, without having to repack the entire application.

  • Built-in Actions: InstallBuilder provides convenient built-in actions for commonly required installation functionality such as auto-detecting a Java(tm) Runtime, changing file permissions and ownership, substituting text in a file, adding environment variables, adding directories to the path, creating symbolic links, changing the Windows registry, launching external scripts and so on.

  • Crossplatform Build Support: The installer builder tool can run on Windows, Mac OS X, Linux and all other supported Unix platforms and generate installers for all target platforms from a single project file. Create all your installers from a single build environment!

  • Customization: BitRock installers can be customized in a variety of ways, both graphically and in functionality. It is possible to ask for multiple parameters, like username and passwords, in the same installer screen. This functionality helps to simplify the installation process for end-users.

  • Multiple Installation Modes: BitRock installers provide: several GUI modes with native look-and-feel, for installation in a variety of desktop environments, a text-based installation mode, for console-based and remote installations, and a silent/unattended install mode which can be used for integration in shell scripts for automated deployment.

  • Support for Qt® GUI Frontend: The InstallBuilder for Qt family of products provides a GUI installation mode using the Qt crossplatform toolkit, enhancing the end-user experience

  • Rollback Functionality: BitRock installers by default perform a backup of all the files overwritten during installation, so if there is an error, the system can be recovered to its previous state.

  • Native Package Integration: BitRock installers can register your software with the RPM and DEB package databases, combining the ease of use of an installer wizard with the underlying native package management system.

  • RPM and DEB generation: In addition to creating native executables that can register with the RPM subsystem, BitRock InstallBuilder can generate self-contained RPM and Debian packages that can be installed using the native package management tools.

  • Uninstall Functionality: An uninstall program is created as part of every installation, allowing users to easily uninstall the software. Like the installers, it can be run in a variety of modes. On Windows, uninstall functionality can also be accessed from the Add/Remove Programs entry in the Control Panel.

  • Startup Failure Detection: BitRock installers will automatically and gracefully detect the best installation mode available. Users also have the option to manually select a mode.

  • Language and Platform Independent: BitRock installers can install applications written in any language, including: Java, PHP, Perl, Python, Ruby, C/C++ and .NET/Mono.

  • Multiple Language Support: BitRock installers support a variety of installation languages, including English, German, Japanese, Spanish, Italian, French, Portuguese, Traditional Chinese, Dutch, Polish, Valencian, Catalan, Estonian, Slovenian, Romanian, Hungarian, Russian and Welsh. Installers in Qt mode support right to left languages such as Arabic. The full list can be found in the Languages section. You can specify a default language or let the user decide. Please contact us if you require additional language support.

1.4. Supported Platforms

InstallBuilder provides support for all common (and not so common!) operating systems out there. If you want to know if InstallBuilder supports a particular platform, please contact us - chances are that it does. InstallBuilder-generated installers will run on:

  • Windows XP, 2003, 2008, Vista, Windows 7, Windows 8, Windows 8.1, Windows 10

  • Mac OS X (PPC & Intel) 10.2 and later

  • Linux (Intel x86/x64, Itanium, s390 and PPC) All distributions and version including Ubuntu, RHEL, SLES and Meego.

  • Solaris (Intel and Sparc) 8, 9, 10, 11

  • HP-UX (PA-RISC, Itanium)

  • FreeBSD 4.x and later

  • OpenBSD 3.x and later

  • AIX 4.3 and later

  • OS/400

  • IRIX 6.5

1.5. Requirements

The command line builder tool will run on any of the supported platforms, allowing you to generate installers for any of the other supported platforms for the InstallBuilder edition you are using. For example, if you are running InstallBuilder Professional on Linux, you will be able to generate installers for Windows, Linux and OS X. This is particularly useful for situations in which you need to build the installers as part of a continuous integration/daily build scenario.

The GUI installer design tool helps you to visually create installation projects. The GUI design tool runs on Linux x86/x64, OS X and Windows with a minimum of 800x600 screen resolution. Note that you can always edit XML projects directly or even alternate between using the GUI and editing the XML project file as needed.

1.6. Editions

InstallBuilder is distributed in multiple editions, with the primary differentiation being the supported platforms that you can create installers for. The link below provides a detailed comparison of the available editions:

1.7. The GUI

InstallBuilder allows projects to be created and edited with an easy to use graphical editor tool. Adding new actions to the installation logic or files to pack is as easy as double-clicking the appropriate element and navigating through the organized dialogs. The GUI is only available on Linux x86/x64, Windows and OS X.

Once the GUI is launched, you will be welcomed with the screen displayed in Figure 1. From this main screen you can use the top menu entries to create a new project or open an existing one, launch the build process, check for an updated version of InstallBuilder, register your copy of the tool and open the documentation.

GUI welcome screen
Figure 1: GUI welcome screen

Alternatively, you can use the shortcut buttons to perform the most common actions:

GUI Toolbar
Figure 2: GUI Toolbar

Some of the toolbar buttons will be disabled depending on whether a project is loaded or not. Figure 2 also shows the notification you will see when a new version is available. If the builder has access to the Internet and is configured to check for updates, it will automatically report these notifications for each new version released. The process can also be manually triggered using the Update menu. Clicking on the blue arrow will open the downloads page in a web browser.

Note
Disabling checking for new versions of InstallBuilder

If you do not want the installer to check for updates on startup, you can edit the update.dat file located in the same directory as the builder and set check_for_updates=0

After loading or creating a new project, a new UI will appear, divided in different sections:

  • Product Details: This section presents a quick overview of the basic configuration settings for the project (Figure 3).

New project
Figure 3: New project

The main project settings Vendor name, Product Name, Product Filename and Version Number are defined once and used multiple times when displaying information during the installation process; in the Add/Remove Program menu, the installer filename and so on. It is always possible to override these default values when necessary.

Enabling Save Relative Paths will convert all of the absolute paths related to the build process (files to pack, images, readme…) to relative paths, using the location of the project file as the reference. This setting will be applied automatically and transparently when saving and loading the project so it will not be noticeable while working in the GUI. This particular setting is especially useful when sharing a project between developers or operating systems, as the location of the resources is not hardcoded, as explained in theWhen is it necessary to use the Save Relative Paths option? note. If the paths were already manually configured as relative, they will be preserved and resolved when building, also using the location of the project to absolutize them.

The License File setting specifies a license file that will be displayed during installation. The end user will need to accept this license text before continuing with the installation process. If you do not provide a license file, the license acceptance screen will not be displayed to the end user.

You can also provide an alternate HTML License File. This HTML-formatted license will be used if the front-end supports it (currently only the case for the Qt front-end). Otherwise the default license text specified in the License File setting will be displayed.

You can also display multiple licenses in different languages or display them conditionally, as described in the Displaying a localized license and readme section.

  • Files: This section allows managing all of the resources included in the project such as files to pack, and shortcuts to create. These resources are organized in components, designed to group common functionalities, and files, which are divided into folders (Figure 4).

Files screen
Figure 4: Files screen

Shortcuts may also be added in this section.

  • Advanced: The same way the Files section specifies the resources that will be packaged, the Advanced section deals with the configuration of the actions and rules associated with them (Figure 5). It also allows you to describe the inputs that the installer will accept and the pages to display at runtime to interact with the end user. The nodes in the tree can also be reordered, moved (you can drag and drop them) and copied (press shift while performing a drag and drop operation). In addition, the root node, representing the project, allows configuring the global project properties.

Advanced screen
Figure 5: Advanced screen
  • Customization: The Customization section (Figure 6) provides a convenient way to configure the most common project properties. It is a subset of the properties available in the Advanced tab.

Customization screen
Figure 6: Customization screen
  • Packaging: This section allows you to specify the target platform for which you want to build the installer. It provides a log of the build process, including a progress bar and displaying build-errors in red when they occur (Figure 7).

Packaging screen
Figure 7: Packaging screen
Note

The GUI is only available on Linux, Linux x64, Windows and OS X. The command line builder is available on all platforms.

1.8. The XML

InstallBuilder project files are stored in XML format. This enables and simplifies source control integration, collaborative development and customizing projects both by hand and using external scripts.

Our XML is human friendly, and although the project can be fully managed through the GUI, advanced users can also directly edit the XML project using the built-in XML editor or their preferred text editor or IDE. The following is a complete example of what an InstallBuilder project looks like. This particular project does not package any files.

<project>
    <shortName>sample</shortName>
    <fullName>Sample Project</fullName>
    <version>1.0</version>
    <enableRollback>1</enableRollback>
    <enableTimestamp>1</enableTimestamp>
    <componentList>
        <component>
            <name>default</name>
            <description>Default Component</description>
            <canBeEdited>1</canBeEdited>
            <selected>1</selected>
            <show>1</show>
            <folderList>
                <folder>
                    <description>Program Files</description>
                    <destination>${installdir}</destination>
                    <name>programfiles</name>
                    <platforms>all</platforms>
                    <shortcutList>
                        <shortcut>
                            <comment>Uninstall</comment>
                            <exec>${installdir}/${project.uninstallerName}</exec>
                            <icon></icon>
                            <name>Uninstall ${project.fullName}</name>
                            <path>${installdir}</path>
                            <platforms>all</platforms>
                            <runAsAdmin>0</runAsAdmin>
                            <runInTerminal>0</runInTerminal>
                            <windowsExec>${installdir}/${project.uninstallerName}.exe</windowsExec>
                            <windowsExecArgs></windowsExecArgs>
                            <windowsIcon></windowsIcon>
                            <windowsPath>${installdir}</windowsPath>
                        </shortcut>
                    </shortcutList>
                </folder>
            </folderList>
            <startMenuShortcutList>
                <startMenuShortcut>
                    <comment>Uninstall ${project.fullName}</comment>
                    <name>Uninstall ${project.fullName}</name>
                    <runAsAdmin>0</runAsAdmin>
                    <runInTerminal>0</runInTerminal>
                    <windowsExec>${installdir}/${project.uninstallerName}.exe</windowsExec>
                    <windowsExecArgs></windowsExecArgs>
                    <windowsIcon></windowsIcon>
                    <windowsPath>${installdir}/</windowsPath>
                </startMenuShortcut>
            </startMenuShortcutList>
        </component>
    </componentList>
    <parameterList>
        <directoryParameter>
            <name>installdir</name>
            <description>Installer.Parameter.installdir.description</description>
            <explanation>Installer.Parameter.installdir.explanation</explanation>
            <value></value>
            <default>${platform_install_prefix}/${project.shortName}-${project.version}</default>
            <allowEmptyValue>0</allowEmptyValue>
            <ask>yes</ask>
            <cliOptionName>prefix</cliOptionName>
            <mustBeWritable>yes</mustBeWritable>
            <mustExist>0</mustExist>
            <width>30</width>
        </directoryParameter>
    </parameterList>
</project>

If your XML editor supports it, you can use a RELAX NG schema for validation. It is included as InstallBuilder.rng, inside the docs directory of your installation.

Note

For Atom you can use the linter-autocomplete-jing package. This package allows autocompletion of XML documents against RELAX NG.

Xml autocompletion in Atom
Figure 1. Xml autocompletion in Atom

Most of the examples presented in this guide are provided as XML snippets, but you can achieve identical functionality using the GUI

Note

The XML specification requires that specific characters are escaped. This is done automatically if entering the values through the GUI but if you are directly editing the XML code you must take it into account. The table below summarizes the most common characters and their escape sequence:

Table 1. Common XML escape sequences
Character XML escaped sequence

&

&amp;

<

&lt;

>

&gt;

'

&apos;

"

&quot;

\n

&#xA;

Some of the values only need to be escaped if provided as part of an attribute value, not an element.

The snippet below adds some lines to an existing file, separating them using escaped line breaks (\n):

 <addTextToFile>
    <file>${installdir}/foo.txt</file>
    <text>line1&#xA;line2&#xA;line3</text>
 </addTextToFile>

It is also possible to escape a full block of code using the <![CDATA[ .. ]]> notation

  <writeFile>
    <path>${installdir}/${project.vendor}-x-my-mime.xml</path>
    <text><![CDATA[
<?xml version="1.0"?>
<mime-info xmlns='http://www.freedesktop.org/standards/shared-mime-info'>
  <mime-type type="application/x-my-mime">
    <comment>My new file type</comment>
    <glob pattern="*.mymime"/>
  </mime-type>
</mime-info>
 ]]></text>
  </writeFile>

The text inside the <![CDATA[ .. ]]> block will be interpreted literally, so you do not need to escape any character.

2. Installation and Getting Started

2.1. Installation

This section describes how to get up and running with InstallBuilder on a variety of platforms

2.1.1. Installing on Windows

You can download BitRock InstallBuilder from the BitRock website: installbuilder.bitrock.com. To start the installation process, double-click on the downloaded file.

You will be greeted by the Welcome screen shown in Figure 8:

Windows Welcome Screen
Figure 8: Windows Welcome Screen

Pressing Next will take you to the License Agreement page, shown in Figure 9. You need to accept the agreement to continue with the installation. The next step is to select the installation directory Figure 10. The default value is C:\Program Files\BitRock InstallBuilder\

Windows License Agreement
Figure 9: Windows License Agreement
Windows Select Installation Directory
Figure 10: Windows Select Installation Directory

The rest of this guide assumes you installed BitRock InstallBuilder in C:\Program Files\BitRock InstallBuilder\

You are now ready to start the installation process itself (Figure 11), which will take place once you press Next (Figure 12). When the installation completes, you will see the Installation Completed page shown in Figure 13. You may choose to view the README file at this point.

Windows Ready To Install
Figure 11: Windows Ready To Install
Windows Installation Under Way
Figure 12: Windows Installation Under Way
Windows Installation Completed
Figure 13: Windows Installation Completed
Note

If you found a problem and could not complete the installation, please refer to the Troubleshooting section or contact us at support@bitrock.com. Please refer to the Support section for details on which information you should include with your request.

2.1.2. Installing on Unix

The process for installing on Linux and other Unix platforms is similar. The rest of this section assumes you are running Linux. You can download the BitRock InstallBuilder binary from the BitRock website. It should have a name similar to installbuilder-professional-17.1.0-linux-installer.run. Make sure it has read and executable permissions by right clicking on the file, selecting "Properties" and then setting the appropriate permissions. Alternatively you can issue the following shell command:

  $> chmod +x installbuilder-professional-17.1.0-linux-installer.run

You can now start the installation by double-clicking on the file from your Desktop environment or by invoking it directly from the command line with:

  $> ./installbuilder-professional-17.1.0-linux-installer.run

You will be greeted by a Welcome screen if you are running in a Desktop environment or a text message (if no GUI mode is available).

The default value for installation will be a folder in your home directory if you are running the installer as a regular user (recommended) or /opt/installbuilder-17.1.0/ if you are running the installation as superuser (root).

2.1.3. Installing on Mac OS X

The Mac OS X version of InstallBuilder is distributed as a zip file containing a .app that will be uncompressed automatically at download time by the browser. Alternatively you can uncompress it with:

  $> unzip installbuilder-professional-17.1.0-osx-installer.app.zip

You can launch the application by double-clicking on it in Finder or from the command line with the following instruction

  $> open installbuilder-professional-17.1.0-osx-installer.app

2.2. Registering your Copy of InstallBuilder

The InstallBuilder version you can download from installbuilder.bitrock.com is a fully functional evaluation version. It can only be used for a period of 30 days, and is intended for evaluation purposes only. It will add a reminder message to each installer ("Created with an evaluation version of BitRock InstallBuilder") which will disappear once you purchase and register a license.

There are two ways of registering your license with the product:

  • Using the GUI interface: From the main application menu select "License", then "Register License", and a window will appear where you can enter the location of your license file.

  • Manually: The product can be manually registered by copying the license.xml file to the directory where InstallBuilder was installed.

2.2.1. Specifying a License in the Command Line

Sometimes you may need to specify a license at build time, instead of registering your copy of InstallBuilder. For example, this is necessary when you do not have write permissions for the InstallBuilder installation directory.

To do so, you can use the --license flag both with the GUI and command line builder.

$> builder build ~/project.xml --license ~/licenses/license.xml
$> builder --license ~/licenses/license.xml

The code above will launch the command line or GUI builder and all generated installers will be registered with the license ~/licenses/license.xml. If the GUI builder is closed and then reopened without specifying the --license flag, the generated installers will use a previously registered license. If no license is registered or an incorrect one is provided, the message Built with an evaluation version of InstallBuilder will be displayed while building. A similar message will also be displayed in the Welcome page of the generated installers.

2.2.2. Windows-specific License Registration Details

On certain Windows versions, especially those that are UAC-enabled such as Vista and Windows 7, regular users cannot write to the default installation directory of InstallBuilder under c:\Program Files. When registering a new license, the builder will try first to write it to the main installation directory. If it is not writable, it will be placed in the user’s personal folder.

When the builder is launched, it will try to load the license from the user’s personal folder and if none is found, it will look for it in the installation directory.

This process allows multiple users to share the same installation of Installbuilder without interference, even if they do not have administrative rights. It also allow using different licenses for each user. The output directory follows a similar approach as explained in the "Directory structure" section.

2.3. Directory Structure

The installation process will create several directories:

  • bin: BitRock InstallBuilder application binaries.

  • paks: Support files necessary for creating installers.

  • autoupdate: Support and binary files for the bundled automatic update tool.

  • projects: Project files for your installers. See note below for Windows Vista.

  • docs: Product documentation.

  • demo: Files for the sample demo project.

  • output: Generated installers. See note below for Windows Vista and Windows 7.

On Windows Vista and Windows 7, in line with the Application Development Requirements for User Account Control (UAC), the projects and output directories are installed under the user Documents folder, so usually they can be found at C:\Users\Username\Documents\InstallBuilder\projects and C:\Users\Username\Documents\InstallBuilder\output, respectively.

You are ready now to start the application and create your first installer, as described in the next section "Building your First Installer".

2.4. Building Your First Installer

This section explains how to create your first installer in a few simple steps.

2.4.1. Startup and Basic Information

If you are running Gnome or KDE and performed the installation as a regular user, a shortcut was created on your Desktop. You can either start BitRock InstallBuilder by double-clicking on it or by invoking the binary from the command line:

 $> /home/user/installbuilder-17.1.0/bin/builder

If you are running Windows, the installer created the appropriate Start Menu entries. Additionally, a shortcut was placed on your Desktop. Please refer to the Using the Command Line Interface section later in the document for more information on building installers from the command line.

The initial screen will appear (Figure 14). Press the "New Project" button or select that option from the File menu on the top left corner. A pop-up Window will appear, asking you for four pieces of information:

  • Product Name: The full product name, as it will be displayed in the installer

  • Product Filename: The short version of product name, which will be used for naming certain directories and files. It can only contain alphanumeric characters

  • Version Number: Product version number, which will be used for naming certain directories and files.

  • Vendor name: Vendor name that will be used to generate native packages, register the application with the package database or the Windows Add/Remove/Program menu

The rest of this tutorial assumes you kept the default values: "Sample Project", "sample", "1.0" and "Name of your Company".

Main Screen
Figure 14: Main Screen

Once you enter the information, the "Basic settings screen" (Figure 15) will be shown. Here you can specify additional settings:

  • License File: Path to the license file that the user must accept in order to install the software

  • Readme File: Path to the README file that can be shown to the user after installation is completed

  • Save Relative Paths: Determines whether or not to convert absolute paths to relative when saving project files. This is important if the same project file is used by multiple developers. The path will be relative to the location of the project file.

If you do not want to display a license agreement or a README file during installation, you can leave those fields blank.

Note
When is it necessary to use the Save Relative Paths option?

It is necessary when the same project file is shared by multiple developers on different machines or when using the same project file on Windows and Unix. This is due to the differences in how paths are specified on each platform. For example, a Windows path includes a drive identifier, such as c:\myproject\images\logo.png This is fine if only one developer is building the project in the same machine, but will cause problems if the project needs to be rebuilt on a Unix machine. With the save relative paths setting enabled, it is possible to specify the location of the file as ..\images\logo.png which will be appropriately translated as ../images/logo.png on Unix systems.

Basic Settings
Figure 15: Basic Settings

2.4.2. Select the Files

The next step is to click on the "Files" icon, which will lead to the screen shown in Figure 16.

The "Program Files" folder represents the target installation directory. You can add files and directories to this folder by selecting the "Program Files" folder and using the "Add File" and "Add Directory Tree" buttons. You can add multiple files by pressing down the Control key and clicking on them in the File selection dialog. Multiple selection is not available for directories at this time. The selected files and directories will be copied to the destination the user chooses during installation. If a folder only supports a particular target platform, such as Linux, it will only be included in installers for that particular platform.

Most applications only install files under the main installation directory ("Program Files" folder in the Files screen). It is possible, however, to add additional folders to copy files and directories to, such as /usr/bin or /etc/ by pressing the "Add Destination Folder" button in the Files screen. If you need special permissions to write to the destination folders, you may need to require installation by root (see "Customization of the installer" below).

Files Screen
Figure 16: Files Screen

Shortcuts can also be added to folders or the component. Depending on where it is added, it will be created in different places. For example, if a shortcut is added to a folder, it will be created in the destination of that folder. If the shortcuts are added to the Desktop or the Start Menu sections of the component they will be created in those locations (if applicable, Start Menu shortcuts are just created on Windows).

Please refer to the "Menus and Shortcuts" section to find additional information.

2.4.3. Add Logic to the Installer

You can add logic to the installer, such as asking for information from the end user, creating users or writing some information to the registry. The Advanced section allows managing both custom pages and actions.

In most cases, a <initializationActionList> or <preInstallationActionList> element is used to perform a first validation of the system, such as checking for previous installations or enough disk space and the <postInstallationActionList>, executed after the unpack process, is used to perform actions with the installed files. For example, tasks such as changing permissions or starting a bundled Apache server would be performed after your software is installed. You can get a comprehensive list of available actions in the Actions appendix. A listing of all available points during the installation process in which these actions will be executed can be found in the Action Lists section.

With regards to getting information from the end user such as the installation directory, ports or passwords, the User Input and Pages sections include countless examples of how to retrieve all of the information required and how to properly create complex layouts.

2.4.4. Add a license key page

In some cases it is desirable to prevent your users from installing your software without providing a previously purchased license key. The example below explains how to create a custom license key page and how to validate its input:

<project>
  ...
  <!-- Component bundling the validator -->
  <componentList>
    <component>
    <name>tools</name>
       <folderList>
          <folder>
             <name>license</name>
             <destination>${installdir}</destination>
             <distributionFileList>
                <distributionFile origin="/path/to/validator.exe"/>
             </distributionFileList>
          </folder>
       </folderList>
    </component>
  </componentList>
  ...
  <parameterList>
    ...
    <!-- License key page -->
    <parameterGroup>
       <name>licensekey</name>
       <title>License Key</title>
       <explanation>Please enter your registration key</explanation>
       <value></value>
       <default></default>
       <orientation>horizontal</orientation>
       <parameterList>
          <!-- A stringParameter for each field. We include a "-" as description to simulate the license-type format -->
          <stringParameter name="field1" description="" allowEmptyValue="0" width="4"/>
          <stringParameter name="field2" description="-" allowEmptyValue="0" width="4"/>
          <stringParameter name="field3" description="-" allowEmptyValue="0" width="4"/>
          <stringParameter name="field4" description="-" allowEmptyValue="0" width="4"/>
       </parameterList>
       <validationActionList>
          <!-- Check all the fields have the appropriate length -->
          <foreach variables="field">
             <values>"${field1}" "${field2}" "${field3}" "${field4}"</values>
             <actionList>
                <throwError>
                   <text>${field}: Field should be four digits length</text>
                   <ruleList>
                       <compareTextLength text="${field}" logic="equals" length="4" negate="1"/>
                   </ruleList>
                </throwError>
                <throwError>
                   <text>${field}: Should be a pure digit string</text>
                   <ruleList>
                       <stringTest text="${field}" type="digit" negate="1"/>
                   </ruleList>
                </throwError>
             </actionList>
          </foreach>
          <!-- Join all the fields to create the license number -->
          <setInstallerVariable name="normalizedkey" value="${field1}${field2}${field3}${field4}"/>
          <!-- Unpack a bundled validator program and check if the license is correct -->
          <unpackFile>
            <destination>${system_temp_directory}</destination>
            <component>tools</component>
            <folder>license</folder>
            <origin>validator.exe</origin>
          </unpackFile>
          <runProgram>
            <program>${system_temp_directory}/validator.exe</program>
            <programArguments>${normalizedkey}</programArguments>
          </runProgram>
          <throwError text="Wrong license key, please enter a valid one">
            <ruleList>
              <compareText text="${program_stdout}" logic="equals" value="1"/>
            </ruleList>
          </throwError>
       </validationActionList>
       <ruleList>
          <compareText text="${installer_ui}" logic="equals" value="gui"/>
       </ruleList>
    </parameterGroup>
    ...
  </parameterList>
  ...
</project>

Please note that this layout won’t be properly displayed in text mode so the example hides the page if the ${installer_ui} is not gui (see Installation Modes for additional details). If you plan to support it, you should create an additional simplified page to be displayed in text mode:

 <stringParameter>
    <name>licensekeytext</name>
    <title>License Key</title>
    <description>Please introduce your registration key:</description>
    <validationActionList>
       ...
    </validationActionList>
    <ruleList>
       <compareText text="${installer_ui}" logic="equals" value="text"/>
    </ruleList>
 </stringParameter>

In the example, the validation code makes use of an external tool to validate the license. If you do not have any tool, you could implement an algorithm in your XML code to validate it. A very simple validation would be to check that:

${field1}+${field3}==${field2}+${field4}

<validationActionList>
    <mathExpression>
        <text>${field1}+${field3}</text>
        <variable>sum1</variable>
    </mathExpression>
    <setInstallerVariableFromRegEx>
        <name>trimmedSum1</name>
        <pattern>.*(\d{4})$</pattern>
        <substitution>\1</substitution>
        <text>${sum1}</text>
    </setInstallerVariableFromRegEx>
    <mathExpression>
        <text>${field2}+${field4}</text>
        <variable>sum2</variable>
    </mathExpression>
    <setInstallerVariableFromRegEx>
        <name>trimmedSum2</name>
        <pattern>.*(\d{4})$</pattern>
        <substitution>\1</substitution>
        <text>${sum2}</text>
    </setInstallerVariableFromRegEx>
    <throwError>
        <text>Invalid License or License Count Exceeded</text>
        <ruleList>
            <compareValues>
                <logic>does_not_equal</logic>
                <value1>${trimmedSum2}</value1>
                <value2>${trimmedSum1}</value2>
            </compareValues>
        </ruleList>
    </throwError>
 </validationActionList>

Please note this is a very simple algorithm. If you plan to use this in your installer you can create more complex checks using <setInstallerVariableFromRegEx> and <md5> actions.

Another option is to send the provided license key to your server to validate:

<validationActionList>
    <httpPost>
        <filename>${system_temp_directory}/post_result</filename>
        <url>http://www.example.com/validate.php</url>
        <queryParameterList>
            <queryParameter name="key" value="${normalizedkey}"/>
        </queryParameterList>
    </httpPost>
    <md5>
      <text>${normalizedkey}+secretKey</text>
      <variable>expected</variable>
    </md5>

    <readFile name="result" path="${system_temp_directory}/post_result"/>
    <throwError text="Invalid License or License Count Exceeded">
        <ruleList>
            <compareText>
                <logic>does_not_contain</logic>
                <text>${result}</text>
                <value>${expected}</value>
            </compareText>
        </ruleList>
    </throwError>
    <deleteFile path="${system_temp_directory}/post_result"/>
 </validationActionList>

You can also send additional information, such as a required username and password so you can track which user is providing the license key. The drawback of using this approach is that it requires an Internet connection.

2.4.5. Customize the Installer

On the Customization (Figure 17) and the Packaging screens, you can change the default installation settings to match your needs:

User Interface Settings

  • Logo Image: 48x48 GIF or PNG logo image that will be placed at the top right corner of the installer. If no image is specified, the default image will be used

  • Left Side Image: 163x314 GIF or PNG image that will be placed at the left side of the installer in the Welcome and Installation Finished pages. If no image is specified, the default image will be used

  • Windows Executable Icon: ICO file with an specific format -see below- to set the icon for the installer executable file on Windows systems.

  • Default Installation Language: Default language for the installer

  • Allow Language Selection: Allow language selection. If this setting is enabled, the user will be required to specify the language for the installation

  • Wrap License File Text: Wrap license file text displayed to the user

  • Splash screen delay: Extra display time of the splash screen

Installer Settings

  • Require Install by Administrator: Whether or not installation will require super user privileges (root on Linux, Administrator user on Windows and OS X). This setting will prevent the installer from running if the user is not root or Administrator on all operating systems except for OS X. In OS X, the regular authentication dialog window will be shown, asking the user for the administrator password so the installer can be run with root privileges

  • Installer Name: Name of the installer created by the build process.

  • CDROM Files Directory: Name of the directory that will contain the CDROM files created by the build process

  • Uninstaller Directory: Directory where the uninstaller will be created

  • Compression Algorithm: Compression algorithm that will be used to pack the files inside the installer. LZMA compression is available only on Linux, Windows and OS X platforms

  • Backup Directory: Path to a directory where existing files will be stored if enableRollback property is enabled

  • Installation Scope: Whether or not to install Start Menu and Desktop links for All Users or for the current user. If set to auto, it will be installed for All Users if the current user is an administrator or for the current user otherwise.

It is recommended that instead of using the above settings, you use the equivalent action lists, such as <postInstallationActionList> and <preUninstallationActionList>.

Permissions

Please note that these options only take effect when creating installers for Unix platforms from Windows.

  • Default Unix File Permissions: Default Unix file permissions in octal form

  • Default Unix Directory Permissions: Default Unix directory permissions in octal form

Customization screen
Figure 17: Customization screen

Check the Customization section for an in-depth customization guide.

All of these project-level configuration settings can be customized based on the platform using the <platformOptionsList> tag:

<platformOptionsList>
   <platformOptions>
      <platform>linux</platform>
      <leftImage>images/abc_linux_left.png</leftImage>
      <height>400</height>
   </platformOptions>
   <platformOptions>
      <postInstallationScript>${installdir}/linux-x64-script.sh</postInstallationScript>
      <platform>linux-x64</platform>
   </platformOptions>
   <platformOptions>
       <platform>solaris-sparc</platform>
       <leftImage>images/abc_solaris_sparc_left.png</leftImage>
   </platformOptions>
   <platformOptions>
       <platform>solaris-intel</platform>
       <leftImage>images/abc_solaris_intel_left.png</leftImage>
   </platformOptions>
   <platformOptions>
       <platform>windows</platform>
       <leftImage>images/abc_left.png</leftImage>
   </platformOptions>
   <platformOptions>
       <platform>osx</platform>
       <leftImage>images/abc_osx_left.png</leftImage>
       <height>500</height>
   </platformOptions>
</platformOptionsList>

2.4.6. Packaging the Installer

You can now build the installer by pressing the "Build" button. This will take you to the Packaging screen and start the installer building process, as shown in Figure 18. If the build process succeeds, an installer named sample-1.0-linux-installer.run will be placed at the output directory (C:\Users\Username\Documents\InstallBuilder\projects under Windows Vista and Windows 7, as explained earlier). If you are building a Windows installer, the file will be named sample-1.0-windows-installer.exe. If you are building a Mac OS X installer, its name will be sample-1.0-osx-installer.app. The Mac OS X installer binary will need to be packaged inside an archive file or disk image. If any problem is found, such as a file not being readable, a message will be displayed in red and the build will stop.

Building the installer
Figure 18: Building the installer

You can test the generated installer by pressing the "Test Run" button, as seen in Figure 19.

Note
What is the difference between Full Build and Quick build?

Creating an installer can take a long time if your product is hundreds of megabytes in size. You can use the Quick Build button to avoid rebuilding an installer from scratch if you are just making changes to installer-specific settings, such as license and readme files, the default installation path or logo image. It will also do incremental packaging of files that have been added or removed. This incremental package will increase the size of the installer, so it is recommended that you do a full build after development of the installer has completed and before release.

You can customize additional installer functionality as explained in the Advanced Functionality section.

Testing the installer
Figure 19: Testing the installer

2.4.7. CDROM Installers

It is possible to select a CDROM build target. In this case, a directory including a folder with common installer files and a setup file for each one of the supported architectures is created. This allows you to provide a single CDROM for all platforms, avoiding duplication of data.

This method is also the recommended approach for installers above 1GB, especially on Windows, where the UAC mechanism tries to copy the full installer to the %TEMP% folder before launching it, which results in very high delays when starting the installer. Another known issue on Windows is that executables above 1GB do not show their icons.

Using the cdrom-type build will create a set of lightweight installers for the configured platforms and the packed files separately.

To build a CDROM installer you just have to select Multiplatform CDROM as Build Platform in the Packaging screen when using the GUI mode or just provide cdrom as the target in the command line interface:

$> bin/builder build project.xml cdrom

InstallBuilder will then generate a set of folders, each of them containing the files to be burned in the CDROM disk. For example, for a 4 disk installer you will get:

$> ls output/

sample-1.0-cdrom
sample-1.0-cdrom.1
sample-1.0-cdrom.2
sample-1.0-cdrom.3

Where the name of the folders is defined through the <cdromDirectory> project property. The first disk is contained in the folder named sample-1.0-cdrom and, apart from the packed files, it will contain the installers for the different platforms. The other folders will just contain the rest of the files to install. When installing the generated multidisk installer, InstallBuilder will automatically ask for the next disk when needed.

A CDROM build is configured through the below project properties:

  • <cdromFirstDiskSize>: The size (in bytes) of the first CDROM (default value: 650000000). This tag will allow you to reserve some space in the first disk to include presentations, images or video tutorials without affecting the size of the rest of the disks. If you don’t need this extra space in the first disk you can just set it to the same value as the <cdromDiskSize> property.

  • <cdromDiskSize>: The size (in bytes) of the remaining CDROMS (default value: 700000000)

  • <cdromPlatforms>: Space-separated list of platforms that the CDROM installer will support. A launcher binary will be added in the first disk for each of these platforms.

  • <cdromDirectory>: Name of the directory that will contain the CDROM files created by the build process (defaults to ${project.shortName}-${project.version}-cdrom)

  • <compressPackedFiles>: Compress files as if they were being packed into the installer file (defaults to 0). Setting this option to true results in the creation of a dist file that has packed all the files inside it. It usually achieves better compression rates.

Note
Creating DVD disks

In case of DVD disks, the appropriate values for the <cdromFirstDiskSize> and <cdromDiskSize> tags are:

<project>
  ...
  <cdromFirstDiskSize>4650000000</cdromFirstDiskSize>
  <cdromDiskSize>4700000000</cdromDiskSize>
  ...
</project>
Note
Distributing big installers in other media formats

If your product is distributed in other media formats such as a USB drive or SD card you can still use the CDROM-type build.

You just need to set a <cdromFirstDiskSize> above your required disk space so InstallBuilder does not split the data into multiple disks. As internally calculating the required disk space for each disk does not currently take into account the compression gain, a safe value to set would be twice the size of your files.

In the case of a USB bundling your 10GB of files:

<project>
  ...
  <cdromFirstDiskSize>20000000000</cdromFirstDiskSize>
  ...
</project>
How are disks on multidisk installers detected

A common error while testing the multidisk installers is not being able to detect the next disk when the installer requests it. To understand why this happens, it is important to understand how InstallBuilder detects that the inserted disk is valid:

1) When the unpack process starts, InstallBuilder looks for the dist file (or folder depending on the value of the <compressPackedFiles> property) in its parent directory and starts unpacking the files

2) When InstallBuilder finds a file that requires a new disk during the unpack process, a dialog prompts for it.

3) After the new disk is inserted and the user accepts the dialog, InstallBuilder looks for a dist file in the same location of the previous one. If InstallBuilder cannot find it, it will report that the disk is incorrect and will ask again for the disk.

The most common mistake in this step is to rename the dist or to move it to another directory in the new disk.

4) If the dist file is correctly placed and InstallBuilder finds it, it will then look for the next file to unpack. If the dist file does not contain the requested file, InstallBuilder will report that it cannot find the disk as in the previous step.

This error may occur because the wrong disk number was inserted. If this is not the case and you are not using <compressPackedFiles>1</compressPackedFiles>, the filenames inside the dist folder may have been shortened by the burning software. For example, a Joilet file system will only allow you to write up to 64 characters filenames. Using <compressPackedFiles>1</compressPackedFiles> or properly burning the disk to allow long filenames will solve the problem.

5) Once the new file is found, the installation process continues, requesting a new disk if necessary.

2.5. Sample installers bundled with InstallBuilder

InstallBuilder provides several sample projects to help you get started with building your installer.

The welcome screen in the InstallBuilder GUI shows a list of the available projects. These projects will be automatically loaded when clicked:

List of example projects
Figure 20: List of example projects in GUI

Each of these projects can be opened, built and tested without applying any changes. You can also try modifying them to see how the solutions shown in the examples can be reworked to suit your product’s needs.

2.5.1. Basic demo project

This project provides a simple, ready to use installer that will:

  • Prompt the user to accept a license agreement.

  • Display a page to select the installation directory.

  • Install the packed files.

  • Show an optional README file with information about the installation, selectable through a checkbox in the final page.

Demo project's sample license
Figure 21: Demo project's sample license

The demo project includes files for multiple platforms. Depending on the platform built, it will pack different sets of files.

2.5.2. Components, component groups and downloadable components

This project demonstrates how components and component groups can be used to package a complex application. It demonstrates how component groups can be used to organize common files and functionality. Deselecting or selecting the parent parameter group will also affect the installation of its child components.

Component selection for structured components
Figure 22: Component selection for structured components

The project will help you to understand how parent and child components interact. Selecting the Text Editor component will cause some of its child components (Printing support by default) to be installed while Slides and Presentations will enable Printing support and Projector support by default.

Deselecting Import / Export filters causes all of its children to automatically be deselected. Selecting Import / Export filters again will cause the selection status of XML / XSLT filters and Other filters to be restored.

Additional details regarding components and child components can be found in the component groups section of the documentation.

This example project also shows how downloadable components work and how to implement more advanced functionality such as mirror selection for downloads. Several components are marked as component.downloadable, which means that they will be created as separate files when built with the downloadable components flag enabled.

More information about creating installers with downloadable components can be found in downloadable components section of the manual.

Note
Downloadable components and being able to run the installer

When building the project with the downloadable components option enabled during build, the installer will try to download the created components from mirror1.example.com or mirror2.example.com and will fail.

In order to test that the downloadable components functionality is working, copy the generated packages from components/componentgroupsexample-1.0 under the output directory to a web server (you can easily setup a web server using LAMPStack (Linux), WAMPStack (Windows) or MAMPStack (OS X) from BitNami.org) and modify the link in the <componentsUrl> in demo project:

<componentsUrl>http://localhost:8080/components/componentgroupsexample-1.0/</componentsUrl>

2.5.3. Showcase of available parameters

This project shows what types of parameters are available and how you can use them to retrieve information from the user.

It explains how to combine them using parameter groups to create more complex GUIs.

The rest of the section provides examples of the available parameters, including their XML code and how they look in the GUI:

Additional license dialog

<licenseParameter>
    <title>Second License Agreement</title>
    <name>other_license</name>
    <file>docs/otherLicense.txt</file>
    <wrapText>1</wrapText>
</licenseParameter>
Show a text and image with a <labelParameter>

<labelParameter>
  <name>non_linux_user</name>
  <title>Introduction</title>
  <description>Dear ${platform_name} user, you'll now try an example installer that
will display to you examples of the InstallBuilder parameters functionality.</description>
  <image>img/icon.png</image>
</labelParameter>
Installation directory selection with a <directoryParameter>

<directoryParameter>
  <name>installdir</name>
  <description>Installation directory</description>
  <explanation>Please specify the directory where
${project.fullName} will be installed</explanation>
  <insertAfter>welcome_label</insertAfter>
  <default>${platform_install_prefix}/${project.shortName}-${project.version}</default>
  <cliOptionName>prefix</cliOptionName>
  <mustBeWritable>yes</mustBeWritable>
  <mustExist>0</mustExist>
</directoryParameter>
Group multiple fields using a <parameterGroup>

<parameterGroup>
  <name>user_data</name>
  <title>User data</title>
  <explanation>Please insert the desired username and password</explanation>
  <parameterList>
    <stringParameter>
      <name>username</name>
      <description>User Name</description>
      <value>admin</value>
      <allowEmptyValue>0</allowEmptyValue>
    </stringParameter>
    <passwordParameter>
      <name>userpasswd</name>
      <title>User Password</title>
      <description>Password</description>
      <descriptionRetype>Re-enter</descriptionRetype>
      <!-- throw an error if password is empty -->
      <validationActionList>
        <throwError>
          <text>You need to provide a non-empty password</text>
          <ruleList>
            <compareText text="${userpasswd}"
              logic="equals" value="" />
          </ruleList>
        </throwError>
      </validationActionList>
    </passwordParameter>
  </parameterList>
</parameterGroup>
Ask if a database should be installed with a <booleanParameter>

<booleanParameter>
  <name>install_db</name>
  <title>Install a database</title>
  <description>Do you want to install a database?</description>
  <default>1</default>
</booleanParameter>
Select the preferred database using radiobuttons

<choiceParameter>
  <name>preferred_database</name>
  <title>Choose a database</title>
  <explanation>Choose a database to be installed
and configured</explanation>
  <default>mysql</default>
  <cliOptionName>${project.shortName}_database</cliOptionName>
  <displayType>radiobuttons</displayType>
  <optionList>
    <option>
      <text>MySQL</text>
      <image>img/mysql.png</image>
      <value>mysql</value>
      <description>The project will be configured
to use MySQL database.</description>
    </option>
    <option>
      <text>PostgreSQL</text>
      <image>img/postgres.png</image>
      <value>postgres</value>
      <description>The project will be configured
to use PostgreSQL database.</description>
    </option>
    <option>
      <text>SQLite</text>
      <image>img/sqlite.png</image>
      <value>sqlite</value>
      <description>The project will be configured
to use SQLite database.</description>
    </option>
  </optionList>
</choiceParameter>
Multiple <booleanParameter> parameters in a <parameterGroup>

<parameterGroup>
  <name>apps_and_server</name>
  <title>Web framework and server</title>
  <explanation>Is there anything else you wish to install?</explanation>
  <parameterList>
    <booleanParameter>
      <name>install_webframework</name>
      <value>1</value>
      <description>Install a web framework</description>
      <displayStyle>checkbox-left</displayStyle>
    </booleanParameter>
    <booleanParameter>
      <name>install_server</name>
      <value>1</value>
      <description>Install a web server (this is an example of a
right aligned checkbox)</description>
      <displayStyle>checkbox-right</displayStyle>
    </booleanParameter>
  </parameterList>
</parameterGroup>
Choose the preferred framework using radiobuttons

<choiceParameter>
  <name>preferred_apps</name>
  <title>Web Frameworks</title>
  <explanation>Choose the web frameworks you want to install</explanation>
  <default>django</default>
  <cliOptionName>${project.shortName}_apps</cliOptionName>
  <displayType>radiobuttons</displayType>
  <optionList>
    <option>
      <text>Django</text>
      <value>django</value>
      <description>A web framework for Python.</description>
    </option>
    <option>
      <text>Ruby on Rails</text>
      <value>ror</value>
      <description>The famous web framework for Ruby.</description>
    </option>
    <option>
      <text>Cake</text>
      <value>cake</value>
      <description>A web framework
for PHP.</description>
    </option>
  </optionList>
  <ruleList>
    <compareValues>
      <value1>${install_webframework}</value1>
      <logic>equals</logic>
      <value2>1</value2>
    </compareValues>
  </ruleList>
</choiceParameter>
Choose between multiple web server using a combobox

<choiceParameter>
  <name>preferred_server</name>
  <title>Web Servers</title>
  <explanation>Choose the web server you want to install </explanation>
  <default>apache</default>
  <cliOptionName>${project.shortName}_server</cliOptionName>
  <displayType>combobox</displayType>
  <optionList>
    <option>
      <text>Apache</text>
      <value>apache</value>
    </option>
    <option>
      <text>Lighttpd</text>
      <value>light</value>
    </option>
  </optionList>
</choiceParameter>
Choose a file using a <fileParameter>

<fileParameter>
  <name>chooseAFile</name>
  <title>Configuration File</title>
  <explanation>Please include a file</explanation>
  <mustExist>1</mustExist>
</fileParameter>
Using a <booleanParameterGroup> to show optional configuration options

<booleanParameterGroup>
  <name>advanced</name>
  <description>Advanced Mode</description>
  <parameterList>
    <choiceParameter>
      <name>emailNotifications</name>
      <description>Email notifications</description>
      <value>always</value>
      <allowEmptyValue>1</allowEmptyValue>
      <displayType>combobox</displayType>
      <ordering>default</ordering>
      <width>40</width>
      <optionList>
        <option description="Always send notifications"
          text="Always" value="always" />
        <option description="Never send notifications"
          text="Never" value="never" />
      </optionList>
    </choiceParameter>
    <stringParameter name="subject"
      description="Notifications Subject"
      value="[NOTIFICATION] #" />
    <directoryParameter name="cacheDir"
      description="Cache Dir"
      value="${system_temp_directory}/cache" />
  </parameterList>
</booleanParameterGroup>
Using a <choiceParameterGroup> to show multiple options for registration

<choiceParameterGroup>
  <name>keyChoice</name>
  <description>Select how to provide your license key </description>
  <parameterList>
    <fileParameter
      name="keyFile"
      description="Load from file"/>
    <stringParameter
      name="licenseText"
      description="Enter license key"/>
  </parameterList>
</choiceParameterGroup>
<booleanParameterGroup> page with embedded <choiceParameterGroup>

<booleanParameterGroup>
  <name>registerNested</name>
  <description>Register Installation</description>
  <value>1</value>
  <validationType>ifSelected</validationType>
  <parameterList>
    <stringParameter>
      <name>registerUser</name>
      <description>Username</description>
    </stringParameter>
    <choiceParameterGroup>
      <name>registerKeyChoice</name>
      <description>Select how to provide your license key</description>
      <parameterList>
        <fileParameter
          name="registerKeyFile"
          description="Load from file"/>
        <stringParameter
          name="registerLicenseText"
          description="Enter license key"/>
      </parameterList>
    </choiceParameterGroup>
  </parameterList>
</booleanParameterGroup>
Show multiple lines of text with an <infoParameter>

<infoParameter>
  <name>final_review</name>
  <title>Almost done</title>
  <value>These were some examples of what parameters in InstallBuilder
allow you to do in a simple and intuitive way.

After the installation there will be more examples of parameters.</value>
</infoParameter>
Show a clickable link using a <linkParameter>

<linkParameter>
  <name>open_browser</name>
  <title>Open Browser</title>
  <explanation>You can also add parameters to be shown after the installation is complete.

Here's a link parameter:</explanation>
  <insertAfter>installation</insertAfter>
  <clickedActionList>
    <launchBrowser>
      <url>http://www.bitrock.com</url>
    </launchBrowser>
  </clickedActionList>
  <description>Open BitRock Website</description>
</linkParameter>

2.5.4. Actions and when they are executed

This project shows when actions are run during build, before, during and after the installation, uninstallation and actions related to parameters.

Actions run during various stages of installation and uninstallation and can be set for both project and its individual components.

More information about when certain actions are run and their execution order can be found in the action list section.

2.5.5. Creating multiple components

This is a basic project with multiple components and shows how components can be put in separate files.

It shows how the <include> tag can be used to extract components into external files, which can be reused in multiple projects. You can use this approach to create reusable features such as Apache, MySQL or Tomcat and use them as construction blocks in your projects.

You can find more information about the <include> directive in the adding components from external files section.

2.6. Additional Support Resources

In addition to the current document, you can find additional information regarding developing with InstallBuilder in the following resources:

  • A Community Support Forum found at answers.bitrock.com

  • A Relax-NG schema (InstallBuilder.rng) is bundled in the docs directory. It can be used with code editors to validate the code being written.

  • We aim to provide useful and timely support services. If you have any questions or suggestions, please do not hesitate to contact us online at https://bitrock.zendesk.com/ or email us at support@bitrock.com

3. Architecture

3.1. Installer basics

3.1.1. Structure of a Generic Installer

At a high level, you can think of an installer as three related components (resources, logic and user input) delivered together as part of an installation package.

  • Installation Resources

These are the objects that will be bundled in the installer to be delivered to the end-user machine. They may be executable files for your software, SQL scripts or image files.

  • Installation Logic

The installation logic specifies a set of actions that will be performed on the resources, such as copying files around and substituting values in them or the system itself, starting or stopping services or creating a new user. The installation logic can be conditional, based on a set of rules that can take into account multiple factors such as the operating system the installer is running on or which options the end-user selected.

  • External Input

Often, you want to make the installation logic depend on input from the end user, such as the installation directory or the TCP/IP port the application should listen to. The user input is usually collected through a GUI frontend, but could also be provided using command line options passed to the installer or written in a response file.

  • Installation Package

The installation package contains the installation logic and resources. It can be a self-contained executable or a native package, such as an RPM or Debian package.

The following section explains how the previous concepts are implemented within InstallBuilder.

3.1.2. Structure of a BitRock Installer

  • Installation Resources

InstallBuilder supports multiple types of resources. The most important ones are files and directories that will be bundled when the installer is created, but also supports desktop and start menu shortcuts. Files and directories get assigned to folders, which specify a location in the target machine. The location does not need to be fixed and can be changed at runtime. Installer resources can be further organized in components that specify multiple folders and shortcuts that go together. In addition to the resources that will be installed in the end user’s system, there are resources for customizing the installer itself, such as graphics, language files and descriptions of the installer screens.

  • Installation Logic

InstallBuilder allows controlling the flow of the installation using actions and rules. InstallBuilder includes built-in actions for the most common functionality, such as creating users, starting services or changing file permissions, but it is also possible to invoke external programs. Actions can be run at multiple points during the installer lifecycle, such as at build time, startup time or when certain UI screens are displayed. Rules can be attached to these actions to decide which of them should be executed at runtime based on the external input.

  • External Input

InstallBuilder presents a set of pages to collect user input in addition to a command line interface. It is also possible to retrieve environment variables or information about the OS in which the installer is running.

  • Installation Package

By default, InstallBuilder generates single-file, self-contained installers which can easily be distributed over the Internet. The end user just needs to download the file, and double-click or execute it from a console prompt in order to launch the installer. It is also possible to generate multiplatform CDROM/DVD installers and native Linux packages, such as Debian and RPM. For native packages, the end result of the build process is an .rpm or .deb package that contains the installation files and a small binary that encapsulates the installation logic and will be run automatically at package install time. Installation values are fixed at build time for native packages and there is no external input collected at runtime.

4. Variables

4.1. Basic Syntax

Installer variables are an important concept in InstallBuilder. They allow you to store user input, temporary values, establish flags and use that information at different points during the build and installation processes. There are a number of built-in variables and you are also able to create them directly. The basic way of creating or changing the value of a variable in InstallBuilder is using the <setInstallerVariable> action:

 <setInstallerVariable name="foo" value="bar"/>

The action above will store the value bar in the variable foo. Once you have defined the variable, its value can be accessed in any other part of the project as ${foo}. If you require a variable that you are creating at install time to be also available in the uninstallation steps, you have to set the optional persist attribute to 1:

 <setInstallerVariable name="foo" value="bar" persist="1"/>

At uninstallation time, this variables will contain the value of the last assignment using the persist property.

Variable names must not contain characters other than digits, letters, dashes and underscores. There is only one exception to this rule: it is possible to use a variable as part of the name of another variable (as long as it is a valid one).

For example, if you have a variable foo with a value of bar, then:

 <setInstallerVariable name="${foo}" value="Hello"/>

will be equivalent to:

 <setInstallerVariable name="bar" value="Hello"/>

In addition to regular variables, parameters can also be accessed as variables. One good example is the well-known installdir variable which is in reality a <directoryParameter>:

<runProgram program="${installdir}/myApplication.run" programArguments="--install"/>

Some additional information to take into account when working with variables is:

  • Curly brackets are mandatory: Although the syntax is similar to the notation used in Unix bash-like shells to access variables, it is not the same. If $foo is used instead of ${foo}, it will not be resolved but treated as a literal string.

  • Accessing an undefined variable will not throw an error. Instead, if the variable name was bar, the value will be set to ***unknown variable bar***

  • Variables are not case sensitive. This means that you can use any of the following variants, ${variablename}, ${VariableName} or ${VARIABLENAME} and obtain the same value in all cases.

4.2. Modifier Suffixes

When accessing a variable, some operations can be specified through the usage of special suffixes:

  • ${installdir.dos}: If the variable contains a path, this modifier returns the DOS-style name for it. This will only take effect if the file exists and the platform is Windows. This is particularly useful when the value of the variable may contain spaces and you need to pass it as an argument to a program. Using the .dos suffix will remove the need of quoting the path as spaces will be removed. Take into account that using .dos over a path with forward slashes won’t convert them to backslashes.

  • ${installdir.unix}: If the variable contains a path, it will be converted to a Unix-style path and all of the backslashes will be translated into forward slashes. This will only take effect if the platform is Windows.

  • ${myPassword.password}: The .password suffix is used to mark a variable as a password to be hidden in the logs. This way, you can use a password as an argument in a <runProgram> action and log the execution without showing the plain text password. For example, the following action:

     <setInstallerVariable name="pass" value="myhiddenpassword!"/>
     <runProgram>
         <program>mysql</program>
         <programArguments>-u root --password=${pass.password}</programArguments>
     </runProgram>

will be logged as:

Executing mysql -u root --password=****
Script exit code: 0

Please note this suffix is only considered when resolving variables that will be used when writing to the installation log or in the error messages thrown by the <runProgram> and <setInstallerVariableFromScriptOutput> actions. For example, <logMessage> will interpret the suffix when logging its information but <writeFile> will ignore it.

  • ${myVariable.escape_backslashes}: This will escape all of the backslashes in the text stored in the variable. It is especially useful for substitution of values in Java property files.

  • ${installdir.dos.unix.escape_backslashes}: The modifiers can be combined.

The below table summarizes all the suffixes:

Original value

Modifier

Resolved value

alongfilename.txt

${installdir.dos}

ALONGF~1.TXT

c:\Program Files\myFile.exe

${installdir.unix}

c:/Program Files/myFile.exe

c:\Program Files\myFile.exe

${myVariable.escape_backslashes}

c:\\Program Files\\myFile.exe

c:\Program Files\myLongFile.exe

${installdir.dos.unix}

C:/PROGRA~1/MYLONG~1.EXE

Note
Convert forward slashes to backslashes

InstallBuilder does not have a modifier suffix to convert forward slashes to backslashes the same way as the .unix suffix does. To achieve the same result you just have to use a <setInstallerVariableFromRegEx> action:

 <setInstallerVariableFromRegEx>
    <name>backslash_path</name>
    <pattern>/</pattern>
    <substitution>\</substitution>
    <text>${forwardslash_path}</text>
 </setInstallerVariableFromRegEx>

The above will store the backslash-version of the Unix-like ${forwardslash_path} in the backslash_path variable.

4.3. Accessing Environment Variables

It is possible to access any environment variable using the ${env(varname)} construct, where varname is the name of an environment variable. For example, on Windows you can refer to the system drive with ${env(SYSTEMDRIVE)} and, on Linux, Mac OS X and other Unix systems to the user home directory with ${env(HOME)}

To get a list of the environment variables on your system that will be available to the installer you can execute:

  • On Windows Systems: Open a command window and execute: set

  • On Unix Systems: Open a console and execute: env

Both commands will print a list of the defined environment variables. However, you must take into account that some of these variables could vary from one machine to another.

4.4. Advanced syntax

Almost all of the elements of an InstallBuilder project can be accessed and modified as variables. This makes InstallBuilder a very versatile tool because it allows installers to customize themselves at runtime, based on the environment or on end user feedback. The three basic elements which can be accessed are:

4.4.1. Project properties

All of the project properties such as <version>, <shortName>, <installerFilename> and so on, can be referenced using the notation ${project.property}. For example, ${project.shortName} for the <shortName>. Similarly to regular variables, you can use any capitalization when referencing an element. Using ${PrOjEct.InstallerFilename} is equivalent to using ${project.installerFilename}.

The below example changes the <installationType> at runtime to perform an upgrade if the previous installed version, stored in an environment variable, is lower than the current one:

<project>
   ...
   <shortName>myProduct</shortName>
   <installationType>normal</installationType>
   ...
   <initializationActionList>
     <setInstallerVariable>
       <name>project.installationType</name>
       <value>upgrade</value>
       <ruleList>
         <!-- Check that the env variable exists -->
         <compareText>
            <text>${env(MYPRODUCT_VERSION)}</text>
            <logic>does_not_equal</logic>
            <value></value>
         </compareText>
         <!-- Compare the versions -->
         <compareVersions>
            <version1>${project.version}</version1>
            <logic>greater</logic>
            <version2>${env(MYPRODUCT_VERSION)}</version2>
         </compareVersions>
       </ruleList>
     </setInstallerVariable>
   </initializationActionList>
   ...
</project>

You can refer to the Project Properties appendix for the complete list of properties.

4.4.2. Components

Using this notation you can also modify component settings:

  • ${project.component(default).selected}

  • ${project.component(mysql).show}

This allows, for example, disabling components at runtime when the user does not provide a license key:

<stringParameter>
  <name>licenseKey</name>
  <description>Please provide a license key. If you leave the field empty
  you just will be able to test the basic functionality</description>
  <insertBefore>components</insertBefore>
  <postShowPageActionList>
    <actionGroup>
      <actionList>
        <setInstallerVariable>
          <name>project.component(premiumComponent).selected</name>
          <value>0</value>
        </setInstallerVariable>
        <setInstallerVariable>
          <name>project.component(premiumComponent).canBeEdited</name>
          <value>0</value>
        </setInstallerVariable>
      </actionList>
      <ruleList>
        <compareText>
          <text>${licenseKey}</text>
          <logic>equals</logic>
          <value></value>
        </compareText>
      </ruleList>
    </actionGroup>
  </postShowPageActionList>
</stringParameter>

You can refer to the Components appendix for the complete list of properties.

4.4.3. Parameters

Using the advanced syntax on parameters will allow you to modify not only their values but their entire set of properties such as <description>, <explanation> and the especially useful <ask>. The basic usage is:

${project.parameter(nameOfTheParameter).propertyName}

For example:

  • ${project.parameter(installdir).value}

  • ${project.parameter(tomcat).description}

  • ${project.parameter(mySQL).default}

If the parameter to access is a child of a <parameterGroup>, the parent must also be specified. For example, the port parameter in the below code:

<project>
  ...
  <parameterList>
    <parameterGroup>
      <name>mysqlConfiguration</name>
      <parameterList>
        <stringParameter name="port" description="MySQL port" value="3306"/>
        <passwordParameter name="password" description="MySQL root password" value=""/>
        ...
      </parameterList>
    </parameterGroup>
  </parameterList>
  ...
</project>

Can be accessed using:

${project.parameter(mysqlConfiguration).parameter(port).value}

If the parameters are also included inside a component, instead of directly under the <project> <parameterList>, it must be also specified. For example, reusing the above example:

<project>
  ...
  <componentList>
    <component>
      <name>mySQL</name>
      <parameterList>
        <parameterGroup>
          <name>mysqlConfiguration</name>
          <parameterList>
            <stringParameter name="port" description="MySQL port" value="3306"/>
            <passwordParameter name="password" description="MySQL root password" value=""/>
            ...
          </parameterList>
        </parameterGroup>
      </parameterList>
    </component>
  </componentList>
  ...
</project>

The parameter should now be accessed using:

${project.component(mysql).parameter(mysqlConfiguration).parameter(port).value}

You can use this functionality to disable pages or parameters at runtime based on the user input:

<project>
  ...
  <componentList>
   <component>
     <name>mySQL</name>
     <parameterList>
       <booleanParameter>
         <name>enableAdvanced</name>
         <description>Do you want to enable the advanced configuration?</description>
         <postShowPageActionList>
           <!-- Enable the page, which is disabled by default -->
           <setInstallerVariable>
             <name>project.component(mySQL).parameter(mysqlAdvanced).ask</name>
             <value>1</value>
             <ruleList>
                <isTrue value="${project.component(mySQL).parameter(enableAdvanced).value}"/>
             </ruleList>
           </setInstallerVariable>
         </postShowPageActionList>
       </booleanParameter>
       <parameterGroup>
          <name>mysqlAdvanced</name>
          <parameterList>
             <stringParameter name="mysqlPort" description="MySQL port" value="3306"/>
             <passwordParameter name="mysqlPassword" description="MySQL root password" value=""/>
             ...
          </parameterList>
       </parameterGroup>
     </parameterList>
   </component>
  </componentList>
  ...
</project>

Parameters are also handy when you want to preserve variables defined at build time. Accessing a variable defined in the <preBuildActionList> at runtime will result in an ***unknown variable varName*** error. To workaround this issue, you could use a hidden parameter (setting ask="0"), that won’t be displayed in the help menu nor the installer pages. For example, to pass a random generated key for each of the built installers you could use the below code:

<project>
  ...
  <parameterList>
    ...
    <stringParameter name="build_identifier" value="" ask="0"/>
    ...
  </parameterList>
  <preBuildActionList>
     <!-- Create random identifier for the build -->
     <generateRandomValue>
       <variable>build_identifier</variable>
     </generateRandomValue>
     <!-- Date of the build -->
     <createTimeStamp>
        <variable>timestamp</variable>
     </createTimeStamp>
     <!-- Register the build information in a local file -->
     <addTextToFile>
        <file>${build_project_directory}/builds</file>
        <text>${build_identifier} - Product Version: ${project.version} - IB Version: ${installer_builder_version} - Built On: ${timestamp}</text>
     </addTextToFile>
  </preBuildActionList>
  ...
</project>

As you are using a hidden parameter, the ${build_identifier} will be available at runtime and you could, for example, send it to your server using an <httpPost> action to register the installations for each release:

  <postInstallationActionList>
     ...
     <httpPost url="http://www.example.com/register.php" filename="${installdir}/activationUrl">
        <queryParameterList>
           <queryParameter name="build_identifier" value="${build_identifier}"/>
           <queryParameter name="version" value="${project.version}"/>
        </queryParameterList>
     </httpPost>
  </postInstallationActionList>
Note
Accessing a parameter as a regular variable

If you try to access a parameter as if it were a regular variable, it will give you its value. That is, using ${installdir} or ${project.parameter(installdir).value} will return the same result.

The advantage of using the long notation is that it provides a very descriptive path to the element you are modifying. For example, if you are working with a very big project that is maintained by multiple developers and divided into multiple files using the <include> directive, locating where the below values are located could be troublesome (they could be parameters or regular variables, located in any of the included files or the main project):

   <throwError text="You have selected strict password checking and your password is too short" >
     <ruleList>
       <isTrue value="${enableStrictChecking}"/>
       <compareTextLength>
         <text>${password}</text>
         <logic>less</logic>
         <length>${minLength}</length>
       </compareTextLength>
     </ruleList>
   </throwError>

Where using the long location will point you directly to where they are defined (assuming the included files are named according to the component names, for example):

   <throwError text="You have selected strict password checking and your password is too short" >
     <ruleList>
       <isTrue value="${project.component(settings).parameter(basicConfiguration).parameter(enableStrictChecking).value}"/>
       <compareTextLength>
         <text>${password}</text>
         <logic>less</logic>
         <length>${project.component(settings).parameter(defaultPasswordSettings).parameter(minLength).value}</length>
       </compareTextLength>
     </ruleList>
   </throwError>

In addition to the above-mentioned elements, any other tag in the XML project with a unique identifier can be referenced. For example, is possible to reference a folder in a component to get its destination:

`<showInfo text="${project.component(mysql).folder(mysqlConfig).destination}"/>`

But not a file in its <distributionFileList> because files do not have a unique name.

4.5. Accessing Language Strings

You can also access language strings, either built-in or user-defined (check the Languages section for more details), using the special notation ${msg(stringKey)}. It will be resolved to the localized string identified by the key stringKey in the current installation language:

   <showInfo text="${msg(hello.world)}"/>

If you have defined the hello.world localized string in the <customLanguageFileList>, depending on the installation language you will get results such as Hello world!, Hola Mundo! or Hallo Welt.

4.6. Escaping Variables

In some cases, for example when modifying shell scripts programmatically, you may need a literal ${foo} instead of the contents of the foo variable (which may result in an ***unknown variable foo***). For these cases, InstallBuilder implements a special notation to specify that you want the text treated literally, without trying to be resolved: ${'${variableName}'}.

For example, ${'${foo}'} will be resolved to: ${foo}. More complex text can be escaped as shown in the snippet below:

     <writeFile>
       <path>~/.bashrc</path>
        <text>${'
PATH=${PATH}:/some/path
Foo=${bar}
'}</text>
     </writeFile>

It will write:

PATH=${PATH}:/some/path
Foo=${bar}

As shown in the example, it accepts line breaks in the text to escape. The only limitation is that it cannot contain the characters '} in the text to escape or it will be interpreted as the end of the escaped reference.

4.7. Nested Variables

Nested variables are also allowed. They will be evaluated from the most inner reference:

     <showInfo>
       <text>${text_${foo-${i}}_${bar}}</text>
     </showInfo>

This feature is especially useful when iterating using a <foreach> action. For example, if you have a list of component names and you want to create a list with those that are selected:

<setInstallerVariable name="selectedComponents" value=""/>
<foreach variables="component" values="componentA componentB componentC componentD">
   <actionList>
      <setInstallerVariable name="slectedComponents" value="${selectedComponents} ${component}" >
         <ruleList>
            <isTrue value="${project.component(${component}).selected"/>
         </ruleList>
      </setInstallerVariable>
  </actionList>
</foreach>

4.8. Built-in variables

InstallBuilder also provides a list of built-in variables containing information about the installer or the environment in which it is executed:

HTTP
  • installer_http_code: Contains the HTTP status code of the last httpGet or httpPost action.

    Example values:

    200, 404, 500

Java
  • java_autodetected: Whether or not a valid Java was autodetected

    Possible values:

    0, 1

  • java_bitness: Autodetected Java bitness

    Possible values:

    32, 64

  • java_executable: Location of the autodetected Java executable

    Example values:

    /usr/bin/java, c:/Program Files/Java/jre1.6.0_10/bin/java.exe

  • java_vendor: Autodetected Java vendor

    Possible values:

    Any, IBM, Sun

  • java_version: Autodetected Java version

    Example values:

    1.6.0, 1.5.0

  • java_version_full: Autodetected Java full version

    Example values:

    1.6.0_07, 1.5.0_11

  • java_version_major: Autodetected Java major version

    Example values:

    1.6, 1.5

  • javaw_executable: Autodetected javaw executable path

    Example values:

    /usr/bin/java, c:/Program Files/Java/jre1.6.0_10/bin/java.exe

  • javaws_executable: Location of the autodetected Java Web Start executable

    Example values:

    /usr/bin/javaws, c:/Program Files/Java/jre1.6.0_10/bin/javaws.exe

User Interface
  • installer_interactivity: The level of interactivity of the installation mode

    Possible values:

    none, normal, minimalWithDialogs, minimal

  • installer_ui: The mode in which the installer is run

    Possible values:

    unattended, gui, text

  • installer_ui_detail: The detailed mode in which the installer is run

    Possible values:

    unattended, xwindow, qt, text, osx, gtk, win32

.NET Framework
  • dotnet_autodetected: Whether or not a valid .NET framework was autodetected

    Possible values:

    0, 1

  • dotnet_framework_type: .NET framework type

    Possible values:

    , full, client

  • dotnet_version: .NET framework version

    Example values:

    2.0, 3.5, 4.0, 4.5

Installer
  • installation_aborted_by_user: Whether or not installation was manually aborted by user

    Possible values:

    0, 1

  • installation_finished: Whether or not the installation finished successfully

    Possible values:

    0, 1

  • installation_guid: Unique installation ID

    Example values:

    eee0103b-a8b1-4100-50e2-a0360485e019

  • installation_language_code: Language code of the installation

    Possible values:

    es, lt, sv, ro, et, lv, ko, eu, az, cy, pt, it, id, da, tr, sk, va, sl, ru, fa, pt_BR, fr, el, de, bg, zh_CN, es_AR, hr, nl, ja, en, ar, zh_TW, th, pl, sq, ca, sr, no, hu, he, kk, cs, vi, tk, fi

  • installer_builder_timestamp: Timestamp of the InstallBuilder used to build the installer

    Example values:

    201001220702

  • installer_builder_version: Version of InstallBuilder used to build the installer

    Example values:

    6.2.7

  • installer_command_line_arguments: Command line arguments as passed to installer

    Example values:

    --mode gtk, --installdir /opt/app-1.0

  • installer_error_message: Contains the error of the last failed action, possibly masked by its <customErrorMessage>

    Example values:

    Unknown error installing MySQL

  • installer_error_message_original: Contains the original error of the last failed action

    Example values:

    Unknown error executing action

  • installer_exit_code: Installer Exit Code value. It is equal 0 by default and set to 0 if there was an error executing an action.

  • installer_installation_log: The location of the installer log

    Example values:

    /tmp/bitrock_install.log, C:\Users\Username\Appdata\Local\Temp

  • installer_is_root_install: Whether or not the current user has root privileges

    Possible values:

    0, 1

  • installer_package_format: Type of installer

    Possible values:

    executable

  • installer_pid: PID of the running installer or uninstaller

    Example values:

    53008

  • program_exit_code: Exit code from program; set by runProgram and setInstallerVariableFromScriptOutput actions

    Example values:

    0, 1

  • program_stderr: Program’s error output; set by runProgram and setInstallerVariableFromScriptOutput actions

    Example values:
  • program_stdout: Program’s output; set by runProgram and setInstallerVariableFromScriptOutput actions

    Example values:
  • required_diskspace: Required disk space to install the application in Kilobytes

    Example values:

    10000, 25000

Windows Folders
  • windows_folder_program_files: Directory for program files

    Example values:

    C:\Program Files

  • windows_folder_program_files_common: Directory for components shared across applications

    Example values:

    C:\Program Files\Common Files

  • windows_folder_system: Windows system directory

    Example values:

    C:\Windows\system32

  • windows_folder_systemroot: Windows root directory

    Example values:

    C:\Windows

  • windows_folder_windows: Windows root directory

    Example values:

    C:\Windows

Windows Folders - System Scope
  • windows_folder_common_admintools: Directory that stores administrator tools for all users

    Example values:

    C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Administrative Tools

  • windows_folder_common_appdata: Directory that stores common application-specific data

    Example values:

    C:\ProgramData

  • windows_folder_common_desktopdirectory: Directory that stores common desktop files

    Example values:

    C:\Users\Public\Desktop

  • windows_folder_common_documents: Directory that stores common document files

    Example values:

    C:\Users\Public\Documents

  • windows_folder_common_favorites: Directory that stores common favorite items

    Example values:

    C:\Users\Administrator\Favorites

  • windows_folder_common_music: Directory that stores common music files

    Example values:

    C:\Users\Public\Music

  • windows_folder_common_pictures: Directory that stores common picture files

    Example values:

    C:\Users\Public\Pictures

  • windows_folder_common_programs: Directory that stores common program groups in start menu

    Example values:

    C:\ProgramData\Microsoft\Windows\Start Menu\Programs

  • windows_folder_common_startmenu: Directory that stores common start menu items

    Example values:

    C:\ProgramData\Microsoft\Windows\Start Menu

  • windows_folder_common_startup: Directory that stores common Startup program group

    Example values:

    C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Startup

  • windows_folder_common_templates: Directory that stores common templates

    Example values:

    C:\ProgramData\Microsoft\Windows\Templates

  • windows_folder_common_video: Directory that stores common video files

    Example values:

    C:\Users\Public\Videos

Cross-platform Folders
  • installdir: The installation directory

    Example values:

    /home/user/programx, C:\Program Files\programx

  • installer_directory: The directory location of the installer binary

    Example values:

    /home/user/example, C:\example

  • installer_pathname: The full path of the installer binary

    Example values:

    /home/user/example/installer.bin, C:\example\installer.exe

  • platform_install_prefix: The platform specific default installation path

    Example values:

    /home/user, C:\Program Files, /Applications

  • system_temp_directory: Path to the system’s temporary directory

    Example values:

    /tmp, C:\Users\Username\Appdata\Local\Temp

  • user_home_directory: Path to the home directory of the user who is running the installer

    Example values:

    /home/username, C:\Users\Username

Build-time Variables
  • build_project_directory: Directory containing the XML project used to generate the installer.

    Example values:

    /home/username/installbuilder-7.0.0/projects, C:\Program Files\Bitrock InstallBuilder for Windows 7.0.0\projects

  • installbuilder_install_root: Installation directory of InstallBuilder. This variable is available only at build time, as it does not make sense to access this information at runtime

    Example values:

    /home/username/installbuilder-7.0.0, C:\Program Files\Bitrock InstallBuilder for Windows 7.0.0

  • installbuilder_output_directory: InstallBuilder output directory. This variable is available only at build time, as it does not make sense to access this information at runtime

    Example values:

    /home/username/installbuilder-7.0.0/output, C:\Program Files\Bitrock InstallBuilder for Windows 7.0.0\output

  • installbuilder_output_filename: Location of the generated installer. This variable is available only at build time, as it does not make sense to access this information at runtime

    Example values:

    /home/username/installbuilder-7.0.0/output/sample-1.0-linux-installer.run, C:\Program Files\Bitrock InstallBuilder for Windows 7.0.0\output\sample-1.0-window-installer.exe

  • installbuilder_ui: The mode in which the builder is run

    Possible values:

    gui, text

Windows Folders - User Scope
  • windows_folder_admintools: Directory that stores administrator tools for individual user

    Example values:

    C:\Users\Administrator\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Administrative Tools

  • windows_folder_appdata: Directory that stores user application-specific data

    Example values:

    C:\Users\Administrator\AppData\Roaming

  • windows_folder_cookies: Directory that stores user cookies

    Example values:

    C:\Users\Administrator\AppData\Roaming\Microsoft\Windows\Cookies

  • windows_folder_desktopdirectory: Directory that stores user desktop files

    Example values:

    C:\Users\Administrator\Desktop

  • windows_folder_favorites: Directory that stores user favorite items

    Example values:

    C:\Users\Administrator\Favorites

  • windows_folder_history: Directory that stores user Internet history items

    Example values:

    C:\Users\Administrator\AppData\Local\Microsoft\Windows\History

  • windows_folder_internet_cache: Directory that stores user temporary internet files

    Example values:

    C:\Users\Administrator\AppData\Local\Microsoft\Windows\Temporary Internet Files

  • windows_folder_local_appdata: Directory that stores user local (non-roaming) repository for application-specific data

    Example values:

    C:\Users\Administrator\AppData\Local

  • windows_folder_mymusic: Directory that stores user music files

    Example values:

    C:\Users\Administrator\Music

  • windows_folder_mypictures: Directory that stores user picture files

    Example values:

    C:\Users\Administrator\Pictures

  • windows_folder_myvideo: Directory that stores user video files

    Example values:

    C:\Users\Administrator\Videos

  • windows_folder_nethood: Directory that stores user network shortcuts

    Example values:

    C:\Users\Administrator\AppData\Roaming\Microsoft\Windows\Network Shortcuts

  • windows_folder_personal: Directory that stores user document files

    Example values:

    C:\Users\Administrator\Documents

  • windows_folder_printhood: Directory that stores printer shortcuts

    Example values:

    C:\Users\Administrator\AppData\Roaming\Microsoft\Windows\Printer Shortcuts

  • windows_folder_profile: Directory that stores user profile

    Example values:

    C:\Users\Administrator

  • windows_folder_programs: Directory that stores user program groups in start menu

    Example values:

    C:\Users\Administrator\AppData\Roaming\Microsoft\Windows\Start Menu\Programs

  • windows_folder_recent: Directory that stores shortcuts to user’s recently used documents

    Example values:

    C:\Users\Administrator\AppData\Roaming\Microsoft\Windows\Recent

  • windows_folder_sendto: Directory that stores user Send To menu items

    Example values:

    C:\Users\Administrator\AppData\Roaming\Microsoft\Windows\SendTo

  • windows_folder_startmenu: Directory that stores user start menu items

    Example values:

    C:\Users\Administrator\AppData\Roaming\Microsoft\Windows\Start Menu

  • windows_folder_startup: Directory that stores user Startup program group

    Example values:

    C:\Users\Administrator\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup

  • windows_folder_templates: Directory that stores user templates

    Example values:

    C:\Users\Administrator\AppData\Roaming\Microsoft\Windows\Templates

Linux Specific
  • linux_distribution: Type of Linux distribution

    Possible values:

    gentoo, suse, redhat, redflag, slackware, fedora, arch, amazon, mandrake, debian

  • linux_distribution_codename: Linux distribution code name (based on Linux Standard Base tool: lsb_release)

  • linux_distribution_description: Linux distribution description (based on Linux Standard Base tool: lsb_release)

    Example values:

    Debian, GNU/Linux

  • linux_distribution_fullname: Linux distribution fullname

    Possible values:

    Suse, Scientific Linux, Fedora, Core, Flag, openSUSE, Red, Mandrake, Red Hat Linux, Red Hat Enterprise Linux, Debian, Gentoo, CentOS, SME Server Linux, Slackware, Arch

  • linux_distribution_id: Linux distribution distributor’s ID (based on Linux Standard Base tool: lsb_release)

    Example values:

    Debian

  • linux_distribution_release: Linux distribution release number(based on Linux Standard Base tool: lsb_release)

    Example values:

    3.1

  • linux_distribution_shortname: Linux distribution shortname

    Possible values:

    gentoo, suse, redflag, slackware, fedora, arch, amazon, rh, mandrake, debian, rhel

  • linux_distribution_version: Linux distribution mayor version

    Example values:

    5.0

OSX Specific
  • osx_major_version: OSX major version number

    Example values:

    10.3, 10.5

  • osx_version: OSX version number

    Example values:

    10.3.9, 10.5.7

Windows Specific
  • windows_os_family: Type of Windows OS

    Possible values:

    Windows NT, Windows 95

  • windows_os_family_shortname: Windows OS family shortname

    Possible values:

    winnt, win9x

  • windows_os_flavor: Flavor of Windows OS

    Possible values:

    Home Premium, Enterprise, Home, Standard, Essentials, Home Basic, Storage Server Workgroup, Ultimate, Foundation, Server, Web Edition, Data Center, Storage Server, Business, Workstation, Storage Server Standard, Starter, Advanced Server, Professional

  • windows_os_name: Windows OS name

    Possible values:

    Windows 2012, Windows 7, Windows 8.1, Windows 8, Windows 2016, Windows 2012 R2, Windows 2000, Windows 2003, Windows 95, Windows 2008 R2, Windows Vista, Windows XP, Windows 7 WSLK, Windows 10, Windows 98, Windows 2008

  • windows_os_service_pack: Windows OS Service Pack version number

    Example values:

    1, 2, 3

  • windows_os_uac_enabled: Whether or not UAC is enabled

    Possible values:

    0, 1

  • windows_os_version_number: Windows OS version number

    Possible values:

    6.0, 5.1, 7.0, 6.1, 5.2, 4.0, 5.0, 4.1

System Configuration
  • machine_cpu_count: Number of CPUs in the machine

    Example values:

    1, 2

  • machine_cpu_speed: The machine’s CPU speed in MHZ

    Example values:

    1500

  • machine_fqdn: The machine’s fully qualified domain name

    Example values:

    bitrock-desktop.mydomain.com

  • machine_hostname: The machine’s hostname

    Example values:

    example.com

  • machine_ipaddr: The machine’s IP address

    Example values:

    10.0.0.2

  • machine_swap_memory: The machine’s swap memory in MB

    Example values:

    512

  • machine_total_memory: The machine’s total physical memory in MB

    Example values:

    512

  • platform_exec_suffix: The platform specific binary suffix

    Possible values:

    app, run, exe

  • platform_has_smp: Whether or not the machine has multiple processors

    Possible values:

    0, 1

  • platform_name: At build-time, it contains the target build platform. At runtime, the platform in which the installer is running

    Possible values:

    linux, osx, windows

  • platform_path_separator: The platform specific path separator

    Possible values:

    \, /

  • system_locale: Current system locale

    Possible values:

    es, lt, sv, ro, et, lv, ko, eu, az, cy, pt, it, id, da, tr, sk, va, sl, ru, fa, pt_BR, fr, el, de, bg, zh_CN, es_AR, hr, nl, ja, en, ar, zh_TW, th, pl, sq, ca, sr, no, hu, he, kk, cs, vi, tk, fi

  • system_username: Name of the user who is running the installer

    Example values:

    root, Administrator, guest

Installer Page Order Control
  • back_page: The previous page to show

    Example values:

    installdir, welcome, installation, installationFinished

  • next_page: The next page to show

    Example values:

    installdir, welcome, installation, installationFinished

5. Components

Depending on the complexity of your software, you may need to split your project into several components. Components are a bundle of folders and associated installation logic.

They are able to execute actions (include Action Lists), copy files and prompt the user for data (display Parameters), as the project does:

<component>
    <name>component</name>
    <description>component</description>
    <detailedDescription>This is a component</detailedDescription>
    <initializationActionList>
        <setInstallerVariable name="my_variable" value="1" />
    </initializationActionList>
    <parameterList>
        <booleanParameter>
            <name>boolean_question</name>
            <title>Boolean Question</title>
            <description>Please answer yes or no</description>
        </booleanParameter>
    </parameterList>
    <folderList>
        <folder>
            <description>Program Files</description>
            <destination>${installdir}</destination>
            <name>programfiles</name>
            <platforms>all</platforms>
            <distributionFileList>
                <distributionDirectory origin="program" />
            </distributionFileList>
        </folder>
    </folderList>
</component>

The ability to enable / disable components at build time and runtime allows your installer to provide as many setup combinations as you need.

The basic properties you should configure when adding a component are:

  • <name>: Name of the Component. This name must be unique and just contain alphanumeric characters and underscores.

  • <description>: Description of the Component. This description will be included in the list of the visible components presented to the user.

  • <detailedDescription>: A detailed description of the component. This detailed description will be displayed when clicking in the component description in the component selection page.

  • <selected>: Whether or not the component is selected. If the component is not selected, its action lists won’t be executed and its folders won’t be unpacked.

  • <show>: Whether or not the component is visible in the component selection page.

  • <canBeEdited>: Whether or not the component can be edited in the component selection page.

  • <requiredSize>: Required disk space in the target system. If 0, then it will automatically be calculated based on the size of the packed files. The sum of the sizes of all of the installed components can be later accessed through the built-in variable ${required_diskspace}.

Components are defined in the project <componentList> and presented to the end user as in the Figure 23:

Component Selection Page
Figure 23: Component Selection Page

As mentioned above, depending on the value of <show>, the component will be visible or not, and if so, the <canBeEdited> property will decide if the user will be able to select and deselect it.

The example below illustrates some of the possible combinations when including components:

<project>
    ...
    <!-- Shows the component selection page -->
    <allowComponentSelection>1</allowComponentSelection>
    ...
    <componentList>
        <!-- Main base component, it must be always
        installed. We hide it  -->
        <component>
            ...
            <name>main</name>
            <selected>1</selected>
            <show>0</show>
            ...
        </component>
        ...
        <!-- Important required component. We show it
        in the component selection but made it mandatory
        to install -->
        <component>
            ...
            <name>core</name>
            <description>Core product</description>
            <detailedDescription>This is the base of the application.</detailedDescription>
            <selected>1</selected>
            <show>1</show>
            <canBeEdited>0</canBeEdited>
            ...
        </component>
        ...
        <!-- Optional Useful Component. We allow deselecting it but we suggest it
        by default setting show=1 -->
        <component>
            ...
            <name>docs</name>
            <description>Documentation</description>
            <detailedDescription>Documentation of the product</detailedDescription>
            <selected>1</selected>
            <show>1</show>
            <canBeEdited>1</canBeEdited>
            ...
        </component>

        <!-- Additional Optional Component. It is not very important so
        we do not include it by default (show=0)  -->
        <component>
            ...
            <name>extra</name>
            <description>Extra files</description>
            <detailedDescription>Extra files including images
            and translation files</detailedDescription>
            <selected>0</selected>
            <show>1</show>
            <canBeEdited>1</canBeEdited>
            ...
        </component>
    </componentList>
    ...
</project>

Please note that the code also enables <allowComponentSelection>1</allowComponentSelection>. This setting makes the component selection page (which is hidden by default) visible to the end user.

5.1. Enabling and disabling components

The easiest way of configuring if a component will be selected or not is by modifying its <selected> property:

<componentList>
   <!-- This component is selected -->
   <component>
     ...
     <name>component1</name>
     ...
     <selected>1</selected>
     ...
   </component>
   <!-- This component is not selected -->
   <component>
     ...
     <name>component2</name>
     ...
     <selected>0</selected>
     ...
   </component>
</componentList>

However, in most of the cases you will need to decide whether to select or not components at runtime, based on certain conditions. For this purpose, InstallBuilder includes a <componentSelection> action. For example, if you detect and existing installation of your product, you may want to deselect your core component and select the update component:

<project>
  ...
  <componentList>
    <component>
      <name>core</name>
      ...
      <selected>1</selected>
      ...
    </component>
    <component>
      <name>update</name>
      ...
      <selected>0</selected>
      ...
    </component>
  </componentList>
  <readyToInstallActionList>
     <componentSelection>
        <deselect>core</deselect>
        <select>update</select>
        <ruleList>
           <fileExists path="${installdir}/wellKnown/file"/>
        </ruleList>
     </componentSelection>
  </readyToInstallActionList>
  ...
</project>

The <componentSelection> action also accepts multiple components to select or deselect, separated by commas, in its <deselect> and <select> tags. This way you can change the behavior of the installer with a single action.

The code below explains how to prompt the user to select between a minimal (core components), standard (core and useful components) and full installation (also include documentation and videos):

<project>
  ...
  <allowComponentSelection>0</allowComponentSelection>
  ...
  <componentList>
    <component>
      <name>core</name>
      ...
    </component>
    <component>
      <name>xmlEditor</name>
      ...
    </component>
    <component>
      <name>debugger</name>
      ...
    </component>
    <component>
      <name>documentation</name>
      ...
    </component>
    <component>
      <name>videos</name>
      ...
    </component>
  </componentList>
  ...
  <parameterList>
     <choiceParameter>
        <name>installationMode</name>
        <ask>1</ask>
        <default>normal</default>
        <description>Please select the installation mode</description>
        <title>Installation Mode</title>
        <optionList>
           <option>
             <value>minimal</value>
             <text>Minimal</text>
           </option>
           <option>
             <value>standard</value>
             <text>Standard</text>
           </option>
           <option>
             <value>full</value>
             <text>Full</text>
           </option>
        </optionList>
        <postShowPageActionList>
           <componentSelection>
              <deselect>xmlEditor,debugger,documentation,videos</deselect>
              <select>core</select>
              <ruleList>
                 <compareText>
                   <text>${installationMode}</text>
                   <logic>equals</logic>
                   <value>minimal</value>
                 </compareText>
              </ruleList>
           </componentSelection>
           <componentSelection>
              <deselect>documentation,videos</deselect>
              <select>core,xmlEditor,debugger</select>
              <ruleList>
                 <compareText>
                   <text>${installationMode}</text>
                   <logic>equals</logic>
                   <value>standard</value>
                 </compareText>
              </ruleList>
           </componentSelection>
           <componentSelection>
              <deselect></deselect>
              <select>core,xmlEditor,debugger,documentation,videos</select>
              <ruleList>
                 <compareText>
                   <text>${installationMode}</text>
                   <logic>equals</logic>
                   <value>full</value>
                 </compareText>
              </ruleList>
           </componentSelection>
        </postShowPageActionList>
     </choiceParameter>
  </parameterList>
  ...
</project>

You can also check the state of a component using the <componentTest> rule:

<throwError>
  <text>You cannot install 'Component A' and 'Component B' at the same time!</text>
  <ruleList>
     <componentTest name="componentA" logic="selected"/>
     <componentTest name="componentB" logic="selected"/>
  </ruleList>
</throwError>

Another way of selecting or deselecting a component is to directly modify the <selected> property using the <setInstallerVariable> action as explained in the Advanced Syntax section:

  <setInstallerVariable name="project.component(core).selected" value="0"/>

The same way, you can check if a component is selected (or any other of its properties):

<directoryParameter>
   <name>installdir</name>
   <validationActionList>
      <actionGroup>
         <actionList>
            <getFreeDiskSpace path="${installdir}" units="KB" variable="diskSpace"/>
            <throwError>
              <text>You don't have enough disk space to install
              ${project.component(bigComponent).description}</text>
              <ruleList>
                <compareValues>
                  <value1>${project.component(bigComponent).requiredSize}</value1>
                  <logic>greater</logic>
                  <value2>${diskSpace}</value2>
                </compareValues>
              </ruleList>
            </throwError>
         </actionList>
         <ruleList>
           <isTrue value="${project.component(bigComponent).selected}"/>
         </ruleList>
      </actionGroup>
   </validationActionList>
</directoryParameter>

Finally, visible and editable components can also be selected and deselected using the command line:

$> /path/to/installer --disable-components windowsdata,unixdata --enable-components osxdata

Where --disable-components and --enable-components accept a comma-separated list of components. Only visible components (<show>1</show>) will be displayed in the help menu and only those which are also editable (<canBeEdited>1</canBeEdited>) will be configurable using these flags. For example, if your project has the component list below:

 <componentList>
    <!-- Main base component, it must be always
    installed. We hide it  -->
    <component>
       ...
       <name>main</name>
       <selected>1</selected>
       <show>0</show>
       ...
    </component>
    ...
    <!-- Important required component. We show it
    in the component selection but made it mandatory
    to install -->
    <component>
       ...
       <name>core</name>
       <description>Core product</description>
       <selected>1</selected>
       <show>1</show>
       <canBeEdited>0</canBeEdited>
       ...
    </component>
    ...
    <!-- Optional Useful Component. We allow deselecting it but we suggest it
    by default setting show=1 -->
    <component>
       ...
       <name>docs</name>
       <selected>1</selected>
       <show>1</show>
       <canBeEdited>1</canBeEdited>
       ...
    </component>
    <!-- Additional Optional Component. It is not very important so
    we do not include it by default (show=0)  -->
    <component>
       ...
       <name>extra</name>
       <selected>0</selected>
       <show>1</show>
       <canBeEdited>1</canBeEdited>
       ...
    </component>
 </componentList>

The output in the help menu will be:

 --enable-components <enable-components> Comma-separated list of components
                                Default: core,docs
                                Allowed: docs extra

 --disable-components <disable-components> Comma-separated list of components
                                Default: extra
                                Allowed: docs extra

In this output, main is not mentioned, as it was configured as hidden, and just docs and extra are allowed values, as core was configured as a non-editable component and always selected.

These command line options are only available if <allowComponentSelection> is enabled.

Note
Only the hardcoded state of the components is considered when displaying the help menu.

As the help menu is completely independent from regular action lists, even if you are changing the components properties in the <initializationActionList> using a <setInstallerVariable> action, the changes won’t be visible when displaying the help. For example:

 <componentList>
    <!-- Main base component, it must be always
    installed. We hide it  -->
    <component>
       ...
       <name>A</name>
       <selected>1</selected>
       <show>0</show>
       ...
    </component>
    <component>
       ...
       <name>B</name>
       <selected>1</selected>
       <show>0</show>
       ...
    </component>
    <component>
       ...
       <name>C</name>
       <selected>1</selected>
       <show>0</show>
       ...
    </component>
 </componentList>
 <initializationActionList>
   <setInstallerVariable name="component(A).show" value="1"/>
   <setInstallerVariable name="component(B).show" value="1"/>
   <setInstallerVariable name="component(C).show" value="1"/>
 </initializationActionList>

Will result in an empty list of components in the help menu:

 --enable-components <enable-components> Comma-separated list of components
                                Default:

 --disable-components <disable-components> Comma-separated list of components
                                Default:

But all of them will be visible and editable in the graphical component selection.

Note
The <selected> property cannot contain variables

The component <selected> tag cannot contain variables. The below component will always be deselected, regardless of the value of the variable:

<project>
  ...
  <componentList>
    <component>
       ...
       <name>documentation</name>
       ...
       <!-- The variable won't be resolved, so it will
       be considered false -->
       <selected>${installDocumentation}</selected>
       ...
    </component>
  </componentList>
  ...
</project>

If you need to bind a boolean variable to the <selected> tag, you should modify the property using a <setInstallerVariable> instead:

<booleanParameter>
    <name>installDocumentation</name>
    <title>Documentation</title>
    <description>Would you like to install the documentation files?</description>
    <postShowPageActionList>
       <setInstallerVariable>
          <name>project.component(documentation).selected</name>
          <value>${installDocumentation}</value>
       </setInstallerVariable>
    </postShowPageActionList>
</booleanParameter>

5.2. Component Action Lists

Components can include all of the Action Lists available for the main project with the exception of the <preShowHelpActionList> and the <finalPageActionList.

In addition, components include a few new action lists:

5.2.1. Component Selection Validation Actions

The <componentSelectionValidationActionList> is executed right after clicking Next in the component selection page and allows checking if the provided component configuration is valid. It works the same way as the <validationActionList>; if an error is thrown inside it, instead of aborting the installation, the error message is displayed and the page redrawn.

This is really useful when implementing dependencies between components:

<project>
    ...
    <allowComponentSelection>1</allowComponentSelection>
    ...
    <componentList>
      <component>
        ...
        <name>A</name>
        ...
      </component>
      <component>
        ...
        <name>B</name>
        ...
      </component>
      <component>
        <name>C</name>
        <description>Component C</description>
        <detailedDescription>This component depends on 'A' and 'B'</detailedDescription>
        ...
        <componentSelectionValidationActionList>
          <throwError>
            <text>Component 'C' cannot be installed if you have not selected both 'A' and 'B'.</text>
            <ruleList>
              <isFalse value="${component(A).selected}"/>
              <isFalse value="${component(B).selected}" />
            </ruleList>
          </throwError>
        </componentSelectionValidationActionList>
        ...
      </component>
      ...
    </componentList>
    ...
</project>

The <componentSelectionValidationActionList> is only executed when the component selection page is displayed and the component defining the validation is selected (regardless of whether or not it is visible). This could be an issue if, for example, you need to validate that at least one of two optional components are selected and if the user deselects them, none of the validations will be executed. In these cases, you can use a hidden component, just used to validate the others:

How to establish dependencies between components

<project>
    ...
    <allowComponentSelection>1</allowComponentSelection>
    ...
    <componentList>
      <component>
        ...
        <name>A</name>
        ...
      </component>
      <component>
        ...
        <name>B</name>
        ...
      </component>
      <component>
        <name>validatorComponent</name>
        <selected>1</selected>
        <show>0</show>
        ...
        <componentSelectionValidationActionList>
          <throwError>
            <text>You have to select at least one component.</text>
            <ruleList>
              <isFalse value="${component(A).selected}"/>
              <isFalse value="${component(B).selected}" />
            </ruleList>
          </throwError>
        </componentSelectionValidationActionList>
        ...
      </component>
      ...
    </componentList>
    ...
</project>

5.2.2. On Download Error Actions

If the component was marked as <downloadable> and the installer was built accordingly (check the Downloadable components section for more details), the <onDownloadErrorActionList> allows providing a set of of actions to execute if the download process fails and the user decides to ignore it.

This allows properly recovering from the error, for example, deselecting other components that depend on it.

5.3. Adding files and directories

Components can also contain a list of <folder> elements, which are mainly used to define files to pack:

<component>
   ...
   <name>default</name>
   ...
   <folderList>
     <!-- The installation directory -->
     <folder>
        <name>programfiles</name>
        <description>Program Files</description>
        <destination>${installdir}</destination>
        <platforms>all</platforms>
        <distributionFileList>
          <distributionFile>
            <origin>/path/to/file.txt</origin>
          </distributionFile>
          ...
          <distributionDirectory>
            <origin>/path/to/directory</origin>
          </distributionDirectory>
          ...
        </distributionFileList>
     </folder>

     <!-- Configuration files that should be installed inside
     /etc, and for linux only -->
     <folder>
        <name>linuxconfigfiles</name>
        <description>Linux Configuration Files</description>
        <destination>/etc</destination>
        <platforms>linux</platforms>
        <distributionFileList>
           ...
        </distributionFileList>
     </folder>
   </folderList>
   ...
</component>

The next section explains in detail how to work with folders.

5.4. Adding shortcuts to the components

Each component has three shortcut lists which can be used to create shortcuts:

 <component>
   <name>default</name>
   ...
   <desktopShortcutList>
     <!-- Intended to launch an application -->
     <shortcut>
        <comment>Launch My Program</comment>
        <exec>${installdir}/bin/myprogram</exec>
        <icon></icon>
        <name>My Program</name>
        <path>${installdir}/bin</path>
        <platforms>all</platforms>
        <runInTerminal>0</runInTerminal>
        <windowsExec>${installdir}/bin/myprogram.exe</windowsExec>
        <windowsExecArgs></windowsExecArgs>
        <windowsIcon></windowsIcon>
        <windowsPath>${installdir}/bin</windowsPath>
     </shortcut>

     <!-- Intended to launch a web browser pointing to a specific url -->
     <linkShortcut>
        <comment>Launch a web browser pointing to My Program website</comment>
        <icon></icon>
        <name>Visit My Program website</name>
        <platforms>all</platforms>
        <runInTerminal>0</runInTerminal>
        <url>http://www.example.com/myprogram</url>
        <windowsIcon></windowsIcon>
     </linkShortcut>

     <!-- Intended to launch a viewer for a specific file -->
     <fileShortcut>
        <comment>Check the user guide</comment>
        <filePath>${installdir}/doc/userguide.pdf</filePath>
        <icon></icon>
        <name>My Program User Guide</name>
        <platforms>all</platforms>
        <runInTerminal>0</runInTerminal>
        <windowsIcon></windowsIcon>
     </fileShortcut>
     ...
   </desktopShortcutList>
   ...
 </component>

 <component>
   <name>default</name>
   ...
   <startMenuShortcutList>
     <!-- Intended to launch an application -->
     <startMenuShortcut>
        <comment>Launch My Program</comment>
        <exec>${installdir}/bin/myprogram</exec>
        <icon></icon>
        <name>My Program</name>
        <path>${installdir}/bin</path>
        <platforms>all</platforms>
        <runInTerminal>0</runInTerminal>
        <windowsExec>${installdir}/bin/myprogram.exe</windowsExec>
        <windowsExecArgs></windowsExecArgs>
        <windowsIcon></windowsIcon>
        <windowsPath>${installdir}/bin</windowsPath>
     </startMenuShortcut>

     <!-- Intended to launch a web browser pointing to a specific url -->
     <startMenuLinkShortcut>
        <comment>Launch a web browser pointing to My Program website</comment>
        <icon></icon>
        <name>Visit My Program website</name>
        <platforms>all</platforms>
        <runInTerminal>0</runInTerminal>
        <url>http://www.example.com/myprogram</url>
        <windowsIcon></windowsIcon>
     </startMenuLinkShortcut>

     <!-- Intended to launch a viewer for a specific file -->
     <startMenuFileShortcut>
        <comment>Check the user guide</comment>
        <filePath>${installdir}/doc/userguide.pdf</filePath>
        <icon></icon>
        <name>My Program User Guide</name>
        <platforms>all</platforms>
        <runInTerminal>0</runInTerminal>
        <windowsIcon></windowsIcon>
     </startMenuFileShortcut>
     ...
   </startMenuShortcutList>
   ...
 </component>

 <component>
   <name>default</name>
   ...
   <quickLaunchShortcutList>
     <!-- Intended to launch an application -->
     <quickLaunchShortcut>
        <comment>Launch My Program</comment>
        <exec>${installdir}/bin/myprogram</exec>
        <icon></icon>
        <name>My Program</name>
        <path>${installdir}/bin</path>
        <platforms>all</platforms>
        <runInTerminal>0</runInTerminal>
        <windowsExec>${installdir}/bin/myprogram.exe</windowsExec>
        <windowsExecArgs></windowsExecArgs>
        <windowsIcon></windowsIcon>
        <windowsPath>${installdir}/bin</windowsPath>
     </quickLaunchShortcut>

     <!-- Intended to launch a web browser pointing to a specific url -->
     <quickLaunchLinkShortcut>
        <comment>Launch a web browser pointing to My Program website</comment>
        <icon></icon>
        <name>Visit My Program website</name>
        <platforms>all</platforms>
        <runInTerminal>0</runInTerminal>
        <url>http://www.example.com/myprogram</url>
        <windowsIcon></windowsIcon>
     </quickLaunchLinkShortcut>

     <!-- Intended to launch a viewer for a specific file -->
     <quickLaunchFileShortcut>
        <comment>Check the user guide</comment>
        <filePath>${installdir}/doc/userguide.pdf</filePath>
        <icon></icon>
        <name>My Program User Guide</name>
        <platforms>all</platforms>
        <runInTerminal>0</runInTerminal>
        <windowsIcon></windowsIcon>
     </quickLaunchFileShortcut>
     ...
   </quickLaunchShortcutList>
   ...
 </component>

5.5. Adding components from external files

Components can also be extracted to a different file, making them usable as modules between different projects. These external files can be later inserted in the <componentList> using the <include> directive as seen in the code below:

<componentList>
    <include file="my_external_component.xml" />
</componentList>

Of course, you can mix external and internal components in the project file

<componentList>
    <component>
        <name>internal</name>
    </component>
    <include file="my_external_component.xml" />
</componentList>

In fact, the <include> directive can be used to include any external piece of XML code in any place of the project if some conditions are met:

  • The parent XML node is a <*List> tag: <actionList>, <parameterList>, <ruleList>

  • The inserted code is valid in the insertion point. For example, trying to include a file containing a <showInfo> action in a <ruleList> will fail.

  • The inserted XML code is grouped in a single element. For example, inserting a code containing two <runProgram> actions will fail but inserting an <actionGroup> with multiple actions on it will work.

<project>
    <shortName>sample</shortName>
    <fullName>Sample Project</fullName>
    <version>1.0</version>
    <enableRollback>1</enableRollback>
    <enableTimestamp>1</enableTimestamp>
    <componentList>
        <!-- component.xml contains a component -->
        <include file="path/to/component.xml"/>
        <component>
            <name>default</name>
            <description>Default Component</description>
            <canBeEdited>1</canBeEdited>
            <selected>1</selected>
            <show>1</show>
            <folderList>
              <!-- folder.xml contains a folder -->
              <include file="path/to/folder.xml"/>
            </folderList>
        </component>
    </componentList>
    <parameterList>
        <!-- installdir.xml contains a directory parameter -->
        <include file="path/to/installdir.xml"/>
        <booleanParameter>
            <name>boolean_question</name>
            <title>Boolean Question</title>
            <description>Please answer yes or no</description>
            <validationActionList>
               <!-- validationActions.xml contains an actionGroup -->
               <include file="path/to/validationActions.xml"/>
               <throwError text="You must click yes!" >
                  <ruleList>
                     <!-- isTrue.xml contains a set of rules in a ruleGroup -->
                     <include file="path/to/isTrue.xml"/>
                  </ruleList>
               </throwError>
            </validationActionList>
        </booleanParameter>
       ...
    </parameterList>
    ...
</project>

It is not possible to configure whether or not an <include> should be inserted. The <include> directives are evaluated when loading the project so they cannot contain variables or rules.

5.6. Excluding components at build time

Although a component can be disabled and hidden at runtime by modifying its <selected> and <show> properties, sometimes it is desirable to do not bundle them at all. In these situations, you can use the <shouldPackRuleList>. This set of rules is evaluated at build time and will decide whether or not the component containing them will be packed. For example, to just pack a component when building for OS X:

   <component>
       <name>osxComponent</name>
       <description>OS X Component</description>
       <canBeEdited>1</canBeEdited>
       <selected>1</selected>
       <show>1</show>
       ...
       <shouldPackRuleEvaluationLogic>and</shouldPackRuleEvaluationLogic>
       <shouldPackRuleList>
           <compareText>
               <logic>equals</logic>
               <text>${platform_name}</text>
               <value>osx</value>
           </compareText>
       </shouldPackRuleList>
   </component>

Please note the usage of the built-in variable ${platform_name}, which contains the build target at build time. In this case, using a <platformTest> will not work because it would evaluate the platform in which the builder is running and not the platform for which the installer is being built.

The same way as a <ruleList>, the <shouldPackRuleList> can contain <ruleGroup> rules to create complex conditions. You can also configure its rule evaluation logic using the <shouldPackRuleEvaluationLogic> property.

5.7. Component Groups

A <componentGroup> is a special type of <component> that can contains other components in its <componentList>:

<project>
    ...
    <componentList>

        <!-- componentGroup, a component with sub-components -->
        <componentGroup>
            <name>application1</name>
            <description>Application 1</description>
            ...
            <folderList>
                ...
            </folderList>
            <componentList>
                <component>
                    <name>feature1</name>
                    <description>Optional feature 1</description>
                    <folderList>
                        ...
                    </folderList>
                </component>
                <component>
                    <name>feature2</name>
                    <description>Optional feature 2</description>
                    <folderList>
                        ...
                    </folderList>
                </component>

                <!-- embedding a group inside a group -->
                <componentGroup>
                    <name>feature3</name>
                    <description>Optional feature 3</description>
                    <componentList>
                        <component>
                            <name>feature4</name>
                            <description>Optional feature 4</description>
                            <folderList>
                                ...
                            </folderList>
                        </component>
                    </componentList>
                    <folderList>
                        ...
                    </folderList>
                </componentGroup>
            </componentList>
        </componentGroup>

        <component>
            <name>application2</name>
            <description>Application 2</description>
            <folderList>
                ...
            </folderList>
        </component>

        <!-- component group that is always selected and cannot be edited -->
        <componentGroup>
            <name>application3</name>
            <description>Application 3</description>
            <selected>1</selected>
            <canBeEdited>0</canBeEdited>
            <folderList>
                ...
            </folderList>
            <componentList>
                <component>
                    <name>feature5</name>
                    <description>Optional feature 5</description>
                    <folderList>
                        ...
                    </folderList>
                </component>
            </componentList>
        </componentGroup>
    </componentList>
    ...
</project>

Component groups are displayed as a tree in the component selection page, where the user may choose to install any subset of its sub-components.

The following image shows the component selection screen for the example above:

Component selection screen
Figure 24: Component selection screen

As with a regular component, a component group can include its own files (in its <folderList>) and actions.

Component groups may also be nested, creating multiple levels. This can be done by embedding a <componentGroup> in the <componentList> of another <componentGroup>. The feature4 component is an example of this - it is inside the feature3 <componentGroup>, which is a sub-component of application1.

A child component will be installed only if it is selected and all of its parent component groups are selected as well. For example, if application1 is not selected, then regardless of whether or not feature1 was previously selected, it will not be installed. In the GUI component selection, this behavior is represented by visually deselecting all of the child components when deselecting a parent. For example, the following shows that when application1 is deselected, all of its child components are automatically deselected and cannot be edited:

Component selection screen
Figure 25: Component selection screen

Selecting a child component for installation requires enabling its parent components. In the example, in order to install feature1, the user first has to select application1 by clicking on the checkbox next to it. This will allow editing of the children of application1. Similarly, to enable feature4, the user needs to select both the application1 and feature3 component groups.

Specifying which components to enable from the command line differs in behavior. Whenever the user specifies --enable-components, all parents of specified components are also automatically selected. For example, if the user specifies that feature4 should be enabled, feature3 and application1 are automatically selected.

5.7.1. Installing in text mode

When running an installer in text mode, sub-components can only be chosen if a parent has been chosen. For example:

 $> /path/to/installer --mode text

...

Select the components you want to install; clear the components you do not want
to install. Click Next when you are ready to continue.

Application 1 [Y/n] :y

Application 1 - Optional feature 1 [Y/n] :y

Application 1 - Optional feature 2 [Y/n] :y

Application 1 - Optional feature 3 [Y/n] :n

Application 2 [Y/n] :y

Application 3 : Y (Cannot be edited)

Application 3 - Optional feature 5 [Y/n] :n

...

Please note that the user was not asked about feature4 since the feature3 component group was not selected.

As a regular parameter group, a <componentGroup> with its <show> property set to false won’t be visible, hidden its child as well.

If a <componentGroup> has its <canBeEdited> set to false but is selected by default, its sub-components can be still edited (if they individually allow it). However, in the case of a deselected component group that cannot be edited, their child won’t allow any user interaction, regardless of their individual configurations.

5.8. Downloadable components

InstallBuilder provides the ability to configure some or all of the available components to be separate, downloadable content instead of being embedded in the installer. This means that elements of the application that are not always used can be made downloadable to decrease an installer’s size.

Each downloadable component is built as a separate file for each platform. After building a project, its components should be copied to a web server or file hosting service so that users can download it.

5.8.1. How to create downloadable components

Any existing or new project can be configured to have its components downloadable as separate files.

To do so, enable the <downloadable> tag for any <component> in the project that should be made downloadable.

In addition, the <componentsUrl> should be a URL that points to the directory where all files are to be placed.

For example, the following is a complete project, including the URL where the components will be copied:

<project>
  <shortName>downloadabledemo</shortName>
  <version>1.0</version>
  <componentsUrl>http://example.com/installer/components/</componentsUrl>
  ...
  <componentList>
    <!-- component that should be embedded in the installer -->
    <component>
      <name>core</name>
      <description>Core features</description>
      ...
    </component>

    <!-- another component that should be embedded in the installer, specified explicitly -->
    <component>
      <name>osintegration</name>
      <downloadable>0</downloadable>
      <description>Integration with operating system</description>
      ...
    </component>

    <!-- another component that should be built as downloadable component -->
    <component>
      <name>optional</name>
      <downloadable>1</downloadable>
      <description>Optional content</description>
      ...
    </component>

  </componentList>
  ...
</project>

In order to build the project with downloadable components enabled, the --downloadable-components flag should be passed to the CLI.

 $> path/to/bin/builder build project.xml linux --downloadable-components

When using the GUI, the downloadable components checkbox should be enabled in the Build section before building the project.

After building the project for Linux, an additional directory downloadabledemo-1.0-components will be created with an optional-1.0-linux.pak file inside. When a project contains more components or is built for other platforms, additional files will be created in this directory.

After building the project, all contents of this directory should be uploaded to a web server so that they are available at <componentsUrl>. For the example above, the full URL should be http://example.com/installer/components/optional-1.0-linux.pak.

Some components may be available under different URLs. In this case, it is possible to specify the location using the <url> tag. The example below shows how optional content can be placed at a different URL:

<project>
  ...
  <componentList>
    <!-- another component that should be built as downloadable component -->
    <component>
      <name>optional3rdparty</name>
      <downloadable>1</downloadable>
      <description>Optional content, provided by other vendor</description>
      <url>http://example.net/downloads/optional3rdparty-1.0-${platform_name}.pak</url>
      ...
    </component>
  </componentList>
  ...
</project>

The component above will be downloaded from a different website using different platform names.

It is also possible to configure the directory for outputting the components using the <componentsDirectory> tag. This can be specified relatively. In this case it is relative to <outputDirectory>.

For example, to copy all component files into the same directory as <outputDirectory>, do the following:

<project>
  <componentsDirectory>.</componentsDirectory>
  ...
</project>

5.8.2. Running the installers with downloadable components

The behavior for installers with one or more downloadable components is the same as it is with regular installers.

The component selection page shows the downloadable file size for each component available for download:

Component selection with downloadable component
Figure 26: Component selection with downloadable component

If a user does not select any downloadable component, the installer does not perform any download or show any additional information related to downloading components.

If a user does want to install a downloadable component, after the Ready To Install page is shown, the user is presented with a proxy configuration page:

Proxy server configuration
Figure 27: Proxy server configuration

After the user configures or skips the proxy server configuration, the installer starts downloading the specified components:

Download progress
Figure 28: Download progress

If no error occurs, the installation proceeds when all components are downloaded and no user interaction is required.

In the event of an error, the user is prompted with three options:

Download error
Figure 29: Download error
  • Retry - retry the download

  • Ignore - do not attempt to download the current component and proceed without installing it

  • Abort - abort installation

5.8.3. Handling errors

In the event of download errors, the user is able to ignore the fact that a component could not be downloaded and proceed with the installation. It is possible to define actions that should be run when a component failed to download and the user chose to ignore it. For example:

<project>
  <shortName>downloadabledemo</shortName>
  <version>1.0</version>
  <componentsUrl>http://example.com/installer/components/</componentsUrl>
  ...
  <componentList>
    <component>
      <name>php</name>
      <downloadable>1</downloadable>
      <description>PHP module for Apache</description>
      <onDownloadErrorActionList>
        <throwError>
          <text>PHP module is required for phpMyAdmin. Aborting installation</text>
          <ruleList>
            <isTrue>
              <value>${project.component(phpmyadmin).selected}</value>
            </isTrue>
          </ruleList>
        </throwError>
      </onDownloadErrorActionList>
    </component>

  </componentList>
  ...
</project>

In this case, if the PHP module is not downloaded and another component depends on it, the installation will abort.

5.8.4. Text mode and unattended installers

Text mode installers provide the same support for downloadable components as GUI installers. After all parameters have been specified and at least one component needs to be downloaded, the user is prompted with a proxy configuration question. The user may choose to skip proxy configuration or specify it.

Next, downloading begins and the overall progress of installation is shown (this is the same feedback provided in the form of a progress meter for GUI installations).

Unattended installers also provide support for downloadable components. Components are downloaded and installation occurs automatically.

If unattendedmodeui is specified as minimalWithDialogs, progress for downloads is shown only as the overall download progress.

Download in unattended mode UI
Figure 30: Download in unattended mode UI

Similar to GUI installers, when all components are downloaded, the installation proceeds.

5.9. Adding or removing components to existing installations

InstallBuilder offers the ability to install and uninstall individual components without reinstalling or uninstalling the entire application.

This functionality is disabled by default. In order to enable it, enable <allowAddRemoveComponents>.

5.9.1. Storing installation information

InstallBuilder stores the location of all applications inside of the application directory. When performing an installation, the user specifies the directory where the application should be installed. If <allowAddRemoveComponents> is enabled, a check is made to see if a previous installation exists in specified directory before the component selection page is shown.

If it contains information about a previous installation, it is used by the installer. This information will consist of currently installed components and optionally for storing previous values for parameters that allow it.

It also contains information about the currently installed version. If the versions do not match, information about the currently selected components and values for parameters that allow it is used. However, all components are reinstalled in such a case.

5.9.2. Installing additional components

If <allowAddRemoveComponents> is enabled, the installer will automatically detect whenever a valid installation of the application is present in the installation directory.

Components previously installed will always be selected and the user will not be able to uninstall components using the installer. The user may choose to install additional components.

Whenever any change is made, all actions for newly selected components are run. However, actions for components previously installed are not run. This prevents actions that set up default values from overriding settings that user has already modified.

After a successful installation, the uninstaller and all related information will be updated to reflect that the user has installed additional components.

5.9.3. Uninstalling components

If <allowAddRemoveComponents> is enabled, running the uninstaller will show an additional choice page with the following options:

  • Entire application - removes the entire application and all files installed by the application

  • Individual components - removes individual components while leaving the rest of the application intact.

When a user selects the Entire application option, the behavior is the same as when <allowAddRemoveComponents> is disabled.

When a user selects Individual components, a component selection page will be shown. All components not currently installed will not be shown in the component selection tree. Components that have their <canBeEdited> disabled will not be editable.

When a user selects a component group, the component and all of its sub-components will be removed. For example if a user selects application1, this causes feature1, feature2, feature3 and feature4 to be uninstalled:

Selecting components to uninstall
Figure 31: Selecting components to uninstall

Selecting a component group to be uninstalled also causes all of its child components to be uninstalled. Those components are shown as selected and cannot be edited. For example the following shows that the component application1 will be uninstalled, which will also cause all of its child components to be uninstalled:

Selecting components to uninstall
Figure 32: Selecting components to uninstall

If a parent is deselected, the selection of its children is reverted - if a child component was previously explicitly selected before selecting the parent, it will remain selected. Otherwise the child component will be deselected.

When a user selects all of the components, the installer will behave as if the Entire application option was chosen. Otherwise, selected components will be removed and pre- and post- uninstallation actions for these components will be run. Remaining components will remain installed and no actions for these components will be run.

After successful uninstallation, the uninstaller and all related information will be updated to reflect that the user has uninstalled some of the components.

When the Entire application option is chosen or the user selects all components in the component tree, the entire application is uninstalled along with uninstaller itself. This also triggers pre- and post- uninstallation actions for the project to be run.

6. Working with Files and Folders

The installation resources (files and directories) are grouped into <folder> elements.

<project>
    ...
    <componentList>
       <component>
          <name>myComponent</name>
          ...
          <folderList>
              <folder>
                 <name>documents</name>
                 <destination>${installdir}/docs</destination>
                 <platforms>linux windows</platforms>
                 <distributionFileList>
                     <distributionDirectory origin="/home/johndoe/docs"/>
                     <distributionFile origin="/home/johndoe/README"/>
                 </distributionFileList>
                 <shortcutList>
                     ...
                     <shortcut/>
                     ...
                 </shortcutList>
                 <actionList>
                     <addTextToFile file="${installdir}/docs/README" text="some text"/>
                 </actionList>
              </folder>
          </folderList>
       </component>
    </componentList>
</project>

The most important tags in a folder element are:

<folder>
   ...
   <distributionFileList>
       <distributionFile>
          <origin>${build_project_directory}/license.txt</origin>
       </distributionFile>
       <distributionDirectory allowWildcards="1">
          <origin>${build_project_directory}/readmeFiles/*.txt</origin>
          <includeFiles>*/README-*.txt</includeFiles>
          <excludeFiles>*/README-template.txt</excludeFiles>
       </distributionDirectory>
   </distributionFileList>
</folder>
  • <platforms>: This tag defines a space-separated list of platforms for which the files will be packed. This is evaluated at build time and matched against the specified build target. It allows a single project to define a multiplatform installer. The special platform identifier all can be used and represents all platforms. The full list of supported values in the tag is summarized in the table below:

Supported Platforms

Platform Identifier

Platform Description

all

All Platforms

linux

Linux

linux-x64

Linux x86 64 bits

linux-ia64

Linux IA64

windows

Windows

osx

Mac OS X

solaris-sparc

Solaris Sparc

solaris-intel

Solaris Intel

linux-ppc

Linux PPC

linux-s390

Linux s390

linux-s390x

Linux s390x

freebsd

FreeBSD 5

freebsd4

FreeBSD 4

freebsd6

FreeBSD 6

freebsd6-x64

FreeBSD 6 64 bits

freebsd7

FreeBSD 7/8

freebsd7-x64

FreeBSD 7/8 64 bits

openbsd3

OpenBSD x86

hpux

HP-UX

aix

AIX, OS/400

irix-n32

IRIX

  • <destination>: The destination directory in which all the bundled files in the folder will be unpacked.

  • <shortcutList>: Along with the files, a folder can define a list of shortcuts to create. You can find a detailed reference in the shortcuts section.

  • <actionList>: Actions executed right after the files of the folder are unpacked.

6.1. Conditionally Packing a Folder

Although the <platforms> tag provides a built-in mechanism to avoid packing folders for different platforms, there are scenarios in which you need a more complex condition than just the target platform. This can be achieved using the <shouldPackRuleList>:

  <folder>
    <name>documents</name>
    <destination>${installdir}/docs</destination>
    <platforms>linux</platforms>
    <distributionFileList>
       <distributionDirectory origin="/home/johndoe/docs"/>
       <distributionFile origin="/home/johndoe/README"/>
    </distributionFileList>
    <shouldPackRuleEvaluationLogic>and</shouldPackRuleEvaluationLogic>
    <shouldPackRuleList>
       <fileExists path="/home/johndoe/docs"/>
       <fileExists path="/home/johndoe/README"/>
    </shouldPackRuleList>
  </folder>

The above folder will only be packed if the target platform is linux and the files exist. The evaluation logic of the rules can be modified through the <shouldPackRuleEvaluationLogic> property.

This is also helpful when you are developing the installer and do not need all of the files that will be included in the final version (that can greatly increase the build time) to be packed. For example, you could create an environment variable (DEMO_BUILD) to indicate to the builder you do not need an official build:

  <folder>
    <name>optionalFiles</name>
    <destination>${installdir}</destination>
    <platforms>linux</platforms>
    <distributionFileList>
       <distributionDirectory origin="videos"/>
       <distributionDirectory origin="images"/>
       <distributionDirectory origin="documentation"/>
    </distributionFileList>
    <shouldPackRuleList>
       <!-- Check if the variable is defined -->
       <compareText text="${env(DEMO_BUILD)}" logic="equals" value=""/>
    </shouldPackRuleList>
  </folder>

You can find a more complex example in the "Custom Build Targets" section.

Note
Do not confuse <shouldPackRuleList> with <ruleList>

Rules inside a <ruleList> are evaluated at runtime while rules within a <shouldPackRuleList> are evaluated at build time.

6.2. Conditionally Unpacking a Folder

By default, folders will be unpacked if they were packed (as described in the previous section) and if the <component> in which they are bundled was selected. However, you can add additional logic to discern if it should be unpacked by attaching rules to its <ruleList>:

  <folder>
    <name>documents</name>
    <destination>${installdir}/docs</destination>
    <platforms>windows</platforms>
    <distributionFileList>
       <distributionDirectory origin="/home/johndoe/docs"/>
       <distributionFile origin="/home/johndoe/README"/>
    </distributionFileList>
    <ruleEvaluationLogic>and</ruleEvaluationLogic>
    <ruleList>
       <platformTest type="windows-xp"/>
    </ruleList>
  </folder>

The above folder will be packed for any Windows target but will only be unpacked if the platform in which the installer is executing is Windows XP.

6.3. Filters

6.3.1. Basic Filters

InstallBuilder implements a basic filtering mechanism for folders. This functionality will allow you to pack the contents of a folder instead of including the folder itself and to apply filters to include or exclude specific files. For example, if you have a folder named "documentation" and you want to pack a subset of its contents and unpack it to ${installdir}/myDocs, you just need to use the snippet below:

<folder>
   <description>Documentation Files</description>
   <destination>${installdir}/myDocs</destination>
   <name>documentation</name>
   <platforms>all</platforms>
   <distributionFileList>
       <distributionDirectory allowWildcards="1">
          <origin>/some/path/to/documentation/*</origin>
          <includeFiles>*/project-1-*.txt</includeFiles>
          <excludeFiles>*/project-1-secret.txt</excludeFiles>
       </distributionDirectory>
   </distributionFileList>
</folder>

In the above example, all of the .txt files related to "project-1" will be packaged, with the exception of "project-1-secret.txt"

The following are the filtering-related tags that you can use:

  • <allowWildcards> : This tag determines the behavior of the filtering mechanism. If it is set to "0" (the default), there will not be any global pattern interpretation and patterns will be taken as literal strings. For example, if you define <origin>/some/path/to/documentation/*</origin>, the installer will look for a folder named "*" inside the /some/path/to/documentation/ directory. In addition, the includeFiles and excludeFiles tags will be ignored.

However, if allowWildcards is set to "1", the <origin> will be expanded and the installer will generate a list of matching files.

  • <includeFiles> : This tag allows you to select files over the matches produced by the <origin> tag when wildcards are enabled. The default value of the <includeFiles> tag is "*" so all the files matched by the <origin> tag will be packed.

  • <excludeFiles> : Once the list of files has been filtered with the <includeFiles> pattern, the <excludeFiles> filter will be applied over the result. The default value of this tag is empty so no filter is applied. This tag is ignored if wildcards are disabled. Only files directly returned by the evaluation of the <origin> pattern can be excluded, the builder won’t try to recursively exclude files at deeper hierarchy levels in the packed directories.

The pattern interpretation in the <origin>, <includeFiles> and <excludeFiles> does not follow the same rules. The <origin> pattern is expanded over the existing files, like a "dir c:\Program Files\*txt" on Windows or "ls ~/*txt" on Unix. Forward and backwards slashes are normalized according to the platform. However, the patterns in the <includeFiles> and <excludeFiles> tags follow a stricter format:

  • Forward slashes are used as path separators, which let us escape special characters using backslashes. For example, to match .txt files, you must use */*.txt files in both Windows and Unix systems.

  • The pattern is applied over the full path of the files and a string comparison is performed: <includeFiles>my.txt<includeFiles> will not work because it will compare "/some/path/to/my.txt" with "my.txt". */my.txt has to be used instead.

  • Multiple patterns can be included and must be separated by ; or \n characters:

   <distributionDirectory allowWildcards="1">
       <origin>/some/path/*</origin>
       <includeFiles>*/*.txt;*/*.jpg;*/*.bmp</includeFiles>
       <excludeFiles>*/*secret*.txt;*/myImage.bmp</excludeFiles>
    </distributionDirectory>

The special characters used in all of the patterns are listed below:

  • ? : Matches any single character.

  • * : Matches any sequence of zero or more characters.

  • [chars] : Matches any single character in chars. If chars contains a sequence of the form a-b then any character between a and b (inclusive) will match.

  • {a,b,...} : Matches any of the strings a, b, etc.

Note
Basic filters do not operate recursively

The basic filters mechanism is not intended to recursively skip packing files in the directory provided in the <origin> tag. Just the results returned by the evaluation of the <origin> pattern can be filtered. For example, if you are packing a directory images and want to exclude the file demo.png, the below won’t work:

<folder>
   ...
   <destination>${installdir}</destination>
   ...
   <distributionFileList>
       <distributionDirectory allowWildcards="1">
          <origin>images</origin>
          <excludeFiles>*/demo.png</excludeFiles>
       </distributionDirectory>
   </distributionFileList>
</folder>

The reason is that the <origin> pattern will only return images as matching file, which does not match the exclusion pattern */demo.png.

If demo.png is packed directly under images you could use:

<folder>
   ...
   <destination>${installdir}/images</destination>
   ...
   <distributionFileList>
       <distributionDirectory allowWildcards="1">
          <origin>images/*</origin>
          <excludeFiles>*/demo.png</excludeFiles>
       </distributionDirectory>
   </distributionFileList>
</folder>

In this case, evaluating <origin> will return all the contained images (sample-01.png, left-image.jpg, details.gif, demo.png, …), and the exclusion pattern will be able to match demo.png.

If you want to filter certain files at any level of the hierarchy in the packed directory, you should use the Advanced Filters instead, which operate recursively.

6.3.2. Advanced Filters

In addition to the basic filters, which allow providing a pattern to the <origin> tag while excluding some of the results returned, InstallBuilder also includes a more complex filtering mechanism that allows excluding files located at any level in the folder hierarchy of the <distributionDirectory>.

Note that you have to define filters that will decide if the file will be packed or not. Currently, just filters based on the file path are allowed: <fileNameFilter>. These are the basic tags in the <fileNameFilter>:

  • <pattern>: Pattern to match against the path of the file

  • <patternType>: Whether to use glob or regular expressions matching

  • <logic>: Whether or not the pattern must match to pass the filter.

These filters are grouped into the <onPackingFilterList>. If the file in consideration matches the expressed conditions in this list, it will be packed, if not, it will be skipped.

For example, if you want to pack a folder dist-files:

dist-files/
|-- bin
|   `-- productA
|       `-- data
|           |-- info.ini
|           `-- info.ini~
|-- docs
|   `-- reference
|       |-- README.tct~
|       |-- reference.html
|       |-- reference.html~
|       |-- reference.pdf
|       `-- reference.pdf~
`-- libraries
    |-- lib1.so
    |-- .#lib2.so
    `-- lib2.so

To exclude all of the temporary files (files ending in ~), you could use:

 <folder>
   <description>Program Files</description>
   <destination>${installdir}</destination>
   <name>programfiles</name>
   <platforms>all</platforms>
   <distributionFileList>
     <distributionDirectory>
       <origin>dist-files</origin>
       <onPackingFilterList>
          <fileNameFilter pattern="*~" logic="does_not_match" patternType="glob"/>
       </onPackingFilterList>
     </distributionDirectory>
   </distributionFileList>
 </folder>

After the installation, you will find the dist-files directory clean of temporary files:

sample-1.0
|-- dist-files
|   |-- bin
|   |   `-- productA
|   |       `-- data
|   |           `-- info.ini
|   |-- docs
|   |   `-- reference
|   |       |-- reference.html
|   |       `-- reference.pdf
|   `-- libraries
|       |-- lib1.so
|       |-- .#lib2.so
|       `-- lib2.so
|-- uninstall
`-- Uninstall Sample Project.desktop

If you also want to exclude files starting with .#, you just need to add another filter to the <onPackingFilterList>:

 <folder>
   <description>Program Files</description>
   <destination>${installdir}</destination>
   <name>programfiles</name>
   <platforms>all</platforms>
   <distributionFileList>
     <distributionDirectory>
       <origin>dist-files</origin>
       <filterEvaluationLogic>and</filterEvaluationLogic>
       <onPackingFilterList>
          <fileNameFilter pattern="*~" logic="does_not_match" patternType="glob"/>
          <fileNameFilter pattern="*/.#*" logic="does_not_match" patternType="glob"/>
       </onPackingFilterList>
     </distributionDirectory>
   </distributionFileList>
 </folder>

The default <filterEvaluationLogic> is and but you can also set it to or. A file will be packed if its full path in the build machine matches all the filters when using and logic or when matching any of them when using or.

For example, if you want to pack just .png and .jpg files, you could rewrite the code with or logic:

 <folder>
   <description>Program Files</description>
   <destination>${installdir}</destination>
   <name>programfiles</name>
   <platforms>all</platforms>
   <distributionFileList>
     <distributionDirectory>
       <origin>dist-files</origin>
       <filterEvaluationLogic>or</filterEvaluationLogic>
       <onPackingFilterList>
          <fileNameFilter pattern="*.png" logic="matches" patternType="glob"/>
          <fileNameFilter pattern="*.jpg" logic="matches" patternType="glob"/>
       </onPackingFilterList>
     </distributionDirectory>
   </distributionFileList>
 </folder>

The filters can also include more complex patterns if instead of using the glob <patternType> you set it to regexp. For example, you can exclude .txt files that start with a number and contain temp in their paths and .png files that start with three capital letters using a single filter:

 <folder>
   <description>Program Files</description>
   <destination>${installdir}</destination>
   <name>programfiles</name>
   <platforms>all</platforms>
   <distributionFileList>
     <distributionDirectory>
       <origin>dist-files</origin>
       <onPackingFilterList>
          <fileNameFilter pattern="/([A-Z]{3}[^/]*\.png|[0-9]+[^/]*temp[^/]*\.txt)$" logic="does_not_match" patternType="regexp"/>
       </onPackingFilterList>
     </distributionDirectory>
   </distributionFileList>
 </folder>

Both regexp and glob pattern types allow providing a semicolon-separated list of sub patterns. If any of the sub patterns in the list evaluates to true, the full pattern will also evaluate to true. For example, to pack all of the .png and .jpg files in a directory, you could use any of the below snippets:

 <folder>
   <destination>${installdir}</destination>
   <name>programfiles</name>
   <distributionFileList>
     <distributionDirectory>
       <origin>dist-files</origin>
       <onPackingFilterList>
          <fileNameFilter pattern="*.png;*.jpg" logic="matches" patternType="glob"/>
       </onPackingFilterList>
     </distributionDirectory>
   </distributionFileList>
 </folder>

 <folder>
   <description>Program Files</description>
   <destination>${installdir}</destination>
   <name>programfiles</name>
   <platforms>all</platforms>
   <distributionFileList>
     <distributionDirectory>
       <origin>dist-files</origin>
       <filterEvaluationLogic>or</filterEvaluationLogic>
       <onPackingFilterList>
          <fileNameFilter pattern="*.jpg" logic="matches" patternType="glob"/>
          <fileNameFilter pattern="*.png" logic="matches" patternType="glob"/>
       </onPackingFilterList>
     </distributionDirectory>
   </distributionFileList>
 </folder>

 <folder>
   <destination>${installdir}</destination>
   <name>programfiles</name>
   <distributionFileList>
     <distributionDirectory>
       <origin>dist-files</origin>
       <filterEvaluationLogic>and</filterEvaluationLogic>
       <onPackingFilterList>
          <fileNameFilter pattern=".*\.(png|jpg)$" logic="matches" patternType="regexp"/>
       </onPackingFilterList>
     </distributionDirectory>
   </distributionFileList>
 </folder>

Even more complex conditions can be expressed using a <filterGroup>. This special type of filter allows grouping a set of filters with a configurable <filterEvaluationLogic>. For example, you can exclude all of the .txt files except for those in the readme folder and exclude all of the .png and .jpg files that are not under the images folder:

 <folder>
   <description>Program Files</description>
   <destination>${installdir}</destination>
   <name>programfiles</name>
   <platforms>all</platforms>
   <distributionFileList>
     <distributionDirectory>
       <origin>dist-files</origin>
       <filterEvaluationLogic>and</filterEvaluationLogic>
       <onPackingFilterList>
          <!-- Include files that do not end in .txt or if they are located in the readme dir -->
          <filterGroup>
             <filterEvaluationLogic>or</filterEvaluationLogic>
             <onPackingFilterList>
               <fileNameFilter pattern="*.txt" logic="does_not_match" patternType="glob"/>
               <fileNameFilter pattern="*/readme/*" logic="matches" patternType="glob"/>
             </onPackingFilterList>
          </filterGroup>
          <!-- Include files that do not end in .png or .jpg or if they are located in the images dir -->
          <filterGroup>
             <filterEvaluationLogic>or</filterEvaluationLogic>
             <onPackingFilterList>
               <fileNameFilter pattern=".*\.png;.*\.jpg" logic="does_not_match" patternType="regexp"/>
               <fileNameFilter pattern="*/images/*" logic="matches" patternType="glob"/>
             </onPackingFilterList>
          </filterGroup>
       </onPackingFilterList>
     </distributionDirectory>
   </distributionFileList>
 </folder>

Filter groups can also be nested as needed.

Take into account that all of the files in the <distributionDirectory> will be matched against the filter, so using a lot of very complex files could slightly increase the build time (the performance at runtime will not be affected at all).

Note
The pattern is applied to the full path of the file

Because of the pattern is applied to the full path of the file to be packed, when trying to match files ending in an specific suffix, you should always prefix it with * (when using glob <patternType>) or .* (when using regexp <patternType>).

For example, specifying:

<fileNameFilter pattern="images/*.png" logic="matches" patternType="glob"/>

Wont work because it will be matched against the full path, for example: /home/bitrock/demo/files/images/foo.png

To make it independent to the location, it should be rewritten to:

<fileNameFilter pattern="*/images/*.png" logic="matches" patternType="glob"/>

Or

<fileNameFilter pattern="${build_project_directory}/files/images/*.png" logic="matches" patternType="glob"/>

6.4. Unix Permissions

InstallBuilder preserves the permissions of bundled files. It also includes two convenient tags: <defaultUnixGroup> and <defaultUnixOwner>. If a value is specified for those tags, the owner and group of the unpacked files will be modified at runtime:

<project>
   ...
   <defaultUnixGroup>wheel</defaultUnixGroup>
   <defaultUnixOwner>root</defaultUnixOwner>
   ...
</project>

Please take into account that the specified group and owner must exist in the target machine. If not, you can always create them before the installation phase:

<project>
   ...
   <defaultUnixGroup>coolUsers</defaultUnixGroup>
   <defaultUnixOwner>john</defaultUnixOwner>
   ...
   <readyToInstallActionList>
      <addUser username="john"/>
      <addGroup groupname="coolUsers"/>
   </readyToInstallActionList>
   ...
</project>

Despite the permissions being preserved, in some situations they must be fixed. The most convenient way of fixing them is to use the <actionList> of the folder containing the files and set the appropriate rights:

<folder>
   <description>Binary Files</description>
   <destination>${installdir}</destination>
   <name>executables</name>
   <platforms>all</platforms>
   <distributionFileList>
       <distributionDirectory>
          <origin>/some/path/executables</origin>
       </distributionDirectory>
   </distributionFileList>
   <actionList>
       <changePermissions permissions="0755" files="${installdir}/executables/*"/>
   </actionList>
</folder>

A common scenario in which permissions must be fixed is when you are building a Linux installer on Windows. In that case, you could either manually fix the permissions as explained in the latest snippet or define the default permissions:

<project>
   ...
   <defaultUnixFilePermissions>644</defaultUnixFilePermissions>
   <defaultUnixDirectoryPermissions>755</defaultUnixDirectoryPermissions>
   ...
</project>

Please take into account that, contrary to the owner and group tags, the default Unix permissions are only applied when building on Windows. This way, if the installer is created on Unix, the configured values will be ignored.

Note
Files packed on Windows lose their executable permissions

Windows does not understand Unix permissions, so Unix installers created on Windows will be unpacked without executable permissions and must be manually fixed. It is recommended that you use Unix machines to build the installers as they do not present any limitation.

When a symbolic link is specified as a <distributionFile>, InstallBuilder does not follow the link to pack its target. Depending on the build type, it will either pack the link (deb, rpm) or it will be registered and recreated at runtime.

6.6. Unpacking Before Installation Time

It is common to have a separate tool or program that must be bundled with and run from the installer but before the file copying phase of the installation process has completed. A common example would be a license validation program. Typically, all files bundled within an installer are unpacked and then any tools are run. In the case of a license validation tool, that is less than ideal because the user may end up waiting for the files to be unpacked only to find that the license is not valid. The user would then have to wait for the installation to be rolled back.

InstallBuilder provides you with actions to deal with these situations. The most important are <unpackFile> and <unpackDirectory>:

<unpackDirectory>
   <destination>${installdir}</destination>
   <component>tools</component>
   <folder>license</folder>
   <origin>management</origin>
</unpackDirectory>

<unpackFile>
   <destination>${system_temp_directory}</destination>
   <component>tools</component>
   <folder>license</folder>
   <origin>management/validator.exe</origin>
</unpackFile>

The <unpackDirectory> action is intended to unpack a directory and its contents while the <unpackFile> action operates over files. Trying to unpack the wrong type in those actions will generate an error at runtime.

The configuration options for these actions specify the folder and component bundling the files, the path relative to the packed element, and the destination directory to unpack them.

The structure in Figure 33 (also represented in XML code) should help you understand how to reference internal files:

Internal Files Structure
Figure 33: Internal Files Structure

<project>
  ...
  <componentList>
     <component>
       <name>componentA</name>
       <description>Component A</description>
       <folderList>
         <folder>
           <name>folder1</name>
           <description>Folder 1</description>
           <distributionFileList>
              <distributionDirectory>
                <!-- someDirectory contains: readme.txt,
                logo.jpg and directory1 -->
                <origin>/path/to/someDirectory</origin>
              </distributionDirectory>
              <distributionFile>
                <origin>/path/to/someFile</origin>
              </distributionFile>
              <distributionFile>
                <origin>/path/to/someOtherFile</origin>
              </distributionFile>
           </distributionFileList>
         </folder>
       </folderList>
     </component>
     <component>
       <name>componentB</name>
       <description>Component B</description>
       <folderList>
         <folder>
           <name>folder2</name>
           <description>Folder 2</description>
           <distributionFileList>
              <distributionDirectory>
                <!-- someDirectory contains: movie.avi and
                installer.exe -->
                <origin>/path/to/someOtherDirectory</origin>
              </distributionDirectory>
           </distributionFileList>
         </folder>
       </folderList>
     </component>
  </componentList>
  ...
</project>

To reference logo.jpg:

<unpackFile>
  <component>componentA</component>
  <folder>folder1</folder>
  <origin>someDirectory/logo.jpg</origin>
  <destination>${installdir}</destination>
</unpackFile>

You could also unpack directory1:

<unpackDirectory>
  <component>componentA</component>
  <folder>folder1</folder>
  <origin>someDirectory/directory1</origin>
  <destination>${installdir}</destination>
</unpackDirectory>

Please note the <origin> is always provided as the relative path to the file or directory to unpack, relative to the <folder> containing it. It does not matter where the file was originally located in the building machine, just the path inside the installer:

<component name="componentA">
   <folderList>
     <folder>
       <name>folder1</name>
       <distributionFileList>
         <distributionDirectory>
            <origin>/some/long/path/in/the/building/machine/someDirectory</origin>
         </distributionDirectory>
       </distributionFileList>
     </folder>
   </folderList>
</component>

The example below details a real scenario, in which the installer unpacks a license validator and checks the provided key in the <validationActionList> of the page:

<project>
  ...
  <componentList>
    <component>
    <name>tools</name>
       <folderList>
          <folder>
             <name>license</name>
             <destination>${installdir}</destination>
             <distributionFileList>
                <!-- The management directory contains a lot of
                tools, one of the our validator.exe -->
                <distributionDirectory origin="/path/to/dir/to/management"/>
             </distributionFileList>
          </folder>
       </folderList>
    </component>
  </componentList>
  <parameterList>
    <stringParameter>
       <name>licenseCheck</name>
       <description>Introduce your license key</description>
       <value></value>
       <validationActionList>
         <unpackFile>
            <component>tools</component>
            <folder>license</folder>
            <!-- Relative path from the packed folder 'management' -->
            <origin>management/validator.exe</origin>
            <destination>${system_temp_directory}</destination>
         </unpackFile>
         <runProgram>
           <program>${system_temp_directory}/validator.exe</program>
           <programArguments>${project.parameter(licenseCheck).value}</programArguments>
         </runProgram>
         <throwError text="Wrong license key, please enter a valid one">
           <ruleList>
             <compareText text="${program_stdout}" logic="equals" value="1"/>
           </ruleList>
         </throwError>
       </validationActionList>
    </stringParameter>
  </parameterList>
    ...
</project>

7. User Input

7.1. Parameters

In most cases, you will need to request some information from your end users, such as the installation directory or username and password. For this purpose, InstallBuilder allows the creation of custom pages, which make it easy to request and validate user input. In addition, the provided information will automatically be stored in installer variables so it can be used later in the installation process, for example to pass it as arguments to a script in the post-installation. You can define such pages by adding parameters to the <parameterList> section in the XML project file.

There are different types of parameters: strings, booleans, option selection, and so on. Each one of them will be displayed to the user appropriately through the GUI and text interfaces. For example, a file parameter will be displayed with a graphical file selection button next to it and an option selection parameter will be displayed as a combobox. The parameters will also be available as command line options and as installer variables.

Parameter example

 <fileParameter>
     <name>apacheconfig</name>
     <cliOptionName>apacheconfig</cliOptionName>
     <ask>yes</ask>
     <default>/etc/httpd/conf/httpd.conf</default>
     <title>Configuring Apache</title>
     <explanation>Please specify the location of the Apache configuration file</explanation>
     <description>Apache Configuration File</description>
     <mustBeWritable>yes</mustBeWritable>
     <mustExist>1</mustExist>
     <value></value>
 </fileParameter>

This will create the appropriate GUI screens for the graphical installers and make the parameter available as the command line option --apacheconfig and as the installer variable ${apacheconfig}. It is also possible to have a different name for the command line flag and the internal variable name using the <cliOptionName> tag. For example, the installdir parameter (accessible using ${installdir}) is usually mapped to the --prefix command line flag:

 <directoryParameter>
   <name>installdir</name>
   ...
   <cliOptionName>prefix</cliOptionName>
   ...
 </directoryParameter>

A number of fields are common across all parameters:

  • <name>: Name of the parameter. This will be used to create the corresponding installer variable and command line option. Because of that, it may only contain alphanumeric characters.

  • <value>: Value for the parameter.

  • <default>: Default value, in case one is not specified by the user.

  • <explanation>: Long description for the parameter.

  • <description>: Short description for the parameter.

  • <title>: Title that will be displayed for the corresponding installer page. If none is specified, the <description> field will be used instead.

  • <cliOptionName>: Command line option associated with the parameter. If none is provided, it will default to the value of the <name> field.

  • <ask>: Whether or not to show the page to the end user (it can still be set through the command line interface). If it is set to 0, the page not only won’t be displayed but also the associated command line option won’t appear in the help menu.

  • <leftImage>: When using <style>custom</style> inside the <project> tag in your project file, it displays a custom PNG or GIF image at the left side of the installer page associated with this parameter. Its purpose is the same as the <leftImage> property inside the <project> tag, but allows you set a different image for each parameter page.

Each one of the fields can reference installer variables (${project.fullName}, ${installdir}, and so on) that will be substituted at runtime.

Note
Difference between the <default> and <value> tags

The <default> tag of a parameter is used when its <value> is empty, either because it was configured that way or because the user set it. For example, for the parameter below:

  <directoryParameter>
     <name>installdir</name>
     <value></value>
     <description>Installation Directory</description>
     <explanation>Please specify the directory where ${project.fullName} will be installed</explanation>
     <default>${platform_install_prefix}/${project.shortName}-${project.version}</default>
     <cliOptionName>prefix</cliOptionName>
     <ask>yes</ask>
    <mustBeWritable>yes</mustBeWritable>
  </directoryParameter>

As <value> is empty, the value displayed in the page will be configured in the <default> field: ${platform_install_prefix}/${project.shortName}-${project.version}. If the user manually set that value to empty, the installer will automatically restore it to its <default> value when clicking next.

If you want to allow your users to provide an empty value but still display an initial value in the page, you should set <default> to empty and use <value> instead:

  <stringParameter>
     <name>customWelcome</name>
     <value>Welcome!!</value>
     <description>Introduce here the desired welcome message</description>
     <default></default>
  </stringParameter>

This way, the user can provide an empty welcome message.

7.1.1. Configuring Parameters At Runtime

Parameters can be configured at runtime by modifying their properties using the <setInstallerVariable> action as explained in the Variables section. Although any action list can be used, the recommended approach is to use their <preShowPageActionList> and <posShowPageActionList> action lists, when possible:

  • <preShowPageActionList>: This Action List is executed right before displaying the page containing the parameter. It is really useful to modify the information displayed. For example, if you are working to implement a summary page using a <labelParameter>, you should construct the information in its <preShowPageActionList>:

  <labelParameter>
     <name>summary</name>
     <title>Summary</title>
     <explanation></explanation>
     <preShowPageActionList>
        <setInstallerVariable>
           <name>text</name>
           <value>You are about to install ${project.fullName}.

Please review the below information:

Installation Directory: ${installdir}

Username: ${username}

License File: ${license_file}

Installed Components:
</value>
        </setInstallerVariable>
        <foreach>
           <variables>component</variables>
           <values>component1 component2 component3</values>
           <actionList>
              <!-- Just include selected Components -->
              <continue>
                <ruleList>
                   <isFalse>
                     <value>${component(${component}).selected}</value>
                   </isFalse>
                </ruleList>
              </continue>
              <setInstallerVariable>
                <name>text</name>
                <value>${text}

${component(${component}).description}</value>
              </setInstallerVariable>
           </actionList>
        </foreach>
     </preShowPageActionList>
  </labelParameter>
  • <postShowPageActionList>: This Action List is executed after clicking Next in the page containing the parameter and after successfully executing the <validationActionList>. One example of how this is useful is configuring installation settings based on the user input:

  <choiceParameter>
     <name>installMode</name>
     <description>Select the installation mode</description>
     <explanation></explanation>
     <displayType>combobox</displayType>
     <width>30</width>
     <optionList>
       <option>
         <description>Upgrade</description>
         <text>Upgrade</text>
         <value>upgrade</value>
       </option>
       <option>
         <description>Uninstall</description>
         <text>Uninstall</text>
         <value>uninstall</value>
       </option>
     </optionList>
     <postShowPageActionList>
        <!-- Set upgrade mode in the project -->
        <setInstallerVariable>
          <name>project.installationType</name>
          <value>upgrade</value>
          <ruleList>
             <compareText text="${installMode}" logic="equals" value="upgrade"/>
          </ruleList>
        </setInstallerVariable>
     </postShowPageActionList>
  </choiceParameter>

7.1.2. Validating User Input

Parameters can also include checks to validate the data introduced through their <validationActionList>. The actions included in this <actionList> will be executed right after clicking Next. If an error occurs, it will be displayed and, instead of aborting the installation, the page will be redrawn. For example, you can use the snippet below to check if a provided password is strong enough:

<passwordParameter>
   <name>password</name>
   <description>Password</description>
   <explanation>Administrator account password. It must include at least 2 uppers, 2 lowers, 2 digits and 2 special characters and be at least 10 characters long.</explanation>
   <value></value>
   <default></default>
   <allowEmptyValue>1</allowEmptyValue>
   <descriptionRetype></descriptionRetype>
   <width>20</width>
   <validationActionList>
     <throwError text="The password provided is not strong enough">
       <ruleList>
          <regExMatch>
             <logic>does_not_match</logic>
             <pattern>^(?=(?:\D*\d){2})(?=(?:[^a-z]*[a-z]){2})(?=(?:[^A-Z]*[A-Z]){2})(?=(?:[^!@#$%^&amp;*+=]*[!@#$%^&amp;*+=]){2}).{10,}$</pattern>
             <text>${password}</text>
          </regExMatch>
       </ruleList>
     </throwError>
   </validationActionList>
</passwordParameter>

Or validate if the user has enough free disk space install your application:

  <directoryParameter>
     <name>installdir</name>
     <value></value>
     <description>Installation Directory</description>
     <explanation>Please specify the directory where ${project.fullName} will be installed</explanation>
     <default>${platform_install_prefix}/${project.shortName}-${project.version}</default>
     <cliOptionName>prefix</cliOptionName>
     <ask>yes</ask>
     <mustBeWritable>yes</mustBeWritable>
     <validationActionList>
        <throwError>
            <text>You don't have enough disk space to install the application,
            please select another installation directory</text>
            <ruleList>
               <checkFreeDiskSpace>
                  <logic>less</logic>
                  <path>${installdir}</path>
                  <!-- ${required_diskspace} is automatically calculated by
                  InstallBuilder with all the files packed -->
                  <size>${required_diskspace}</size>
               </checkFreeDiskSpace>
            </ruleList>
        </throwError>
     </validationActionList>
  </directoryParameter>

You must to take into account that these validations won’t be executed in unattended mode (as explained here). If you want to validate the information provided through command line when running in unattended mode, you can include the validations in the <preInstallationActionList>, executed after the command line options are processed:

<preInstallationActionList>
  <actionGroup>
     <actionList>
        <!-- Validate the password is not empty -->
        <throwError text="You must provide a non-empty password using --masterpassword command line flag">
           <ruleList>
              <compareText text="${masterpassword}" logic="equals" value=""/>
           </ruleList>
        </throwError>

        <!-- Validate the installation directory has enough disk space -->
        <throwError>
           <text>You don't have enough disk space to install the application,
           please select another installation directory</text>
           <ruleList>
             <checkFreeDiskSpace>
                <logic>less</logic>
                <path>${installdir}</path>
                <!-- ${required_diskspace} is automatically calculated by
                InstallBuilder with all the files packed -->
                <size>${required_diskspace}</size>
             </checkFreeDiskSpace>
           </ruleList>
        </throwError>
        ...
     </actionList>
     <ruleList>
       <compareText>
         <text>${installer_interactivity}</text>
         <logic>does_not_equal</logic>
         <value>normal</value>
       </compareText>
     </ruleList>
  </actionGroup>
</preInstallationActionList>
...
<parameterList>
  <passwordParameter>
     <ask>yes</ask>
     <name>masterpassword</name>
     <allowEmptyValue>0</allowEmptyValue>
     <description>Password</description>
     ...
  </passwordParameter>
  <directoryParameter>
     <name>installdir</name>
     <value></value>
     <default>${platform_install_prefix}/${project.shortName}-${project.version}</default>
     ...
  </directoryParameter>
  ...
</parameterList>

7.1.3. Available Parameters

This section provides an exhaustive list of all of the available parameters.

String Parameter

The <stringParameter> allows you to request a text string from the user. It accepts all of the common options.

    <stringParameter>
      <name>hostname</name>
      <default>localhost</default>
      <value></value>
      <ask>1</ask>
      <description>Hostname</description>
      <explanation>Please enter the hostname for your application server.</explanation>
    </stringParameter>
String Parameter
Figure 34: String Parameter
Label Parameter

The <labelParameter> allows you to display a string of read-only text inside an installer page. Optionally, you can include an image to the left side of the text.

    <labelParameter>
        <name>label</name>
        <title>labelParameter test</title>
        <description>This is a warning message inside an installer page.</description>
        <image>/path/to/icons/warning.png</image>
    </labelParameter>

It is also useful to display a read-only version of the installation directory:

  <!-- The installation directory won't be selectable by the end user so we
  hide it setting ask=0 -->
  <directoryParameter>
     <name>installdir</name>
     ...
     <description>Installation Directory</description>
     <default>${platform_install_prefix}/${project.shortName}-${project.version}</default>
     <ask>0</ask>
     ...
  </directoryParameter>
  <!-- We display the read-only version of the installation directory -->
  <labelParameter>
     <name>readOnlyInstalldir</name>
     <title>Installation Directory</title>
     <explanation>Directory where ${project.fullName} will be installed</explanation>
     <description>Installation Directory: ${installdir}</description>
  </labelParameter>
Label Parameter
Figure 35: Label Parameter

  <linkParameter>
     <name>visitwebsite</name>
     <description>More information.</description>
     <clickedActionList>
        <launchBrowser url="http://example.com/more_information.html" />
     </clickedActionList>
  </linkParameter>
Link Parameter
Figure 36: Link Parameter
File Parameter

The <fileParameter> asks the user to enter a file. They also support additional fields:

  • <mustExist>: Whether or not to require that the file must already exist.

  • <mustBeWritable>: Whether or not to require that the file must be writable.

  • <osxBundlesAreFiles>: Whether or not OS X bundles (*.app and *.bundle) will be considered files. The setting will just have effect on OS X, in other platforms they will be always considered directories.

  <fileParameter>
     <name>licenseFile</name>
     <value></value>
     <description>License File</description>
     <explanation>Please specify the downloaded license file</explanation>
     <ask>yes</ask>
     <mustBeWritable>yes</mustBeWritable>
  </fileParameter>

Usually, on OS X, some bundles are considered as files although they really are special directories. Using the <osxBundlesAreFiles> tag, you can configure whether you want the parameter to validate them as files or to complain when trying to select them. Note that *.bundle and *.app bundles will be considered as *.framework bundles and are not treated as files by the OS.

  <fileParameter>
     <name>previousProductPath</name>
     <value></value>
     <description>Previous Installation Path</description>
     <explanation>The installer cannot find "${project.shortName}-${oldVersion}.app" bundle under /Applications. Please manually select it</explanation>
     <osxBundlesAreFiles>1</osxBundlesAreFiles>
     <ruleList>
        <fileExists path="/Applications/${project.shortName}-${oldVersion}.app" negate="1"/>
     </ruleList>
  </fileParameter>
File Parameter
Figure 37: File Parameter
Directory Parameter

The <directoryParameter> asks the user to enter a directory. They also support additional fields:

  • <mustExist>: Whether or not to require that the directory must already exist.

  • <mustBeWritable>: Whether or not to require that the directory must be writable.

  • <osxBundlesAreFiles>: Whether or not OS X bundles (*.app and *.bundle) will be considered files. The setting will just have effect on OS X, in other platforms they will be always considered directories

  <directoryParameter>
     <name>installdir</name>
     <value></value>
     <description>Installation Directory</description>
     <explanation>Please specify the directory where ${project.fullName}  will be installed</explanation>
     <default>${platform_install_prefix}/${project.shortName}-${project.version}</default>
     <cliOptionName>prefix</cliOptionName>
     <ask>yes</ask>
    <mustBeWritable>yes</mustBeWritable>
  </directoryParameter>
Directory Parameter
Figure 38: Directory Parameter
Boolean Parameter

The <booleanParameter> is identical to the <stringParameter>, except it accepts either a 1 or a 0 as a value. You can control how the boolean parameter is displayed in GUI mode using the <displayStyle> tag with the values of combobox, checkbutton-left and checkbutton-right.

    <booleanParameter>
      <name>createdb</name>
      <ask>yes</ask>
      <default>1</default>
      <title>Database Install</title>
      <explanation>Should initial database structure and data be created?</explanation>
      <value>1</value>
    </booleanParameter>
Boolean Parameter
Figure 39: Boolean Parameter
Text Display Parameter

The <infoParameter> will display a read-only text information page. It does not support the <cliOptionName> field as it is a read-only parameter.

    <infoParameter>
      <name>serverinfo</name>
      <title>Web Server</title>
      <explanation>Web Server Settings</explanation>
      <value>Important Information! In the following screen you will be asked to provide (...)</value>
    </infoParameter>
Info Parameter
Figure 40: Info Parameter

In InstallBuilder for Qt, the <infoParameter> is also capable of displaying HTML text:

    <infoParameter>
      <name>serverinfo</name>
      <title>Web Server</title>
      <explanation>Web Server Settings</explanation>
      <value>Important Information! In the following screen you will be asked to provide (...)</value>
      <!-- CDATA is just used to avoid the need of escaping the HTML tags -->
      <htmlValue><![CDATA[
<H1><font color="red">Important Information! </font></H1><br/>
In the following screen you will be asked to provide (...)
]]></htmlValue>
    </infoParameter>

Please note you still have to provide a plain text version in the <value> to be displayed in non-qt modes (text, gtk, win32, osx).

Choice Parameter

A <choiceParameter> allows the user to select a value from a predefined list. In GUI mode, it will be represented by a combobox or a group of radio buttons (depending on the configured <displayType>). It takes an extra field, <optionList>, which contains a list of value/text pairs. The <text> will be the description presented to the user for that option and the <value> will be the value of the associated installer variable if the user selects that option. You can control how the choice parameter is displayed in GUI modes using the <displayType> tag with the values of combobox and radiobuttons.

 <choiceParameter>
      <ask>1</ask>
      <default>http</default>
      <description>Which protocol?</description>
      <explanation>Default protocol to access the login page.</explanation>
      <title>Protocol Selection</title>
      <name>protocol</name>
      <optionList>
        <option>
          <value>http</value>
          <text>HTTP (insecure)</text>
          <description>Hypertext Transfer Protocol</description>
          <image>http.png</image>
        </option>
        <option>
          <value>https</value>
          <text>HTTPS (secure)</text>
          <description>Hypertext Transfer Protocol Secure</description>
          <image>https.png</image>
        </option>
      </optionList>
 </choiceParameter>

By default, the order in which the choices are displayed in the installer page is the same in which they are listed in the XML code. This behavior can be modified through the <ordering> tag which accepts the below values:

  • default: List the choices in the same order used in the XML project.

  • alphabetical: Sort the choices in alphabetical order.

  • alphabeticalreverse: Sort the choices in reverse alphabetical order.

Password Parameter

A <passwordParameter> allows the user to input a password and confirm it. The password will not be echoed back to the user in text mode installations and will be substituted by * characters in GUI mode installations.

They also support additional fields:

  • <askForConfirmation>: If set to 1 (the default value), a second entry field will be displayed, forcing the user to retype the password, receiving an error if both fields do not match

  • <descriptionRetype>: Description used as the label for the password retype field displayed when enabling <descriptionRetype>.

      <passwordParameter>
        <ask>yes</ask>
        <name>masterpassword</name>
        <description>Password</description>
        <askForConfirmation>1</askForConfirmation>
        <descriptionRetype>Retype password</descriptionRetype>
        <explanation>Please provide a password for the database user</explanation>
        <cliOptionName>password</cliOptionName>
        <default/>
        <value/>
      </passwordParameter>
Password Parameter
Figure 41: Password Parameter
License Parameter

A <licenseParameter> presents a license screen to the user containing the text specified in the <file> field. An optional <fileEncoding> field allows you to specify the encoding and a <wrapText> field allows you to specify whether the license text should be wrapped to fit the screen. It does not support the <cliOptionName> field as it is a read-only parameter.

<licenseParameter>
  <name>javalicense</name>
  <fileEncoding>utf-8</fileEncoding>
  <file>/path/to/license.txt</file>
</licenseParameter>

In InstallBuilder for Qt, you can also provide an HTML license file using the <htmlFile> tag:

<licenseParameter>
  <name>javalicense</name>
  <fileEncoding>utf-8</fileEncoding>
  <file>/path/to/license.txt</file>
  <htmlFile>/path/to/license.html</htmlFile>
</licenseParameter>

A plain text license is still provided to be displayed in non-qt modes (text, gtk, win32, osx). On Unix, you can easily generate a plain text version of your HTML license using the lynx command:

$> lynx -dump license.html > license.txt

7.1.4. Populating Choice parameters at Runtime

In addition to hard-coding the options of a <choiceParameter> when writing your XML project, you can also modify them at runtime using the <addChoiceOptions>, <removeChoiceOptions> and <addChoiceOptionsFromText> actions.

The snippets below explains the simplest approach, using the <addChoiceOptions> action:

 <addChoiceOptions>
    <name>language</name>
    <optionList>
      <option>
        <value>en</value>
        <text>English</text>
      </option>
      <option>
        <value>es</value>
        <text>Spanish</text>
      </option>
    </optionList>
 </addChoiceOptions>

The action takes the <name> of an existing <choiceParameter> and adds the specified options hardcoded in the <optionList>. It is useful when you need to modify the choices of a <choiceParameter> depending on some other configuration but you know the set of choices for each of them.

One of the limitations of the action is that the <value> must be a valid key identifier, that is, it can only contain alphanumeric characters and underscores so you cannot use variables when defining it.

A more powerful approach is to use the <addChoiceOptionsFromText> action, which allows you to provide the list of options in plain text:

 <addChoiceOptionsFromText>
    <name>language</name>
    <text>
jp=Japanese
jp.description=Language spoken in Japan
de=German
de.description=Language spoken in Germany
it=Italian
it.description=Language spoken in Italy
pl=Polish
pl.description=Language spoken in Poland
ru=Russian
ru.description=Language spoken in Russia
</text>
 </addChoiceOptionsFromText>

The keys in the text will be used to set the <value> property of option. The key value (the righthand side) will be used to set the <text> property. Optionally, if a key has a .description suffix and matches an existing <value>, the key value will be used to set the <description> property.

Contrary to the <addChoiceOptions> action, the <addChoiceOptionsFromText> action allows using variables in its <text>:

 <addChoiceOptionsFromText>
    <name>choice</name>
    <text>
${value1}=${text1}
${value1}.description=${description1}
${value2}=${text2}
${value2}.description=${description2}
${value3}=${text3}
${value3}.description=${description3}
</text>
 </addChoiceOptionsFromText>

The <addChoiceOptionsFromText> action is very useful when you have a long list of options to add or if you are going to generate the choices at runtime based on the output of some external program. For example, if you want to generate a language list based on the contents of your lang directory, you could use the below:

 <!-- Get list of files -->
 <setInstallerVariableFromScriptOutput>
   <name>languages</name>
   <exec>find</exec>
   <execArgs>*.lng</execArgs>
   <workingDirectory>${installdir}/lang</workingDirectory>
 </setInstallerVariableFromScriptOutput>

 <!-- Iterate over the files and create the choice text file -->
 <setInstallerVariable name="choiceText" value=""/>
 <foreach variables="file" values="${languages}">
    <actionList>
        <!-- Strip the extension to create the key -->
        <setInstallerVariableFromRegEx name="key" pattern="([^\.])*" substitution="\1" text="${file}"/>
        <!-- Add a new choice option to the text &#xA; is the escaped sequence for \n-->
        <setInstallerVariable name="choiceText" value="${choiceText}&#xA;lang_${key}=${file}"/>
    </actionList>
 </foreach>

 <addChoiceOptionsFromText>
    <name>language</name>
    <text>${choiceText}</text>
 </addChoiceOptionsFromText>

It also allows using variables in the <text> of the choices

When creating the options at runtime, especially in the <preShowPageActionList> of the parameter, you may end up with duplicate options if the user displays the page more than once (each time the page is displayed, the <preShowPageActionList> will add the options again). In those scenarios you can use a <removeChoiceOptions> action:

 <removeChoiceOptions>
    <name>language</name>
    <options>en,es,jp</options>
 </removeChoiceOptions>

The format of the <options> tag is different from similar actions, since you are not interested in the <text> of the option to remove. It is defined as a comma separated list of options, each of them matching the <value> of an existing choice option. However, if you do not know which options were added, as in the <addChoiceOptionsFromText>, you can still delete all of the options of the parameter if you provide an empty value to the <options> tag:

 <removeChoiceOptions name="language"/>

In a real world example:

  <choiceParameter>
      <ask>1</ask>
      <default></default>
      <description></description>
      <explanation>Installation Language of the installer application.</explanation>
      <title>Installation Language</title>
      <name>language</name>
      <preShowPageActionList>
          <removeChoiceOptions name="language"/>
          <!-- Get the list of languages and create the choice options -->
          <setInstallerVariableFromScriptOutput ... />
          ...
          <setInstallerVariable name="choiceText" value=""/>
          <foreach variables="file" values="${languages}">
              <actionList>
              ...
              </actionList>
          </foreach>
          <addChoiceOptionsFromText name="language" text="${choiceText}"/>
      </preShowPageActionList>
   </choiceParameter>

For all of the above actions, if the specified parameter to be modified does not exist, the action will be skipped.

Another useful example would be displaying the list of your installed applications and letting the user select one to uninstall:

<choiceParameter>
  <name>applicationToDelete</name>
  <description>Select the Application to uninstall</description>
  <displayType>combobox</displayType>
  <ordering>default</ordering>
  <width>40</width>
  <postShowPageActionList>
    <foreach>
      <values>${installedApplications}</values>
      <variables>key name value</variables>
      <actionList>
        <md5 text="${key}" variable="md5"/>
        <actionGroup>
          <actionList>
            <registryGet>
              <key>${key}</key>
              <name>UninstallString</name>
              <variable>uninstallCmd</variable>
            </registryGet>
            <showProgressDialog>
              <title>Uninstalling ${value}</title>
              <actionList>
                <runProgram>
                  <program>${uninstallCmd}</program>
                  <programArguments>--mode unattended</programArguments>
                </runProgram>
              </actionList>
            </showProgressDialog>
            <break/>
          </actionList>
          <ruleList>
            <compareText>
              <text>${md5}</text>
              <logic>equals</logic>
              <value>${applicationToDelete}</value>
            </compareText>
          </ruleList>
        </actionGroup>
      </actionList>
    </foreach>
  </postShowPageActionList>
  <preShowPageActionList>
    <removeChoiceOptions>
      <name>applicationToDelete</name>
      <options></options>
    </removeChoiceOptions>
    <registryFind>
      <findAll>1</findAll>
      <keyPattern>*</keyPattern>
      <namePattern>DisplayName</namePattern>
      <rootKey>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall</rootKey>
      <searchDepth>1</searchDepth>
      <variable>installedApplications</variable>
    </registryFind>
    <setInstallerVariable>
      <name>text</name>
      <value></value>
    </setInstallerVariable>
    <foreach>
      <values>${installedApplications}</values>
      <variables>key name value</variables>
      <actionList>
        <registryGet>
          <key>${key}</key>
          <name>Publisher</name>
          <variable>publisher</variable>
        </registryGet>
        <actionGroup>
          <actionList>
            <md5 text="${key}" variable="md5"/>
            <setInstallerVariable>
              <name>text</name>
              <value>${text}
${md5}=${value}</value>
            </setInstallerVariable>
          </actionList>
          <ruleList>
            <compareText>
              <logic>equals</logic>
              <text>${publisher}</text>
              <value>${project.vendor}</value>
            </compareText>
          </ruleList>
        </actionGroup>
      </actionList>
    </foreach>
    <addChoiceOptionsFromText>
      <name>applicationToDelete</name>
      <text>${text}</text>
    </addChoiceOptionsFromText>
  </preShowPageActionList>
</choiceParameter>

Another example might be showing a list of drives for the user to pre-select on Microsoft Windows. The following actions will create and execute a Visual Basic script, whose output will be used to populate the choices of the parameter:

<project>
  ...
  <initializationActionList>
    <writeFile>
      <encoding>utf-8</encoding>
      <path>${system_temp_directory}/drives.vbs</path>
      <text>Set objFSO = CreateObject("Scripting.FileSystemObject")
Set colDrives = objFSO.Drives
For Each objDrive in colDrives
  If objDrive.DriveType = 2 Then
    Wscript.Echo objDrive.DriveLetter
  End If
Next
  </text>
    </writeFile>
    <setInstallerVariableFromScriptOutput>
      <exec>cscript.exe</exec>
      <execArgs>//NOLOGO "${system_temp_directory}/drives.vbs"</execArgs>
      <name>drives</name>
    </setInstallerVariableFromScriptOutput>
    <foreach>
      <values>${drives}</values>
      <variables>drive</variables>
      <actionList>
        <addChoiceOptions>
          <name>targetdrive</name>
          <optionList>
            <option>
              <value>${drive}</value>
              <text>Drive ${drive}</text>
           </option>
          </optionList>
        </addChoiceOptions>
      </actionList>
    </foreach>
  </initializationActionList>
  ...
  <parameterList>
    <choiceParameter>
      <name>targetdrive</name>
      <description>Which drive?</description>
      <explanation>Disk drive to install application to</explanation>
      <value></value>
      <default></default>
      <allowEmptyValue>0</allowEmptyValue>
      <displayType>radiobuttons</displayType>
      <ordering>default</ordering>
      <width>40</width>
      <postShowPageActionList>
        <setInstallerVariable>
          <name>installdir</name>
          <value>${targetdrive}:/${project.shortName}</value>
        </setInstallerVariable>
      </postShowPageActionList>
      <validationActionList>
        <!-- Do not allow selecting a drive without write access -->
        <throwError>
          <text>Selected drive cannot be written to</text>
          <ruleList>
             <fileTest>
               <condition>not_writable</condition>
               <path>${targetdrive}:/</path>
             </fileTest>
          </ruleList>
        </throwError>
      </validationActionList>
    </choiceParameter>
    ...
    <directoryParameter>
      <name>installdir</name>
      <value></value>
      <allowEmptyValue>0</allowEmptyValue>
      <ask>0</ask>
    </directoryParameter>
  </parameterList>
</project>

Please note that the above code is hiding the regular installdir page and configuring it in the choice <postShowPageActionList> to the chosen disk drive.

7.1.5. Parameter Groups

Group Parameter

A group parameter allows you to logically group other parameters. They will be presented in the same screen in GUI and text installers. You need to place the grouped parameters in a parameterList section, as shown in the example below. Please note that parameter groups also need to contain a <name> tag.

   <parameterGroup>
     <name>userandpass</name>
     <explanation>Please enter the username and password for your database.</explanation>
     <parameterList>
       <stringParameter>
         <name>username</name>
         <default>admin</default>
         <description>Username</description>
       </stringParameter>
       <passwordParameter>
         <ask>yes</ask>
         <name>masterpass</name>
         <description>Password</description>
         <descriptionRetype>Retype password</descriptionRetype>
         <explanation>Please provide a password for the database user</explanation>
         <cliOptionName>password</cliOptionName>
       </passwordParameter>
     </parameterList>
   </parameterGroup>

You can also implement more complex layouts, for example, a page to request a serial key:

 <parameterGroup>
    <name>licensekey</name>
    <title>License Key</title>
    <explanation>Please enter your registration key</explanation>
    <value></value>
    <default></default>
    <orientation>horizontal</orientation>
    <parameterList>
       <!-- A stringParameter for each field. We include a "-" as description to simulate the license-type format -->
       <stringParameter name="code1" description="" allowEmptyValue="0" width="4"/>
       <stringParameter name="code2" description="-" allowEmptyValue="0" width="4"/>
       <stringParameter name="code3" description="-" allowEmptyValue="0" width="4"/>
       <stringParameter name="code4" description="-" allowEmptyValue="0" width="4"/>
    </parameterList>
    <validationActionList>
       <foreach variables="field">
          <values>"${code1}" "${code2}" "${code3}" "${code4}"</values>
          <actionList>
             <throwError>
                <text>${field}: Field should be four digits length</text>
                <ruleList>
                    <compareTextLength text="${field}" logic="equals" length="4" negate="1"/>
                </ruleList>
             </throwError>
             <throwError>
                <text>${field}: Should be a pure digit string</text>
                <ruleList>
                    <stringTest text="${field}" type="digit" negate="1"/>
                </ruleList>
             </throwError>
          </actionList>
       </foreach>
    </validationActionList>
    <postShowPageActionList>
       <setInstallerVariable name="normalizedkey" value="${code1}${code2}${code3}${code4}"/>
    </postShowPageActionList>
    <ruleList>
        <compareText text="${installer_ui}" logic="equals" value="gui"/>
    </ruleList>
 </parameterGroup>

Please note this layout won’t be properly displayed in text mode so the example hides the page if the ${installer_ui} built-in variable is not gui (see Installation Modes for additional details). If you plan to support text mode, you should then create an additional simplified page to be displayed instead:

 <stringParameter>
    <name>licensekeytext</name>
    <title>License Key</title>
    <description>Please introduce your registration key:</description>
    <ruleList>
       <compareText text="${installer_ui}" logic="equals" value="text"/>
    </ruleList>
 </stringParameter>

7.1.6. Dynamic Parameter Groups

Boolean Parameter Group

This parameter is a special <parameterGroup> that allows toggling its state through clicking a checkbox. In addition to grouping the contained parameters, the <booleanParameterGroup> also contains a <value>, like the <booleanParameter> does, that can be accessed like any other parameters. A basic example snippet would be:

<booleanParameterGroup>
   <name>advanced</name>
   <description>Advanced Mode</description>
   <validationType>always</validationType>
   <value>0</value>
   <parameterList>
      <choiceParameter>
         <name>emailNotifications</name>
         <value>always</value>
         <description>Email notifications</description>
         <optionList>
            <option description="Always send notifications" text="Always" value="always"/>
            <option description="Never send notifications" text="Never" value="never"/>
         </optionList>
      </choiceParameter>
      <stringParameter name="subject" description="Notifications Subject" value="[NOTIFICATION] #"/>
      <directoryParameter description="Cache Dir" name="cacheDir" value="${system_temp_directory}/cache"/>
   </parameterList>
</booleanParameterGroup>

The parameters in the <parameterList> will be surrounded by a frame, selectable by a checkbox. If the checkbox is deselected, the child parameters will be displayed as read only (or won’t be displayed in text mode):

Boolean Parameter Group Deselected
Figure 2. Boolean Parameter Group Deselected

Enabling the checkbox will then make the child parameters editable:

Boolean Parameter Group Selected
Figure 3. Boolean Parameter Group Selected

The <booleanParameterGroup> also allows specifying under which conditions their grouped parameters will execute their <postShowPageActionList> and <validationActionList> actions through the <validationType> setting. Its default value is always, which makes all of the visible child components to execute their <postShowPageActionList> and <validationActionList> actions like a regular parameter group would. This is the recommended setting when you just need the <booleanParameterGroup> to group a set of settings and allow them to be disabled so end users does not focus their attention on secondary configuration fields. For example, the example above showed a group containing some secondary settings, disabled by default. This way users will know that they do not require much attention or that they do not need to worry if they does not understand them.

In other circumstances, you won’t need the <booleanParameterGroup> only for grouping, but also to perform some actions on the provided information only if the checkbox is selected. For example, you could ask your users if they want to register the installation. In the case of the user not checking the <booleanParameterGroup> checkbox, you won’t be interested in the information contained in the child parameters or in reporting errors on its validation actions. In these cases you can set the <validationType> to ifSelected.

Take into account that, regardless of the state of the <booleanParameterGroup> or the setting configured in its <validationType>, its child will unconditionally execute its <preShowPageActionList>. The reason is that the <preShowPageActionList> is intended to be used to customize the values of the page prior to displaying it, not to perform operations on the values, which have not yet been introduced or acknowledged by the end user.

In addition, the <booleanParameterGroup> action lists are also not affected. As any other parameter, it will execute all of its actions.

The below snippet illustrates the behavior:

<booleanParameterGroup>
   <name>register</name>
   <description>Register Installation</description>
   <validationType>ifSelected</validationType>
   <value>0</value>
   <parameterList>
      <stringParameter name="username" description="User Name" allowEmptyValue="0" value=""/>
      <stringParameter name="email" description="Email" allowEmptyValue="0" value="">
         <validationActionList>
            <throwError text="The provided value does not seem an email address">
               <ruleList>
                 <regExMatch>
                   <logic>does_not_match</logic>
                   <pattern>[a-zA-Z0-9\._-]+@[a-zA-Z0-9\._-]+</pattern>
                   <text>${email}</text>
                 </regExMatch>
               </ruleList>
            </throwError>
         </validationActionList>
      </stringParameter>
      <stringParameter description="License Key" name="key" value="" allowEmptyValue="0"/>
   </parameterList>
   <validationActionList>
      <httpPost>
        <url>http://example.com/register.php</url>
        <filename>${installdir}/result</filename>
        <queryParameterList>
          <queryParameter name="name" value="${username}"/>
          <queryParameter name="email" value="${email}"/>
          <queryParameter name="license" value="${key}"/>
        </queryParameterList>
        <ruleList>
           <isTrue value="${register}"/>
        </ruleList>
      </httpPost>
      ...
   </validationActionList>
</booleanParameterGroup>

If the user checks the checkbox, the parameters will execute their validations. Please note that the code adds the registration actions to the <validationActionList> of the <booleanParameterGroup>, which are always executed. That is why it includes a rule checking its state.

Choice Parameter Group

This parameter is a special <parameterGroup> that allows selecting a subset of widgets. In addition to grouping the contained parameters, the <choiceParameterGroup> also contains a <value>, like the <choiceParameter> does, that can be accessed like any other parameters. The value stored will represent the name of the selected child parameter. A basic example snippet would be:

<choiceParameterGroup>
   <name>usbLocation</name>
   <description>Select an USB Drive</description>
   <value>usbDetectedList</value>
   <parameterList>
      <choiceParameter>
         <name>usbDetectedList</name>
         <value></value>
         <description>Autodetected List</description>
         <optionList>
         </optionList>
         <preShowPageActionList>
             <addChoiceOptionsFromText>
               <name>usbDetectedList</name>
               <text>${driveInfo}</text>
             </addChoiceOptionsFromText>
         </preShowPageActionList>
      </choiceParameter>
      <directoryParameter name="customDir" description="Custom Location" value=""/>
   </parameterList>
</choiceParameterGroup>

The parameters in the <parameterList> will be surrounded by a frame. The <choiceParameterGroup> will present a radiobutton for each of its first-level child parameters, labeled with the description of the child parameter:

Choice Parameter Group
Figure 4. Choice Parameter Group

The <choiceParameterGroup> will execute all of its child parameters <preShowpageActionList> (to allow them to auto-reconfigure) but will only execute the <validationActionList> and <postShowPageActionList> of the selected parameter.

Similarly to the <booleanParameterGroup>, the <choiceParameterGroup> will always execute its action lists regardless of the selected child.

The default look and feel of the parameter is to show as disabled all the deselected parameters, preventing the user from editing their information until the corresponding radiobutton is selected. If you want to overwrite this behavior and make all the parameters editable regardless of the selected option, you just have to use the <unselectedOptionsBehavior> tag:

<choiceParameterGroup>
   <name>usbLocation</name>
   <description>Select an USB Drive</description>
   <unselectedOptionsBehavior>none</unselectedOptionsBehavior>
   <value>usbDetectedList</value>
   <parameterList>
      ...
   </parameterList>
</choiceParameterGroup>
Nesting

The <booleanParameterGroup> and <choiceParameterGroup> parameters, like any other parameter, can be grouped, either using a regular <parameterGroup> or another <booleanParameterGroup> or <choiceParameterGroup>.

Their only limitation is that they cannot configure their orientation as regular parameterGroups do.

An example of a complex layout using nesting could be the produced using the below code:

 <booleanParameterGroup>
   <name>register</name>
   <description>Register Installation</description>
   <explanation></explanation>
   <value>1</value>
   <default></default>
   <validationType>ifSelected</validationType>
   <parameterList>
     <stringParameter>
       <name>username</name>
       <description>Username</description>
       <allowEmptyValue>0</allowEmptyValue>
       <width>40</width>
     </stringParameter>
     <passwordParameter>
       <name>password</name>
       <description>Enter password</description>
       <allowEmptyValue>0</allowEmptyValue>
       <descriptionRetype></descriptionRetype>
       <width>20</width>
     </passwordParameter>
     <stringParameter>
       <name>phone</name>
       <description>Phone</description>
       <allowEmptyValue>1</allowEmptyValue>
       <width>40</width>
       <validationActionList>
         <throwError>
           <text>The provided phone '${phone}' does not seem a valid one</text>
           <ruleList>
             <regExMatch>
               <logic>does_not_match</logic>
               <pattern>^[\d+-]*$</pattern>
               <text>${phone}</text>
             </regExMatch>
           </ruleList>
         </throwError>
       </validationActionList>
     </stringParameter>
     <choiceParameterGroup>
       <name>keyChoice</name>
       <description>Select how to provide your license key</description>
       <explanation></explanation>
       <value></value>
       <default></default>
       <parameterList>
         <fileParameter>
           <name>keyFile</name>
           <description>Load from file</description>
           <allowEmptyValue>0</allowEmptyValue>
           <mustBeWritable>0</mustBeWritable>
           <mustExist>0</mustExist>
           <width>40</width>
         </fileParameter>
         <stringParameter>
           <name>licenseText</name>
           <description>Enter license key</description>
           <allowEmptyValue>1</allowEmptyValue>
           <width>40</width>
         </stringParameter>
       </parameterList>
     </choiceParameterGroup>
   </parameterList>
 </booleanParameterGroup>
Complex Parameter Group Layout
Figure 5. Complex Parameter Group Layout

7.1.7. Command Line Parameters

All of the parameters in a project are mapped to command line flags and, depending on the visibility of the parameter (configured by the <ask> property,) they will be displayed in the help menu.

The name of the command line flag will default to the parameter name but, if needed, it can be configured setting by a value for its <cliOptionName> property:

    <parameterList>
       <directoryParameter>
          <name>installdir</name>
          <description>This is the description</description>
          <explanation>And here goes the explanation</explanation>
          <default>${platform_install_prefix}/${project.shortName}-${project.version}</default>
          <ask>yes</ask>
          <cliOptionName>prefix</cliOptionName>
       </directoryParameter>
       <!-- Will Not be displayed in help menu -->
       <stringParameter name="secretFlg" value="" ask="0"/>
    </parameterList>

Even if a parameter is configured as hidden by setting its <ask> property to 0, it will be accessible by the command line interface; it will just not be visible to the end user. Hidden parameters are very useful because they can be used as permanent variables that can be reconfigured when launching the installer. A good example would be to disable license validation when testing:

    <parameterList>
       <stringParameter>
          <name>license</name>
          <description>License Registration Page</description>
          <explanation>Please introduce you license number</explanation>
          <ask>yes</ask>
          <ruleList>
              <isTrue value="${validateLicense}"/>
          </ruleList>
       </stringParameter>
       <!-- Will Not be displayed in help menu -->
       <booleanParameter name="validateLicense" value="1" ask="0"/>
    </parameterList>

To avoid having to introduce the license number each time you launch the installer, you just have to disable the page when launching the installer:

$> myInstaller.run --validateLicense 0

Although the <ask> property allows us to configure whether or not a page is displayed through the installation process and in the help menu, there are some scenarios in which it is desirable to show the associated command line flag while permanently hiding the page at runtime. This can be achieved by attaching a rule to the page:

    <parameterList>
       <stringParameter>
          <name>create_shortcuts</name>
          <description>Create shortcuts</description>
          <explanation>Whether to create or not shortcuts to the application</explanation>
          <ask>yes</ask>
          <ruleList>
              <isTrue value="0"/>
          </ruleList>
       </stringParameter>
    </parameterList>

As you have set ask="1", the command line flag is visible through the help menu but at runtime, when the rule attached is evaluated, it will not be displayed.

Note
If a page is not displayed, its associated actions are not executed

Independently of whether the page is hidden through a rule or by setting ask="0", the action lists associated with the page will not be executed. The same will happen in unattended mode, as the pages are never displayed.

7.1.8. Option Files

As explained in the previous section, the values of the installer parameters can be configured by passing command line options. However, when a large number of parameters must be configured, there is a more convenient way to do so using an option file.

An option file is just a .properties file containing all of the parameters to configure:

prefix=/tmp
validateLicense=0
installDocumentation=1
...

This file can be passed to the installer using the --optionfile command line flag:

$> myInstaller.run --optionfile path/to/configuration.options

Another way of providing the option file is to create a file in the same directory as the installer with the same name plus the .options suffix:

$> ls some/output/directory
$> myInstaller.run
$> myInstaller.run.options

In both cases, the installer will parse the file and will map all the entries to internal parameters. Lines starting with a first non-blank # character will be treated as comments.

8. Actions

8.1. What are Actions?

There are a number of installation tasks that are common to many installers, such as changing file permissions, substituting a value in a file, and so on. BitRock InstallBuilder includes a large number of useful built-in actions for these purposes.

You can add new actions by manually editing the XML project file directly or in the Advanced section of the GUI building tool. Actions are either attached to a particular folder tag in the project file (<actionList>) that will be executed after the contents of the folder have been installed, or can be part of specific action lists that are executed at specific points during installation.

Actions usually take one or more arguments. If one of those arguments is a file matching expression (<files>) and the action was included in a <folder> action list, the matching will also occur against the contents of the folder:

<folder>
  <name>binaries</name>
  ...
  <destination>${installdir}</destination>
   <distributionFileList>
       <distributionDirectory>
          <origin>/some/path/to/bin</origin>
       </distributionDirectory>
   </distributionFileList>
  <actionList>
     <changePermissions permissions="0755" files="*"/>
  </actionList>
</folder>

In the example above, although the <changePermissions> action is not recursive, as it was executed inside a <folder> action list, the pattern will be recursively matched against all of the files contained in the bin directory. Alternatively, you could use the <postInstallationActionList> to change the permissions, but at that point the <changePermissions> action won’t execute recursively and you will need to provide a more complex pattern:

<folder>
  <name>binaries</name>
  ...
  <destination>${installdir}</destination>
   <distributionFileList>
       <distributionDirectory>
          <origin>/some/path/to/bin</origin>
       </distributionDirectory>
   </distributionFileList>
</folder>
...
<postInstallationActionList>
   <!-- Multi-level pattern so child files from sublevel 0 to 4 are considered -->
   <changePermissions permissions="0755" files="${installdir}/bin/{*,*/*,*/*/*,*/*/*/*}"/>
</postInstallationActionList>

In addition, if the arguments contain references to installer variables, such as the installation directory, they will be properly expanded before the action is executed.

8.1.1. Showing the Progress Text in Builder GUI

Complex InstallBuilder projects often consist of multiple <actionGroup> items that contain actions, which may be difficult to manage.

The GUI building tool allows showing the <actionGroup>'s <progressText> in the GUI instead of the action type.

To do this, simply open the Preferences dialog and enable the Show Progress Text in GUI option, such as:

InstallBuilder Preferences Window
Figure 42: InstallBuilder Preferences Window

After enabling it, all <actionGroup> elements that have their <progressText> set will show it in the action list tree:

Action Lists Showing Progress Text
Figure 42: Action Lists Showing Progress Text

8.2. Action Lists

InstallBuilder actions are organized in what are called action lists, which are executed at specific points of the installation process. It is important to understand how and when each action must be performed, what differences exist between action lists inside components and within the primary installer, how the installer will behave when you run it in different installation modes (GUI, text, or unattended) and what happens when you generate rpm or deb packages.

You can place your action lists in the main installer project or in one of its components. Figure 43 shows all the available action lists in the GUI:

BitRock InstallBuilder Action Lists (in order of execution)
Figure 43: BitRock InstallBuilder Action Lists (in order of execution)

8.2.1. Building the Installer

  • Pre-build Actions - <preBuildActionList>: Executes before generating the installer file. These actions usually include setting environment variables or performing some type of processing on the files that will go into the installer before they are packed into it. For multi-platform CDROM installers, the preBuildActionList is executed once at the beginning of the CDROM build, and then again for every one of the specific platform installers.

  • Post-build Actions - <postBuildActionList>: Executes after generating the installer file. These actions are usually useful to reverse any changes made to the files during the preBuildActionList or to perform additional actions on the generated installer, such as signing it by invoking an external tool. For multi-platform CDROM installers, the postBuildActionList is executed once for every one of the specific platform installers and one final time for the whole CDROM build.

8.2.2. Help Menu

  • Pre Show Help Actions - <preShowHelpActionList>: Executes before help information is displayed. The help is displayed when the --help command line option is passed to an installer. It can be useful for example for modifying the description of parameters based on the system the installer is running on.

Help menu
Sample Project 1.0
Usage:

 --help                                      Display the list of valid options

 --version                                   Display product information

 --unattendedmodeui <unattendedmodeui>       Unattended Mode UI
                                             Default: none
                                             Allowed: none minimal minimalWithDialogs

 --optionfile <optionfile>                   Installation option file
                                             Default:

 --debuglevel <debuglevel>                   Debug information level of verbosity
                                             Default: 2
                                             Allowed: 0 1 2 3 4

 --mode <mode>                               Installation mode
                                             Default: gtk
                                             Allowed: gtk xwindow text unattended

 --debugtrace <debugtrace>                   Debug filename
                                             Default:

 --enable-components <enable-components>     Comma-separated list of components
                                             Default: default
                                             Allowed: default

 --disable-components <disable-components>   Comma-separated list of components
                                             Default:
                                             Allowed: default

 --installer-language <installer-language>   Language selection
                                             Default: en
                                             Allowed: sq ar es_AR az eu pt_BR bg ca hr cs da nl en et fi fr de el he hu id it ja kk ko lv lt no fa pl pt ro ru sr zh_CN sk sl es sv th zh_TW tr tk va vi cy

 --prefix <prefix>                           Installation Directory
                                             Default: /home/bitrock/sample-1.0

8.2.3. Installation Process

  • Splash Screen: After the installer internal initialization, the Splash Screen is displayed. The duration of this event is configured through the <splashScreenDelay> property or can be skipped if it was disabled setting <disableSplashScreen>1</disableSplashScreen>

Splash Screen
Figure 44: Splash Screen
  • Initialization Actions - <initializationActionList>: Executes when the installer has started, just before the parsing of the command line options.

  • Language Selection: If <allowLanguageSelection> is set to 1 and no language was provided through the command line, the language selection dialog will be displayed, allowing your users to select one of the allowed languages defined in the <allowedLanguages> tag.

Language Selection dialog
Figure 45: Language Selection dialog
  • Pre-installation Actions - <preInstallationActionList>: Executes before the first page of the installer is displayed, right after the parsing of the command line options takes place. It is commonly used for detecting a Java (tm) Runtime Environment or for setting user-defined installer variables that will be used later on:

Redefine ${installdir} based on the platform

<preInstallationActionList>
   <setInstallerVariable>
     <name>installdir</name>
     <value>${env(SYSTEMDRIVE)}/${project.shortName}</value>
     <ruleList>
        <platformTest type="windows"/>
     </ruleList>
   </setInstallerVariable>
   <setInstallerVariable>
     <name>installdir</name>
     <value>/usr/local/${project.shortName}</value>
     <ruleList>
        <platformTest type="linux"/>
     </ruleList>
   </setInstallerVariable>
</preInstallationActionList>
  • Component Selection

Component Selection Page
Figure 46: Component Selection Page
  • Component Selection Validation Actions - <componentSelectionValidationActionList>: Executes after the component page is displayed to check that the selected components are a valid combination.

  • Parameter Pages

Each parameter has three 3 different action lists: validationActionList, preShowPageActionList and postShowPageActionList. Note that those actions are not executed if the installer is executed in unattended mode.

  • Validation Actions - <validationActionList>: Executes once the user has specified a value in the user interface page associated with the parameter and has pressed the Next button (or Enter in a text-based interface). The actions can be used to check that the value is valid (for example, that it specifies a path to a valid Perl interpreter). If any of the actions result in an error, an error message will be displayed to the user and the user will be prompted to enter a valid value.

  • Pre Show Page Actions - <preShowPageActionList>: Executes before the corresponding parameter page is displayed. This can be useful for changing the value of the parameter before it is displayed.

  • Post Show Page Actions - <postShowPageActionList>: Executes after the corresponding parameter page has been displayed. This can be useful for performing actions or setting environment variables based on the value of the parameter.

  • Ready to Install Actions - <readyToInstallActionList>: Executes right before the file copying step starts. It is commonly used to execute actions that depend on user input.

  • Unpacking process

  • Folder Actions - <actionList>: Executes just after files defined in the particular folder are installed, the next folder files are copied and its actionList executed, etc.

  • Shortcuts Creation

  • Post-installation Actions - <postInstallationActionList>: Executes after the installation process has taken place but before the uninstaller is created and the final page is displayed.

  • Post-Uninstaller Creation Actions - <postUninstallerCreationActionList>: Executes after the uninstaller has been created but before the final page has been displayed.

  • Final Page Actions - <finalPageActionList>: Executes after the installation has completed and the final page has been displayed to the user. These actions usually include launching the program that has just been installed. For each one of the actions contained in this list, a checkbox will be displayed (or a question in text mode). If the checkbox is selected, then the action will be executed when the Finish button is pressed.

8.2.4. Uninstallation

  • Pre-uninstallation Actions - <preUninstallationActionList>: Executes before the uninstallation process takes place, such as unsetting user-defined installer variables or deleting files created after installation occurred.

  • Post-uninstallation Actions - <postUninstallationActionList>: Executes after the uninstallation process takes place.

8.2.5. Special action lists

  • Installation Aborted Actions - <installationAbortedActionList>: Executes when the installation process is aborted.

8.2.6. Unattended mode, RPM and DEB packages

These are special cases. There is no interaction with the end-user and the following action lists are not executed:

As the file installation step is executed by the RPM / DEB package manager and not by InstallBuilder itself, there is no way to execute any action from the installer until the files have been installed on the system. To be precise, the <preInstallationActionList> will not be executed, and the <initializationActionList>, <readyToInstallActionList> and any folder’s actionList will be executed after the files have been installed on the system.

As a final note, the <installationAbortedActionList> will only be executed if the error was generated by any of the actions performed directly by the installer. I.e., if the error is generated during the file installation step, which is performed by the RPM / DEB package manager, the BitRock installer application will not be notified and therefore the <installationAbortedActionList> will not be executed.

To summarize, the following list provides all of the differences regarding action lists when installing an RPM / DEB package:

8.2.7. Main Project and Components Execution Order

Each action list may be included in the main project or inside the components. Let’s take an <initializationActionList> as an example. You have one main <initializationActionList> and 4 others in the components A, B, C and D. The components are declared following the order A, B, C, D (A is the first entry and D is the last one). In this case, the main <initializationActionList> is executed first and then each component’s action lists are executed (A, B, C, D - the order of component declaration is important).

You can divide all action lists into two groups based on what is executed first: main project or component action lists:

The installer executes action lists by group, which means that first, all <initializationActionList> actions take place and then all <preInstallationActionList> actions are executed:

Initialization Action List
  • Project Initialization Action List

  • Component A Initialization Action List

  • Component B Initialization Action List

Preinstallation Action List
  • Project Preinstallation Action List

  • Component A Preinstallation Action List

  • Component B Preinstallation Action List …

For example, for a project with two components:

<project>
    ...
    <initializationActionList>
        <showInfo>
            <text>I'm the project in the initialization</text>
        </showInfo>
    </initializationActionList>
    <preInstallationActionList>
        <showInfo>
            <text>I'm the project in the preInstallation</text>
        </showInfo>
    </preInstallationActionList>
    <componentList>
        <component>
            <name>componentA</name>
            <description>Component A</description>
            ...
            <initializationActionList>
                <showInfo>
                    <text>I'm Component A in the initialization</text>
                </showInfo>
            </initializationActionList>
            <preInstallationActionList>
                <showInfo>
                    <text>I'm Component A in the preInstallation</text>
                </showInfo>
            </preInstallationActionList>
        </component>
        <component>
            <name>componentB</name>
            <description>Component B</description>
            <canBeEdited>1</canBeEdited>
            ...
            <initializationActionList>
                <showInfo>
                    <text>I'm Component B in the initialization</text>
                </showInfo>
            </initializationActionList>
            <preInstallationActionList>
                <showInfo>
                    <text>I'm Component B in the preInstallation</text>
                </showInfo>
            </preInstallationActionList>
        </component>
    </componentList>
</project>

If you build and execute the installer in, for example, unattended mode, you will see the following in the console:

 I'm the project  in the initialization
 I'm Component A in the initialization
 I'm Component B in the initialization
 I'm the project  in the preinstallation
 I'm Component A in the preInstallation
 I'm Component B in the preInstallation

The <installationAbortedActionList> will only be executed if the error was generated by any of the actions performed directly by the installer. If the error is generated during the file installation step, which is performed by the RPM / DEB package manager, the BitRock installer application will not be notified and therefore the <installationAbortedActionList> will not be executed.

8.3. Running External Programs

In addition to built-in actions, InstallBuilder allows external programs to be executed through the <runProgram> action:

<runProgram>
  <program>kill</program>
  <programArguments>-f myBin</programArguments>
</runProgram>

After the external program ends, its standard streams are registered in the built-in variables ${program_stdout}, ${program_stderr} and ${program_exit_code}:

  • ${program_stdout}: Program Standard Output

  • ${program_stderr}: Program Standard Error

  • ${program_exit_code}: Program Exit Code

For example, to get the path of the gksudo command on Linux you could use the snippet below:

   <runProgram>
      <program>which</program>
      <programArguments>gksudo</programArguments>
      <!-- The gksudo program may not be
      installed so it is necessary to mask errors -->
      <abortOnError>0</abortOnError>
      <showMessageOnError>0</showMessageOnError>
   </runProgram>

And get the path from the ${program_stdout} variable. If the execution fails, the variable will be defined as empty.

You can also execute more complex commands such as pipes or include redirections. For example, the code below can be used to count the number of files in a directory:

   <runProgram>
      <program>ls</program>
      <programArguments>-l ${installdir}/logs/*.log | wc -l</programArguments>
   </runProgram>

Although you can always check the created built-in variables, if you are explicitly calling the external program to use its output like in the gksudo example (as opposed to other cases, such us creating a MySQL database in which the important result is the database being created) it may be a better solution to use a <setInstallerVariableFromScriptOutput> action:

   <setInstallerVariableFromScriptOutput>
      <exec>which</exec>
      <execArgs>gksudo</execArgs>
      <name>gksudoPath</name>
      <!-- The gksudo program may not be
      installed so it is necessary to mask errors -->
      <abortOnError>0</abortOnError>
      <showMessageOnError>0</showMessageOnError>
   </setInstallerVariableFromScriptOutput>

The code above will create a new variable gksudoPath containing the ${program_stdout} of the executed program.

On Windows, the <runProgram> action will by default launch programs by their 8.3 names (the same path type obtained through the .dos suffix) to avoid potential errors dealing with spaces and invalid characters in the path. However, as the 8.3 path may change depending on other files in the folder, sometimes this is not convenient. For example, when you need to check if the executable is running through the <processTest> rule. In these cases, you can prevent the automatic 8.3 conversion using the <useMSDOSPath> tag:

<project>
   ...
   <finalPageActionList>
     ...
     <runProgram>
       <progressText>Launch Application</progressText>
       <program>${installdir}/My Application with long filename.exe"</program>
       <programArguments>&amp;</programArguments>
       <!-- Use long filename -->
       <useMSDOSPath>0</useMSDOSPath>
     </runProgram>
     ...
   </finalPageActionList>
   ...
   <preUninstallationActionList>
     <while>
       <actionList>
         <showWarning>
            <text>The application "My Application with long filename.exe" is still running, please close it and click ok</text>
         </showWarning>
       </actionList>
       <conditionRuleList>
         <processTest>
            <logic>is_running</logic>
            <name>My Application with long filename.exe</name>
         </processTest>
       </conditionRuleList>
     </while>
     ...
   </preUninstallationActionList>
   ...
</project>

The <runProgram> action can also be used to call external interpreters, for example, to execute Visual Basic or AppleScripts. The example below explains how to take advantage of this to restart the computer after the installation on OS X, in which the <rebootRequired> tag is not allowed:

<finalPageActionList>
  <actionGroup progressText="Reboot Computer">
    <actionList>
      <runProgram>
        <abortOnError>0</abortOnError>
        <program>osascript</program>
        <programArguments>-e "tell application \"Finder\" to restart"</programArguments>
        <showMessageOnError>0</showMessageOnError>
      </runProgram>
      <!-- If using osascript failed, try using reboot -->
      <runProgram>
        <program>reboot</program>
        <programArguments></programArguments>
        <ruleList>
          <compareText>
            <logic>does_not_equal</logic>
            <text>${program_stderr}</text>
            <value></value>
          </compareText>
        </ruleList>
      </runProgram>
    </actionList>
  </actionGroup>
</finalPageActionList>
Caution
When running shell scripts with subscripts in background

On Unix, when calling shell scripts that also call subscripts in the background, even if the execution of the main shell script terminates, the installer keeps waiting for the launched child processes in background to close their standard streams. An example of this situation would be when manually starting a Unix service backup-daemon:

backup-daemon script
# chkconfig:        235 30 90
# ...
start()
{
    #...
    /opt/backups/bin/start-backup-daemon.sh &
    #...
}

# ...
exit 0

When calling this script from the installer, for example using the code below:

 <runProgram>
   <program>/etc/init.d/backup-daemon</program>
   <programArguments>start</programArguments>
   <workingDirectory>/etc/init.d</workingDirectory>
 </runProgram>

The child script /opt/backups/bin/start-backup-daemon.sh is executed in background and the main service script quickly reaches to the end and executes exit 0. However, as the child process is still running, the installer hangs until it finishes or its standard streams are closed. The solution for this issue would be to redirect the output of the child script to /dev/null:

backup-daemon script reworked
# chkconfig:        235 30 90
# ...
start()
{
    #...
    /opt/backups/bin/start-backup-daemon.sh > /dev/null 2> /dev/null &
    #...
}

# ...
exit 0

This way the installer won’t hang waiting for output from /opt/backups/bin/start-backup-daemon.sh and the installation will continue after the script reaches the exit 0.

Another solution that does not require modifying the service script would be to redirect the output when calling it from the installer:

 <runProgram>
   <program>/etc/init.d/backup-daemon</program>
   <programArguments>start &gt; /dev/null 2&gt; /dev/null</programArguments>
   <workingDirectory>/etc/init.d</workingDirectory>
 </runProgram>

Or, if you are interested in the output, redirect it to files. The snippets below create a custom action to wrap the <runProgram> and make it return the redirected streams:

Custom action wrapping the <runProgram> to redirect its streams to files and return the result

<functionDefinitionList>
  <actionDefinition>
    <name>runProgramRedirected</name>
    <actionList>
      <!-- Create a timestamp to use unique filenames -->
      <createTimeStamp>
        <format>%Y%m%d%H%M%S</format>
        <variable>timestamp</variable>
      </createTimeStamp>
      <!-- Call the problematic script redirecting its output to files -->
      <runProgram>
        <program>${program}</program>
        <programArguments>${programArguments} &gt; ${system_temp_directory}/stdout_${timestamp}.txt 2&gt; ${system_temp_directory}/stderr_${timestamp}.txt</programArguments>
        <workingDirectory>${workingDirectory}</workingDirectory>
      </runProgram>

      <!-- Read the result into variables -->
      <readFile>
        <name>${stdout}</name>
        <path>${system_temp_directory}/stdout_${timestamp}.txt</path>
      </readFile>
      <readFile>
        <name>${stderr}</name>
        <path>${system_temp_directory}/stderr_${timestamp}.txt</path>
      </readFile>
      <!-- Remove the files -->
      <deleteFile path="${system_temp_directory}/stdout_${timestamp}.txt"/>
      <deleteFile path="${system_temp_directory}/stderr_${timestamp}.txt"/>

      <globalVariables names="${stderr} ${stdout}"/>
    </actionList>
    <parameterList>
       <stringParameter name="program" value="" default=""/>
       <stringParameter name="programArguments" value="" default=""/>
       <stringParameter name="workingDirectory" value="" default=""/>
       <stringParameter name="stderr" value="" default="program_stderr"/>
       <stringParameter name="stdout" value="" default="program_stdout"/>
    </parameterList>
  </actionDefinition>
</functionDefinitionList>

And call it when needed:

 <runProgramRedirected>
   <program>/etc/init.d/backup-daemon</program>
   <programArguments>start</programArguments>
   <workingDirectory>/etc/init.d</workingDirectory>
 </runProgramRedirected>

8.3.1. Launching in the Background

The standard behavior of the <runProgram> action is to wait for the spawned process to end but it is also possible to launch the process in the background by appending an ampersand to the arguments. For example, to execute our application at the end of the installation without preventing the installer from finishing you could use the following snippet:

 <finalPageActionList>
   <runProgram>
      <program>${installdir}/bin/myApplication.exe</program>
      <programArguments>--arg1 value1 --arg2 value 2 &amp;</programArguments>
   </runProgram>
 </finalPageActionList>

8.3.2. Opening Programs in OS X

Application bundles are the most common way of distributing software packages on OS X. They are presented as a single file which is actually a directory containing all of the necessary resources (images, libraries…).

These bundles can be executed by double-clicking on them, as if they were regular files, so it is a common mistake to try to execute them using the command line as:

$> /Applications/BitRock\ InstallBuilder\ Professional\ 17.1.0/bin/Builder.app

Or alternatively, using InstallBuilder actions:

   <runProgram>
      <program>/Applications/BitRock InstallBuilder Professional 17.1.0/bin/Builder.app</program>
   </runProgram>

Which results in an error similar to: "-bash: /Applications/BitRock InstallBuilder Professional 17.1.0/bin/Builder.app/: is a directory" or a more detailed error suggesting using open (see below) in recent InstallBuilder versions.

There are two ways of executing an application bundle:

  • Using the open command: This command is the equivalent of a double-click over the bundle. It can be also used to open regular files, which will launch the associated application:

   <runProgram>
      <program>open</program>
      <programArguments>"${installdir}/YourApplication.app"</programArguments>
   </runProgram>

The default behavior of the open command is to launch the process in background, so you don’t need to add an "&" at the end of the arguments.

However, if you want to make InstallBuilder wait for the process to finish (launch the bundle in the foreground) you can use the -W command line flag:

   <runProgram>
      <program>open</program>
      <programArguments>-W "${installdir}/YourApplication.app"</programArguments>
   </runProgram>

A limitation of using open to launch the bundle is that it does not support passing arguments to the launched application in its early versions (it started supporting it from OS X 10.6.2). If you just support versions newer than OS X 10.6.2, you can use the --args command line flag:

   <runProgram>
      <program>open</program>
      <programArguments>-W "${installdir}/YourApplication.app" --args --data-dir ${installdir}/data --check-for-updates</programArguments>
   </runProgram>

All the arguments after --args are directly passed to the application, so you don’t have to surround them by quotes.

  • Calling the CFBundleExecutable specified in the Info.plist file: The application bundle contains an XML document describing multiple aspects of the bundle behavior (the binary to execute when double clicked, the icon to use in the dock…). One of the keys specified is CFBundleExecutable, which determines which of the contained files will be executed when opening the bundle. There are multiple ways of retrieving this key but the easiest way is by executing:

$> defaults read /Applications/BitRock\ InstallBuilder/bin/Builder.app/Contents/Info CFBundleExecutable

Which will return the file that will be executed relative to the directory Builder.app/Contents/MacOS. In the case of InstallBuilder application bundles, it will return installbuilder.sh (Builder.app/Contents/MacOS/installbuilder.sh).

Another possibility would be to just open it with a text editor and look for the CFBundleExecutable key and its <string>:

$> emacs Builder.app/Contents/Info.plist

Or from Finder, in the "right-click" menu, clicking "Show Package Contents" and opening Contents/Info.plist.

Using this information, you can execute it using the <runProgram> action:

   <runProgram>
      <program>/Applications/BitRock InstallBuilder/bin/Builder.app/Contents/MacOS/installbuilder.sh</program>
      <programArguments>build ~/project.xml linux</programArguments>
   </runProgram>

8.4. Displaying Progress While Executing Long Running Actions

When the actions executed require a long time to complete, such as waiting for a service to start or when uncompressing a zip file, it is advisable to provide some feedback to the end user. The first way of providing feedback is defining a progressText in your action. If the actions are executed during the <postInstallationActionList>, <postUninstallerCreationActionList> or in a <folder>'s action list, the main progress bar used to display the unpacking process will display the defined message:

  <component>
     <name>myComponent</name>
     ...
     <folderList>
       <folder>
          <name>documents</name>
          ...
          <actionList>
             <runProgram progressText="Starting Apache Server...">
               <program>${installdir}/apache/apachectl</program>
               <programArguments>start &amp;</programArguments>
             </runProgram>
             <wait ms="3000" progressText="Waiting apache server to start..."/>
          </actionList>
       </folder>
     </folderList>
  </component>

However, if the action is going to take a lot of time, it would be an even better idea to wrap the actions in a <showProgressDialog>. This dialog displays an indeterminate progress bar in a pop-up while executing the wrapped child actions. It will also take control of the execution so the user will not be able to interact with the main window until the actions complete. Canceling the pop-up will cancel the installation:

 <showProgressDialog>
    <title>Extracting files</title>
    <width>400</width>
    <height>100</height>
    <actionList>
      <!-- The unzip action will provide a built-in progress text with
      the file being unpacked so you don't need to provide one -->
      <unzip>
        <destinationDirectory>${installdir}/content</destinationDirectory>
        <zipFile>${installdir}/content.zip</zipFile>
      </unzip>
      <deleteFile>
        <progressText>Removing original zip file</progressText>
        <path>${installdir}/content.zip</path>
      </deleteFile>
    </actionList>
 </showProgressDialog>
Show Progress Dialog
Figure 47: Show Progress Dialog

The <showProgressDialog> will behave differently when its only child is an <httpGet> action. In this case, instead of displaying an indeterminate progress pop-up, a continuous bar with the speed and the progress of the download will be displayed:

<showProgressDialog>
    <title>Downloading files</title>
    <actionList>
        <httpGet>
            <filename>/tmp/ib.run</filename>
            <url>http://installbuilder.bitrock.com/installbuilder-enterprise-17.1.0-linux-installer.run</url>
        </httpGet>
    </actionList>
</showProgressDialog>
Continuous Progress Dialog
Figure 48: Continuous Progress Dialog

8.5. Creating Custom Actions

In addition to the built-in actions, InstallBuilder allows you to create new custom actions using a mix of base actions and rules. New actions are defined using the <functionDefinitionList>.

For example, let’s suppose you have a lot of long running <runProgram> actions (for example installing sub installers in unattended mode) and you are enclosing all of them in a <showProgressDialog>:

  <showProgressDialog>
     <title>Please wait ...</title>
     <actionList>
        <runProgram>
           <program>${yourProgram}</program>
           <programArguments>--mode unattended --prefix "${installdir}"</programArguments>
        </runProgram>
     </actionList>
  </showProgressDialog>

You could then create a new action called <unattendedRunProgamWithProgress> that will just accept the program to execute and some additional arguments:

<project>
    ...
    <functionDefinitionList>
        <!-- Define the action -->
        <actionDefinition>
            <name>unattendedRunProgamWithProgress</name>
            <actionList>
                <showProgressDialog>
                    <title>Please wait ...</title>
                    <actionList>
                        <runProgram progressText="Installing ${program}">
                            <program>${program}</program>
                            <programArguments>--mode unattended ${programArguments}</programArguments>
                        </runProgram>
                    </actionList>
                </showProgressDialog>
            </actionList>
            <parameterList>
                <stringParameter name="program" value="" default=""/>
                <stringParameter name="programArguments" value="" default=""/>
            </parameterList>
        </actionDefinition>
    </functionDefinitionList>
    <initializationActionList>
        <!-- Use the new action -->
        <unattendedRunProgamWithProgress>
            <program>${yourProgram}</program>
            <programArguments>--prefix "${installdir}"</programArguments>
        </unattendedRunProgamWithProgress>
    </initializationActionList>
    ...
</project>

This new action will take care of displaying the progress dialog and launching the program in unattended mode. The basics of how to define a new custom action are as follow:

  • <name>: The new custom action will be available in other parts of the XML by its name. No other custom action can be defined with the same <name>.

  • <actionList>: This <actionList> defines the set of actions to wrap. In addition to built-in actions, it also accepts other custom actions (if they were previously defined).

  • <parameterList>: This <parameterList> defines the parameters of the new action. They are used to interface with the inner actions in the <actionList>. In addition to the settings defined in the <parameterList>, the new custom action will also support all the common action properties such as <progressText>, <show>, <abortOnError>, <action.showMessageOnError>

For example, if you want to wrap the built-in <unpackDirectory> action to make it safer and previously backup the destination, you could use:

<functionDefinitionList>
  <actionDefinition>
   <name>unpackDirectoryWithBackup</name>
     <actionList>
        <actionGroup>
           <actionList>
              <createTimeStamp>
                 <format>%s</format>
                 <variable>timestamp</variable>
              </createTimeStamp>
              <logMessage>
                 <text>File ${destination} already exists, renaming it to ${destination}.${timestamp}</text>
              </logMessage>
              <renameFile>
                 <destination>${destination}.${timestamp}</destination>
                 <origin>${destination}</origin>
              </renameFile>
           </actionList>
           <ruleList>
              <fileExists path="${destination}"/>
           </ruleList>
        </actionGroup>
        <unpackDirectory>
           <component>${component}</component>
           <destination>${destination}</destination>
           <folder>${folder}</folder>
           <origin>${origin}</origin>
        </unpackDirectory>
     </actionList>
     <parameterList>
        <stringParameter name="component" value="" default=""/>
        <stringParameter name="folder" value="" default=""/>
        <stringParameter name="origin" value="" default=""/>
        <stringParameter name="destination" value="" default=""/>
     </parameterList>
  </actionDefinition>
</functionDefinitionList>

The new action will then be available at any point in the installation:

<project>
  ...
  <initializationActionList>
     <unpackDirectoryWithBackup>
       <component>binaries</component>
       <folder>bin</folder>
       <origin>checker/checker.bin</origin>
       <destination>${installdir}/temp</destination>
     </unpackDirectoryWithBackup>
  </initializationActionList>
  ...
</project>

In the example above, the <parameterList> was basically a map of the main properties accepted by the <unpackDirectory> action and the <actionList> included a couple of actions to do the backup and log some information before calling <unpackDirectory>.

Another useful example could be to manage your bundled Apache server:

<project>
 ...
 <functionDefinitionList>
  <actionDefinition>
    <name>apache</name>
      <actionList>
         <runProgram program="${apacheCtlPath}" programArguments="${action}"/>
      </actionList>
      <parameterList>
         <stringParameter name="action" value="" default="start"/>
         <stringParameter name="apacheCtlPath" value="" default="${installdir}/apache2/bin/apachectl"/>
      </parameterList>
  </actionDefinition>
 </functionDefinitionList>
 ...
 <initializationActionList>
   <apache action="start"/>
 </initializationActionList>
 ...
</project>

8.5.1. Returning values from a custom action

I some cases, you may want to create custom actions that perform some operations and return the result in a variable. The obvious way of achieving this would be to implement something like the following:

<project>
 ...
 <functionDefinitionList>
  <actionDefinition>
    <name>getPreviousInstallDir</name>
      <actionList>
         <setInstallerVariable name="dir" value=""/>
         <setInstallerVariable name="dir" value="${env(OLD_DIR)}" >
           <ruleList>
              <platformTest type="unix"/>
           </ruleList>
         </setInstallerVariable>
         <registryGet>
           <key>HKEY_LOCAL_MACHINE\Software\${project.windowsSoftwareRegistryPrefix}</key>
           <name>Location</name>
           <variable>installdir</variable>
           <ruleList>
              <platformTest type="windows"/>
           </ruleList>
         </registryGet>
         <!-- Set the return value. ${result} contains the name
         of the variable provided by the caller -->
         <setInstallerVariable name="${result}" value="${dir}"/>
      </actionList>
      <parameterList>
         <stringParameter name="result" value="" default=""/>
      </parameterList>
  </actionDefinition>
 </functionDefinitionList>
 ...
 <initializationActionList>
   <getPreviousInstallDir result="previous_dir"/>
 </initializationActionList>
 ...
</project>

However, if you try this, you will realize that the previous_dir variable will still be undefined after the execution of the custom action. The reason is that all the variables used in the custom action are just a local copy of the project level variables. The same way, variables created inside the custom action are not available in the global scope. This way, you can safely use any variable inside the function without affecting other project level variables.

To solve this issue, you just need to mark the desired variables as global using the <globalVariables> action. This action accepts a space-separated list of variable names that will then be preserve their values outside the custom action. In our example:

<project>
 ...
 <functionDefinitionList>
  <actionDefinition>
    <name>getPreviousInstallDir</name>
      <actionList>
         <!-- Define the variable configured as global -->
         <globalVariables names="${result}"/>
         <setInstallerVariable name="dir" value=""/>
         <setInstallerVariable name="dir" value="${env(OLD_DIR)}" >
           <ruleList>
              <platformTest type="unix"/>
           </ruleList>
         </setInstallerVariable>
         <registryGet>
           <key>HKEY_LOCAL_MACHINE\Software\${project.windowsSoftwareRegistryPrefix}</key>
           <name>Location</name>
           <variable>installdir</variable>
           <ruleList>
              <platformTest type="windows"/>
           </ruleList>
         </registryGet>
         <!-- Set the return value. ${result} contains the name
         of the variable provided by the caller -->
         <setInstallerVariable name="${result}" value="${dir}"/>
      </actionList>
      <parameterList>
         <stringParameter name="result" value="" default=""/>
      </parameterList>
  </actionDefinition>
 </functionDefinitionList>
 ...
 <initializationActionList>
   <getPreviousInstallDir result="previous_dir"/>
 </initializationActionList>
 ...
</project>

Take into account that once a variable is defined as global, it will always be accessible from other custom actions, even if they did not declare it as global.

Note
Custom actions return values

To return values from a custom action you must create a parameter in which the result will be returned and mark it as global using the <globalVariables> action.

8.5.2. Current Limitations

The Custom Actions are still under development and although the functionality is fully usable, they have some known limitations:

Order matters

To make the builder recognize a custom action as a valid XML element, it must be defined in the XML project before it is used. For example, the below will fail with "Unknown tag <myShowInfo>" error:

<project>
  ...
  <initializationActionList>
    <myShowInfo/>
  </initializationActionList>
  ...
  <functionDefinitionList>
    <actionDefinition>
       <name>myShowInfo</name>
       <actionList>
         <showInfo text="This is a customized showInfo: ${text}"/>
       </actionList>
       <parameterList>
         <stringParameter name="text"/>
       </parameterList>
    </actionDefinition>
  </functionDefinitionList>
  ...
</project>

However, changing the order will fix the issue:

<project>
  ...
  <functionDefinitionList>
    <actionDefinition>
       <name>myShowInfo</name>
       <actionList>
         <showInfo text="This is a customized showInfo: ${text}"/>
       </actionList>
       <parameterList>
         <stringParameter name="text"/>
       </parameterList>
    </actionDefinition>
  </functionDefinitionList>
  ...
  <initializationActionList>
    <myShowInfo/>
  </initializationActionList>
  ...
</project>

Future versions will fix the issue by implementing a two-pass XML parser.

Custom actions cannot be defined in the GUI tree

They cannot be defined in the tree, but actions defined using the integrated XML editor (or externally added) will be available as other regular actions in the action-selector dialog.

Name conventions

The <name> must only contain ascii letters. The same applies to its parameters.

Custom actions cannot overwrite built-in ones

If you define a new <showInfo>, and a built-in <showInfo> already exists, it will be ignored.

8.6. Error Handling

During the installation or uninstallation process, there are scenarios in which the installer encounters a non-recoverable error or simply is manually aborted. This section explains how these scenarios are handled by InstallBuilder and how to manually define actions in case of failure either to clean the installation or to try to recover.

8.6.1. Handling Action Errors

All actions include some error handling tags that make it very easy to specify the desired behavior when an error is found during its execution.

  • <abortOnError> : This property configures whether or not to abort the execution of the current action list when one of its child actions fails. Its default value is 1.

For example, in the next snippet, the second action will never be executed:

<initializationActionList>
   <throwError text="This will abort the installation!"/>
   <showInfo text="This will never be executed"/>
</initializationActionList>

But if you set abortOnError="0", even if a message is displayed, the execution will not be aborted:

<initializationActionList>
   <throwError text="This will not abort the installation!" abortOnError="0"/>
   <showInfo text="And this will be executed after the error pop-up"/>
</initializationActionList>
  • <showMessageOnError>: This property configures whether or not to display a pop-up notifying the user of the error. Its default value is 1. If you set showMessageOnError="0" and an error occurs, if the action is not configured to ignore errors with abortOnError="0", the rest of the actions in the action list will be skipped. However, although the actions will be skipped, no error will be propagated upward so the installation will not be aborted:

<initializationActionList>
   <throwError text="This will not abort the installation but no other action in the initializationActionList will be executed!" showMessageOnError="0"/>
   <showInfo text="This will never be executed"/>
</initializationActionList>

To completely mask an error, you can use a combination of showMessageOnError="0" and abortOnError="0". A real world example could be to determine if certain Linux command is available and getting its path:

<initializationActionList>
   <!-- The below will fail in some cases
   but we do not want to display any error or to abort -->
   <runProgram>
      <program>which</program>
      <programArguments>gksudo</programArguments>
      <showMessageOnError>0</showMessageOnError>
      <abortOnError>0</abortOnError>
   </runProgram>
   <showInfo text="gksudo is not available" >
      <ruleList>
         <compareText text="${program_stdout}" logic="equals" value=""/>
      </ruleList>
   </showInfo>
   <showInfo text="gksudo is available and its path is ${program_stdout}" >
      <ruleList>
         <compareText text="${program_stdout}" logic="does_not_equal" value=""/>
      </ruleList>
   </showInfo>
</initializationActionList>
  • <customErrorMessage> : When an action fails, InstallBuilder generates a built-in error to be displayed if showMessageOnError="1" This error message can be overwritten using the customErrorMessage property. For example, calling a nonexistent command foo would normally result in an error such as "foo not found" but you can customize it to: "foo must be installed, aborting…":

 <runProgram>
   <program>foo</program>
   <customErrorMessage>foo must be installed, aborting...</customErrorMessage>
 </runProgram>

The errors are also stored in the ${installer_error_message} (containing the error message reported to the user, masked by the <customErrorMessage> if any) and ${installer_error_message_original} (the original error message, unmasked by the <customErrorMessage>) built-in variables. The variables are accessible at the time the <customErrorMessage> is resolved so you could create a custom error message that also includes the original error as the details:

 <runProgram>
   <program>foo</program>
   <customErrorMessage>foo must be installed: ${installer_error_message_original}</customErrorMessage>
 </runProgram>
  • <onErrorActionList>: When an action reports an error during its execution, regardless of the values of showMessageOnError and abortOnError, its onErrorActionList will be executed. For example, you can use it to clean the effects of the failed action before continuing aborting:

  <!-- Try to copy some images to the installation directory and then create a pdf
  file but if the process fail, do not want to preserve the images and the malformed
  pdf file. The action will take care of the cleaning itself -->
  <actionGroup>
     <actionList>
        <!-- ${installer_directory} is resolved to the
        directory of the installer -->
        <copyFile origin="${installer_directory}/images" destination="${installdir}"/>
        <runProgram>
          <program>convert</program>
          <programArguments>${installdir}/images/*.jpg ${installdir}/myImages.pdf</programArguments>
        </runProgram>
     </actionList>
     <onErrorActionList>
        <deleteFile path="${installdir}/images"/>
        <deleteFile path="${installdir}/myImages.pdf"/>
     </onErrorActionList>
  </actionGroup>

Using the <onErrorActionList> and the ${installer_error_message_original} variable you could also throw a friendly error to your users while still providing the specific details in the log for debugging purposes:

 <runProgram>
    <customErrorMessage>Error generating pdf file</customErrorMessage>
    <program>convert</program>
    <programArguments>${installdir}/images/*.jpg ${installdir}/myImages.pdf</programArguments>
    <onErrorActionList>
      <logMessage>
        <text>Error generating pdf file: ${installer_error_message_original}</text>
      </logMessage>
    </onErrorActionList>
 </runProgram>

8.6.2. Installation Aborted Action List

This action list gets executed when the project is aborted, either by the user or by an internal error. It provides a global way of dealing with the error in contra-position to the specific approach of the <onErrorActionList>. For example, it could be used to make sure the installation directory is deleted after the installation is being canceled:

<project>
  ...
  <installationAbortedActionList>
     <deleteFile path="${installdir}"/>
  </installationAbortedActionList>
  ...
</project>

You can also differentiate between an installation aborted by the user or an error checking the built-in variable ${installation_aborted_by_user}.

8.6.3. When Does an Error Not Abort the Installation?

In most cases, when an error is thrown and it is not caught at any point using abortOnError="0" (the error is completely ignored) or showMessageOnError="0" (the error aborts the current action list but is not propagated upwards), it aborts the installation. However, there are some special cases in which the error is treated as a warning or is ignored:

  • Parameter’s Validation Actions (<validationActionList>): If an unmasked error occurs inside a parameter action list, the rest of actions in the <validationActionList> are skipped and the error is reported to the user but instead of aborting the installation, the page is redrawn. For example, if you unconditionally throw an error in a <validationActionList>, the installer will never continue after this page:

<directoryParameter>
   <name>installdir</name>
   <validationActionList>
      <throwError text="This page will be displayed again and again !"/>
   </validationActionList>
</directoryParameter>

<component>
    <name>C</name>
    <description>Component C</description>
    <detailedDescription>This component depends on 'A' and 'B'</detailedDescription>
    ...
    <componentSelectionValidationActionList>
        <throwError>
            <text>Component 'C' cannot be installed if you have not selected both 'A' and 'B'.</text>
            <ruleList>
                <isFalse value="${component(A).selected}"/>
                <isFalse value="${component(B).selected}" />
            </ruleList>
        </throwError>
    </componentSelectionValidationActionList>
    ...
</component>

8.6.4. Cleaning and Rollback Directory Restoration

When an installation is aborted during the installation of files, all of the unpacked files will be automatically deleted, and if the rollback functionality was enabled using <enableRollback>1</enableRollback>, the old files overwritten by the process will be restored.

Take into account that files manually deleted, copied or moved will not be automatically handled so the <installationAbortedActionList> must be used for this purpose.

8.7. List of Available Actions

HTTP Actions

HTTP GET Request

Access a URL and save the result into a file. The allowed properties in the <httpGet> action are:

Examples:

Download a readme file
<httpGet>
    <filename>${installdir}/README.txt</filename>
    <url>http://www.example.com/docs/readme.txt</url>
    <username>foo</username>
    <password>bar</password>
</httpGet>
Display a progress bar while downloading a big file
<showProgressDialog>
    <title>Downloading files</title>
    <actionList>
        <httpGet>
            <filename>${system_temp_directory}/ib.run</filename>
            <url>http://installbuilder.bitrock.com/installbuilder-enterprise-17.1.0-linux-installer.run</url>
        </httpGet>
    </actionList>
</showProgressDialog>
Checking the HTTP status code of a httpGet request
<httpGet>
    <filename>${installdir}/README.txt</filename>
    <url>http://www.example.com/docs/readme.txt</url>
</httpGet>
<throwError>
    <text>Failed to retrieve remote file</text>
    <ruleList>
        <compareText text="${installer_http_code}" logic="does_not_equal" value="200"/>
    </ruleList>
</throwError>
Adding custom headers to the HTTP request
<httpGet>
    <filename>${installdir}/welcome.txt</filename>
    <url>http://www.example.com/index.php</url>
    <httpHeadersList>
        <httpHeader>
            <name>Accept-Language</name>
            <value>en-US,en;q=0.8,es;q=0.6</value>
        </httpHeader>
    </httpHeadersList>
</httpGet>

Additional Examples: Example 1, Example 2

HTTP POST Request

Access a URL using HTTP POST and save the result into a file. The allowed properties in the <httpPost> action are:

Examples:

Query your server to validate user provided input
<parameterGroup>
   <name>credentials</name>
   <title>Account Credentials</title>
   <explanation>Introduce Your account credentials</explanation>
   <parameterList>
      <stringParameter name="username" description="Username:"/>
      <passwordParameter name="password" description="Password:"/>
      <stringParameter name="key" description="License key:"/>
   </parameterList>
   <validationActionList>
      <httpPost>
        <url>http://www.example.com/register.php</url>
        <filename>${installdir}/result</filename>
        <queryParameterList>
          <queryParameter name="name" value="${username}"/>
          <queryParameter name="pass" value="${password}"/>
          <queryParameter name="license" value="${key}"/>
        </queryParameterList>
      </httpPost>
      <readFile path="${installdir}/result" name="result"/>
      <deleteFile path="${installdir}/result"/>
      <throwError>
        <text>The provided credentials are not valid</text>
        <ruleList>
          <compareText>
            <text>${result}</text>
            <logic>does_not_contain</logic>
            <value>OK</value>
          </compareText>
        </ruleList>
      </throwError>
   </validationActionList>
</parameterGroup>
Checking the HTTP status code of a httpPost request
<httpPost>
    <url>http://www.example.com/register.php</url>
    <filename>${installdir}/result</filename>
    <queryParameterList>
        <queryParameter name="name" value="${username}"/>
        <queryParameter name="pass" value="${password}"/>
        <queryParameter name="license" value="${key}"/>
    </queryParameterList>
</httpPost>
<throwError>
    <text>Could not register installation</text>
    <ruleList>
        <compareText text="${installer_http_code}" logic="does_not_equal" value="200"/>
    </ruleList>
</throwError>
Sending a raw payload in a HTTP POST request
<httpPost>
    <url>http://www.example.com/register.php</url>
    <filename>${installdir}/result</filename>
    <contentType>application/json</contentType>
    <data><![CDATA[{
  "user": "JohnDoe",
  "password": "secret"
}]]>
    </data>
</httpPost>

Additional Examples: Example 1, Example 2, Example 3

Configure proxy

Configure a proxy to be used by the http actions (<httpGet> and <httpPost>).

The allowed properties in the <httpProxyInit> action are:

  • <exclude>: Space separated list of patters for urls that will be excluded from the proxy configuration

  • <password>: Proxy server password

  • <port>: Proxy server port

  • <server>: Proxy server url

  • <username>: Proxy server username

If no properties are defined, the action will try to aoutodetect the proxy configured in the system.

Examples:

Ask the user to configure the proxy
<parameterGroup>
   <name>proxyConfiguration</name>
   <title>Configuration</title>
   <explanation></explanation>
   <parameterList>
      <stringParameter name="username" description="Username:"/>
      <passwordParameter name="password" description="Password:"/>
      <parameterGroup>
        <name>proxyServer</name>
        <orientation>horizontal</orientation>
        <parameterList>
          <stringParameter name="server" description="Server:     "/>
          <stringParameter name="port" description="Port:" width="5"/>
        </parameterList>
      </parameterGroup>
   </parameterList>
   <postShowPageActionList>
      <httpProxyInit>
         <username>${username}</username>
         <password>${password}</password>
         <server>${server}</server>
         <port>${port}</port>
      </httpProxyInit>
   </postShowPageActionList>
</parameterGroup>
Use system proxy configuration
<httpProxyInit/>
Encode URL

Encode a given text using URL formatting specifications and place the result in a variable. The allowed properties in the <urlEncode> action are:

Examples:

Encode text
<urlEncode>
    <text>Some long text to
send to your server containg a lot of
forbiden characters such as ? [ and @</text>
    <variable>encodedText</variable>
</urlEncode>

In the example above, the encoded text would be Some+long+text+to%0d%0asend+to+your+server+containg+a+lot+of%0d%0aforbiden+characters+such+as+%3f+%5b+and+%40, ready to send to our server using an <httpPost> action.

Decode URL

Decode a given text using URL formatting specifications and place the result in a variable. The allowed properties in the <urlDecode> action are:

Examples:

Decode url
<urlDecode>
   <text>Some+long+text+to%0d%0asend+to+your+server+containg+a+lot+of%0d%0aforbiden+characters+such+as+%3f+%5b+and+%40</text>
   <variable>decodedText</variable>
</urlDecode>

The action will store the below text in the variable ${decodedText}:

Some long text to
send to your server containg a lot of
forbiden characters such as ? [ and @
Launch Browser

Launch the default web browser with a given URL. The allowed properties in the <launchBrowser> action are:

  • <url>: URL of the page to be shown.

Examples:

Visit your website at the end of the installation
<finalPageActionList>
   <launchBrowser>
     <url>www.downloads.com/optional</url>
     <progressText>Would you like to visit our website to download
     additional modules?</progressText>
   </launchBrowser>
</finalPageActionList>

Additional Examples: Example 1, Example 2, Example 3

File Manipulation Actions

DOS to Unix File Conversion

Convert plain text files in DOS/Mac format to Unix format. It is specially useful to fix Unix shell scripts modified on Windows.

The allowed properties in the <dos2unix> action are:

Examples:

Convert all shell scripts to Unix line endings
<dos2unix>
    <files>${installdir}/scripts/*.sh</files>
</dos2unix>
Unix to DOS File Conversion

Convert plain text files in Unix format to DOS format. It is specially useful to fix Windows bat files modified on Unix.

The allowed properties in the <unix2dos> action are:

Examples:

Convert all batch scripts to Unix line endings
<unix2dos>
  <files>${installdir}/scripts/*.bat</files>
</unix2dos>
Read value from XML file

Read value of element or attribute from an XML file The allowed properties in the <xmlFileGet> action are:

  • <attribute>: If present, the action will refer to the attribute instead of the element

  • <element>: XPath expression pointing to the selected element

  • <file>: Path to XML file

  • <variable>: Variable where to start the result

Examples:

Extract a property from an Info.plist file

If you have an Info.plist file with contents:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
   <dict>
        <key>CFBundleDevelopmentRegion</key>
        <string>English</string>
        <key>CFBundleExecutable</key>
        <string>installbuilder.sh</string>
        <key>CFBundleIdentifier</key>
        <string>com.bitrock.installbuilder</string>
        <key>CFBundleInfoDictionaryVersion</key>
        <string>6.0</string>
        ...
   </dict>
</plist>

You can access the CFBundleExecutable associated string using:

<xmlFileGet>
    <attribute></attribute>
    <element>/plist/dict[1]/string[preceding-sibling::key[1]/text()="CFBundleExecutable"]</element>
    <file>${installdir}/some.app/Contents/Info.plist</file>
    <variable>CFBundleExecutable</variable>
</xmlFileGet>

Extract an attribute from an XML

If instead of working with XML elements you need to read an attribute, like the <progressText> in the below InstallBuider action:

<actionList>
  <runProgram progressText="Launch ${project.fullName}" >
    <program>${installdir}/bin/app.exe</program>
    <programArguments>&amp;</programArguments>
  </runProgram>
</actionList>

You can use:

<xmlFileGet>
    <!-- Specify the XML element containing the attribute -->
    <element>/actionList/runProgram</element>
    <!-- Specify the attribute -->
    <attribute>progressText</attribute>
    <file>${build_project_directory}/actionList.xml</file>
    <variable>progressText</variable>
</xmlFileGet>

Set value in XML file

Set the value of an element or attribute in an XML file The allowed properties in the <xmlFileSet> action are:

  • <attribute>: If present, the action will refer to the attribute instead of the element

  • <element>: XPath expression pointing to the selected element

  • <file>: Path to XML file

  • <value>: Value to store in element or attribute

Examples:

Modify an item in a XML list

To modify an entry in a XML address book:

<addressBook>
   <addressList>
      <address name="Jhon" email="jhon@myemail.com"/>
      <address name="joseph" email="joseph@myemail.com"/>
   </addressList>
</addressBook>

You can use:

<xmlFileSet>
    <attribute>email</attribute>
    <element>/addressBook/addressList/address[@name="Jhon"]</element>
    <file>${installdir}/config/address.xml</file>
    <value>jhonhome@otheremail.com</value>
</xmlFileSet>
Comment subtree of XML file

Comment entire subtree of an XML file The allowed properties in the <xmlFileCommentElement> action are:

  • <element>: XPath expression pointing to the selected element

  • <file>: Path to XML file

Examples:

Comment an entry in an XML list

To remove (commenting it) one of the entries in the XML address book from our previous example:

<xmlFileCommentElement>
    <element>/addressBook/addressList/address[@name="joseph"]</element>
    <file>${installdir}/config/address.xml</file>
</xmlFileCommentElement>
Read File Contents

Read the contents of a file and save it in a variable. The allowed properties in the <readFile> action are:

  • <encoding>: Encoding of the text file

  • <endOfLineConversion>: End Of Line Conversion

  • <name>: Variable to which to save the file contents

  • <path>: Path to the file you wish to read the contents from

  • <removeBOM>: Whether or not to remove or not Byte Order Mark on Unicode files

Examples:

Read a packed .txt file and display it in the <finalPageActionList>
<finalPageActionList>
   <actionGroup progressText="View readme file">
      <actionList>
        <readFile>
          <name>text</name>
          <path>${installdir}/readmes/README-1.txt</path>
        </readFile>
        <showText>
          <text>${text}</text>
          <title>README</title>
        </showText>
      </actionList>
   </actionGroup>
</finalPageActionList>

Additional Examples: Example 1, Example 2, Example 3

Write Text to File

Create or replace a file with a certain text content. The allowed properties in the <writeFile> action are:

Examples:

Write a summary of the installation
<writeFile>
    <path>${installdir}/summary.txt</path>
    <!-- &#xA; is the XML escape sequence for
    the line break -->
    <text>Username: ${username}
Password: *******
Installation Type: ${project.installationType}
IP: ${ip}
Port: ${port}</text>
</writeFile>

Additional Examples: Example 1, Example 2, Example 3

Append Text to File

Append text to a file. If the file does not exist, it will be created. The allowed properties in the <addTextToFile> action are:

Examples:

Append information to a file in an upgrade installation:
<addTextToFile>
    <file>${installdir}/ChangeLog</file>
    <text>* Fixed application failing to start from directory with spaces.
* Added new plugins
* Removed unnecessary libraries
* Reworked UI
</text>
    <ruleList>
       <compareText text="${project.installationType}" logic="equals" value="upgrade"/>
       <fileExists path="${installdir}/ChangeLog"/>
    </ruleList>
</addTextToFile>

Additional Examples: Example 1, Example 2, Example 3

Set INI File Property

Set property values of a INI file. If the file does not exists it will be created.

The allowed properties in the <iniFileSet> action are:

Examples:

Configure MySQL
<iniFileSet>
    <file>${installdir}/mysql/my.cnf</file>
    <section>mysqld</section>
    <key>port</key>
    <value>${port}</value>
</iniFileSet>
<iniFileSet>
    <file>${installdir}/mysql/my.cnf</file>
    <section>mysqld</section>
    <key>socket</key>
    <value>/tmp/mysql.sock</value>
</iniFileSet>
<iniFileSet>
    <file>${installdir}/mysql/my.cnf</file>
    <section>client</section>
    <key>password</key>
    <value>somePassWord!</value>
</iniFileSet>

Additional Examples: Example 1

Get INI File Property

Extract property values out of a INI file. If the key does not exists, the variable will be set to empty.

The allowed properties in the <iniFileGet> action are:

Examples:

Read PHP configuration
<iniFileGet>
    <file>${installdir}/php/etc/php.ini</file>
    <key>include_path</key>
    <section>PHP</section>
    <variable>php_include_path</variable>
</iniFileGet>

Additional Examples: Example 1

Write Property File Value

Writes out property values to a properties file, creating a new file if it does not exist. The allowed properties in the <propertiesFileSet> action are:

Examples:

Update the version of the installed application in an upgrade
<propertiesFileSet>
    <file>${installdir}/installation.properties</file>
    <key>version</key>
    <value>${project.version}</value>
</propertiesFileSet>
Get Property File Value

Extract property values out of a properties file. The allowed properties in the <propertiesFileGet> action are:

Examples:

Check the version of an existing installation to upgrade and abort if greater than the current
<propertiesFileGet>
   <file>${installdir}/installation.properties</file>
   <key>version</key>
   <variable>installedVersion</variable>
</propertiesFileGet>
<throwError text="The installed application is up to date. Aborting">
   <ruleList>
     <compareVersions>
       <version1>${installedVersion}</version1>
       <logic>greater_or_equal</logic>
       <version2>${project.version}</version2>
     </compareVersions>
   </ruleList>
</throwError>
Read value from YAML file

Read value of element from a YAML file The allowed properties in the <yamlFileGet> action are:

  • <element>: Path expression pointing to the selected element

  • <file>: Path to YAML file

  • <variable>: Variable where to start the result

Examples:

Retrieve path to database file from a YAML file

To retrieve path to production database in the following YAML file to application_database_path variable:

production:
  adapter: sqlite3
  database: db/production.sqlite3
  pool: 5
  timeout: 5000

You can use:

<yamlFileGet>
    <element>/production/database</element>
    <file>${installdir}/config/database.yml</file>
    <variable>application_database_path</variable>
</yamlFileGet>
Set value in YAML file

Set the value of an element in a YAML file The allowed properties in the <yamlFileSet> action are:

  • <element>: Path expression pointing to the selected element

  • <file>: Path to YAML file

  • <value>: Value to store in element

Examples:

Modify an item in a YAML file

To modify path to database in a YAML file:

production:
  adapter: sqlite3
  database: db/production.sqlite3
  pool: 5
  timeout: 5000

You can use:

<yamlFileSet>
    <element>/production/database</element>
    <file>${installdir}/config/database.yml</file>
    <value>db/otherpath.sqlite3</value>
</yamlFileSet>
Substitute Text in File

Substitute a value in a file. The allowed properties in the <substitute> action are:

Examples:

Replace well known placeholders
<substitute>
    <files>${installdir}/conf/*</files>
    <type>exact</type>
    <substitutionList>
       <substitution pattern="PATH_PLACEHOLDER" value="${installdir.unix}" />
       <substitution pattern="PORT_PLACEHOLDER" value="${server_port}" />
    </substitutionList>
</substitute>

As the text to match is known, the code uses the exact <type>, which makes the action work faster.

Replace an unknown port in httpd.conf
<substitute>
    <files>${installdir}/apache2/conf/httpd.conf</files>
    <type>regexp</type>
    <substitutionList>
       <substitution pattern="\s*Listen\s+[0-9]+" value="${apache_port}"/>
    </substitutionList>
</substitute>

As the port is unknown, we use the regexp <type>.

Add Directories to the Uninstaller

This action allows you to add new directories to the uninstaller, so they will be removed during the uninstallation process. The uninstaller just takes care of deleting those files unpacked in the installation step. If your installer generates new files at runtime or copies unpacked files to other locations you can use the <addDirectoriesToUninstaller> (and <addFilesToUninstaller>) to make the uninstaller also delete them in the uninstallation stage. The directories to add must exists at the time the action is executed or it will just skip.

The allowed properties in the <addDirectoriesToUninstaller> action are:

Examples:

Add directory without its contents.
<createDirectory>
  <path>${installdir}/config</path>
</createDirectory>
<addDirectoriesToUninstaller>
  <files>${installdir}/config</files>
</addDirectoriesToUninstaller>

As just the directory and not its contents were added, the uninstaller will just delete the directory if it is empty. This way your user can preserve the configuration files stored in that directory.

Add directory and its contents to the uninstaller.
<copyFile>
  <origin>${installdir}/data</origin>
  <destination>${installdir}/backup</destination>
</copyFile>

<addDirectoriesToUninstaller>
  <files>${installdir}/data</files>
  <addContents>1</addContents>
  <matchHiddenFiles>1</matchHiddenFiles>
</addDirectoriesToUninstaller>

If new files are added to the ${installdir}/data folder, the uninstaller won’t delete them, just those files registered will be removed. This is how the uninstaller works for the unpacked files. Take into account that adding a directory with a big number of files and nested directories could take some time to finish as the action must locate all the files to add.

Additional Examples: Example 1, Example 2

Add Files to Uninstaller

This action allows you to add new files to the uninstaller, so they will be removed during the uninstallation process. This action behaves the same way the <addDirectoriesToUninstaller> does but is intended to files. If the action is used with directories, the uninstaller will delete them regardless of the changes in its contents.

The allowed properties in the <addFilesToUninstaller> action are:

Examples:

Adds the temporary files created at runtime
<addFilesToUninstaller>
   <files>${installdir}/*~
${installdir}/*/*~
${installdir}/*/*/*~
${installdir}/*/*/*/*~</files>
</addFilesToUninstaller>
Delete a directory regardless of its contents
<addFilesToUninstaller>
   <files>${installdir}/someDirectory/</files>
</addFilesToUninstaller>

The action will make the uninstaller delete the ${installdir}/someDirectory/ directory even if new files are added. In addition, as the action does not care about the contents of the directory, it is much more faster.

Additional Examples: Example 1, Example 2

Remove Files from Uninstaller

This action allows you to remove files or directories from the uninstaller, so they will not be removed during the uninstallation process. This action is used when some files unpacked by the installer (so they are automatically marked to be uninstalled) must be preserved after uninstalling.

The allowed properties in the <removeFilesFromUninstaller> action are:

Examples:

<postInstallationActionList>
  <removeFilesFromUninstaller>
    <files>${installdir}/licenses</files>
  </removeFilesFromUninstaller>
</postInstallationActionList>

Additional Examples: Example 1

Flow Control Actions

Foreach

Iterate over a set of values and execute a given set of actions The allowed properties in the <foreach> action are:

  • <values>: Space-separated values to iterate over

  • <variables>: Space-separated list of variables that will be assigned a value with each iteration

  • <actionList>: List of actions

Examples:

Create a summary page with the installed components
  <labelParameter>
     <name>summary</name>
     <title>Summary</title>
     <explanation></explanation>
     <preShowPageActionList>
        <setInstallerVariable>
           <name>text</name>
           <value>You are about to install ${project.fullName}.

Please review the below information:

Installation Directory: ${installdir}

Username: ${username}

License File: ${license_file}

Installed Componets:
</value>
        </setInstallerVariable>
        <foreach>
           <variables>component</variables>
           <values>component1 component2 component3</values>
           <actionList>
              <!-- Just include selected Components -->
              <continue>
                <ruleList>
                   <isFalse>
                     <value>${component(${component}).selected}</value>
                   </isFalse>
                </ruleList>
              </continue>
              <setInstallerVariable>
                <name>text</name>
                <value>${text}

${component(${component}).description}</value>
              </setInstallerVariable>
           </actionList>
        </foreach>
     </preShowPageActionList>
  </labelParameter>
Iterate to define variables from the registry using multiple variables
<foreach>
   <variables>name variable</variables>
   <values>Version oldVersion Location ondInstalldir Language installationLanguage</values>
   <actionList>
      <registryGet>
         <key>HKEY_LOCAL_MACHINE\Software\${project.windowsSoftwareRegistryPrefix}</key>
         <name>${name}</name>
         <variable>${variable}</variable>
      </registryGet>
   </actionList>
</foreach>

Additional Examples: Example 1, Example 2, Example 3

While

Execute a group of actions as long as conditions are met The allowed properties in the <while> action are:

Examples:

Wait for the user to close a running application
<while>
  <actionList>
    <showWarning>
      <text>The application "myapp.exe" is still running, please close it and click ok</text>
    </showWarning>
  </actionList>
  <conditionRuleList>
    <processTest>
      <logic>is_running</logic>
      <name>My Application with long filename.exe</name>
    </processTest>
  </conditionRuleList>
</while>

Additional Examples: Example 1, Example 2

If / Else

Conditionally execute a group of actions The allowed properties in the <if> action are:

Examples:

Execute the installed application depending on the platform
<if>
  <conditionRuleEvaluationLogic>or</conditionRuleEvaluationLogic>
  <conditionRuleList>
     <platformTest type="linux"/>
     <platformTest type="osx"/>
  </conditionRuleList>
  <actionList>
     <runProgram>
        <program>${installdir}/scripts/launch.sh</program>
     </runProgram>
  </actionList>
  <elseActionList>
     <runProgram>
        <program>${installdir}/scripts/launch.bat</program>
     </runProgram>
  </elseActionList>
</if>
Continue

Continue current loop. If the <continue> action it is executed outside a loop (a <while> or a <foreach>) it will throw an error.

Examples:

Backup a list of folders if they are not empty
<foreach>
   <variables>dir</variables>
   <values>${installdir}/data ${installdir}/conf ${installdir}/samples</values>
   <actionList>
     <continue>
       <ruleList>
         <fileTest path="${dir}" condition="is_empty"/>
       </ruleList>
     </continue>
     <copyFile>
        <origin>${dir}</origin>
        <destination>${installdir}/backup</destination>
     </copyFile>
   </actionList>
</foreach>

Additional Examples: Example 1, Example 2, Example 3

Break

Break current loop. If the <continue> action it is executed outside a loop (a <while> or a <foreach>) it will throw an error.

Examples:

Wait until a service is started or a timeout is reached
<startWindowsService>
    <abortOnError>0</abortOnError>
    <displayName>myservice</displayName>
    <serviceName>My Service</serviceName>
</startWindowsService>
<setInstallerVariable name="time" value="0"/>
<while>
  <actionList>
    <!-- Break the loop if port is freed -->
    <break>
      <ruleList>
        <windowsServiceTest service="myService" condition="is_running"/>
      </ruleList>
    </break>
    <!-- Wait a second to avoid using too much cpu -->
    <wait ms="1000"/>
    <mathExpression>
      <text>${time}+1000</text>
      <variable>time</variable>
    </mathExpression>
  </actionList>
  <conditionRuleList>
    <!-- Iterate until the timeout reach 30 sec (30000msec) -->
    <compareValues>
      <value1>${time}</value1>
      <logic>less_or_equal</logic>
      <value2>30000</value2>
    </compareValues>
  </conditionRuleList>
</while>

Additional Examples: Example 1, Example 2

OSX-specific actions

Change OSX file attributes

Change OSX attributes of a file or directory. Trying to set an attribute on a read only file will result in a failure. Make sure the file is writable before attempting to change any attribute other than, of course, readOnly The allowed properties in the <changeOSXAttributes> action are:

  • <creator>: Creator to set to file or directory

  • <excludeFiles>: Patterns to exclude files

  • <files>: File patterns to apply action to

  • <hidden>: Whether the file is visible or not

  • <readOnly>: Whether the file is read only or writable

  • <type>: Type to set to file or directory

The <hidden> and <readOnly> tags allow specifying a boolean value (0 or 1) or unchanged, to preserve the current value of the attribute. You can check the result of the action using the OS X command /Developer/Tools/GetFileInfo:

$> /Developer/Tools/GetFileInfo path/to/someFile

Examples:

Hide a set of files and define their creator and type
<changeOSXAttributes>
    <creator>doug</creator>
    <files>${installdir}/conf/*</files>
    <type>TEXT</type>
    <hidden>1</hidden>
    <readOnly>unchanged</readOnly>
</changeOSXAttributes>
Change attributes of a readOnly file
<!-- The file must be first to be writable -->
<changeOSXAttributes>
    <files>${installdir}/some/file</files>
    <readOnly>0</readOnly>
</changeOSXAttributes>

<!-- Then we change the attributes -->
<changeOSXAttributes>
    <files>${installdir}/some/file</files>
    <creator>jhon</creator>
    <readOnly>unchanged</readOnly>
</changeOSXAttributes>

<!-- Then we revert the readOnly attribute -->
<changeOSXAttributes>
    <files>${installdir}/some/file</files>
    <readOnly>1</readOnly>
</changeOSXAttributes>

Java Actions

Autodetect Java

Autodetects an existing Java (tm) installation in the system and creates corresponding installer variables: java_executable java_vendor java_version java_version_major java_version_full java_bitness. If a valid java version was found, the variable java_autodetected will be set to 1 The allowed properties in the <autodetectJava> action are:

You can find additional information in the Java section.

Examples:

Detect a Java version between 1.4 and 1.5
<autodetectJava>
  <promptUser>0</promptUser>
  <validVersionList>
     <validVersion>
        <vendor>sun</vendor>
        <minVersion>1.4</minVersion>
        <maxVersion>1.5</maxVersion>
     </validVersion>
  </validVersionList>
</autodetectJava>

Additional Examples: Example 1, Example 2, Example 3

Create Launchers

Creates one or more Java launchers in specified location. The allowed properties in the <createJavaLaunchers> action are:

You can find additional information in the Java Launchers section. Examples:

Create a launcher for a bundled JAR file.
<createJavaLaunchers>
  <destination>${installdir}/launchers</destination>
  <javaLauncherList>
    <javaLauncher>
      <binaryName>myLauncher</binaryName>
      <jarFile>testapplication.jar</jarFile>
    </javaLauncher>
  </javaLauncherList>
</createJavaLaunchers>

Additional Examples: Example 1, Example 2

Installer Actions

Encode base64

Encode a string using base64. The allowed properties in the <encodeBase64> action are:

Examples:

Encode a message in Base64
<encodeBase64>
    <text>This is some secret text to encode</text>
    <variable>${secretEncodedText}</variable>
</encodeBase64>
Decode base64

Decode a string using base64. The allowed properties in the <decodeBase64> action are:

Examples:

Decode a message encided in Base64
<decodeBase64>
    <text>${secretEncodedText}</text>
    <variable>${result}</variable>
</decodeBase64>
MD4

Generate a MD4 from a given text. The allowed properties in the <md4> action are:

Examples:

Calculate the MD4 has of a password
<md4>
    <text>${password}</text>
    <variable>result</variable>
</md4>
MD5

Generate a MD5 from a given text. The allowed properties in the <md5> action are:

  • <text>: Text to calculate the MD5 on.

  • <variable>: Variable to which to save the MD5 to.

Examples:

Check the integrity of a file
<readFile>
  <path>${installdir}/keys.txt</path>
  <name>data</name>
</readFile>
<md5>
  <text>${data}</text>
  <variable>result</variable>
</md5>
<throwError>
   <text>The file has been corrupted!</text>
   <ruleList>
     <compareText>
       <text>${result}</text>
       <logic>does_not_equal</logic>
       <value>3f62e6df4607c4be16f4946dc9fa16ca</value>
     </compareText>
   </ruleList>
</throwError>

Additional Examples: Example 1, Example 2, Example 3

SHA-1

Generate a SHA-1 from a given text. The allowed properties in the <sha1> action are:

  • <text>: Text to calculate the SHA-1 on.

  • <variable>: Variable to which to save the SHA-1 to.

Examples:

Encode some secret data with a secret key to send using <httpPost>
<sha1>
  <text>${user}+thisIsAsecretKey+${password}</text>
  <variable>encodedText</variable>
</sha1>
<httpPost url="http://www.example.com/checkdata.php">
  <filename>${installdir}/activationUrl</filename>
  <queryParameterList>
    <queryParameter name="data" value="${encodedText}"/>
  </queryParameterList>
</httpPost>
SHA-256

Generate a SHA-256 from a given text. The allowed properties in the <sha256> action are:

  • <text>: Text to calculate the SHA-256 on.

  • <variable>: Variable to which to save the SHA-256 to.

Examples:

Encode some secret data with a secret key to send using <httpPost>
<sha256>
  <text>${user}+thisIsAsecretKey+${password}</text>
  <variable>encodedText</variable>
</sha256>
<httpPost url="http://www.example.com/checkdata.php">
  <filename>${installdir}/activationUrl</filename>
  <queryParameterList>
    <queryParameter name="data" value="${encodedText}"/>
  </queryParameterList>
</httpPost>
Math

Calculate math expression The allowed properties in the <mathExpression> action are:

Examples:

Calculate the square root of a number
<mathExpression>
    <text>sqrt(${number})</text>
    <variable>result</variable>
</mathExpression>

Additional Examples: Example 1

Add Choice Options

Add options to an existing choice parameter The allowed properties in the <addChoiceOptions> action are:

  • <name>: Name of an existing choice parameter.

  • <optionList>: List of options to give to a choice parameter

Examples:

Add options for English and Spanish for an existing choice parameter language.
 <addChoiceOptions>
    <name>language</name>
    <optionList>
      <option>
        <value>en</value>
        <text>English</text>
      </option>
      <option>
        <value>es</value>
        <text>Spanish</text>
      </option>
    </optionList>
 </addChoiceOptions>

Each <option> specifies an additional option to be added to a <choiceParameter>.

Additional Examples: Example 1, Example 2, Example 3

Add Choice Options from Text

Add options to an existing choice parameter from a given text The allowed properties in the <addChoiceOptionsFromText> action are:

  • <name>: Name of an existing choice parameter.

  • <text>: Text with the options to give to a choice parameter

Examples:

Add options parsing text format existing choice parameter language.
 <addChoiceOptionsFromText>
    <name>language</name>
    <text>
jp=Japanese
jp.description=Language spoken in Japan
de=German
de.description=Language spoken in Germany
it=Italian
it.description=Language spoken in Italy
pl=Polish
pl.description=Language spoken in Poland
ru=Russian
ru.description=Language spoken in Russia
</text>
 </addChoiceOptionsFromText>

The keys in the text will be used to set the <value> property of option. The key value (the righthand side) will be used to set the <text> property. Optionally, if a key has a .description suffix and matches an existing <value>, the key value will be used to set the <description> property.

Additional Examples: Example 1, Example 2, Example 3

Remove Choice Options

Clear choice values for a parameter The allowed properties in the <removeChoiceOptions> action are:

  • <name>: Name of an existing choice parameter.

  • <options>: Options to remove

Examples:

Remove options for English and Spanish from existing choice parameter `language.
<removeChoiceOptions>
   <name>language</name>
   <options>es,en</options>
</removeChoiceOptions>

This action can take a single option to remove or multiple options, which are separated using comma.

Additional Examples: Example 1, Example 2, Example 3

Generate Random Value

Generate a random value. The allowed properties in the <generateRandomValue> action are:

  • <length>: Character length for the generated value.

  • <variable>: Variable to which to save the generated value.

Examples:

Create an unique filename
<generateRandomValue>
   <length>5</length>
   <variable>suffix</variable>
</generateRandomValue>
<setInstallerVariable name="${installdir}/.tmp${suffix}"/>

Additional Examples: Example 1

Action Group

Group a set of actions. The allowed properties in the <actionGroup> action are:

Examples:

Read a file and show its contents
   <actionGroup>
     <actionList>
       <readFile>
         <path>${installdir}/notes.txt</path>
         <name>text</name>
       </readFile>
       <showText>
          <title>InstallBuilder Notes</title>
          <width>500</width>
          <height>600</height>
          <text>${text}</text>
       </showText>
     </actionList>
     <ruleList>
        <isTrue value="${viewNotes}"/>
     </ruleList>
   </actionGroup>

Additional Examples: Example 1, Example 2, Example 3

Log Message

Write a message to the installation log. Useful for debugging purposes. The allowed properties in the <logMessage> action are:

  • <enableTimeStamp>: Whether to enable timestamp in the message or not.

  • <text>: Message to include in log

  • <timeStampFormat>: Format string for the optional timestamp. The string allows a number of field descriptors.

Examples:

Add additional details to the log
<logMessage>
   <text>Starting MySQL...</text>
</logMessage>
<runProgram>
    <program>${installdir}/ctlscript.sh</program>
    <programArguments>start mysql</programArguments>
</runProgram>
<logMessage>
   <text>MySQL started!</text>
</logMessage>

Additional Examples: Example 1, Example 2, Example 3

Component Selection

Select or deselect components for installation. The allowed properties in the <componentSelection> action are:

  • <deselect>: Comma separated list of components you wish to deselect for installation.

  • <select>: Comma separated list of components you wish to select for installation.

Examples:

Configure the selected components based on the installation type
<componentSelection>
   <deselect>minimumDoc</deselect>
   <select>fullDocs,core,images</select>
   <ruleList>
     <compareText text="${installationMode}" logic="equals" value="full"/>
   </ruleList>
</componentSelection>
<componentSelection>
   <deselect>fullDocs,images</deselect>
   <select>minimumDoc,core</select>
   <ruleList>
     <compareText text="${installationMode}" logic="equals" value="minimal"/>
   </ruleList>
</componentSelection>

Additional Examples: Example 1, Example 2, Example 3

Mark variables as global

Mark a list of variables as global. Global variables defined or modified inside custom actions preserve their values after the execution while regular variables are not visible outside. The allowed properties in the <globalVariables> action are:

Examples:

Create a function that generates an unique name and stores its path in a variable
<project>
 ...
 <functionDefinitionList>
  <actionDefinition>