InstallBuilder Action Lists

Published on

Creating an installer is not as straightforward as most people think. This is especially the case for more sophisticated configurations, such as when you need to execute different platform-specific actions at different stages of the installation process. You may need to check a registry value, create a configuration file, execute a particular command, make substitutions in text files or even connect to an external server via a HTTP POST request. BitRock InstallBuilder includes a number of useful built-in actions to facilitate adding complex functionality to your installer. Actions can be accessed by editing the XML project file directly or in the 'Advanced' section of the InstallBuilder GUI.

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. Action lists include your actions of choice and are executed at a specific point of the installation process as outlined below.

BitRock InstallBuilder Action Lists (in order of execution)

BUILDING THE INSTALLER
  • preBuildActionList

Executes before generating the installer file. These actions usually include setting environment variables or performing some kind 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.

  • 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 then it is executed one final time for the whole CDROM build.

INSTALLATION
  • preShowHelpActionList

Executes before help information is displayed.

  • initializationActionList

Executes when the installer has started, just before the parsing of the command line options.

LANGUAGE SELECTION
  • 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 setting user-defined installer variables that will be used later on or for detecting a Java (tm) Runtime Environment.

COMPONENTS SELECTION
  • componentSelectionValidationActionList

Executes after the component page is displayed to check that the selected components are a valid combination.

PARAMETER PAGES

For each parameterPage, you can specify 3 different action lists: validationActionList, preShowPageActionList and postShowPageActionList. Note that those actions are not executed if the installer is executed in unattended mode.

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

  • preShowPageActionList

Executes before the corresponding parameter page is displayed. This can be useful for changing the value of the parameter before it is displayed.

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

COPYING FILES
  • readyToInstallActionList

Executes right before the file copying step starts. It is commonly used to execute actions that depend on user input.

  • Folder actionList

Executes just after files defined in the particular folder are installed, the next folder files are copied and its actionList executed, etc.

  • postInstallationActionList

Executes after the installation process has taken place but before the uninstaller is created and the final page is displayed.

  • postUninstallerCreationActionList

Executes after the uninstaller has been created but before the final page has been displayed.

  • 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. The text displayed can be specified in the property.

UNINSTALLATION
  • preUinstallationActionList

Executes before the uninstallation process takes place, such as unsetting user-defined installer variables or deleting files created after installation occured.

  • postUninstallationActionList

Executes after the uninstallation process takes place.

SPECIAL ACTION LISTS
  • installationAbortedActionList

Executes when the installation process is aborted.

Order of Execution of Action Lists

Each action list may be included in the main project or inside the components. Lets take an initializationActionList as an example. We 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).

We can divide all action lists into two groups based on what is executed earlier: main project or components action lists:

  • the main project action lists then components onespreBuildActionList, initializationActionList, preIstallationActionList, readyToInstallActionList, preUninstallationActionList
  • components action lists then the main project onespostBuildActionList, postInstallationActionList, postUninstallationActionList

The installer executes action lists by group, which means that first all initializationActionList actions take place and then all preInstallationActionList actions are executed.

Unattended mode, RPM and DEB packages

These are special cases. There is no interaction with the user and the following action lists are not executed:

  • componentSelectionValidationActionList

  • finalPageActionList

  • Any parameter's validationActionList

  • Any parameter's preShowPageActionList

  • Any parameter's postShowPageActionList

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.