InstallBuilder Home
Contact Support Download

Builder

InstallBuilder supports two build modes, "build" and "quickbuild", which are explained in the following sections.

Build

This is the slower but safer build process. For each build process, if a file already exists with the name of the installer to build, it will be first deleted. The list of steps performed for a full build are:

  • Load and validate the XML project. If the GUI builder is being used, the project has already been loaded and validated.

  • Check if the destination filename is locked, for example if it is currently running

  • Execute the <preBuildActionList>

  • Replace the current file in the output directory

  • Modify Windows resources and icons if the target is Windows

  • Add language files, licenses, readmes and images to the installer

  • Pack all the files defined in the XML project

  • Execute the <postBuildActionList>

Quickbuild

A regular build always creates a new installer and repacks all of the files. On the contrary, using Quick Build makes it possible to do incremental builds in which only new files or files that have changed will be repackaged. If you are packaging hundreds of megabytes, this should result in significantly quicker builds, but the resulting installers may increase in size with each new incremental build. It is recommended that you use quickbuild during the development process and do a full builds before the official release.

bin/builder quickbuild /path/to/project.xml

It is also possible to only update project files like logos, splash screen, readme a license files and project XML without repackaging any files at all. You can do so with the following option:

bin/builder quickbuild /path/to/project.xml --onlyprojectfiles

This build process is slightly different:

  • Load and validate the XML project. If the GUI builder is being used, the project has already been loaded and validated.

  • If the file does not exist, abort quickbuild and perform a regular full build

  • Check if the destination filename is locked, for example if it is currently running

  • Execute the <preBuildActionList>

  • Modify Windows resources and icons if the target is Windows. The <requestedExecutionLevel> property is ignored in quickbuilds

  • Add language files, licenses, readmes and images to the installer

  • Pack just new or modified files

  • Execute the <postBuildActionList>

Using the Command Line Interface

One of the most useful features of InstallBuilder is the ability to automate the build process. Installers can be built from a shell script or the command line by issuing the following command:

 $> bin/builder build /path/to/project.xml

By default, it will build an installer for the current platform. However, you can pass an optional argument to the command line to indicate the target platform to build for. For example:

 $> bin/builder build /path/to/project.xml windows

On Windows, there are separate executables for the Graphical Builder Interface (builder.exe) and the Command Line Interface (builder-cli.exe). This is because Windows imposes a compilation-time switch to distinguish between command line applications and graphical applications, the latter lacking the ability to write to the console.

You can build an installer from the command line on Windows by issuing the following command:

C:\Program Files\InstallBuilder\bin/builder-cli.exe build /path/to/project.xml linux

It is also possible to set different project settings and variables from the command line by passing the option --setvars and its arguments as in the following example:

  bin/builder build /path/to/project.xml --setvars project.fullName="New Project Name"
project.version=0.1beta some_variable_name=some_value

where some_variable_name is a variable that will be available in the installer <preBuildActionList>.

In addition, the builder application allows some options for both the console and the GUI build process:

 --help                                                                    Display the list of valid options

 --version                                                                 Display product information

 --verbose                                                                 Write files being packed on command line builds

 --license <license>                                                       Provide an alternative license to the builder
                                                                           Default:

 --setvars <setvars>                                                       Modify project variables before the build process: --setvars installdir=/tmp project.version=1.5
                                                                           Default:

 --downloadable-components                                                 Build downloadable components as separate files

 --onlyprojectfiles                                                        On quickbuild mode, just update project files without considering new packed files

 --project <project>                                                       Open specified project for editing
                                                                           Default:

 --disable-parallel-compression                                            Disable performing LZMA / LZMA Ultra compression using multiple cores

 --disable-parallel-compression-throttling                                 Disable performing parallel compression for LZMA / LZMA Ultra at lower priority

 --parallel-compression-cores <cores>                                      Number of cores to use for LZMA / LZMA Ultra parallel compression
                                                                           Default: auto

 --parallel-compression-init-timeout <parallel-compression-init-timeout>   Number of seconds to wait before assuming child process initialization has timed out
                                                                           Default: 30

Creating Custom Builds

The preceding sections introduced the basic command line build process, specifying the project to build and the target platform. They also presented the --setvars flag, which allows some project elements to be modified. However, the build process allows much more significant customizations.

This example assumes that you plan to build two different installers. A complete project, including documentation and some optional applications and a lightweight installer, that will only bundle the main project files. The obvious solution would be to have two projects: one that bundles all of the components and the other with the primary project files. This can be achieved by organizing the files and logic into components and using the <include> directive, which will allow you to separate them into multiple .xml files.

The drawback of this approach is that you will be forced to duplicate some logic, such as the project properties. A more efficient approach would be to have a single XML project file and decide whether or not to pack the components based on the build target. For example, you could use:

$> builder build project.xml --setvars buildFlavor=full

To build the complete installer and

$> builder build project.xml --setvars buildFlavor=minimal

to only pack the main application.

For this approach, you simply have to create a hidden parameter to make the buildFlavor type persistent at runtime and use the <shouldPackRuleList>:

   <project>
      <shortName>myProject</shortName>
      <version>1.4</version>
      ...
      <parameterList>
         ...
         <stringParameter name="buildFlavor" value="minimal" ask="0"/>
         ...
      </parameterList>
      <componentList>
          <component>
             <name>main</name>
             ...
          </component>
          <component>
             <name>optionalComponent</name>
             ...
             <shouldPackRuleList>
                 <compareText text="${buildFlavor}" logic="equals" value="full"/>
             </shouldPackRuleList>
          </component>
      </componentList>
   </project>

You could also combine it with the <preBuildActionList> and customize the particular aspects of the project as in:

   <preBuildActionList>
      <actionGroup>
         <actionList>
             <setInstallerVariable name="project.fullName"
              value="Basic Product Installation"/>
             <setInstallerVariable name="project.windowsExecutableIcon"
             value="/path/to/minimal.ico"/>
             <setInstallerVariable name="project.installerFilename"
             value="minimal-installation.exe"/>
         </actionList>
         <ruleList>
            <compareText text="${buildFlavor}" logic="equals" value="minimal"/>
         </ruleList>
      </actionGroup>
      <actionGroup>
         <actionList>
             <setInstallerVariable name="project.fullName"
              value="Full Product Installation"/>
             <setInstallerVariable name="project.windowsExecutableIcon"
             value="/path/to/full.ico"/>
             <setInstallerVariable name="project.installerFilename"
             value="full-installation.exe"/>
         </actionList>
         <ruleList>
            <compareText text="${buildFlavor}" logic="equals" value="full"/>
         </ruleList>
      </actionGroup>
   </preBuildActionList>

All the above functionality would work if you defined buildFlavor as a regular variable instead of creating a hidden parameter, but you would not be able to access it at runtime in that case.

You can use that functionality, for example, to show a link to a download page at the end of installation if the user wants to download optional applications:

   <finalPageActionList>
       <launchBrowser url="www.downloads.com/optional" progressText="Would you
       like to visit our website to download additional modules?">
          <ruleList>
              <compareText text="${buildFlavor}" logic="equals" value="minimal"/>
          </ruleList>
       </launchBrowser>
   </finalPageActionList>

Compression algorithms

InstallBuilder provides three compression types that can be set in the project properties.

The available algorithms are:

  • ZIP: Provides fast installer build time and decompression, but compression ratio is low

  • LZMA Ultra: Very slow installer build time, but provides reasonable decompression speed, often on par with ZIP algorithm; provides the best compression ratio

  • LZMA: Installer is built faster compared to LZMA Ultra, but slower than ZIP ; installation time is often slower than other algorithms; the compression ratio is better than ZIP but worse than LZMA Ultra

Different algorithm may be used depending on requirements. The ZIP compression is recommended for installers that deliver small installers or consists of files that cannot be effectively compressed - such as consisting mainly of media files.

LZMA Ultra is recommended for installers that deliver payload that can be compressed - such as binary files or other file formats that are not compressed.

In terms of memory usage, ZIP requires the least memory when building the installers as well as at runtime.

LZMA algorithm has slightly higher memory requirements when installing and larger memory requirements when building.

LZMA Ultra compression requires more memory than either ZIP or LZMA algorithms - both when building the installers and when installer is unpacking the files.

LZMA Ultra Block Size

Memory that is used by LZMA Ultra can be configured by setting the <lzmaUltraBlockSize> option. This option specifies the maximum size of a block in megabytes that will be used to compress files.

The value affects memory requirements both for build time as well as installation time. The default value is 80, which means a block up to 80MB will be used. The recommended value range is between 40 and 100.

Setting this value to a lower value will decrease the memory requirements, but at the same time make the installer slightly larger. Setting this value to a higher value will increase memory requirements, but may decrease installer size.

Below is an example to decrease the block size to 40MB:

<project>
  <compressionAlgorithm>lzma-ultra</compressionAlgorithm>
  <lzmaUltraBlockSize>40</lzmaUltraBlockSize>
  ...
</project>
Note
Setting this value too high may cause builder to run out of memory

Setting <lzmaUltraBlockSize> to high values such as 120 may cause the 32-bit versions of the builder to run out of memory.

If the project has to be built with <lzmaUltraBlockSize> set to a high value, it is recommended to use the InstallBuilder on Linux 64-bit platform as it can use more than 4GB of process memory.

Parallel compression

InstallBuilder supports using multiple cores and/or threads for building installers.

This is supported for projects that use LZMA and LZMA Ultra compression algorithms and when the payload encryption is disabled.

This functionality is enabled by default and uses all of the logical CPUs that the machine has. For example a machine with 4 cores that have 2 threads each will try to use all 8 logical processors.

When using the command line tool the compression can be customized using options described in more details below. The settings are applied to current build only.

When using the GUI building tool, the settings for parallel compression can be found by opening the Preferences window. The settings from the preferences window are stored in user settings and used by all builds made from the GUI.

InstallBuilder Preferences Window
Figure 74: InstallBuilder Preferences Window

The LZMA Parallel Compression option allows disabling this functionality entirely. When the option is disabled, InstallBuilder will only use single core when performing the compression.

The command line equivalent is --disable-parallel-compression, which will disable the parallel compression for the current build. Example usage:

$> bin/builder build project.xml --disable-parallel-compression

The Number of Cores for Parallel Compression option allows specifying number of logical processors that will be used for the build process.

The value Auto indicates using all available logical processors and is the default value. Setting it to any other value will cause InstallBuilder to use that amount of logical processors for the compression, regardless of machine’s current processor count.

The command line equivalent is --parallel-compression-cores. Example usage:

$> bin/builder build project.xml --parallel-compression-cores 4

It is also possible to specify auto or auto-N, where N is the number of cores to not use. For example the below build will use all but 2 cores (such as using up 6 out of 8 cores):

$> bin/builder build project.xml --parallel-compression-cores auto-2

The Parallel Compression Throttling option enabled or disabled running the compression processes at lower priority.

When enabled, this option prevents InstallBuilder from using all of machine’s resources which may degrade performance of other applications or processes running on the machine.

It is recommended to leave this option enabled.

The command line equivalent is --disable-parallel-compression-throttling`, which will disable the using the lower priority for the current build. Example usage:

$> bin/builder build project.xml --disable-parallel-compression-throttling

Parallel decompression

InstallBuilder supports using multiple cores and/or threads when installing files on the target machine.

This is supported for installers that are built using the LZMA and LZMA Ultra compression algorithms and when the payload encryption is disabled.

This functionality is enabled by default and by default InstallBuilder uses all of the logical processors that the machine has.

The limit for maximum number of cores to use is 8. This is because using more cores will not decrease the installation time, but the process will use more memory.

It is possible to customize it using the <parallelDecompressionCores> project property, which will specify the maximum number of cores to use during uncompression.

<project>
  <parallelDecompressionCores>4</parallelDecompressionCores>
  ...
</project>

This option is mainly useful when installer will often be run on machines with large number of processors, but very little memory being available and it is not recommended to change the default value.

Regardless of the value for <parallelDecompressionCores>, the installer will use either the number of logical processors available on the target machine if it is lower than <parallelDecompressionCores>.

It is also possible to customize the number of logical processors to use when running the installer from the command line by using the --parallel-decompression-cores option. Such as:

$> output/installer.run --parallel-decompression-cores 2

Setting the value to 1 will completely disable the parallel decompression functionality.

← Previous: Native Packages | ↑ Up: InstallBuilder User Guide 24 | Next: Windows →