BitRock InstallBuilder User Guide 8

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:

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\

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.

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

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:

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-8.0.2/ if you are running the installation as superuser (root).

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:

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

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.

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.

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.

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:

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:

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

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

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

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

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.

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.

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:

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:

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:

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:

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.

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

User Interface Settings

Installer Settings

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.

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:

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\user\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.

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

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

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:

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:

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:

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

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

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.

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.

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:

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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:

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

Using this notation you can also modify component settings:

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

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

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:

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:

Can be accessed using:

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:

The parameter should now be accessed using:

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

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:

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:

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:

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

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:

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

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.

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

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.

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:

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

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:

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: