School of BitRock

InstallBuilder 6.4 Released!

2010-06-14T11:30:00.000-07:00

We just released version 6.4.0 of BitRock InstallBuilder. The new release features the following improvements:

Added support for nested variables
Now all variable references are case insensitive
New <createShortcuts> action
Prevent GUI builder from accepting incorrect values in its dialogs
Added new <while> and <break> actions
New <autodetectDotNetFramework> action
New <locate> action
Added new <zip> action
Added matchHiddenFiles flag to <touchFile>, <copyFile> and <deleteFile> actions
Added OS X support for user and group manipulation actions
Added new built-in variable windows_os_flavor
Allow <foreach> and <if> actions to be accessed through the GUI
Fixed Qt installer abnormaly resizing in "custom" mode
Fixed patterns in folders' inclusion filters not resolved when using backslashes
Allow <showProgressDialog> to display a download progress bar when containing a single <httpGet> child action
Normalize all relative paths to reference project directory in Autoupdate tool
New validation of duplicated project tags
Disabled RPM registration in platforms with non-native RPM support
Increase size of builder project properties dialog
Allow empty user and password to be provided in <addScheduledTask> action
New <runOnlyIfLoggedOn> tag in <addScheduledTask> action
Disable language selection dialog when a value is provided through command line
Allow InstallBuilder license to be saved to and loaded from user personal directory on Windows
Added Japanese string for Installer.DirectorySelection built-in string
Fixed glitch in button states after installation page
Allow task name with spaces in <addScheduledTask> action

Visit installbuilder.bitrock.com to download or to view our changelog.

InstallBuilder 6.3.1 released!

2010-05-06T05:23:00.000-07:00

We recently released version 6.3.1 of InstallBuilder, which includes the following improvements:

New <sha1> action
New <md4> action
New <addDirectoriesToUninstaller> action
Added <password> tag to <addUser> action
Improved <httpProxyInit> to autodetect system proxy settings
Improved RPM integration
Improved Qt look and feel on Windows and OS X
Validate user provided input for parameters while creating them.
Added Windows support for user and group manipulation actions
Fixed <registryDelete> failing to delete keys on Windows 64bit
Documented windows_os_service_pack
Prevent fileTest rule from failing when testing a non-existent link
Fixed autoupdate returning update available when check_for_updates was set to '0'
Fixed Windows 7 not being recognized when Windows 7 Logo Toolkit is installed
Fixed symbolic links not being properly packed when included as <distributionFile>
Fixed variables not being resolved in some Autoupdate project tags.
Fixed error parsing Autoupdate projects containing utf-8 BOM
Built-in registry keys are now created in the 64bit view when <windows64bitMode> is enabled
Fixed Windows 2008 autodetection failing in some environments

Visit installbuilder.bitrock.com to download or to view our changelog.

We're Hiring!

2010-04-21T10:48:00.000-07:00

BitRock is growing and we’re looking for smart, motivated and talented individuals to join our team! The position we’re currently working to fill is for a Stack Engineer. Our Stack Engineers work with clients throughout the world to deliver customized native installers, virtual machine images and cloud templates for their software. These are similar to the software stacks we build for the BitNami project. Stack Engineers also bring new BitNami Stacks to market and keep the current ones up to date. This position provides an excellent opportunity to work with technologies such as Ruby on Rails, PHP, Python, Apache, MySQL and many other Open Source projects across Windows, Linux, OS X and various cloud platforms such as Amazon, Rackspace, GoGrid and OpSource. If you are a distro packager or a sysadmin who likes to automate his or her work, you’ll love this job!

Qualified applicants must be fluent in a scripting language such as Ruby, Python or Tcl, and familiar with common Open Source development tools. Interaction with customers is mostly over email, so the ability to write fluently and communicate effectively in English is a must. A big chunk of the development team is in Spain, so a bit of ‘Spanglish’ would not hurt, either :)

If you’re local (or would like to live in) Seville, Spain, we have an office there ready and waiting for the right candidate. We also have several employees in other countries who work from home, so if you have a home office and are comfortable working remotely, we will be happy to consider your application. To apply, please send your CV along with a letter telling us a little about yourself and why you’d like to join our team to careers@bitrock.com.

DevOps Meetup Tomorrow in Palo Alto

2010-04-20T16:35:00.000-07:00

We're excited to announce the first San Francisco Bay Area DevOps Meetup, happening April 21st at The Old Pro in Palo Alto. If you're not familiar with the term DevOps, take a look at this article, which gives a great explanation.

This first meetup is all about getting to know and networking with your fellow DevOps enthusiasts. We'll be meeting at 7pm to drink beer, eat food, and talk DevOps. We're co-sponsoring the event with DTO Solutions and rPath to make sure there is some tasty food and beer to keep everyone fueled up. We hope you're able to join us!

InstallBuilder 6.3 Released - Localization and Memory Improvements

2010-04-19T15:02:00.000-07:00

We recently released version 6.3.0 of InstallBuilder, which includes a number of improvements, including the ability to include localized license agreements and set the default installation language based on the previous installation. We have also reduced the memory consumption when unpacking large single-file installers. Other InstallBuilder improvements include:

Multiple improvements to CD-ROM installers
Allow HTML license files in Qt mode
New installer_builder_version and installer_builder_timestamp built-in variables
New <httpProxyInit> action to configure proxy to use with http actions
New <xmlFileGet> and <xmlFileSet> actions
New <addScheduledTask> and <deleteScheduledTask> Windows actions
New .password suffix to mask passwords in log messages
Support for osx-intel and osx-pcc in platform test
Add support for FreeBSD 8
Improve the RPM removal process

Visit installbuilder.bitrock.com to download or to view our changelog.

InstallBuilder 6.2.7 Released

2010-01-25T13:37:00.000-08:00

We just released v6.2.7 of InstallBuilder which includes the following improvements:

New <useMSDOSPath> property in <runProgram> action to configure whether to use or not 8.3 format in the <program> path
Added encoding property in <addTextToFile> action and <fileContentTest> rule
New <unix2dos> action
Allow file type filters in <fileParameter> dialogs for xwindow, osx and win32 modes
Include InstallBuilder version by default in the generated installers version info
Fixed error with file selection crashing if third-party Explorer extensions change locale
Fixed unpacking error in some Windows environments due to antivirus software locking files

Check out our changelog and download the latest release to benefit from the new features and bug fixes.

Handling Access Control List on Windows With BitRock InstallBuilder

2010-01-04T09:20:00.000-08:00

Access Control List (ACL) is the way in which Windows manages permissions on NTFS file systems.

There are several command line tools on Windows for handling this: cacls, xcals, icacls. Unfortunately, these tools are not always present in a default Windows installation and depending on the Windows version, different tools may be required.

BitRock InstallBuilder now provides you with <setWindowsACL> built-in actions. This powerful action for managing permissions allows you to modify ACL on Windows. It is based in the icacls windows tool (http://technet.microsoft.com/en-us/library/cc753525(WS.10).aspx).

You can define the files you want to apply the permissions to. It allows you to specify if you want to "allow" or "deny" access. You can also match a list of users for which the permissions will be applied, and to specify any of the allowed permissions types.

You can define the users either using names or SIDs. Please take into account that special users, like "Everyone" are localized so it is a good practice to use SIDs instead for these users. You can find a list of the well known SIDs in this article:

http://support.microsoft.com/kb/243330

The most common file permissions are also detailed below:

http://msdn.microsoft.com/en-us/library/aa364399(VS.85).aspx

http://support.microsoft.com/kb/243330

Note that ACL are only supported on NFTS file systems.

Example 1 - Basic:

The following example will allow all users in the system to read, write and execute the files that match the pattern in <files>. For the directories that match that pattern, the users will be allowed to read the content and write new content in that directory.

<setWindowsACL>
<user>Everyone</users> 
<permissions>file_read_data file_write_data file_execute</permissions>
<files>c:\myfolder\*;c:\myfolder\*\*;c:\myfolder\*\*\*</files>
<action>allow</action>
</setWindowsACL>

Example 2 – Inheritance:

It is also possible to define the inheritance level:

<setWindowsACL>
     <action>deny</action>
     <files>c:\some\folder</files>
     <permissions>file_read_data</permissions>
     <recurseContainers>0</recurseContainers>
     <recurseObjects>0</recurseObjects>
     <recurseOneLevelOnly>0</recurseOneLevelOnly>
     <self>1</self>
     <users>Everyone</users>
</setWindowsACL>

<self> : determines if the objects specified in the <files> tag will be modified or just their children, if the recursion tags are enabled.
<recurseOneLevelOnly> : Only applies inheritance to the first level of hierarchy if one of the below are enabled.
<recurseObjects> : Applies inheritance to objects (files).
<recurseContainers> : Applies inheritance to containers (folders).

Example 3 – Using InstallBuilder GUI:

Of course this action is also available from the InstallBuilder GUI.

How to use Custom Build Targets

2010-01-04T09:16:00.000-08:00

One of the most useful features of InstallBuilder is the ability to automate the build process. Installers can be built from a command line prompt such as:

installbuilder-6.2.6/bin/builder build /path/to/project.xml linux

The above describes the basic command line build process. You can also make changes to the project prior to the build process to adapt it to your needs using the --setvars flag.

In most cases, this is used to modify project properties such as the <version>, the <fullName> or the <windowsExecutableIcon>:

builder build project.xml --setvars version=1.2.3  project.fullName="New Installer Name"

However, there is much more you can achieve using this functionality.

Lets assume we have a complete project, including documentation, some optional applications and a lightweight installer that bundles 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 allows us to separate them into multiple .xml files.

This approach forces us to repeat 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, we 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 we defined buildFlavor as a regular variable instead of creating a hidden parameter, but we would not be able to access it at runtime in that case. We 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>

Additional information can be found in the links below:

How to Integrate InstallBuilder with Apache Ant and Apache Maven

2009-11-10T06:06:00.000-08:00

Apache Ant and Apache Maven are two of the most popular tools for building projects. This article explains how to integrate InstallBuilder with these two tools.

If you use Apache Ant for building your projects, you can include the following section for building your binary installer.

build.xml


<project name="MyProject">
    <exec executable="/home/bitrock/installbuilder-6.2.4/bin/builder">
        <arg line="build /home/bitrock/installbuilder-6.2.4/projects/demo.xml linux"></arg>
    </exec>
</project>

Where the executable tag sets the path of the builder program and the arg tag defines the build process, the location of your InstallBuilder project file and the target platform.

During the build process, you will see something similar to:


Buildfile: build.xml
     [exec]  Building Demo Project linux
     [exec]  0% ______________ 50% ______________ 100%
     [exec]  #########################################
     [exec] 

BUILD SUCCESSFULTotal time: 1 second

If you use Apache Maven for building your projects, you can find below an example of a pom.xml file to build a demo project.

pom.xml


<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.mycompany.app</groupId>
  <artifactId>my-app</artifactId>
  <version>1</version>

  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>exec-maven-plugin</artifactId>
        <version>1.1</version>
        <executions>
          <execution>
            <goals>
              <goal>exec</goal>
            </goals>
          </execution>
        </executions>
        <configuration>
          <executable>/home/bitrock/installbuilder-6.2.4/bin/builder</executable>
          <arguments>
            <argument>build</argument>
            <argument>/home/bitrock/installbuilder-6.2.4/projects/demo.xml</argument>
            <argument>linux</argument>
          </arguments>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

The executable tag contains the path to the builder program and the argument tags describe the build process, the location of your InstallBuilder project file and the platform target.

You can launch the build using the following command:

$ mvn exec:exec


[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Building Unnamed - com.mycompany.app:my-app:jar:1
[INFO]    task-segment: [exec:exec]
[INFO] ------------------------------------------------------------------------
[INFO] [exec:exec {execution: default-cli}]
[INFO]  Building Demo Project linux
[INFO]  0% ______________ 50% ______________ 100%
[INFO]  #########################################
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2 seconds
[INFO] Finished at: Thu Nov 05 11:47:09 CET 2009
[INFO] Final Memory: 3M/64M
[INFO] ------------------------------------------------------------------------

InstallBuilder Action Lists

2009-10-20T00:44:00.000-07:00

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

InstallBuilder actions are organized in what are called action lists, which are executed at specific points of the installation process. It is important to understand how and when each action must be performed, what differences exist between action lists inside components and within the primary installer, how the installer will behave when you run it in different installation modes (GUI, text, or unattended) and what happens when you generate rpm or deb packages.

You can place your action lists in the main installer project or in one of its components. Action lists include your actions of choice and are executed at a specific point of the installation process as outlined below.

BitRock InstallBuilder Action Lists (in order of execution)

BUILDING THE INSTALLER

preBuildActionList
Executes before generating the installer file. These actions usually include setting environment variables or performing some kind of processing on the files that will go into the installer before they are packed into it. For multi-platform CDROM installers, the preBuildActionList is executed once at the beginning of the CDROM build, and then again for every one of the specific platform installers.

postBuildActionList
Executes after generating the installer file. These actions are usually useful to reverse any changes made to the files during the preBuildActionList or to perform additional actions on the generated installer, such as signing it by invoking an external tool. For multi-platform CDROM installers, the postBuildActionList is executed once for every one of the specific platform installers and then it is executed one final time for the whole CDROM build.

INSTALLATION

preShowHelpActionList
Executes before help information is displayed.

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

LANGUAGE SELECTION

preInstallationActionlist
Executes before the first page of the installer is displayed, right after the parsing of the command line options takes place. It is commonly used for setting user-defined installer variables that will be used later on or for detecting a Java (tm) Runtime Environment.

COMPONENTS SELECTION

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

PARAMETER PAGES

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

validationActionList
Executes once the user has specified a value in the user interface page associated with the parameter and has pressed the 'Next' button (or 'Enter' in a text-based interface). The actions can be used to check that the value is valid (for example, that it specifies a path to a valid Perl interpreter). If any of the actions result in an error, an error message will be displayed to the user and the user will be prompted to enter a valid value.

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

postShowPageActionList
Executes after the corresponding parameter page has been displayed. This can be useful for performing actions or setting environment variables based on the value of the parameter.

COPYING FILES

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

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

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

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

finalPageActionlist
Executes after the installation has completed and the final page has been displayed to the user. These actions usually include launching the program that has just been installed. For each one of the actions contained in this list, a checkbox will be displayed (or a question in text mode). If the checkbox is selected, then the action will be executed when the 'Finish' button is pressed. The text displayed can be specified in the property.

UNINSTALLATION

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

postUninstallationActionList
Executes after the uninstallation process takes place.

SPECIAL ACTION LISTS

installationAbortedActionList
Executes when the installation process is aborted.

Order of Execution of Action Lists

Each action list may be included in the main project or inside the components. Lets take an initializationActionList as an example. We have one main initializationActionList and 4 others in the components A, B, C and D. The components are declared following the order A, B, C, D (A is the first entry and D is the last one). In this case, the main initializationActionList is executed first and then each component's action lists are executed (A, B, C, D - the order of component declaration is important).

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

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

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

Unattended mode, RPM and DEB packages

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

componentSelectionValidationActionList

finalPageActionList

Any parameter's validationActionList

Any parameter's preShowPageActionList

Any parameter's postShowPageActionList

The installationAbortedActionList will only be executed if the error was generated by any of the actions performed directly by the installer. If the error is generated during the file installation step, which is performed by the RPM / DEB package manager, the BitRock installer application will not be notified and therefore the installationAbortedActionList will not be executed.

Unattended Mode

2009-10-13T01:08:00.000-07:00

As you may know, installers generated with InstallBuilder provide different execution modes using the command line option "--mode". The mode "unattended" is particularly useful when we need to incorporate installations into an automated process. With this mode, the installer will not prompt the user for any information and will instead take the default settings configured for each of the parameters. That way, it is possible to incorporate the installer execution into scripts since no input is required from the user during the installation.

Note that you are not forced to use only the default values when running the installer in this mode. You can also define the values through command line switches which are generated for each parameter definition inside the InstallBuilder project. If we want to use specific values, we should run the installation as follows:

"$ installer_binary --mode unattended --param1 value1 --param2 value2 ...."

As the number of parameters grows, it may be best to define the options values inside a text file. This is possible using the command line switch "--optionfile <filename>". This will instruct the installer to take the values from the specified file. Here is an example:

"$ installer_binary --mode unattended --optionfile optionfile"

Where optionfile should contain a list of pairs <key>=<value>. For instance:

param1=value1
param2=value2
....

Configuring Unattended Mode Parameters in an Installer

Let's take a look at how you can configure the installer so it behaves as expected in unattended mode and provides the appropriate feedback to the user through "--help".

In order to configure the default values for each parameter, you need to edit the field "default" which appears in the "Main" tab inside parameter window or adding the property "default" to its definition inside the XML file:


<stringParameter>
 <name>port</name>
 <default>8080</default>
</stringParameter>

As mentioned earlier, each parameter will have its own command line option. When the installer is run with the --help option, the whole list of available command line switches is displayed. Each parameter is shown with a message similar to:


--option_name  option_description
   default: option_default_value

The given information can be modified using the properties inside the "Command Line" tab in the parameter window or adding the properties "cliOptionName", "cliOptionText" and "cliOptionShow" to its definition in the XML file:

option_name will be set to the value in "Command Line Name" (cliOptionName) or to the property name if it is not defined.

option_description will be set to the value in "Command Line Text" (cliOptionText) or to the property description if it is not defined.

It is also possible to hide parameters from the --help menu by setting the option "Show in Command Line" (cliOptionShow) to false.


<stringParameter>
 <name>port</name>
 <default>8080</default>
 <description>...</description>
 <cliOptionName>webport</cliOptionName>
 <cliOptionText>Web server port</cliOptionText>
 <cliOptionShow>1</cliOptionShow>
</stringParameter>

Using this settings, help will show the following entry:


--webport   Web server port
    default: 8080

Additional Switches

As previously mentioned, each parameter will have its own command line option. However, there are additional command line switches that may be useful while performing installations in unattended mode.

You can enable and 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 each component. Component names are case sensitive.

You can also modify the user interface shown during the installation process adding the option "--unattendedmodeui" It can take the values:

"none" : no progress bar will be shown when performing an unattended installation (default).

"minimal" : this value will show a graphical progress bar during an unattended installation.

"minimalWithDialogs" : In this mode, pop-ups will also be displayed in addition to the progress bar of the minimal mode.

Behaviour Modifications in Unattended Mode

While using unattended mode, the installation process is altered. It is important to note that all of the actions inside action lists that require user interaction are not executed, including those inside:


<componentselectionvalidationactionlist>
<finalpageactionlist>
Any parameter's <validationactionlist>
Any parameter's <preshowpageactionlist>
Any parameter's <postshowpageactionlist>

Also, be sure to take into account that during "initializationActionList", the parameters haven't yet been initialized with the values provided through the command line switches. They will contain the default values.

You may need to modify your installer behavior according to the mode used. In order to do this, you can use the "${installer_ui}" variable, which contains the mode that has been used to run the installer (gui, text, unattended).

You can define specific actions for unattended mode or prevent any actions from running in that mode by adding one of the following rules inside the specific ruleList.

<compareText text="${installer_ui}" logic="does_not_equal" value="unattended"/>
<compareText text="${installer_ui}" logic="equals" value="unattended"/>

For example, you can de-select a component at initialization if the installer detects that it is in unattended mode as follows:


<initializationActionList>
<componentSelection deselect="componentname">
 <ruleList>
 <compareText text="${installer_ui}" logic="equals" value="unattended"/>
 </ruleList>
</componentSelection>
</initialiationActionList>

Unattended Uninstallation

Unattended mode is also present in the uninstaller and it behaves in a similar way. This functionality may be useful for performing an uninstallation operation in the background without requiring any user feedback during an upgrade. Assuming that the path to the uninstaller is known, we could add the following action before starting to copy the new files:


<runProgram>
 <program>${uninstaller_path}</program>
 <programArguments>--mode unattended</programArguments>
 <ruleList>
     <fileTest>
         <path>${uninstaller_path}</path>
         <condition>exists</condition>
     </fileTest>
 </ruleList>
</runProgram>

Of course, we may also need to backup the application data before running the uninstaller and recover it once the new version is in place.

Usage Examples

Unattended mode may be used to automate any process that requires performing several installations with different settings. A few examples are provided below.

Simple Installer Tests

After building an installer, we may want to check to make sure it will work correctly while being run with different configurations. Instead of doing this by hand each time you build a new version, you can write a script that will try to install the application and ensure that no errors are thrown during the process. This script may use different option files containing the specific settings to be tested.

For example, under Unix systems we may implement a shell script as follows:


#!/bin/sh
OPTIONFILES_PATH="option_files/"
for optionfile in `ls $OPTIONFILES_PATH | cat`
do
installer.bin --mode-unattended --optionfile $optionfile
if [ $? -eq 0 ]
then
 echo "Test $optionfile: OK"
else
 echo "Test $optionfile: FAILED"
fi
done

Each of the configurations that we want to test should be defined inside optionfile in option_files folder. We may want to run the script in different machines or operating systems to detect if any parameter combination causes the installer to fail. Additional checks may be also included once each installation finishes.

Simple Automated Script

Let's imagine you have an application which could act as client or server. Each client installation has to be configured to connect to a specific server. If you want to perform a network installation with several client machines and one server you may proceed as follows:

Define the necessary parameters inside the installer. For instance: nodetype, servernode, servernodeport.

<stringParameter name="nodetype"   default="client"/>
<stringParameter name="servernode"   default=""/>
<stringParameter name="servernodeport"   default=""/>
<stringParameter name="port"   default="8080"/>

Write the different optionfile configurations needed:

server_options.ini:
nodetype=server
port=8003
client_options.ini:
nodetype=client
servernode=192.168.1.200
serverport=8003

Write a simple script which performs the installations in unattended mode with the proper option files. In Unix systems we may do something like:


#!/bin/sh
CLIENT_OPTIONS=client_options.ini
SERVER_OPTIONS=server_options.ini

SERVER=192.168.1.200
CLIENTS="192.168.1.201 192.168.1.202 192.168.1.203 192.168.1.204"
INSTALLER=node-installer.bin

scp $INSTALLER $SERVER:/tmp
scp $SERVER_OPTIONS $SERVER:/tmp
ssh $SERVER chmod +x /tmp/$INSTALLER
ssh $SERVER /tmp/$INSTALLER --mode unattended --optionfile /tmp/$SERVER_OPTIONS

for c in $CLIENTS
do
 scp $INSTALLER $c:/tmp
 scp $CLIENT_OPTIONS $c:/tmp
 ssh $c chmod +x /tmp/$INSTALLER
 ssh $c /tmp/$INSTALLER --mode unattended --optionfile /tmp/$CLIENT_OPTIONS
done

After running the script, all the machines will be configured with the appropriate configuration and without requiring any user interaction in the process.

We are assuming that the proper ssh keys have been configured in the network and the user running the script has access to all of them and required permissions.

As you can see, the script acts as a template network configuration that may be used on different environments.

Modular Installer

Let's imagine that we have an application which contains several modules. We want to have the ability to install/uninstall them separately with a global installer / uninstaller. How could we achieve this ?

One possible approach is to use unattended mode. We could generate one installer for each module and then construct a primary installer which will package them as binary files. When the primary installation is performed, each of the additional installers would be run in unattended mode in the background. The primary installation process should ask for the necessary parameters and send them to the background installations through the command line switches. For example, we can use a parameter "prefix" to tell each module where it should be installed.

Each installation will generate its own uninstaller so they can be run separately. Once again, to achieve global uninstallation, we will need to run each uninstaller in unattended mode.

Taking all of this into account, we can define a component inside primary installer for each module as follows:


<component>
<name>module1</name>
<canBeEdited>1</canBeEdited>
<selected>1</selected>
<show>1</show>

<folderList>
 <folder>
   <name>module1_installer</name>
   <destination>${installdir}</destination>
   <platforms>all</platforms>
   <distributionFileList>
      <distributionFile origin="module1_installer.bin"/>
   </distributionFileList>
   <actionList>
     <runProgram>
       <program>${installdir}/module1_installer.bin</program>
       <programArguments>--mode unattended --prefix=${installdir}/module1</programArguments>
     </runProgram>
   </actionList>
   <deleteFile path="${installdir}/module1_installer.bin"/>
 </folder>
</folderList>

<postUninstallationActionList>
 <runProgram>
   <program>${installdir}/module1/uninstaller</program>
   <programArguments>--mode unattended</programArguments>
   <ruleList>
     <fileTest>
       <path>${installdir}/module1/uninstaller</path>
       <condition>exists</condition>
     </fileTest>
   </ruleList>
 </runProgram>
</postUninstallationActionList>

</component>

As we can see, the component packs the module installer. During installation, it is copied to the installation directory and executed with the specific parameters. Then, the binary is removed.

During uninstallation, we run the module uninstaller, checking to make sure that the binary is still there, as it might have already been uninstalled by the user.

InstallBuilder 6.2.4 Now Available

2009-10-07T04:40:00.000-07:00

We just released version 6.2.4 of InstallBuilder our crossplatform installation and automatic update tool. The new release includes several enhancements, such as an improved builder tool on Mac OS X x86 and unattended install support for the autoupdate mechanism. The addition of unattended mode in the automatic update tool means that updates can be applied silently without user interaction. A complete list of improvements can be viewed in InstallBuilder's changelog.

Bundle Tomcat in Your BitRock InstallBuilder installer

2009-09-24T02:10:00.000-07:00

If you develop a Java Web Application, you may want to create an installer and redistribute Tomcat together with your software. This allows your users to avoid the time-consuming process of installing and configuring Tomcat in order to use your software and guarantees that the optimal version is used. In this article, we explain how to bundle Tomcat into a BitRock installer. We also provide the code so you can start with that and create an installer that not only installs your software but also configures the Tomcat server according to your requirements.

Product Details

We are going to create a demo installer for installing Tomcat. Of course, you can develop more advanced functionality than what we'll show today, but in this installer we'll focus on the basics. First, we are going to configure the Product Details of our installer. The License File will be shown at the beginning of the installation. The user must agree to it to be able to proceed with the installation process.
At the end of the installation process, an option to view the Readme file will appear if we provide a Readme File field in the Product Details section.

Check installation requirements

For this installer, we want to require the user to have a valid version of Java installed in the system to be able to continue the installation. For this, we will add an action to the pre-installation action list to look for Java in the system. The Autodetect Java action allows us to specify the minumum Java version required, vendor and if a JDK is required or if a JRE will also work.

Screen and validations (I)

Once we ensure that the user's machine has the required software installed, we will ask the user for some information for the installation. We use the Parameters section for this.

We will prompt the user for:

Installation directory
Tomcat HTTP port
Tomcat Shutdown port

We will also add validation rules to check that the information provided by the user is correct.

Screen and validations (II)

Installation Directory

This parameter is created by default as it is used in most installations.

Screen and validations (III)

Tomcat Configuration

Next, we will ask the user which ports we should use for Tomcat. We want to prompt the user for the HTTP port and the Shutdown Port. To minimize the number of screens in the installation process, we will group these ports in a Parameter Group, which will ask for all parameters on one screen.

The internal name that we will use for this screen will be tomcat_configuration and the title will be 'Tomcat Configuration'.

Screen and validations (IV)

We will use two String parameters. Each one will represent one of the ports that we want to configure.

We'll focus on the tomcat_http_port. The steps for the tomcat_shutdown_port will be very similar. You will just need to change the default value and the description.

Screen and validations (V)

In order to ensure the application starts correctly once it is installed, we will check that the selected ports are free and can be used for the Tomcat configuration.

In the Validation Action for each port, we will add a Throw Error action. A Throw Error action usually exits the installer. However, the behavior is a bit different when it is used in a Validation Action context; after showing the error message, the installer will return to the screen allowing the user to re-enter the parameters.

In the Throw Error action we will configure the text that we want to show in case the selected port is already taken.

Screen and validations (VI)

In order to throw the error only if the port is not free, we will add a Port Test rule in the Throw Error action. The error will only be thrown if the condition 'cannot bind to selected port' is true. The port selected by the user is stored (according to the rest of the document) in the variable tomcat_http_port. We want to check its value, so in Port we will enter ${tomcat_http_port}.

The same steps are valid for the tomcat_shutdown_port.

Folders and Files (I)

The next step in the installation process will be to copy the Tomcat files to the user's machine.

As Tomcat is a Java application, the same files will run on Windows and Linux. We'll create a new InstallBuilder folder which will be installed in the installation directory selected by the user, ${installdir}. That will be installed in 'All Platforms' and we'll add the Tomcat directory that we want to pack.

Folders and Files (II)

To make it easier for the user to start and stop Tomcat, we have created some start/stop scripts.

These scripts differ for each platform, so we'll add two new folders: one setting Linux as platform and the other setting Windows as platform.

You can set the description and shortname you prefer for each folder. In both cases the destination of these scripts will be ${installdir}.

Folders and Files (III)

Now you will need to add the script files for each platform: .sh for the Linux folder and .bat for the Windows folder.

Windows Start Menu Entries (I)

In the File section we can also configure the Start Menu entries for our application.

We'll add entries for:

Start Tomcat: This will be an 'application' type shortcut pointing to the start .bat script we are including.

Stop Tomcat: This will be an 'application' type shortcut pointing to the stop .bat script we are including.

Uninstall Tomcat: This will be an 'application' type shortcut pointing to the uninstaller.

Launch Tomcat application: This will be a 'url' type shortcut pointing to the url where the Tomcat application can be accessed.

Windows Start Menu Entries (II)

Windows Start Menu Entries (III)

Post Installation Actions (I)

Once the files are copied to the user system, we need to implement some additional configuration steps:

Configure Tomcat to use the ports selected by the user.

Set the right executable permissions for the Tomcat binaries on Linux.

Get JAVA_HOME in order to configure the startup and stop scripts to use the correct Java version.

Configure the start and stop scripts to use the right JAVA_HOME.

On Linux, set the correct permissions for the start and stop scripts.

Post Installation Actions (II)

The main Tomcat configuration file is server.xml. In this file we can configure the ports Tomcat is using. We will use substitution actions for this.

By default, server.xml contains hard-coded references to 8080 and 8005. These ports represent the http port and the shutdown port respectively.

With the substitution actions, we will replace 8080 with the value of the port selected by the user for the HTTP request and 8005 with the value of the port selected by the user for the Shutdown port. In our example, these values are stored in ${tomcat_http_port} and ${tomcat_shutdown_port}.

Post Installation Actions (III)

Post Installation Actions (IV)

Now, we will add write permissions to the Tomcat executable files in the bin folder. Note that this action will only take effect in Unix platforms so we don't need to add a rule for not executing it on Windows.

Post Installation Actions (V)

At the beginning of the installation, we detected Java. InstallBuilder will create an internal variable named java_executable. However, according to the Tomcat documentation, we need to set the JAVA_HOME variable.

We'll use a regular expression for getting the right value of JAVA_HOME.

Post Installation Actions (VI)

Previously, when we created the start/stop scripts, we used patterns that will be replaced during the installation process with the correct value. We will now replace those patterns with the path to CATALINA_HOME and the path to JAVA_HOME. This is also valid for both Linux and Windows.

Post Installation Actions (VII)

Finally, we will give executable permissions to the start and stop scripts on Linux. With this, we finish with the post installation configuration steps.

Final Page

Once the installation is complete, we will offer the user the option of starting Tomcat. If the user opts to do so, on Linux we will execute the start.sh script, while on Windows we will execute the start.bat script. When the Tomcat server has been started, we will open the browser and show the user that Tomcat is working.

Build

Now we can build our multiplatform installers and give them a try. By default, the installers will be created in your InstallBuilder directory, in the 'output' folder.

Resources

Sample Tomcat installer files

LinuxCon and JEI

2009-09-23T05:04:00.000-07:00

BitRock will be attending LinuxCon in Portland and the JEI Startup event in Zaragoza (Spain). Let us know if you are around and would like to chat with us.

Managing Bundled Files

2009-07-24T05:58:00.000-07:00

In this entry we are going to discuss how to manage files bundled within an installer.

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

InstallBuilder provides you with actions to deal with these situations. The most important are <unpackFile> and <unpackDirectory>. Let's assume we are in the situation detailed above. A typical project XML file would look something like:


<project>
    ...
    <componentList>
        <component>
            <name>default</name>
            <folderList>
                <folder>
                    <name>programfiles</name>
                    <destination>${installdir}</destination>
                    <distributionFileList>
                        <distributionDirectory origin="/path/to/dir/to/pack"/>
                        <distributionFile origin="/path/to/checker"/>
                    </distributionFileList>
                </folder>
            </folderList>
        </component>
    </componentList>
    <parameterList>
        <stringParameter>
            <name>licenseCheck</name>
            <description>Introduce your license key</description>
            <value></value>
        </stringParameter>
    </parameterList>
    ...
</project>

As you can see, the user is asked to supply a license key. Without the <unpack> actions, the information provided would not be checked until several steps later, which is not our desired behavior. Instead, we can do the following:


<parameterlist>
   <stringparameter>
       <name>licenseCheck</name>
       <title>Introduce your license key</title>
       <value></value>
       <validationactionlist>
           <unpackfile component="default" folder="programfiles" origin="checker" destination="/tmp">
           <runprogram>
               <program>/tmp/checker</program>
               <programarguments>${project.parameter(licenseCheck).value}</programarguments>
           </runprogram>
           <throwerror text="Wrong license key, please enter a valid one or cancel the installation">
               <rulelist>
                   <comparetext text="${program_stdout}" logic="equals" value="1">
                   </comparetext>
               </rulelist>
           </throwerror>
           </unpackfile>
       </validationactionlist>
   </stringparameter>
</parameterlist>

The packed file can even be a zip file. You just need to use an <unzip> action before executing it:


<unzip>
  <destinationdirectory>${installdir}</destinationdirectory>
  <zipfile>/tmp/unpacked/file.zip</zipfile>
</unzip>

As you can see in the example above, the <origin> in the unpack action corresponds with the location of the file inside the installer, not with the path to the file in the build machine. If you packed a directory "/path/to/dir/to/pack" containing three files, fileA, fileB and fileC, to unpack fileB, you should use an <unpackfile> with origin="pack/fileB":


<distributiondirectory origin="/path/to/dir/to/pack">

<unpackfile component="default" folder="programfiles" origin="pack/fileB" destination="/some/destination">
</unpackfile>
</distributiondirectory>

You could imagine this structure inside the installer:

To reference logo.jpg:


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

It does not matter where the file was located originally in the building machine, just the path inside the installer:


<component name="componentA">
<folderlist>
<folder>
<name>folder1</name>
<distributionfilelist>
   <distributiondirectory>
        <origin>/some/long/path/in/the/building/machine/someDirectory</origin>
   </distributiondirectory>
</distributionfilelist>
</folder>
</folderlist>
</component>

InstallBuilder also includes functionality to facilitate uninstalling bundled programs or tools. When an uninstaller is run, all files packed are automatically deleted, but if one of the bundled applications generates other files or directories, those have to be manually deleted using <deletefile> actions. Another way to take care of deleting all of the files is to use the <addfilestouninstaller> action:

<addfilestouninstaller path="/some/path/to/the/file"></addfilestouninstaller>

Note that this action will only work with existing files. You cannot add a file that is going to be created but does not yet exist. As a workaround for these situations, you can use a <touchfile> action:


<touchfile path="/some/path/to/the/file">
<addfilestouninstaller path="/some/path/to/the/file">
<deletefile path="/some/path/to/the/file">
</deletefile></addfilestouninstaller></touchfile>

Even if the real file is a directory, the uninstaller will register it correctly.

You can also remove files to be deleted from the uninstaller to avoid deleting them during uninstallation:

<removefilesfromuninstaller files="${installdir}/*" exclude="*.txt"></removefilesfromuninstaller>

This will exclude from the uninstaller all of the contents of "installdir" except for .txt files.

The example above uses the <exclude> tag, introduced in InstallBuilder 6.1.1, which allows you to specify patterns of file that should not be affected by the action.

How to use Rules with InstallBuilder

2009-07-21T00:28:00.000-07:00

The installation of your application does not have to be a rigid, linear sequence of actions. For example, maybe you need to copy certain files only if the target platform is Mac or Linux, but not if it is Windows. Or you may want to modify or add some content to a file, but only if it is needed (you don't want to duplicate configuration settings). Here's another example of common functionality: You may want to discard or accept user input depending on whether it meets certain criteria.

Rules in InstallBuilder allow you to determine when to perform certain actions depending on the circumstances, variables and user inputs that are involved in the installation. It allows you to set conditions related to an action or an action group at any step of the installation, and they will be performed only if the condition is met. You can set not only one, but a set of multiple conditions that can be evaluated with an AND/OR group logic statement.

This article will explain how to implement conditional rules in your actions, how to select the appropriate rule for each case, and how this can help you to optimize your project and avoid duplicating code.

If you don't already have InstallBuilder installed on your system, you can download the latest version from http://installbuilder.bitrock.com.

Now, let's begin!

We will start with GUI in our first, simple example for a fictitious commercial application for Windows. Imagine that you want to distribute your product offering with the option of installing it for a time-limited evaluation period, or installing it as a registered “Enterprise Edition”, depending on whether or not the user has a valid license key on his or her machine.

Your desired behavior is:
- - Your product will be installed as an “Enterprise Edition” if the installer finds a valid license file, “product.lic”, in the user's desktop folder. If that is the case, the installer will report that it is deploying an “Enterprise Edition”.
- - If a valid license file is not found on the user's desktop, the product will be installed as a “Trial Edition” and the installer will inform the user of that.

Of course, this is a very simple case, but it is a good example for demonstrating how rules can work for you. Now, start InstallBuilder and open the Demo project. To do so, use one of the following methods:

a) Go to [File -> Open Project -> From file...] and double-click on demo.xml file...

b) Click on the Open Project button at the toolbar (see the image on the left), and double-click on demo.xml file.

NOTE: It's strongly recommended that you preserve the Demo project for future testing purposes, so it is a good idea to save the project you're working on as a new one. For example, you can save it as 'myruleproject.xml'.

Now, click on the Advanced tab on the left side of the InstallBuilder GUI. This will show you all of the installation steps, components and distribution files/directories, and allow you to specify highly customized settings for your installer.

We want to check if there is a license file before deciding what edition (evaluation or enterprise) will be deployed, so select 'Pre-Installation-Actions'. This step defines the actions the installer must execute before the first page of the installer is displayed. Right-click the item and select 'Add'.

Now, we need a variable in which we will store a value that will depend of whether or not there is a license file found. We will call this variable 'edition_type', and it will store one the following values:

- trial: If there is not any license file found, it will be a 'trial' edition.

- enterprise: If the installer finds a license file, it will be an 'enterprise' edition.

Depending on which of the above values is returned, the installer will install the application as either an 'Enterprise Edition' or a 'Trial Edition'. So, how do you set the right value for the variable? The answer is: with InstallBuilder rules. We will set the variable with rules that will check if there is a license file present.

You can think about a rule like a condition that needs to be met to allow the related action to be be executed. If the rule is met, the action will be performed; if it isn't met, the action will not.

We need to set the value depending on which rule is met:

- -Set: edition_type=trial if a license file is not found)
- -Set: edition_type=enterprise (if a license file is found)

After selecting 'Add', we will find a new dialog window where you can select the type of action that you want to add to this step. We will select 'Installer Actions' on the left, and 'Set Installer Variable' on the right. Then press 'Ok'.

We will be presented with a new dialog window where you must enter the needed parameter for the action.

In this case, the 'Set Installer Variable' action will need the following parameter to work:

-Name: The name of the variable that we want to create. It will be 'edition_type'.

-Value: The value we want to store in the variable. It will be 'trial'.

After that, we will be returned to the advanced section of our project. Notice that there is a new item included as a Pre-installation action. This is the newly created Set Installer Variable action.

Now we will repeat the process and add the same action type, but this time the value for 'edition_type' will be 'enterprise'. As a result, we will get two items in the Pre-installation Actions trunk, each one with the two possibilities.

Notice that you can expand any of the actions that you have just created, and there is a parent node called 'Rules'. Here is where we will set the rule that must be met for the action to be performed.

Windows environment variables
Now that we are ready to add rules to our actions, there is another question to resolve: If the installer will look for a license file in the user's desktop, and the path to this location depends on the user's name and the Windows edition, how do we add the path? The answer is: with environment variables.

All operating systems, including Windows, have environment variables that help us to determine certain variable values and locations. If we read the Windows documentation, we will find that the environment variable called HOMEPATH will return the home directory of the current user. So if the user that executed our installer is named 'Joseph' , this variable will return something like: C:\Documents and Settings\Joseph.

InstallBuilder can read these environment variables for us and return the result. For this purpose we will use ${env()} to load the value of HOMEPATH:

${env(HOMEPATH)}

We are now able to set the location where we want the installer to look for the license file (the user's desktop):

${env(HOMEPATH)}/Desktop/product.lic

Adding the rules

Now, select the Rule node for the first action (edition_type=trial), and right-click to select Add. You will find a new dialog asking for the rule type. Select 'File Exists'. That allows us to check if there is a file present.

Then press 'Ok'.

We will get a new dialog window that asks for the path that points to the where the file would be stored if it exists.

In the field 'Path name' type:

${env(HOMEPATH)}\Desktop\product.lic

Remember to check the Negate option, since what we want is to set the value 'trial' to the variable 'edition_type' if the file does not exist.

Notice that now there is a new item in the Rules node for the first action, so this action will be performed ONLY if the file is not found at the given path.

Now try to add the rule for the second action. This action should try to set the value 'enterprise' to the variable 'edition_type' if the license file is found, so it will be equal to the previous rule, except for the fact that it is not negated this time.

As result, you will have two actions in the Pre-installation Actions folder, each one with its own rule. We have now finished the process during which the installer determines the properly value for the variable 'edition_type'. Let's check if it is all correct.

Adding an info dialog

Now that we have the actions and its rules, we need to create an action to show a dialog to inform the user which edition he or she is installing. For this, we need a Show Info Dialog.

Now that you know how to add an action, you can do it by yourself. Add a 'Dialog Action', type 'Show Info Dialog' just after the last action on Pre-installation Actions.

The text for this dialog will be: The installer will deploy the ${edition_type} edition on your computer.

Notice that the expression ${edition_type} will return the current value for the variable 'edition_type', which would be 'trial' or 'enterprise' in this case. Press 'Ok'.

Now we have three actions on our installer. The last one will be a dialog box that will report which edition will be installed.

We are ready to test the installer.

Testing the installer

To quickly test our installer, we can use the 'Test Run' button that is located in the tool-bar of InstallBuilder. Press it, wait for the build process to complete and the installer will start. Create an empty file on your desktop called 'product.lic' to test the way the installer responds depending on whether or not the file is present.

Of course, if you were to build an installer for production, you would want to check more than just whether or not a license file is present – you would want to confirm that it is actually valid. That can certainly be done using InstallBuilder, but is a topic for another how-to.

And now?

Here are some additional rules that you may find of use:

- Compare Text: Compares two values and check whether or not they are equal.

- Component test: Checks if a certain component is present in the installer.

- File Content Test: Checks if a file contains certain text. Very useful for checking configuration files.

- Host Validation: Helps you to check if a given host is valid.

- Platform Test: Checks to see if the target system is on your list of supported platforms.

- Process Test: Checks for the execution of a process in the target system.

- Regular Expression Match: Checks for a match between a given value and a pattern using regular expressions.

- Registry Test: Looks for certain keys/values in the registry. A must-know rule for Windows installers.

- User Test: Checks for the existence of a certain user in the system, or checks its password is valid.

- Windows Service Test: checks whether a service exists or whether it is running.

How to Use the AutoUpdater in InstallBuilder

2009-07-02T02:36:00.000-07:00

In version 6.0 of InstallBuilder, we started shipping a new tool called AutoUpdater . This tool allows you to enable users to check for, download and apply updates for your software on their machines, getting the necessary files through HTTP or FTP. Although the Autoupdater is not yet available through the InstallBuilder GUI, it is very simple to configure.

How Does it Work?

There is a binary file which will poll the server to get information about the software versions available. The behavior of this binary is:

Read the INI file that contains information about where to contact the server and which version is currently installed (which should be delivered together with the binary)

Get the XML file from the server, which contains available versions for each platform.

If there's a newer version available (checking that the version ID received is higher than the current one stored in INI file), download and install it or notify the user (return code = 0) if it is run in unattended mode.

This binary may be customized to fit your needs using the command line tool 'customize' which is available in the AutoUpdater directory after performing InstallBuilder installation. The binary may be generated for several platforms: windows, linux or linux-x64; and an XML file will be used to indicate the tool how should the updater be customized.

The syntax to use the tool is:

{IB_installdir}/autoupdater/bin/customize build /path/to/project.xml [windows,linux,linux-x64]

The project XML file must have the main tag '<autoUpdateProject>' containing a list of customizations. The ones currently available are:

General settings: allowLanguageSelection, allowedLanguages, customLanguageFileList, rebootRequired (after performing update), requireInstallationByRootUser (only the Administrator can run Autoupdater), saveRelativePaths, singleInstanceCheck (check that theres only one instance running)

Application: fullName, shortName, vendor, version

Modify view: height, width, leftImage (163x314 GIF or PNG), logoImage (48x48 GIF or PNG), splashImage(GIF or PNG image), splashScreenDelay, disableSplashScreen, overrideGtkButtonText, wmImage (48x48 GIF or PNG shown in the window manager task bar on Unix systems)

Windows binary options: windowsExecutableIcon, windowsResourceComments, windowsResourceCompanyName, windowsResourceFileDescription, windowsResourceFileVersion, windowsResourceInternalName, windowsResourceLegalCopyright, windowsResourceLegalTrademarks, windowsResourceOriginalFilename, windowsResourceProductName, windowsResourceProductVersion

After applying the customizations, the new file may be found inside {IB_installdir}/autoupdater/output.

The INI file should be delivered together with the update binary containing next fields inside [Update] section:

URL: The URL of the server from which the updates XML file should be obtained

version_id: The identifier of current installed version

update_download_location: The temporary path where downloaded installers should be stored

check_for_updates: It is possible to enable and disable the AutoUpdater on demand by setting this boolean value

The server XML file with latest version details should be present on the server located at the URL provided in the INI file with the following information inside the '<installerInformation>' tag:

version: name of the version to be shown to the user

versionId: version identifier

platformFileList: list of installer names by platform

downloadLocationList: list of download locations (downloadLocation), each containing a URL which points to a mirror where the software can be downloaded

Note: versionId must be an integer which takes higher values for the newest versions.

Simple example

Imagine we have an application called 'My Application' and we want to include AutoUpdater functionality in version 1.0.0. We may also want, for example, for the update process to be run by an Administrator and while only one process is being run. We can generate a custom binary having the appropriate application name, version and required flags:


<autoUpdateProject>
 <fullName>My Application</fullName>
 <shortName>myapp</shortName>
 <vendor>Acme Inc.</vendor>
 <version>1.0.0</version>
 <singleInstanceCheck>1</singleInstanceCheck>
 <requireInstallationByRootUser>1</requireInstallationByRootUser>
</autoUpdateProject>

You may want to change the images and icons to have application specific ones. To do so, you can add the options: leftImage, logoImage, splashImage, wmImage. Once all desired options are included in project.xml file, we run the customize command:


{IB_installdir}/autoupdater/bin/customize.bin build project.xml linux
{IB_installdir}/autoupdater/bin/customize.bin build project.xml windows

After that, binary files for Linux and Windows should be found in AutoUpdater output directory.

Apart from the AutoUpdater binary, you will need to setup a server with the new installers and update.xml file. In our case, we will use a server running locally in port 8080. (You can easily setup a web server using LAMPStack or WAMPStack from BitNami.org). We just need to copy there the latest installers and an update.xml file describing that version, the filenames and mirrors:


<installerInformation>
   <versionId>200</versionId>
   <version>2.0.0</version>
   <platformFileList>
       <platformFile>
           <filename>myapplication-installer-2.0.0.exe</filename>
           <platform>windows</platform>
       </platformFile>
       <platformFile>
           <filename>myapplication-installer-2.0.0.bin</filename>
           <platform>linux</platform>
       </platformFile>
   </platformFileList>
   <downloadLocationList>
       <downloadLocation>
           <url>http://127.0.0.1:8080/downloads/</url>
       </downloadLocation>
   </downloadLocationList>
</installerInformation>

where versionId has been set to a higher integer value than previous ones and we have configured a single mirror. We can include any number of mirrors by adding multiple download location elements though. That way, the installers will be downloaded from:

http://127.0.0.1:8080/downloads/myapplication-installer-2.0.0.bin
http://127.0.0.1:8080/downloads/myapplication-installer-2.0.0.exe

AutoUpdater should be able to locate that update.xml file as well as know which software version is currently installed. That is done using an “update.ini” file with the following content:


[Update]
url = http://127.0.0.1:8080/update.xml
version_id = 100
check_for_updates = 1
update_download_location = /tmp

In this case, update.xml will be obtained from localhost, saving temporary installers inside the /tmp path. The application upgrade process will be done if received version ID is greater than 100.

Once we have the files available and update.ini is in the same path as the AutoUpdater binary, we can check its behavior:

When it is started , the rules included in customization will be checked: if the user is not an Administrator, he or she will be notified and the AutoUpdate process ends. If there is another instance already running, a notification will let the user know and he or she will be able to chose if the process should continue or not. If both requirements are met, a welcome screen will appear.

Here is what the process will look like from the user's perspective:

After clicking 'Next' button we'll get a screen to configure a proxy if it is necessary.

It will contact the server and check if there are new versions available. If there is an update, the following screen will be shown:

If you click 'Next', a new window with the list of mirrors is shown.

Once the new version is downloaded, the installer is started

Adding AutoUpdate to an Existing InstallBuilder Project

The only steps required to include the new feature as part of the application installation is to copy the appropriate AutoUpdate binary file for each operating system and place update.ini file in the same folder. For instance, we can define a component in the following way:


<component>
   <name>autoupdater</name>
   <description>includes tool to perform updates</description>
   <canBeEdited>0</canBeEdited>
   <selected>1</selected>
   <show>0</show>

   <folderList>
       <folder>
           <name>autoupdaterwin</name>
           <destination>${installdir}</destination>
           <platforms>windows</platforms>
           <distributionFileList>
               <distributionFile origin="autoupdater-windows.exe"/>
           </distributionFileList>
       </folder>
       <folder>
           <name>autoupdaterlinux</name>
           <destination>${installdir}</destination>
           <platforms>linux</platforms>
           <distributionFileList>
               <distributionFile origin="autoupdater-linux.bin"/>
           </distributionFileList>
       </folder>
   </folderList>

   <postInstallationActionList>
       <writeFile>
           <path>${installdir}/update.ini</path>
           <text>[update]
url = ${update_xml_url}
version_id = ${application_version_id}
update_download_location = ${system_temp_directory}
check_for_updates = 1
</text>
       </writeFile>
   </postInstallationActionList>
</component>

Where the 'update_xml_url' installer variable must be setup to point to where update.xml can be fetched and 'application_version_id' must be modified to a higher value on each installer update. Of course, it will be also needed to copy the 'autoupdate-*' binary files to project directory.

Using AutoUpdate as a notifier

Another approach can be to include the AutoUpdate but use it as a notifier which just checks if there are new updates available or not. This can be achieved calling the tool in unattended mode:

$ autoupdater.bin --mode unattended

The exit code will be 0 if an update is available and 1 if not. You can use this approach to show a 'There's a new update available' message to users. To do so, you just call the process in background and generate the message if the returned code is 0:


if (system(“path/to/autoupdater –mode unattended”) == 0){
 printf(“Update available. Run autoupdate to apply it.”);
}

Something similar may be added when the application starts, or as a cron task if it is a web application, so that the user detects that there's a new update without having to run AutoUpdater manually to check it.

For more information on AutoUpdater, please see the AutoUpdate documentation included with each download of InstallBuilder.

You can also watch the following video, that displays the needed steps:

How to Add Components and Make them Optional

2009-07-01T00:43:00.000-07:00

BitRock InstallBuilder allows you to create cross platform installers that make it easy for end users to install your software. Though users are often presented with a simple 5-click process, the software bundled inside and its configuration are typically very complex and difficult to set up manually. Examples of this are posted on BitNami.org, where stacks like Redmine, Alfresco or KnowledgeTree, which are fairly complex to install manually, can be installed in minutes thanks to installers that automate the process.

All of the applications available via BitNami have many different dependencies, such as: libraries, databases, web servers, programming languages, run-times, etc. Apart from that, each of them has to be configured a certain way and then all of the pieces need to be integrated to work together. The installation process gets even more complicated if you want to make those 'modules' optional and allow the end user choose which ones should be installed and how they should be configured. BitRock InstallBuilder's components make the task easier.

What is a Component?

You can think of a component as a 'black box' you use to simplify the way you build the installer. It is kind of a partial installer inside the primary installer that only applies to a subset of the software you are packaging (such as Apache, MySQL, etc). This makes it very easy to re-use pieces of your installer and add and remove them as necessary. You can bundle files within components and add rules, scripts, actions, variables or parameter pages (which are used to ask the user how they want to configure that piece of software). Various components are then bundled inside the primary installer to present end users with a complete package. If you are familiar with DRY (Do not Repeat Yourself) or KISS (Keep It Simple Stupid) terms, then InstallBuilder components will surely make you happy.

How to Add Components

The InstallBuilder demo project comes with a default component. It is important to understand that BitRock InstallBuilder is very component-oriented - even when you create a very simple installer, you will probably have at least one component.

Once you have InstallBuilder running in the GUI mode, go to 'Files' or the 'Advanced' section. All available components are displayed there. There are two ways to add a new one:

- From the 'Files' section: click 'New Component'

- From the 'Advanced' section: select 'Components' and click 'add'

The window shown below should be on your screen.

Here, you specify the three primary options:

'Install by default': The component will be selected by default.
'Can be edited': The end user is able to select or deselect the component in the Component Selection Window.
'Show': The component will be shown in the Component Selection Window.

You can do the same by editing the 'project.xml' file and adding the following snippet of XML:


<componentList>
     ...
     <component>
         <name>componentabc</name>
         <description>Component ABC</description>
         <canBeEdited>1</canBeEdited>
         <detailedDescription>simple description for the component ABC</detailedDescription>
         <selected>0</selected>
         <shouldPackRuleEvaluationLogic>or</shouldPackRuleEvaluationLogic>
         <show>1</show>
     </component>
     ...
</componentList>

People usually associate installer components with a window where the user can select or deselect software to be installed on their machine. This window is not shown by default in the case of InstallBuilder. Very often, you use components to make your installers well organized, clean and your XML code easier to reuse. If you want to show this window during installation, go to the 'Advanced' section, select 'project', click 'More', select 'Installation' in a new window and then 'Allow Component Selection'..

You can do the same by editing your xml file:

<allowComponentSelection>1</allowComponentSelection>

and during installation the following window will be displayed:

Summary

As we have mentioned at the beginning of this post, components are like sub-installers. Inside them, you can bundle part of your application files, configuration, scripts, etc. Try to design your components in such a way that they can be reused in the future. Almost all InstallBuilder functionality, such as parameter pages, action lists, and rule lists are available for components:

Additionally, you can place your components inside separate files and then include them in the main file:


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

... but it is a topic for another article.

You can find more information about components in our online knowledge base. Here are a few articles that may be of interest:

- http://support.bitrock.com/article/how-do-components-work-in-installbuilder

- http://support.bitrock.com/article/does-installbuilder-support-component-selection

- http://support.bitrock.com/article/is-there-a-command-line-option-for-component-selection

- http://support.bitrock.com/article/what-are-the-components-of-a-rulelist

We have also made a video demonstrating this procedure:

How To Integrate Bitrock InstallBuilder with Eclipse

2009-06-16T00:51:00.000-07:00

Did you know that it is possible to integrate InstallBuilder into your development environment?

You may already be familiar with the advanced GUI builder that was added in InstallBuilder 6. You can access most InstallBuilder features from the GUI, so you can develop complex installers without writing a line of code. However, there are situations in which that is not the ideal way to work with InstallBuilder. In addition to the GUI builder, you can work directly with the XML project file or interact with the tool using the command line interface. Both the XML project file and the command line builder interface turn InstallBuilder into a powerful development tool that can be integrated into your development environment.

There are a variety of Integrated Development Environments (IDEs) that support functions such as source code editing, compilation, automation and version control. You can also integrate the packaging functionality that BitRock InstallBuilder provides because most IDEs can be configured to use external tools.

In this article, we'll explain how to configure Eclipse to package your software with InstallBuilder. The configuration with other IDEs would be similar to this. This article is focused only on the basics - more complex configuration can be done to further customize your environment.

Getting BitRock InstallBuilder

To get started, you need to have InstallBuilder installed on your system. You can download the latest version from http://installbuilder.bitrock.com

To install InstallBuilder, you can either click through the steps presented by the GUI installation wizard or you can run the installer in unattended mode. In this case, we'll install it in unattended mode. Once you have downloaded the edition you'd like to use, you just need to execute from a command line console:

$ installbuilder-enterprise-6.1.0-linux-installer.bin --mode unattended --prefix /path/to/installation/directory

Creating a demo project in Eclipse

If you don't already have Eclipse installed in your system you can get it and the installation instructions from http://www.eclipse.org.

Once it is installed, open it and go to [File tab --> New --> Project]. You will be prompted to select a resource, select [General --> Project]. In our example we'll use 'demo' as name of the project.

If you don't see the screen below, you may want to enable the navigator view. To do so, go to the Window tab --> ShowView and look for the 'Navigator' and 'Console' views.

To demonstrate the integration, we'll build one of the demo installers that are bundled in InstallBuilder. Let's use the example for the parameter screens. Import the project file parameters_example.xml that you can find in <installbuilder-installation-directory>/projects/examples/parameters.

To import a file in Eclipse, right-click on the project name and select [Import]. Then select [General --> File System] in the window that appears and navigate through your file system to select the XML project file, docs and img folders.

As you can see, the source of InstallBuilder is an XML file.

Configuring Eclipse to build an Installer with InstallBuilder

Now we are going to configure InstallBuilder as an External Tool. Go to [Run tab --> External Tools --> External Tools Configuration].

Right-click on [Program] and select [New]. Configure Eclipse by pointing it to the InstallBuilder builder tool, selecting the current project as the working directory and adding the appropriate arguments (build projectfile.xml platform). In our example, we need to use:

build parameters_example.xml linux

We can add it to 'Favorites' so this functionality can easily be accessed. Go to the Run tab --> External Tools --> Organize Favorites and select the configuration we have just created:

Now in [Run tab --> External Tools] you should have the [Build Installer] option.

Now it's time to test if our configuration is correct. Go to [Run tab --> External Tools --> Build Installer] and it will start to generate the installer for our demo application. If you have the 'Console' view enabled, you will see the installer being generated:

Configuring Eclipse to Test the Generated Installer

You can now test your installer. In the same way you added InstallBuilder as an External Tool, you can add the generated installer and launch it. Below, you can see the configuration for the new External Tool. Remember to add it to your Favorites to make it easier to access.

Give it a try! You will see your installer being launched from Eclipse.

Before we wrap up, you know that InstallBuilder is a cross-platform installer, right? And that you can build installers for different platforms without the need to switch your development environment? Yes, you can build installers for Linux, OS X and Windows all from a Linux machine. If you have your development environment on Linux and you have 'wine' installed, you will also able to test your Windows installer from your development environment.

We have also made a video that shows how to integrate InstallBuilder with Eclipse:

Great Week at JavaOne

2009-06-09T20:28:00.000-07:00

We had a great week last week at JavaOne in San Francisco. It was great to meet a number of InstallBuilder customers in person. We also had an opportunity to learn about several cool new startups, including JRapid, which has developed a tool that speeds up AJAX application development, ScrumNinja, which offers a slick web app for managing Scrum, Micello, which has a cool indoor location-based-service on mobile devices and AgileIT, which makes it easy to add web services to your application.

I also gave a lightning talk on how BitRock worked with Logical Awesome to develop an on-site version of GitHub that is easy to install. The video should be posted soon and I'll be sure to provide a link once it is available.

As promised, we raffled off an EeePC, which was won by Frank from New York. Congratulations, Frank!

GitHub On-Premise Version Now Available

2009-06-09T16:40:00.000-07:00

Last week, we announced the release of a customer's new product, GitHub:Firewall Install. Congratulations to our friends at Logical Awesome, the makers of Github, for the very successful launch of their on-premise edition!

If you're not already familiar with it, GitHub is a wildly popular web application for social coding, with over 80,000 developers already using the site. Built on top of the Git distributed version control system, it makes it easy for distributed teams to collaborate on software development projects.

Until now, GitHub was only available as a service, which made it inaccessible to companies that will not allow their code to be hosted outside of the corporate firewall for security reasons. After seeing increasing demand for an on-site version of their product, the Logical Awesome team approached BitRock to package the new version, GitHub:FI, for easy installation at customer sites.

BitRock developed a completely self-contained installer for GitHub:FI that enables new users to get up and running in just a few mouse clicks. The installer contains all of the software required to run GitHub: Ruby on Rails, JRuby, Solr, Java, Python, Perl, Git, Pygments, OpenSSL and over 30 additional components. It completely automates the installation and configuration process, so no manual setup steps are required. Logical Awesome is also taking advantage of the BitRock Network Service to better inform product development and support.

Want BitRock to make your software that easy to install?

Whether your software is built on PHP, Rails, Java, Perl or Python, we can deliver a complete package that enables even non-technical end users to have it up and running in minutes on Windows, Linux, OS X or Solaris. To learn more, contact our sales team.

How to Create Custom Pages with InstallBuilder

2009-06-08T15:04:00.000-07:00

This week, we are kicking off a weekly series of 'how-to' posts for InstallBuilder, our crossplatform installation tool. Each how-to will include detailed instructions, as well as downloadable XML examples and (in most cases) a video demonstrating the process. In this first installment, we're going to cover how to create custom pages. InstallBuilder allows you to create multiple parameter pages: stringParameter, choiceParameter, booleanParameter... But what if you want a more customized page? Here is where parameterGroups come into play. parameterGroups allow you to define a list of parameters to be displayed in the same page and how to display them. This tutorial will be divided in 3 steps. First, we will design the page schema. In the second step, we will apply validations to fields. In the last step, we will perform actions based upon the user input.

First step:

For this example, we are going to collect information to configure a web application. The required fields will be:

Username (stringParameter): The administration username.
Password (passwordParameter): The administrator password
IP Address & port (stringParameter): The IP and port in which the server will be listening.
DBMS server (choiceParameter): Either MySQL or PostgreSQL
Basic or advanced installation (booleanParameter): In advanced mode, we can collect additional information.

Lets create a basic template of the page. In this code, we have listed the parameters inside an <actionGroup>:


<project>
<shortName>sample</shortName>
<version>1.0</version>
<parameterList>
<parameterGroup>
<name>configuration</name>
<title>Configuration</title>
<explanation>Configuration page</explanation>
<value></value>
<default></default>
<parameterList>
   <stringParameter>
       <name>username</name>
       <description>Username</description>
       <explanation>Administrator account username</explanation>
       <value></value>
       <default></default>
       <allowEmptyValue>1</allowEmptyValue>
       <width>30</width>
   </stringParameter>
   <passwordParameter>
       <name>password</name>
       <description>Password</description>
       <explanation>Addministrator account password</explanation>
       <value></value>
       <default></default>
       <allowEmptyValue>1</allowEmptyValue>
       <descriptionRetype></descriptionRetype>
       <width>20</width>
   </passwordParameter>
   <stringParameter>
       <name>ipaddress</name>
       <description>Web Server IP</description>
       <explanation></explanation>
       <value></value>
       <default></default>
       <allowEmptyValue>1</allowEmptyValue>
       <width>30</width>
   </stringParameter>
   <stringParameter>
       <name>port</name>
       <description>Web Server Port</description>
       <explanation></explanation>
       <value></value>
       <default></default>
       <allowEmptyValue>1</allowEmptyValue>
       <width>30</width>
   </stringParameter>
   <booleanParameter>
       <name>advancedconfig</name>
       <description>Enable advance</description>
       <explanation>Would you like to perform an advance installation?</explanation>
       <value></value>
       <default></default>
       <displayStyle>checkbox-left</displayStyle>
   </booleanParameter>
   <choiceParameter>
       <name>dbmsserver</name>
       <description>DBMS</description>
       <explanation>Database server</explanation>
       <value></value>
       <default></default>
       <allowEmptyValue>1</allowEmptyValue>
       <displayType>combobox</displayType>
       <width>30</width>
       <optionList>
           <option>
               <description>MySQL server</description>
               <image></image>
               <text>MySQL</text>
               <value>mysql</value>
           </option>
           <option>
               <description>PostgreSQL server</description>
               <image></image>
               <text>PostgreSQL</text>
               <value>postgres</value>
           </option>
       </optionList>
   </choiceParameter>
</parameterList>
</parameterGroup>
</parameterList>
</project>

Then, build and run.

Image 1:

This is obviously not the expected result. We can modify the height of the page but the result is not ideal:


<project>
...
<height>400</height>
...
</project>

Image 2:

As we said, this is better but still not the best it could be.

Using nested parameterGroups, we can use the <orientation> tag to modify the organization of the default parameters inside the parameter group from "vertical" to "horizontal". Also, nested parameter groups allow us to group related fields (for example, username and password):


<parameterGroup>
<name>configuration</name>
<title>Configuration</title>
<explanation></explanation>
<value></value>
<default></default>
<parameterList>
<parameterGroup>
<name>adminaccount</name>
<title></title>
<explanation>Admin Account</explanation>
<orientation>horizontal</orientation>
<value></value>
<default></default>
<parameterList>
  <stringParameter>
    <name>username</name>
    <description>Username</description>
    <explanation></explanation>
    <value></value>
    <default></default>
    <allowEmptyValue>1</allowEmptyValue>
    <width>20</width>
 </stringParameter>
 <passwordParameter>
    <name>password</name>
    <description>Password</description>
    <explanation></explanation>
    <value></value>
    <default></default>
    <allowEmptyValue>1</allowEmptyValue>
    <descriptionRetype></descriptionRetype>
    <width>20</width>
 </passwordParameter>
</parameterList>
</parameterGroup>
<parameterGroup>
<name>serveraddres</name>
<title></title>
<explanation>Server Address</explanation>
<orientation>horizontal</orientation>
<value></value>
<default></default>
<parameterList>
<stringParameter>
  <name>ipaddress</name>
  <description>IP and Port</description>
  <explanation></explanation>
  <value></value>
  <default></default>
  <allowEmptyValue>1</allowEmptyValue>
  <width>30</width>
</stringParameter>

<stringParameter>
  <name>port</name>
  <description>:</description>
  <explanation></explanation>
  <value></value>
  <default></default>
  <allowEmptyValue>1</allowEmptyValue>
  <width>5</width>
</stringParameter>
</parameterList>
</parameterGroup>

<booleanParameter>
<name>advancedconfig</name>
<description>Enable advance</description>
<explanation>Would you like to perform an advance installation?</explanation>
<value></value>
<default></default>
<displayStyle>checkbox-left</displayStyle>
</booleanParameter>
<choiceParameter>
<name>dbmsserver</name>
<description>DBMS</description>
<explanation>Database server</explanation>
<value></value>
<default></default>
<allowEmptyValue>1</allowEmptyValue>
<displayType>combobox</displayType>
<width>30</width>
<optionList>
<option>
 <description>MySQL server</description>
 <image></image>
 <text>MySQL</text>
 <value>mysql</value>
</option>
<option>
 <description>PostgreSQL server</description>
 <image></image>
 <text>PostgreSQL</text>
 <value>postgres</value>
</option>
</optionList>
</choiceParameter>
</parameterList>
</parameterGroup>

Image 3:

We now have the desired result.

Let's continue to step 2, validations.

Step 2: At this point, a user could leave some required fields blank or provide a nonnumeric value for the port. We need to validate the information provided and, in the event that it is not valid, ask for the information again.

Username and password: We need a username, but we want to allow the password field to be blank . We will include a pop-up to warn the user. To require a non-empty value, we just need to set <allowEmptyValue>0</allowEmptyValue> in the desired parameter. For more complex validations, such as launching a pop-up to warn the user, we need a <validationActionList>:


<passwordParameter>
<name>password</name>
...
<!-- In a validationActionList you can execute any desired action -->
<validationActionList>
<showQuestion text="Are you sure you want to provide an empty password?" variable="continue" >
<ruleList>
 <compareText text="${password}" logic="equals" value=""/>
</ruleList>
</showQuestion>
<!-- The next_page built-in variable controls the intallation flow at runtime --> 
<setInstallerVariable name="next_page" value="configuration">
<ruleList>
 <compareText text="${continue}" logic="equals" value="no"/>
</ruleList>
</setInstallerVariable>
</validationActionList>
</passwordParameter>

IP and port: We could do a lot of validations here, but lets limit them to require a pseudo valid IP (four three digit numbers separated by periods) and a valid port that is not in use.


<parameterGroup>
<name>serveraddres</name>
<title></title>
<explanation>Server Address</explanation>
<orientation>horizontal</orientation>
...
<parameterList>
<stringParameter>
 <name>ipaddress</name>
 <description>IP and Port</description>
 ...
 <validationActionList>
     <setInstallerVariableFromRegEx text="${ipaddress}" pattern="^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$" substitution="valid" name="result"/>
     <actionGroup>
         <actionList>
             <throwError text="This not seems to be a valid IP addres"/>
         </actionList>                       
         <ruleList>
             <compareText text="${result}" logic="does_not_equal" value="valid"/>
         </ruleList>
     </actionGroup>
 </validationActionList>
</stringParameter>
<stringParameter>
 <name>port</name>
 <description>:</description>
 ...
 <width>5</width>
 <validationActionList>
     <throwError text="Cannot bind to the selected port. Please choose another one.">
         <ruleList>
             <portTest condition="cannot_bind" port="${port}"/>
         </ruleList>
     </throwError>
 </validationActionList>
</stringParameter>
</parameterList>
</parameterGroup>

As the rest of the parameters are constrained by the installer and cannot contain incorrect values, we do not need to perform any more validations.

Step 3:

Now, once we have all the needed information and we are sure it is correct, we can perform some actions with it before the next page appears. For example, based on the "Advanced Installation" booleanParameter, we could make visible a by default hidden page.

Lets assume the advance configuration is the installation directory. If the parameter is checked, the installation directory will be visible. Otherwise, it will not be displayed.


<directoryParameter>
<name>installdir</name>
<description>Installer.Parameter.installdir.description</description>
<explanation>Installer.Parameter.installdir.explanation</explanation>

<insertAfter>configuration</insertAfter>
<default>${platform_install_prefix}/${product_shortname}-${product_version}</default>
<ask>0</ask>
</directoryParameter>

As we have set by default <ask>0</ask>, this parameter will be hidden and the user would be unable to change it.

Getting back to our custom page, we could use the <postShowPageActionList> to show the installdir parameter:


<parameterGroup>
<name>configuration</name>
<title>Configuration</title>
...
<parameterList>
...
</parameterList>
<!-- Using the notation below we can modify any parameter property -->
<postShowPageActionList>
<setInstallerVariable name="project.parameter(installdir).ask" value="1" >
<ruleList>
  <isTrue value="${advancedconfig}"/>
</ruleList>
</setInstallerVariable>
</postShowPageActionList>
</parameterGroup>

We now have a complete custom page.

You can download the XML project file from the InstallBuilder website

We have also made a video demonstrating the process via the GUI:

For an extensive list of rules and actions to use for custom pages, please refer to the InstallBuilder reference documentation. Also, these articles in our KnowledgeBase provide additional information on the topics mentioned in the article:

Parameters: How to ask the user for more than one parameter in the same screen How to Arrange Parameters Horizontally, How to ask for different inputs during the installation process

Validations: How to Validate User Input

About the next_page built-in variable: How to Control the Flow of Pages

BitRock Presenting at WhyFLOSS Madrid

2009-05-12T21:50:00.000-07:00

In addition to JavaOne, BitRock founder and CTO Daniel Lopez Ridruejo will be giving a talk on BitNami at WhyFLOSS Madrid, a Spanish conference on open source software. If you're not familiar with it, the BitNami project provides popular web applications such as DokuWiki, Drupal, Joomla! and Wordpress in self-contained, easy to install packages. With BitNami, even non-technical users can get BitNami application stacks up and running on Windows, Linux, OS X or Solaris in just a few clicks. BitNami also includes several development stacks for Rails, WAMP, JRuby and more.

The WhyFLOSS event is being held in Madrid on May 21st and registration is free, although all of the talks will be in Spanish.

BitRock Selected Finalist of Spanish 2009 Internet Award

2009-05-11T07:17:00.000-07:00

BitRock has been elected as a finalist of the 2009 Internet Awards in the category of best company. This nomination recognizes our work on BitNami and how it enables users of different backgrounds to quickly have up and running blogs, wikis and other web based programs. You can find more information at Dia de Internet website

Get $100 Off Your JavaOne Pass

2009-05-06T22:07:00.000-07:00

BitRock will be exhibiting and demoing InstallBuilder, our cross platform installer development tool, at JavaOne, and you’re invited! If you’re not familiar with JavaOne, it is one of the leading events for Java developers. Held June 2-5 at the Moscone Center in San Francisco, it offers attendees an opportunity to hear from industry leaders and other technology experts – those programming directly in Java(TM) technology and those looking at it from new perspectives including scripting, RIA, open source and more. A wide range of sessions give developers a chance to get hands-on experience with Java and related technologies.

To sign up and get $100 off of your full conference pass, visit: cplan.com/javaone2009/externalregistration/reg.html and enter the code EXHBCEK5.

If you do attend the conference, be sure to drop by the BitRock kiosk to enter our drawing for a very cool prize!