Please contact us at support@bitrock.com if you find any problems running BitRock InstallBuilder or the generated installers.

A User Guide is provided with the product and can be found in the docs/ subdirectory of the installation path. You can also download it here .

We have an online Knowledge Base that is searchable. We are working on expanding its contents.

1. How do I install BitRock InstallBuilder?
2. I get a payload error. What can I do?
3. I get an ".X Error of failed request: BadAtom (invalid Atom parameter)" executing InstallBuilder. What can I do?
4. I get an "SELinux denied execmem" error executing InstallBuilder. What can I do?
5. I get a "GLib-GObject-WARNING". What can I do?
6. The installer crashes on Linux. What can I do?
7. The installer seems to take a long time to start. Is this normal?

1. What is the format of the installer project file?
2. What do you mean by "our installers do not require a self-extraction step"?
3. How can I perform a silent installation?
4. How can I perform a text installation?
5. Can you install on servers without X-Window?
6. Can you create CDROM installers?
7. Are all of BitRock IntallBuilder's features accessible through the GUI?
8. Do BitRock installer project files support development with version control systems?
9. Can BitRock InstallBuilder generate installers from the command line?
10. What is the difference between RPM packages and BitRock installers?
11. What dependencies do BitRock installers have?
12. Which platforms do BitRock installers support?
13. Does the use of forward slashes and backslashes in paths make any difference?
14. What does the "save relative paths" option mean?
15. The Readme/License file I want to include in my installer is in html. How can I show it to the user?
16. Does the same project.xml work across all platforms InstallBuilder supports?
17. How do I specify a different default installation directory for Unix and Windows?
18. How can I create an update installer?
19. What's the difference between an update installation and a regular installation?
20. How can I set the directory where installer generated are placed?
21. Can I convert a filename or directory path from Windows format to Unix format?
22. How can I register my application with the RPM database?
23. Does InstallBuilder support component selection?
24. Is there a command line option for component selection?
25. How can I determine if a component has been selected?
26. Is there a log file of the installation?
27. How can I log a message to the installation log?

1. What are the advantages of BitRock multiplatform installers over Java(tm)-based multiplatform installers?
2. Are BitRock installers suitable to distribute Java(tm)-based applications?
3. Can the Java autodetection just warn the user instead of aborting if there is not a JVM present?

1. I have an Open Source project, can I use your installer for free?
2. Is there a discount for license renewals?
3. My licensed version of InstallBuilder is working well for me. Do I need to renew the license?

1. What do ${installdir}, ${full_productname} and all the other installer environment variables mean?
2. How can I access the system environment variables?
3. Are installer environment variables case sensitive?
4. Inside my Windows post-installation script I do cd ${installdir} but it is not working. Why is that?
5. How can I create my own installer variables?

1. The installer I have built creates a shortcut in my desktop, but it does not show the right icon image. How can I fix that?
2. The shortcuts work fine in my system, but do not work or do not display an image when installed in a different system. Why is that?
3. On Linux, the installer I have built creates a shortcut in my desktop and points to the right file, but it still does not work. The script works fine from the command line.
4. I made some changes to my installer but QuickBuild does not seem to include the changes. How do I update it?
5. How do I change the location or name of the uninstaller?
6. I changed the location of the uninstaller in the customization screen, and now the shortcut in the start menu does not work. How do I fix this?
7. How can I prevent the installer from creating a Start Menu?

1. What input can I ask the user for during installation?
2. Can InstallBuilder be customized with new installer pages?
3. How can I make the installer ask the user for a password during installation?
4. How do I request a text string from the user?
5. How can I direct the installer to ask the user to enter a file or directory?
6. How do I ask the user for more than one parameter in the same screen?
7. How can I arrange parameters horizontally?
8. How do I make the installer ask the user a yes/no question?
9. How do I display a read-only text information page to the user?
10. How can I direct the user to select a value among a predefined list?
11. How can I validate user input?
12. What does the tag <cliOptionName> inside a parameter section mean?
13. How can I show images while my product is being installed?
14. How can I show custom pages after installation has finished?

1. How do I make the installer perform a string substitution as part of the installation?
2. How can I make the installer convert my plain text files in DOS format to Unix format?
3. How do I set Unix permissions for some files and directories?
4. How do I create a new system environment variable?
5. How do I add a directory to the system PATH?
6. How do I remove a directory from the system PATH?
7. I want to append a certain text at the end of a file. How can I do this?
8. How do I make the installer display an error message to the user under certain circumstances?
9. Can the installer autodetect if there is an existing Java(tm) installation in the system?
10. What if I want the user to select the JVM to use?
11. How can I create a new Windows registry key or modify the value of an existing one?
12. How can I read and store the value of a Windows registry key in an installer variable?
13. How can I delete a Windows registry key?
14. I need to change the owner and group of a file or directory in Unix. How do I do this?
15. How can I create a symbolic link?
16. How can I capture the output of a script?
17. I need to run a program as part of the installation of my application. Can I do this with BitRock InstallBuilder?
18. Can I group certain actions together?
19. What is a rule list?
20. Which logic operands do rule lists support?
21. What are the components of a ruleList?
22. How can I run a program only if certain conditions are met?
23. How can I find out how much free disk space is available for my application?
24. How can I backup a file or directory as part of my installation?
25. Can I delete a file or directory as part of my application installation?
26. How can I copy a file or directory as part of an installation?
27. How can I configure the installer to inform the user but not to abort installation after an error is found running an action?
28. How can I launch an application in the background from InstallBuilder?
29. How can I rename a file or directory as a part of my installation?
30. What is the difference between an action list and an actionGroup?
31. How can I remove a Windows registry key that has subkeys inside?
32. How can I restart the computer after installation has completed?
33. How can I test if a certain TCP/IP port is already taken?
34. How can I display a text page when installation completes?
35. How can I display a web page when installation completes?

1. Which kind of action lists does BitRock InstallBuilder support?
2. How do I direct the installer to perform actions before installation starts?
3. How do I direct the installer to perform actions after installation finishes?
4. How do I direct the installer to perform actions before showing a page?
5. How do I direct the installer to perform actions after showing a page?
6. How can I allow the user to start my software from the final installation page?

1. How can I allow only a limited set of languages for installation?
2. How can I customize the language used in custom installer pages?

1. How can I change the size of the installer screens?

Answers

INSTALLATION

How do I install BitRock InstallBuilder?

After downloading the binary file, change the permissions to allow execution. You can either right-click on the file and select Properties from your desktop environment or issue the following command line :

You are ready to install the software by clicking on it from your desktop environment or by typing :

To complete the installation, just follow the instructions on screen.

I get a payload error. What can I do?

If you get the following error while trying to run the installer from the command line:

Installer payload initialization failed. This is likely due to an incomplete or corrupt downloaded file.

The file was probably not downloaded correctly and you will need to download it again. We have found this problem happens intermittently when using recent versions of the Mozilla browser on Debian unstable.

I get an ".X Error of failed request: BadAtom (invalid Atom parameter)" executing InstallBuilder. What can I do?

This is happening because you are forwarding the X session over ssh. Make sure you have:

ForwardX11Trusted yes

in ~/.ssh/config and /etc/ssh_config

I get an "SELinux denied execmem" error executing InstallBuilder. What can I do?

This is happening because you are running SELinux and it is interfering with the in-memory decompressor used by InstallBuilder. To temporarily disable SELinux, you can execute the following command as root

/usr/sbin/setenforce 0

and then execute InstallBuilder.

To reenable SELinux:

/usr/sbin/setenforce 1

I get a "GLib-GObject-WARNING". What can I do?

This is happening because the version of the GTK GUI libraries that InstallBuilder is using is not exactly the same as the one installed in your system. You can disregard this warning, as the installer should work correctly in most cases.

The installer crashes on Linux. What can I do?

BitRock InstallBuilder has been designed to create installers that will run out of the box in virtually any Linux distribution. In rare ocassions, a certain combination of system libraries and X-Window server setup may cause the installer to crash. If that occurs, you may want to try running in different modes:

./installer-name.bin --mode xwindow

or

./installer-name.bin --mode text

In any case, please report the issue so it can be addressed.

The installer seems to take a long time to start. Is this normal?

Are you running the installer from a network or shared drive? This may cause a delay of 20 - 30s when starting the installer.

INSTALLBUILDER

What is the format of the installer project file?

The format of BitRock InstallBuilder project files is XML. This makes it easy to manipulate with scripts and integrate in source control systems. The XML structure of the file and naming of tags has been designed to be human-friendly, meaning that it is easy to edit by hand as well. In fact, many of our customers prefer to do so, especially for complex projects. You can see a sample installer project in the Appendix of the documentation included with the product.

What do you mean by "our installers do not require a self-extraction step"?

Regular single-file installers from our competitors require extracting the contents first, and then installing the software. For big programs, this doubles space requirements in the target system, slows execution and can cause problems if the user does not have enough space in the partition holding the /tmp directory. BitRock installers do not have these issues, allowing for faster startup and installation times.

How can I perform a silent installation?

You can perform a silent installation, using the --mode unattended option from the command line:

This will perform an unattended installation that will not prompt the user for any information. Any required information can be passed to the installer using command line switches. This mode allows for easy integration of the installer into your own scripts.

Unattended mode can also be used to easily integrate with the Ant build tool.

How can I perform a text installation?

The text installation mode is only available on Unix platforms. It will be automatically used if no graphical mode is available (for example, when running the installer on a server without an X-Window installation). You can also force a text-based installation in those platforms using the --mode text option from the command line:

If you use this option in Windows, the installation will be performed in unattended mode.

Do BitRock installers run on Unix servers without X-Window ?

Yes. The best installation method available is automatically detected at startup time. If no X-Window server is detected, the installation will switch to text mode.

Can InstallBuilder create CDROM installers?

Yes, you can create CDROM installers that share files among installers. Select "Multiplatform CDROM" as "Build Platform" in the "Packaging screen" of InstallBuilder. You also have the option of running the installation from the CD automatically.

Are all of BitRock IntallBuilder's features accessible through the GUI?

No, BitRock InstallBuilder does not currently support configuration of all features through the GUI. Actions and custom pages can be added only by manually editing the XML installer project file. A hand-edited project file can safely be imported into the GUI project and your changes will be preserved. The GUI builder tool will eventually include all available features, but most of our customers creating complex installers tell us they actually prefer editing the XML files by hand.

Do BitRock installer project files support development with version control systems?

Yes, the XML-based project file format enables source control integration, collaborative development and customizing projects both by hand and using external scripts.

Can BitRock InstallBuilder generate installers from the command line?

Yes, BitRock InstallBuilder has a command line interface that allows you to automate and integrate installer creation with your own build process. If you want to build installers from the command line for different platforms, use:

You can specify the target platform to build the installer for. This allows you to generate installers for all platforms from a single build environment. For example, you can generate a Windows installer while running on Linux with the following command line:

You can specify any of the following values for platform: linux, windows, osx, solaris-sparc, solaris-intel, linux-x64, linux-ia64, linux-ppc, linux-s390, freebsd5, freebsd6, freebsd, freebsd4, openbsd3, hpux, aix, irix-n32, and cdrom.

What is the difference between RPM packages and BitRock installers?

BitRock installers serve a different purpose than RPMs. RPMs are designed and optimized to package applications for a particular distribution. BitRock Installers are designed to allow the same software package to be installed across all Linux distributions.

Additionally, RPMs do not allow interaction with the end-user and require root privileges to install any kind of application. BitRock installers allow full interaction with the end-user in graphical, text and unattended modes.

There are scenarios where integration with the underlying package management system can be desirable. BitRock can provide support for generating RPM installers from a BitRock XML project file and integrating with the RPM database at installation time. Please email us if you are interested in these capabilities.

What dependencies do BitRock installers have?

BitRock installers are self-contained binary executables files with no external dependencies.

Which platforms do BitRock installers support?

BitRock InstallBuilder can generate native installers that run on virtually all platforms in use today:

• Windows: Windows 98, ME, 2000, XP, 2003, Vista (x86, x64)
• Mac OS X: 10.2, 10.3, 10.4 (ppc and x86)
• Linux: x86, x64, ia64 (itanium), s390, ppc
• Solaris: 8, 9, 10 (x86 and sparc)
• AIX: 4.3, 5.x
• HP-UX: v11 and later (pa-risc, ia64)
• IRIX: 6.5
• FreeBSD: 4, 5, 6 (x86)
• OpenBSD: 3.x (x86)

Please contact us if you need additional platform support.

Does the use of forward slashes and backslashes in paths make any difference?

Yes, it does. Because there are differences in how paths are specified on Windows and Unix, we recommend the use of forward slashes instead of backslashes to avoid compatibility issues if you are planning to share the same project file among multiple platforms.

What does the "save relative paths" option mean?

It means that absolute paths specified in the installer project file will be relativized when saving. The paths will be relative to the location of the project file. This is especially useful when the same project file is shared by multiple developers on different machines or when using the same project file on Windows and Unix (because of the differences in how paths are specified on each platform).

The Readme/License file I want to include in my installer is in html, how can I show it to the user?

You cannot use html files directly as Readme or License files because their content has to be displayed in multiples modes, including text. On Unix, you can easily convert your html file into text using:

Does the same project.xml work across all platforms InstallBuilder supports?

Yes, but because of the differences in how paths are specified on each platform, if you share the same project.xml among different platform, you have to activate the "save relative paths" option.

How do I specify a different default installation directory for Unix and Windows?

Let's say you want to use c:\myapp-4.0 for Windows and /usr/local/myapp-4.0 for Unix as the default installation directory.

In InstallBuilder, go to "Customization" screen and then to the "Installer" tab. Specify /usr/local/${product_shortname}-${product_version} as Installation Directory and Save the project.xml file. Now edit your project.xml file with your favorite text editor and replace the line <preInstallationActionList/> with this code:

  <preInstallationActionList>
    <setInstallerVariable>
      <name>installdir</name>
        <value>${env(SYSTEMDRIVE)}/${product_shortname}- 
 ${product_version}</value>
        <ruleList>
          <compareText>
            <text>${platform_name}</text>
            <logic>equals</logic>
            <value>windows</value>
            </compareText>
        </ruleList>
    </setInstallerVariable>
  </preInstallationActionList>

Remember that if you choose /usr/local as the destination for your application you have to require that the installation is performed as the root user.

${product_shortname} and ${product_version} are installer variables. You can find the complete list of the default installer variables available and their meaning in the product documentation included with InstallBuilder.

How can I create an update installer?

You can create an update installer using the tag like in the following example:

<installationType>update</installationType>

What's the difference between an update installation and a regular installation?

The difference between using <installationType>normal</installationType> and <installationType>update</installationType> is that with second type no uninstaller will be created and on windows, no Start menu group will be either created.

How can I set the directory where installer generated are placed?

<outputDirectory>/home/user/myInstallers</outputDirectory>

Can I convert a filename or directory path from Windows format to Unix format?

Yes. In order to avoid compatibility issues, we recommend that you always use forward slashes, rather than backslashes, in your paths.

How can I register my application with the RPM database?

To enable RPM support add <registerWithPackageDatabase>1</registerWithPackageDatabase> to your project file. This will register your installation with the RPM database and allow you to query, uninstall, etc. your application using the rpm command line tool. You will need to install as root in an RPM based distribution for this to work, otherwise the setting will be ignored.

To successfully register an RPM, the following tags must be also present in the XML project file:

   <vendor>
   <summary>
   <release>
   <description>

Does InstallBuilder support component selection?

Yes. To specify different components, you have to add <allowComponentSelection>1</allowComponentSelection> to your project.xml. Then, you can add different components inside the componentList section of your installer project file. The components defined will be shown to the user. For example, you may use:

<componentList>
       <component>
           <name>default</name>
           <description>My Application</description>
           <canBeEdited>1</canBeEdited>
           <detailedDescription>My application detailed description 
 </detailedDescription>
           <selected>1</selected>
           <show>1</show>
           <folderList>
                   .....
           </folderList>
        </component>

        <component>
           <name>database</name>
           <description>Database application</description>
           <canBeEdited>1</canBeEdited>
           <detailedDescription>Detailed database description 
 </detailedDescription>
           <selected>0</selected>
           <show>1</show>
           <folderList>
              ......
           </folderList>
        </component>
 </componentList>

Is there a command line option for component selection?

You can enable/disable components from the command line using the following options:

--enable-components name1,name2,name3 --disable-components name1,name2,name3

where name1, name2,... are the names inside the <name> tag of components. Component names are case sensitive.

How can I determine if a component has been selected?

It is often necessary to determine whether a component has been selected in order to show additional pages or execute certain actions. You can do accessing a special variable: ${component(componentname).selected}

You will need to substitute componentname with the specific component's name

How can I log a message to the installation log?

You can add your own messages to the instalation log using the <logMessage> action. This can be useful when debugging your installation

<logMessage text="Value of hostname is ${hostname}" />

Is there a log file of the installation?

JAVA(tm) SUPPORT

What are the advantages of BitRock multiplatform installers over Java(tm)-based multiplatform installers?

Java(tm)-based installers require either a JVM on the target system, or bundling a JVM with the installer. If your application is not Java(tm)-based, you will need to add the JVM to run the installer (even though your application itself does not require it.) That means more than 14Mb overhead on average.

Additionally, you may not have control over the JVM installed by the user. This can create multiple installation issues due to incompatibilities.

Finally, all of our installers provide native look-and-feel and integration for all supported platforms, providing an excellent end-user experience.

Are BitRock installers suitable to distribute Java(tm)-based applications?

Yes! In fact, more than 50% of our clients use InstallBuilder to distribute Java(tm)-based applications. BitRock InstallBuilder includes a set of features specifically designed for Java(tm) developers such as JVM autodetection.

Can the Java autodetection just warn the user instead of aborting if there is not a JVM present?

If you do not want the autodetection action to exit after throwing an error, you can just add:

             <abortOnError>0</abortOnError>

inside the <autodetectJava> action tag. If you want to throw your own custom message, you can also add a <customErrorMessage> tag.

Alternatively, you can add a <showMessageOnError>0</showMessageOnError> so it will fail silently and then, later in the installer you can show a specific installation page or issue a custom <showWarning> action based on the presence of the environment java_version.

LICENSING

I have an Open Source project, can I use InstallBuilder for free?

Yes, we offer free, full-featured licenses for open source projects that meet the following requirements:

• Comply the Open Source Initiative definition of Open Source.
• The license can only be used to build installers for the specific project it is licensed to.
• The license cannot be transferred or used for commercial purposes.

Please contact us at info@bitrock.com if you are interested in using our installers for your open source project.

Is there a discount for license renewals?

Yes, there is a 50% discount on renewals made within 30 days of the expiration of a license.

My licensed version of InstallBuilder is working well for me. Do I need to renew the license?

No, you do not have to renew your license if you are happy with your current version. We are constantly adding new features to InstallBuilder, though, so we recommend that you renew your license so that you can take advantage of new functionality added after your license expires. An active license also entitles you to keep receiving support and bugfixes.

INSTALLER ENVIRONMENT VARIABLES

What do ${installdir}, ${full_productname} and all the other installer environment variables mean?

By default, BitRock installers use a set of installer environment variables. These variables contain data for the installation project that will be substituted for their values at runtime.

You can set and read all of the installation parameters using installer environment variables. For example, if you display the following text in one of the installer's page:

The software will be installed in ${installdir}

if the user selects "/opt/installbuilder" as the installation directory, then the text will be rendered as :

The software will be installed in /opt/installbuilder

You can find the complete list of the default installer environment variables and their meaning in the Advanced Functionality section of the product documentation included with InstallBuilder.

Installer environment variables are not related to the system environment variables. Those can be accessed using the ${env(varname)} construct, as explained below.

How can I access system environment variables?

You can access any system environment variable using the ${env(varname)} construct, where varname is the name of a system environment variable. For example, on Windows you can refer to the system drive with ${env(SYSTEMDRIVE)} and in Unix to the user home directory with ${env(HOME)}

Are installer environment variables case sensitive?

No, installer environment variables are not case sensitive. You can access the value of the installdir installer environment variable using either ${installdir} or ${INSTALLDIR}.

Inside my Windows post-installation script I do cd ${installdir} but it is not working. Why is that?

If the installation directory is in a different drive that the one the installer file is you need to use:

cd /s ${installdir}

How can I create my own installer environment variables?

You can create custom environment installer variables using a <setInstallerVariable> action. For example:

           <setInstallerVariable>
               <name>serverport</name>
               <value>3306</value>
           </setInstallerVariable>

The code above will create an installer environment variable called serverport, which can later be referred to as ${serverport}. Wherever it appears, it will be substituted for its value during installation.

SHORTCUTS AND START MENU

The installer I have built creates a shortcut in my desktop, but it does not show the right icon image. How do I fix that?

Check that the icon is pointing to the correct image file. The image may be present in your system, but not be referenced correctly.

The shortcuts work fine in my system, but do not work or do not display an image when installed in a different system.

This is likely to be happening because you hardcode the path to the image or executable to the location of the files in your system, and do not include those files as part of your installation.

Make sure you include the file the shortcut points to and the image or icon the shortcut is using as part of your installation. Make sure they are referenced as ${installdir}/path/to/image.png so the right path is specified once installed. On Unix, make sure also that if the target is an executable, it has the right permissions (chmod +x filename).

On Linux, the installer I have built creates a shortcut in my desktop and points to the right file, but it still does not work. The script works fine from the command line.

It may be that your script requires a specific working directory. If you find this issue, you can try passing the working directory to the script, and cd into it before running. As exec argument when creating the shortcut put :

${installdir}/example

Then, inside script add the following line at the beginning, after #!/bin/sh:

cd $1

That will cd into the correct directory before executing the rest of the script.

I made some changes to my installer but QuickBuild does not seem to include the changes. How do I update it?

You can use the QuickBuild button to avoid rebuilding an installer from scratch if you are just making changes to installer-specific settings, such as: license and readme file, default installation path, logo image, installation required by root, product name and version, and so on. Those settings will be updated without having to pack every product file again.

You will need to follow the normal build process if you make changes to the product files themselves (the ones you added in the Files screen.)

The QuickBuild feature is intended to make interactive development of installers easier, especially of large installers containing many files. When creating installers for release to others, you should use always use the regular build function.

How do I change the location or name of the uninstaller?

Sometimes, it is desirable to change the name or location of the uninstaller, for example to avoid it from being overwritten if two different products are installed in the same base directory. You can use the uninstallerName and uninstallerDirectory tags for this purpose.

       <uninstallerDirectory>${installdir}/subdir</uninstallerDirectory>
       <uninstallerName>myuninstaller</uninstallerName>

I changed the location of the uninstaller in the customization screen, and now the shortcut in the start menu does not work. How do I fix this?

When creating a new project, InstallBuilder automatically created an uninstallation shortcut. If you change the location of the uninstaller, you must remember to also change the path to the uninstaller inside this shortcut.

How can I prevent the installer from creating a Start Menu?

You can avoid creating a Start Menu group by creating an empty one:

       <startMenuGroupName></startMenuGroupName>

USER INPUT AND CUSTOM INSTALLER PAGES

What input can I ask the user for during installation?

You can ask the user:

• for a password using a passwordParameter as explained here.
• for a text string using a stringParameter as explained here.
• or a file location using a fileParameter as explained here.
• for a directory path using a directoryParameter as explained here.
• to choose among of list of options using a choiceParameter as explained here.
• to answer a yes/no question using a booleanParameter as explained here.

You can also validate user input using a validationActionList as explained here.

Can InstallBuilder be customized with new installer pages?

Yes! You can specify required inputs by adding new parameters to the <parameterList> section in the project file. There are different kind of parameters to ask the user for a string, a file, yes/no questions, and so on. Each one of this parameters will in turn be represented appropriately in each of the installation modes. For example, a yes/no question will be presented in the GUI interface as a couple of radiobuttons and in the text interface as a text prompt [y/n] question. The installer will also create corresponding command line options for each one of the defined parameters.

How can I make the installer ask the user for a password during installation?

You can ask the user for a password during installation using a password parameter. You will have to include a section like the one below inside the parameterList section of your XML installer project file.

       <passwordParameter>
           <name>anonpasswd</name>
           <title>Title of my password page</title>
           <description>Please specify a password</description>
           <descriptionRetype>Retype the password</descriptionRetype>
           <explanation>Text to explain what the 
 password will be used for</explanation>
           <ask>yes</ask>
           <width>40</width>
       </passwordParameter>

Click here to download a sample project.xml file that integrates this functionality.

How do I request a text string from the user?

You can request a text string from the user during installation using a string parameter. You will have to include a section like the one below inside the parameterList section of your xml installer project file.

   <stringParameter>
     <name>hostname</name>
     <default>localhost</default>
     <title>Application Server</title>
     <value></value>
     <ask>1</ask>
     <description>Hostname</description>
     <explanation>Please enter the hostname for 
 your application server.</explanation>
   </stringParameter>

This will create an installer environment variable called hostname that will contain the string introduced by the user. You can later refer to the value of that variable using ${hostname}.

Click here to download a sample project.xml file that integrates this functionality.

How can I direct the installer to ask the user to enter a file or directory?

You can direct the installer to ask the user to enter a file or directory using a file or directory parameter. You will have to include a section like the following inside the parameterList section of your installer project file.

    <directoryParameter>
           <name>mydir</name>
           <value></value>
           <title>Title for you directory page</title>
           <description>Some Directory</description>
           <explanation>Please specify the directory requested</explanation>
           <default></default>
           <cliOptionName>prefix</cliOptionName>
           <ask>yes</ask>
           <mustBeWritable>yes</mustBeWritable>
    </directoryParameter>

This will create an installer environment variable called mydir that will contain the directory or file introduced by the user. You can later refer to the value of the variable using ${mydir}.

Click here to download a sample project.xml file that integrates this functionality.

How do I ask the user for more than one parameter in the same screen?

You can ask for multiple parameters in the same screen using a parameterGroup parameter, as shown in the example. 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>

How can I arrange parameters horizontally?

You can do so setting the orientation property of a parameter group to "horizontal" as shown in the example. This functionality is available only in InstallBuilder 4.2.0 and later.

    <parameterGroup>
        <name>server</name>
        <title>Server Data</title>
        <explanation>Please provide the server information</explanation>
        <orientation>horizontal</orientation>
        <parameterList>
            <stringParameter>
                <name>address</name>
                <description>Address</description>
                <value>127.0.0.1</value>
        <width>20</width>
            </stringParameter>
            <stringParameter>
                <name>port</name>
                <description>Port</description>
            <width>4</width>
                <value>80</value>
            </stringParameter>
        </parameterList>
    </parameterGroup>

How do I make the installer ask the user a yes/no question?

You can make the installer ask the user a yes/no question using a boolean parameter. You will have to include a section like the one below inside the parameterList section of your XML installer project file.

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

This will create an installer environment variable called createdb that will contain the value "1" if the user answered "yes" or the value "0" if the user answered "no" to the question. You can later refer to the content of the variable using ${createdb}.

Click here to download a sample project.xml file that integrates this functionality.

How do I display a read-only text information page to the user?

You can display a read-only text information page to the user using an info parameter. You will have to include a section like the one below inside the parameterList section of your XML installer project file.

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

This will create an installer environment variable called serverinfo that will contain the text displayed. You can later refer to the content of the variable using ${serverinfo}.

Click here to download a sample project.xml file that integrates this functionality.

How can I direct the user to select a value among a predefined list?

You can direct the user to select a value among a predefined list of values using a choice parameter. You will have to include a section like the one below inside the parameterList section of your XML installer project file. In GUI mode, it will be represented by a combobox. In text mode the user will be presented with a list.

<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>
       </option>
       <option>
         <value>https</value>
         <text>HTTPS (secure)</text>
       </option>
     </optionList>
</choiceParameter> 

This will create an installer environment variable called protocol that will contain the value of the text selected by the user. You can later refer to the content of the that variable using ${protocol}. In this example, if the user selects HTTP (unsecure), the variable protocol will contain the value http.

Click here to download a sample project.xml file that integrates this functionality.

How can I validate user input?

You can validate user input adding a <validationActionList> to the parameter, as explained here.

For example, adding the following code to the 'installdir' parameter, will prevent the user from selecting a directory that contains a space.

<validationActionList>
   <throwError>
      <text>This directory path can not contain spaces</text>
      <ruleList>
         <compareText>
          <text>${installdir}</text>
          <logic>contains</logic>
          <value> </value>
         </compareText>
      </ruleList>
   </throwError>
</validationActionList> 

This will create an installer environment variable called protocol that will contain the value of the text selected by the user. You can later refer to the content of the that variable using ${protocol}. In this example, if the user selects HTTP (unsecure), the variable protocol will contain the value http.

Click here to download a sample project.xml file that integrates this functionality.

What does the tag inside a parameter section mean?

<cliOptionName> stands for Command Line Interface Option Name. You can use it to pass the value of that parameter to the installer using the text or the unattended mode. For example, if you have defined a parameter like:

   <stringParameter>
       <name>hostname</name>
       <cliOptionName>host</cliOptionName>
       <default>localhost</default>
       <title>Application Server</title>
       <value></value>
       <ask>1</ask>
       <description>Hostname</description>
       <explanation>Please enter the hostname for your 
 application server.</explanation>
   </stringParameter>

$ sample-1.0-installer.bin --mode unattended --host myhostname

If no <cliOptionName> tag is defined, you can use the name of the parameter directly.

How can I show images while my product is being installed?

You can show images during installation using the <slideShowImageList> section as in the following example:

    <slideShowImageList>
       <slideShowImage><path>image1.png</path></slideShowImage>
       <slideShowImage><path>image2.png</path></slideShowImage>
       <slideShowImage><path>image3.png</path></slideShowImage>
       <slideShowImage><path>image4.png</path></slideShowImage>
    </slideShowImageList>

How can I show custom pages after installation has finished?

Sometimes it is desirable to show additional pages after installation has finished and before the final page is displayed. You can do so by adding the following to the appropriate parameter section:

<insertAfter>installation</insertAfter>

ACTIONS

How do I make the installer perform a string substitution as part of the installation?

You can perform string substitutions with the substitution action. This action allows you to specify pattern/value pairs that will be substituted in certain files. It takes a list of glob file patterns separated by ';' and a list of the pattern/value pairs.

           <substitute>
             <files>*/launcher/launchMyJavaApp.sh;*/bin/*.sh</files>
             <substitutionList>
               <substitution>
                 <pattern>@@INSTALLDIR@@</pattern>
                 <value>${installdir}</value>
               </substitution>
               <substitution>
                 <pattern>@@JAVADIR@@</pattern>
                 <value>${installdir}/jre</value>
               </substitution>
             </substitutionList>
           </substitute>

Suppose the user sets /home/user/application as installdir and the original launchMyJavaApp.sh looked like:

#!/bin/sh
export MYAPPDIR=@@INSTALLDIR@@
@@JAVADIR@@/bin/java com.some.class.Name

Then the script will look like the following after installation:

#!/bin/sh
export MYAPPDIR=/home/user/application
/home/user/application/jre/bin/java com.some.class.Name

Click here to download a sample project.xml file that integrates this functionality.

You can find more information about this action in Actions section of the product documentation included with InstallBuilder.

How can I make the installer convert my plain text files in DOS format to Unix format?

Sometimes your installer will bundle text files with different end-of-line characters than the platform you are installing to understands

You can convert plain text files in DOS/MAC format to Unix format with the dos2unix action.

      <dos2unix>
         <files>*/*.sql;*/*.sh;*.ascii</files>
      </dos2unix>

Click here to download a sample project.xml file that integrates this functionality.

You can find more information about this action in the Unix manual page for the dos2unix command.

How do I set Unix permissions for some files and directories?

You can set Unix permissions for some files or directories using changePermissions action. You will have to include a section like the one below inside an action list section of your XML installer project file.

           <changePermissions>
              <files>*/*.sh;*/*.bin</files>
              <permissions>755</permissions>
           </changePermissions>

The permissions are expressed in octal format. Please see the chmod manual page for details on how permissions work in Unix.

By default, when building an installer on a Unix platform, the installer will preserve the permissions of the files being packed, so the above will not be necessary in most cases.

Click here to download a sample project.xml file that integrates this functionality.

How do I create a new system environment variable?

You can create a system environment variable using a addEnvironmentVariable action. You will have to include a section like the one below inside an action list section of your XML installer project file. On Unix platforms, the variable will be added to any of the shell configuration files: ~/.bashrc, ~/.profile. On Windows, the environment variable will be created in the registry.

           <addEnvironmentVariable>
                 <name>MYAPP_HOME</name>
                 <value>${installdir}</value>
           </addEnvironmentVariable>

Note that in Unix, the effect will not take place until the user logs in again.

Click here to download a sample project.xml file that integrates this functionality.

How do I add a directory to the system PATH?

You can add a directory to the system PATH using an addDirectoryToPath action. You will have to include a section like the one below inside an action list section of your XML installer project file. On Unix platforms, the value will be added to the PATH definition in the shell configuration files: ~/.bashrc, ~/.profile. On Windows, the environment variable will be created in the registry.

           <addDirectoryToPath>
              <path>${installdir}/bin</path>
           </addDirectoryToPath>

Click here to download a sample project.xml file that integrates this functionality.

How do I remove a directory from the system PATH?

You can remove a directory from the system PATH using a removeDirectoryFromPath action. You will have to include a section like the one below inside an action list section of your XML installer project file, usually the postUninstallationActionList section. On Unix platforms, the directory will be added to the PATH definition in the shell configuration files: ~/.bashrc, ~/.profile. On Windows, the environment variable will be created in the registry.

       <removeDirectoryFromPath>
          <path>${installdir}/bin</path>
       </removeDirectoryFromPath>

I want to append a certain text at the end of a file. How can I do this?

You can append text at the end of a file using an addTextToFile action. You will have to include a section like the one below inside an action list section of your XML installer project file.

          <addTextToFile>
              <file>${installdir}/bin/environment.sh</file>
              <text>export JAVA_HOME=${installdir}/jre
              export PATH=$JAVA_HOME/bin:$PATH</text>
          </addTextToFile>

Click here to download a sample project.xml file that integrates this functionality.

How do I make the installer display an error message to the user under certain circumstances?

You can make the installer display an error message to the user if certain conditions are met using a throwError action. Those conditions are expressed by rules as explained in the conditional evaluation chapter of the product documentation included with InstallBuilder.

If used inside a parameter <validationActionList> section, an error message will be displayed to the user and the user will be prompted again for the required information.

If used in any other action list section, such as <preInstallationActionList>, it will display an error message to the user and the application will exit.

The following example code, when placed in <preInstallationActionList> will throw an error and abort the installation if the Apache configuration file is not writable by the current user:

           <throwError>
              <text>The Apache configuration file is not writable by 
 the current user</text>
              <ruleList>
                <fileTest>
                  <path>/usr/local/apache/conf/httpd.conf</path>
                  <condition>not_writable</condition>
                </fileTest>
              </ruleList>
           </throwError>

Click here to download a sample project.xml file that integrates this functionality.

Can the installer autodetect if there is an existing Java(tm) installation in the system?

Yes, you can make the installer autodetect whether or not there is an existing Java(tm) installation in the system by using an <autodetectJava> action. If a suitable Java(tm) is found, the action will also create a number of variables, described later on. This action is usually placed at the <preInstallationActionList> and if no valid JRE or JDK is found, the installer will abort with an error listing the supported JREs and JDKs.

The following example will select any Sun Microsystems JRE 1.3 or newer (for example, 1.3, 1.4, 1.5) or any IBM JRE with version number equal or greater than 1.4.2 but inside the 1.4 series (1.5 will not work at this time).

           <autodetectJava>
             <validVersionList>
               <validVersion>
                 <vendor>sun</vendor>
                 <minVersion>1.4.2</minVersion>
                 <maxVersion>1.4</maxVersion>
               </validVersion>
               <validVersion>
                 <vendor>ibm</vendor>
                 <minVersion>1.3</minVersion>
                 <maxVersion></maxVersion>
               </validVersion>
             </validVersionList>
           </autodetectJava>

Each element in the <validVersionList> contains the following fields:

• vendor: sun (to allow only Sun Microsystems JREs,) ibm (to allow only IBM JREs) or empty (to allow any JRE.)
• minVersion:Minimum supported version of the JRE. Leave empty to not require a minimum version.
• maxVersion: Maximum supported version of the JRE. Leave empty to not require a maximum version. If specified only with major and minimum version numbers then it will match any number in the series. For example, 1.4 will match any 1.4.x version (1.4.1, 1.4.2, ...) but not a 1.5 series JRE.
• requireJDK: Whether to require that the Java(tm) installation needs to be a JDK. By default, it is set to 0 so either a JDK or JRE will work.

Upon successful autodetection, the following installer variables will be created :

• ${java_executable}: Path to the java(tm) command line binary (java.exe in Windows). For example /usr/bin/java, C:\Program Files\Java\j2re1.4.2_03\java.exe.
• ${java_version}: For example, 1.4.2_03
• ${java_version_major}: For example, 1.4
• ${java_vendor}: sun or ibm.

Click here to download a sample project.xml file that integrates this functionality.

What if I want the user to select the JVM to use?

You can do that by adding <promptUser> to the above example as shown below.

           <autodetectJava>
             <validVersionList>
               <validVersion>
                 <vendor>sun</vendor>
                 <minVersion>1.4.2</minVersion>
                 <maxVersion>1.4</maxVersion>
               </validVersion>
               <validVersion>
                 <vendor>ibm</vendor>
                 <minVersion>1.3</minVersion>
                 <maxVersion></maxVersion>
               </validVersion>
             </validVersionList>
             <promptUser>1</promptUser>
           </autodetectJava>

Click here to download a sample project.xml file that integrates this functionality.

How can I create a new Windows registry key or modify the value of an existing one?

You can create a new registry key or modify the value of an existing registry key using a <registrySet> action. You will have to include a section like the one below inside an action list section of your XML installer project file.

<registrySet>
 <key>HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\ 
 Control\Session Manager\Environment</key>
 <name>MY_APPDIR</name>
 <value>${installdir}</value>
</registrySet>

Click here to download a sample project.xml file that integrates this functionality.

How can I read and store the value of a Windows registry key in an installer variable?

You can store the value of a registry key in an installer variable using a <registryGet> action. If the key or name does not exist, then the variable created will be empty. You will have to include a section like the one below inside an action list section of your XML installer project file.

<registryGet>
 <variable>installdir</variable>
 <key>HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet 
 \Control\Session Manager\Environment</key>
 <name>MY_APPDIR</name>
</registryGet>

Click here to download a sample project.xml file that integrates this functionality.

How can I delete a Windows registry key?

You can delete a registry key using a <registryDelete> action. If the key to delete does not exist, the action will be ignored. You will have to include a section like the one below inside an action list section of your XML installer project file.

<registryDelete>
 <key>HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet 
 \Control\Session Manager\Environment</key>
 <name>MY_APPDIR</name>
</registryDelete>

Click here to download a sample project.xml file that integrates this functionality.

I need to change the owner and group of a file or directory in Unix. How do I do this?

You can change the owner and group of a file or directory using a <changeOwnerAndGroup> action. Because these changes require administrative privileges, you will need to require installation by the administrator. You will have to include a section like the one below inside an action list section of your XML installer project file.

           <changeOwnerAndGroup>
               <files>*/somefile.conf;*/var/somefile</files>
               <owner>nobody</owner>
               <group>nobody</group>
           </changeOwnerAndGroup>

Click here to download a sample project.xml file that integrates this functionality.

How can I create a symbolic link?

You can create a symbolic link using a <createSymbolicLink> action. You will have to include a section like the one below inside an action list section of your XML installer project file.

           <createSymLink>
               <linkName>${installdir}/bin/somelinkname</linkName>
               <target>${installdir}/bin/somefile</target>
           </createSymLink>

Click here to download a sample project.xml file that integrates this functionality.

How can I capture the output of a script?

You can create or set the value of an installer variable from the output of a script or program using a <setInstallerVariableFromScriptOutput>. You will have to include a section like the one below inside an action list section of your XML installer project file.

           <setInstallerVariableFromScriptOutput>
               <name>myhostname</name>
               <exec>hostname</exec>
               <execArgs>-f</execArgs>
           </setInstallerVariableFromScriptOutput>

That code will create an installer environment variable called myhostname that will store the output thrown by the program hostname. You can later refer to the content of that variable using ${myhostname}.

Click here to download a sample project.xml file that integrates this functionality.

I need to run a program as part of the installation of my application. Can I do this with BitRock InstallBuilder?

Yes, you can run a program as part of the installation of your application with InstallBuilder by using a <runProgram> action. You will have to include a section like the one below inside an action list section of your XML installer project file.

          <runProgram>
              <program>${installdir}/utils/scripts/init_db.bat</program>
              <programArguments></programArguments>
          </runProgram>

Click here to download a sample project.xml file that integrates this functionality.

Can I group certain actions together?

You can make the installer perform certain actions based on a set of rules using an <actionGroup> section. This will execute more than one action based on the same set of rules. See the conditional evaluation section in the documentation for details on rule-based execution of actions.

You will have to include a section like the one below inside an action list section of your XML installer project file.

          <actionGroup>
              <actionList>
              <setInstallerVariable>
                  <name>installapache</name>
                  <value>1</value>
              </setInstallerVariable>
              <setInstallerVariable>
                  <name>installtomcat</name>
                  <value>1</value>
              </setInstallerVariable>
              </actionList>
              <ruleList>
                 <compareText>
                     <text>${installtype}</text>
                     <logic>equals</logic>
                     <value>server</value>
                 </compareText>
              </ruleList>
          </actionGroup>

Click here to download a sample project.xml file that integrates this functionality.

What is a rule list?

With rule lists you can control whether certain actions take place, pages are shown or files are installed.

Rule lists can be included in action, parameter and folder sections. Each <ruleList> contains a set of rules or conditions that are evaluated, and depending on the result, the action is executed, the page associated with the parameter shown or the folder installed.

Which logic operands do rule lists support?

There are two logic operands rules: and, or. Those operand have to be specified in a <ruleEvaluationLogic> section. <ruleEvaluationLogic> sections can be used inside action, parameter or folder sections. By default, rules are evaluated with 'and' logic.

What are the components of a ruleList?

Each ruleList can contain one or more <compareText>, <fileTest> or <fileContentTest> sections.

<compareText> text comparison rules can contain three fields :

• text: The text to apply the logic comparison to; usually the value of an installer or environment variable.
• logic: One of equals, contains, does_not_contain or does_not_equal.
• value: The value that the text will be compared with.

Example:

    <compareText>
        <text>${server}</text>
        <logic>equals</logic>
        <value>Apache</value>
    </compareText> 

<fileTest> file testing rules contain two fields :

• path: The path to the file to test.

• condition: One of exists, not_exists, writable, not_writable, readable, not_readable, executable, not_executable, is_directory, is_not_directory, is_file, is_not_file, is_empty, is_not_empty.

Example:

    <fileTest>
        <path>/usr/bin/perl</path>
        <condition>executable</condition>
    </fileTest>

<fileContentTest> file content testing rules contain three fields :

• path: The path to the file to test.
• logic: One of contains, does_not_contain
• text: The text to apply the logic comparison to, usually the value of an installer or environment variable.

Example:

    <fileContentTest>
        <path>/etc/group</path>
        <logic>contains</logic>
        <text>apache</text>
    </fileContentTest>

How can I run a program only if certain conditions are met?

The following example shows how a particular script will be executed only if the installation type is 'server', it is running on Linux and a certain file is not already present in the system. The value for the installation type was set during the installation process using a user-defined parameter, as explained earlier in this document.

<runProgram>
    <ruleEvaluationLogic>and</ruleEvaluationLogic>
        <ruleList>
            <compareText>
                <text>${installtype}</text>
                <logic>equals</logic>
                <value>server</value>
            </compareText>
            <compareText>
                <text>${platform_name}</text>
                <logic>equals</logic>
                <value>linux</value>
            </compareText>
            <fileTest>
                <path>/etc/init.d/myservice</path>
                <condition>not_exists</condition>
            </fileTest>
        </ruleList>
     <program>${installdir}/bin/install_service.sh</program>
</runProgram>

Click here to download a sample project.xml file that integrates this functionality.

How can I find out how much free disk space is available for my application?

You can view the free disk space available for your application using a <getFreeDiskSpace> action. This action will retrieve the amount of disk space available on the drive partition holding a particular directory. The directory is specified in the 'path' argument and the value (in Kb) will be stored in the variable specified by 'variable'. For example:

<getFreeDiskSpace>
 <variable>diskspace</variable>
 <path>${installdir}</path>
</getFreeDiskSpace>

How can I backup a file or directory as part of my installation?

You can backup a file or directory using a <backupFile> action as in the following example:

<createBackupFile>
  <path>${installdir}/conf/myapp.conf</path>
</createBackupFile>

This action creates a new file or directory, named after the path specified, with the suffix .bak0. If a backup file with that name already exists, it will create a new one ending in .bak1 (or .bak2, etc.)

Can I delete a file or directory as part of my application installation?

Yes. You can delete a file or directory as part of your application installation using a <deleteFile> action as in the following example:

<deleteFile>
  <path>/tmp/mytempfiles*.*</path>
</deleteFile>

How can I copy a file or directory as part of an installation?

You can copy a file or directory as part of an installation using a <copyFile> action as in the following example:

<copyFile>
   <origin>${installdir}/conf/myfile.template</origin>
   <destination>${installdir}/conf/myfile.conf</destination>
</copyFile>

How can I configure the installer to inform the user but not to abort installation after an error is found running an action?

You can configure the installer to inform the user but not cancel installation after an error is found running an action using the and the tags, as shown in the below example.

<runProgram>
    <program>${installdir}/bin/myapp</program>
    <programArguments>argument1 argument2</programArguments>
    <abortOnError>0</abortOnError>
    <showMessageOnError>1</showMessageOnError>
</runProgram>

How can I launch an application in the background from InstallBuilder?

You can launch an application in the background (so InstallBuilder will not wait for it to finish) by adding & as the final argument of the action. If you edit the XML file directly, remember that & needs to be escaped as &amp;. For example:

<finalPageActionList>
  <runProgram>
    <program>${installdir}/bin/myapp</program>
    <programArguments>&amp;</programArguments>
    <progressText>Do you want to launch ${product_fullname} now? 
 </progressText>
  </runProgram>
</finalPageActionList>

How can I rename a file or directory as a part of my installation?

You can rename a file or directory as part of the installation process by using a <renameFile> action, as shown in the following example:

     <renameFile>
       <origin>${installdir}/conf/myfile.template</origin>
       <destination>${installdir}/conf/myfile.conf</destination>
     </renameFile>

What is the difference between an action list and an actionGroup?

An action list is a list of actions that will be executed individually. There are several types of action lists that are executed at different points of the installation.

An actionGroup is a group of actions that will be executed based on a common set of rules.

How can I remove a Windows registry key that has subkeys inside?

You can remove a main Windows registry key using a <registryDelete> action without specifying any <name> and without a final \ in the <key> value. For example:

     <registryDelete>
             <key>HKEY_LOCAL_MACHINE\SOFTWARE\My Software 
 \${product_fullname}\${product_version_short}</key>
     </registryDelete>

How can I restart the computer after installation has completed?

You can add <rebootRequired>1</rebootRequired> to the project XML file and at the end of installation, the installer will ask the user if they want to restart. If they select "yes", the computer will be restarted.

How can I check if a certain TCP/IP port is aready taken?

During installation of certain applications, such as server side softwate, you may want to allow the user to select a TCP/IP port. It is common to check whether that port is already in use or not. You can use the <portTest> rule to do just that, as shown in the example below. The application will not allow the end user to continue unless he chooses a free port. Remember that in Unix systems, root privileges are required to bind to ports less than 1024.

<stringParameter>
<name>tomcatport</name>
<title>HTTP Port</title>
<description>Tomcat HTTP Port</description>
<explanation>Please enter the port for your Tomcat server.</explanation>
<value>8080</value>
<default>8080</default>
<allowEmptyValue>1</allowEmptyValue>
<ask>1</ask>
<cliOptionName></cliOptionName>
<width>40</width>
<validationActionList>
<throwError>
  <text>Unable to bind to the given port number. Please select another one.</text>
  <ruleList>
    <portTest>
      <condition>cannot_bind</condition>
      <port>${tomcatport}</port>
    </portTest>
  </ruleList>
</throwError>
</validationActionList>
</stringParameter>

How can I display a text page at the end of the installation?

When you specify a README file using the GUI builder or the <readmeFile> setting in the project XML, the user will be presented with an option to display it in the final installation page. Starting with version 4.2.0, you will also be able to display text pages using the <showText> action.

How can I display a web page at the end of the installation?

You can use a <launchBrowser> action inside a <finalPageActionList>, as shown in the example below. You can control the text displayed using the <progressText> tag.

<finalPageActionList>
<launchBrowser url="http://example.com/congratulations/"
progressText="Visit Example website." />
</finalPageActionList>

ACTION LIST

Which kind of action lists does BitRock InstallBuilder support?

• preBuildActionList: Actions that will be performed before the installer is built. You can use this list for executing a script that prepares your files to be packed, such as rearranging files, stripping binaries, and so on.
• preInstallationActionList: The actions included in this section will be executed before the installation starts.
• postInstallationActionList: The actions included in this section will be executed after the installation finishes.
• preShowPageActionList: A preShowPageActionList must be included inside a parameter section. The actions included in this section will be performed before showing to the user the corresponding screen.
• preUninstallationActionList: Actions that can be performed before the uninstallation process begins. This is commonly used for example, to stop specific services or shutdown any instances of your software that may be currently running.
• postUninstallationActionList: List of the actions that can be performed once the unistallation has been completed. This is commonly used to clean up any files that are not automatically cleaned up by the uninstaller.
• postShowPageActionList: A postShowPageActionList must be included inside a parameter section. The actions included in this section will be performed right after the user presses 'Next' on that screen.
• actionList: An actionList section must be included inside a folder section. The actions included in this section will be performed after the contents of the folder are copied into the target system.
• validationActionList: This section must be included inside a parameter section. It will be executed after the user presses 'Next' and before the postShowPageActionList. The actions in this list can be used to ensure that the parameter has a valid value. For example, if the user specified a hostname, you may want to check that the hostname resolves to a valid IP address. If any of the actions throws an error, it will be displayed to the user and the user will be prompted to re-enter the information.
• finalPageActionList: This section includes a list of actions to execute after the installation has completed and the final page has been displayed to the user. These actions usually include launching the program just installed, whether a desktop or server application.

How do I direct the installer to perform actions before installation starts?

You can direct the installer to perform actions before installation starts by using the <preInstallationActionList> section. For example, the following code will set a different installation directory depending on the platform the installer is running on.

     <preInstallationActionList>
       <setInstallerVariable>
         <name>installdir</name>
         <value>${env(SYSTEMDRIVE)}/${product_shortname}</value>
         <ruleList>
           <compareText>
            <text>${platform_name}</text>
            <logic>equals</logic>
            <value>windows</value>
           </compareText>
         </ruleList>
       </setInstallerVariable>
       <setInstallerVariable>
         <name>installdir</name>
         <value>/usr/local/${product_shortname}</value>
         <ruleList>
           <compareText>
            <text>${platform_name}</text>
            <logic>equals</logic>
            <value>linux</value>
           </compareText>
         </ruleList>
       </setInstallerVariable>
     </preInstallationActionList>

Click here to download a sample project.xml file that integrates this functionality.

How do I direct the installer to perform actions after installation finishes?

You can direct the installer to perform some actions after installation is complete by using the <postInstallationActionList> section. The following example makes the installer run different scripts at the end of the installatiion process depending on whether or not is the root user who is performing the installation.

     <postInstallationActionList>
       <runProgram>
         <program>${installdir}/scripts/root_script.sh</program>
         <programArguments>${installdir}</programArguments>
         <ruleList>
           <compareText>
            <logic>equals</logic>
            <text>${installer_root_install}</text>
            <value>1</value>
            </compareText>
         </ruleList>
       </runProgram>
       <runProgram>
         <program>${installdir}/scripts/myscript.sh</program>
         <programArguments>${installdir}</programArguments>
         <ruleList>
           <compareText>
            <logic>equals</logic>
            <text>${installer_root_install}</text>
            <value>0</value>
           </compareText>
         </ruleList>
       </runProgram>
     </postInstallationActionList>

Click here to download a sample project.xml file that integrates this functionality.

How do I direct the installer to perform actions before showing a page?

You can direct the installer to perform actions before a page is shown by using a <preShowPageActionList> section. The following example presents the user with information that stored in a registry key under Windows and in an environment variable under Linux.

     <infoParameter>
       <preShowPageActionList>
         <registryGet>
        <variable>some_info</variable>
            <key>HKEY_LOCAL_MACHINESOFTWARE</key>
           <name>MYAPP</name>
           <ruleList>
             <compareText>
              <text>${platform_name}</text>
              <logic>equals</logic>
              <value>windows</value>
             </compareText>
           </ruleList>
        </registryGet>
        <setInstallerVariable>
          <name>some_info</name>
          <value>${env(SOMEINFO)}</value>
          <ruleList>
             <compareText>
              <text>${platform_name}</text>
              <logic>equals</logic>
              <value>linux</value>
             </compareText>
          </ruleList>
         </setInstallerVariable>
       </preShowPageActionList>
       <name>display_info</name>
       <title>License File Information</title>
       <explanation>This screen shows important information 
 about licensing issues</explanation>
       <value>Important Information! Setup has detected 
 the following : ${some_info}.
In the following screen you 
 will be asked to confirm the information or enter a new (...)</value>


     </infoParameter>

How do I direct the installer to perform actions after showing a page?

You can direct the installer to perform actions after a page is shown by using a <postShowPageActionList> section. The following example sets the value of a registry key with the value specified by the user if the installer is running on Windows, and keeps the same information in an environment variable if the installer is running on Linux.

   <fileParameter>
       <name>confirmation</name>
       <value>${mypath}</value>
       <title>Server File Confirmation</title>
       <description>Server file</description>
       <explanation>Please confirm the information showed below 
 or introduce
a new value</explanation>
       <default></default>
       <ask>yes</ask>
       <mustBeWritable>yes</mustBeWritable>
       <postShowPageActionList>
         <registrySet>
        <value>${mypath}</value>
            <key>HKEY_LOCAL_MACHINESOFTWARE</key>
            <name>MYAPP</name>
           <ruleList>
             <compareText>
              <text>${platform_name}</text>
              <logic>equals</logic>
              <value>windows</value>
             </compareText>
           </ruleList>
        </registrySet>
        <setInstallerVariable>
          <name>mypath</name>
          <value>${mypath}</value>
           <ruleList>
             <compareText>
              <text>${platform_name}</text>
              <logic>equals</logic>
              <value>linux</value>
             </compareText>
           </ruleList>
         </setInstallerVariable>
       </postShowPageActionList>
    </fileParameter>

How can I allow the user to start my software from the final installation page?

You can allow the user to start your software in the final installation page using a <runProgram> action inside a <finalPageActionList> as in the following example:

<finalPageActionList>
 <runProgram>
  <program>${installdir}/bin/myprogram</program>
  <programArguments></programArguments>
  <progressText>Do you want to launch ${product_fullname} now?</progressText>
 </runProgram>
</finalPageActionList>

You can also customize the text that will be shown to the user on the final installation page with the <progressText> property. That text will be placed beside a checkbox. The user can choose whether or not to run the application by checking the box.

MULTIPLE LANGUAGE SUPPORT

How can I allow only a limited set of languages for installation?

You can allow only a limited set of languages to be available at installation time by using the <allowedLanguages> tag in the installer project file.

Available languages are Catalan (ca), Gaelic (cy), Spanish (es), French (fr), Dutch (nl), Brazilian-Portuguese (pt_BR), Romanian (ro), Valencian (va), German (de), English (en), Estonian (et), Hungarian (hu), Italian (it), Japanese (jp), Polish (pl), Portuguese-Portugal (pt), Rusiian (ru), Slovenian (sl), Traditional Chinese (zh_TW), Simplified Chinese (zh_CN).

For example, if you want to allow the installation of your application in English, German and Spanish, check that the Allow Language Selection is activated and add this line to your installer project:

         <allowedLanguages>en de es</allowedLanguages>

How can I customize the language used in custom installer pages?

You can customize the language used in custom installer page messages using the <customLanguageList> tag, as in the following example:

<customLanguageFileList>
     <language>
         <code>en</code>
         <encoding>iso8859-1</encoding>
         <file>pathToLanguageFiles/myapp_en.lng</file>
     </language>
     <language>
         <code>de</code>
         <encoding>iso8859-1</encoding>
         <file>pathToLanguageFiles/myapp_de.lng</file>
     </language>
    <language>
         <code>fr</code>
         <encoding>iso8859-1</encoding>
         <file>pathToLanguageFiles/myapp_fr.lng</file>
     </language>
</customLanguageFileList> 

myapp_de.lng should be a text file with a format similar to this:
database.title=Datenbank auswälhen
database.explanation=Standard Datenbanken
datatabase.description=Welche Datenbank?
.....

and myapp_en.lng:
database.title=Database Selection
database.explanation=Default database
datatabase.description=Which database?
.....

and so on with the rest of custom language files.

Then, you can for example create a <choiceParameter> page and use:

<choiceParameter>
   <ask>1</ask>
   <default>oracle</default>
   <description>${msg(database.description)}</description>
   <explanation>${msg(database.explanation)}</explanation>
   <title>${msg(database.title)}</title>
   <name>database</name>
   <optionList>
     <option>
       <value>oracle</value>
       <text>Oracle</text>
     </option>
     <option>
       <value>mysql</value>
       <text>Mysql</text>
     </option>
   </optionList>
</choiceParameter>

LOOK AND FEEL

How can I change the size of the installer screens?

If you need to display many different parameters in the same installation screens, it may be desirable to change the default GUI installer dimensions. You can do so using the <width> and <height> tags.

         <width>600</width>
         <height>400</height>