How do components work in InstallBuilder?

Products

• VMware

Issue/Introduction

Symptoms:

How do components work in InstallBuilder?

Resolution

Depending on the complexity of your software, you may need to split your installation files into several components. The ability to enable / disable components allows your installer to provide as many setup combinations as you need.

CONTENTS

• What a component can do
• Adding new components to your current project file
• Enabling the component selection screen
• Some useful component properties
• How to enable / disable components based on certain conditions
• How to find out if a component has been selected
• How to enable or disable components using command line options
• How to establish dependencies / restrictions for a given component
• How to calculate the disk space needed for installation
• Adding destination folders to a component
• Adding files and directories to a destination folder
• Adding shortcuts to the desktop / quick launch / start menu

What a component can do

Components are able to execute actions, copy files and prompt the user for data, as the project does. The tags used to achieve it are the same, an example included below

<component>
    <name>component</name>
    <description>component</description>
    <detailedDescription>This is a component</detailedDescription>
    <initializationActionList>
        <setInstallerVariable name="my_variable" value="1" />
    </initializationActionList>
    <parameterList>
        <booleanParameter>
            <name>boolean_question</name>
            <title>Boolean Question</title>
            <description>Please answer yes or no</description>
        </booleanParameter>
    </parameterList>
    <folderList>
        <folder>
            <description>Program Files</description>
            <destination>${installdir}</destination>
            <name>programfiles</name>
            <platforms>all</platforms>
            <distributionFileList>
                <distributionDirectory origin="program" />
            </distributionFileList>
        </folder>
    </folderList>
    <postInstallationActionList />
</component>

Adding new components to your current project file

The sample project which InstallBuilder creates by default defines only a single component, named "default". You can define additional components inside the <componentList>.

<project>
    ...
    <componentList>
        <!-- Main component -->
        <component>

            <name>default</name>
            ...
        </component>

        ...

        <!-- Additional component -->
        <component>
            <name>extras</name>
            ...
        </component>
    </componentList>
    ...
</project>

Components can also be extracted to a different file, making them usable as modules between different projects. To include a component that is placed in an external xml file into the project, you have to use the <include> tag under the <componentList>, as seen in the code below:

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

Of course, you can mix external and internal components in the project file

<componentList>
    <component>
        <name>internal</name>
    </component>
    <include file="my_external_component.xml" />
</componentList>

Enabling the component selection screen

InstallBuilder provides a component selection page, which is disabled by default. To enable it, you will need to set the <allowComponentSelection> project property as follows:

<project>
    ...
    <allowComponentSelection>1</allowComponentSelection>
    ...
</project>

Your installer will then provide a component selection screen like this one.

Some useful component properties

Each component has a set of properties which you can use to provide a description of the component and limit user selection depending on your needs.

<name>: This property allows you to define a name for this component.

<description>: This property allows you to enter a quick description of the component. This text will be displayed in the component selection checkbox.

<detailedDescription>: This property allows you to enter a longer description, which will be displayed at the right side of the component selection screen.

<canBeEdited>: If this property is set to 0, the user will not be allowed to select/unselect the component.

<show>: This property allows you to hide a component. If set to 1, the component will be displayed in the component selection screen. If set to 0, the component will not be displayed in the component selection screen.

<selected>: This property allows you to set the initial selection status for the component. If set to 1, the component will be selected by default. If set to 0, the component will be unselected by default.

<requiredSize>: This property allows you to define the required disk size in kilobytes for this component. If not specified, InstallBuilder will try to estimate the required disk size for each component at build time. This information is used to calculate the value of the required_diskspace installer variable, which allows you to determine the disk space needed to install the currently selected components.

<postInstallationActionList>, <postUninstallationActionList>, <readyToInstallActionList>: These action lists work like the those inside the <project> tag, but will be executed only if the component has been selected.

<parameterList>: This parameter list allows you to define parameters related to this component. The associated installer pages will be displayed only if the component has been selected.

<componentSelectionValidationActionList>: This action list allows you to implement dependency restrictions in the component selection installer page. Below you will find a more comprehensive description and an example of this feature (see "How to establish dependencies / restrictions for a given component").

<desktopShortcutList>: This list allows you to define desktop shortcuts for this component: these will be created only if the component has been selected. By the end of this page you will find an example of this feature.

<startMenuShortcutList>: This list allows you to define Windows start menu shortcuts for this component: these will be created only if the component has been selected. By the end of this page you will find an example of this feature.

<quickLaunchShortcutList>: This list allows you to define quick launch shortcuts for this component: these will be created only if the component has been selected. By the end of this page you will find an example of this feature.

<folderList>: This list allows you to include files and folders for this component: these will be installed only if the component has been selected.

How to enable / disable components based on certain conditions

You can use the <componentSelection> action to enable or disable components. This action should be located inside an action list: two examples of action lists are the <preInstallationActionList> inside the <project> tag and the <postShowPageActionList> inside a parameter tag.

The following example assumes the existence of two components: windowsdata and unixdata. During the installer initialization, the component related to the current platform will be enabled and the other one will be disabled.

<project>
    ...
    <initializationActionList>
        ...
        <!-- For Windows, enable windowsdata and disable unixdata -->
        <componentSelection>
            <select>windowsdata</select>
            <deselect>unixdata</deselect>
            <ruleList>
                <platformTest>
                    <type>windows</type>
                </platformTest>
            </ruleList>
        </componentSelection>
        ...
        <!-- For Unix platforms, enable unixdata and disable windowsdata -->
        <componentSelection>
            <select>unixdata</select>
            <deselect>windowsdata</deselect>
            <ruleList>
                <platformTest>
                    <type>unix</type>
                </platformTest>
            </ruleList>
        </componentSelection>
        ...
    </initializationActionList>
    ...
</project>

Please note that selecting or deselecting components outside of the component selection page will not be affected by dependencies or restrictions defined in the <componentSelectionValidationActionList> of any component.

How to find out if a component has been selected

It is often necessary to determine whether a component has been selected in order to show additional pages or execute certain actions. This can be done accessing the ${component(componentname).selected} installer variable. Notice you will need to substitute componentname with the specific component's name.

The following example will display a popup message if the windowsdata component is enabled, right before installing files (after clicking "next" in the "ready to install" page):

<project>
    ...
    <readyToInstallActionList>
        ...
        <!-- Display popup message if windowsdata is selected -->
        <showInfo>
            <text>windowsdata is selected.</text>
            <ruleList>
                <compareText>
                    <text>${component(windowsdata).selected}</text>
                    <logic>equals</logic>
                    <value>1
                </value></compareText>
            </ruleList>
        </showInfo>
        ...
    </readyToInstallActionList>
    ...
</project>

How to enable or disable components using command line options

If you are executing the installer from command line, you will be able to disable components using the --disable components command line option. You can specify a comma-separated list of component names: /path/to/installer --disable-components windowsdata,unixdata

In the same fashion, you can use the --enable-components command line option to enable a list of components. /path/to/installer --enable-components windowsdata,unixdata

Please note that --enable-components and --disable-components command line options are available only if you enable component selection in your project file (using <allowComponentSelection>1</allowComponentSelection>)

How to establish dependencies / restrictions for a given component

You can try using a <componentSelectionValidationActionList> inside a component to implement dependency checks in the component selection installer page, preventing the installer from going further if these are not satisfied.

For example, let's say you have defined components xxx and yyy: a third component, zzz, depends on them. In order to prevent the installation from going further if the user enables zzz and disables both xxx and yyy, you can insert the following <componentSelectionValidationActionList> inside component zzz:

<component>
    <name>zzz</name>
    <description>Component zzz</description>
    <detailedDescription>This component depends on xxx and yyy.</detailedDescription>
    ...
    <componentSelectionValidationActionList>
        <throwError>
            <text>Component zzz cannot be installed if you have not selected both xxx and yyy.</text>
            <ruleList>
                <compareText text="${component(xxx).selected}" value="0" logic="equals" />
                <compareText text="${component(yyy).selected}" value="0" logic="equals" />
            </ruleList>
        </throwError>
    </componentSelectionValidationActionList>
    ...
</component>

Please note that the <componentSelectionValidationActionList> of a given component is executed only if the component is selected.

How to calculate the disk space needed for installation

You can use the required_diskspace installer variable to get the disk space (in kilobytes) needed to install the currently selected components. This value is obtained from the sum of the property for each currently selected component.

Adding destination folders to a component

Before adding files or directories to a component, you will need to define a destination folder for them. Most applications will just need to create one installation directory. It is possible, however, to create additional destination folders to copy files and directories to, such as /usr/bin or /etc. To define destination folders inside a component you can add <folder> tags inside the component's <folderList>. The following example defines two destination folders for a particular component:

...
<component>
    ...        
    <folderList>
        <!-- The installation directory -->
        <folder>
            <name>programfiles</name>
            <description>Program Files</description>
            <destination>${installdir}</destination>
            <platforms>all</platforms>
            <distributionFileList>
                ...
            </distributionFileList>
        </folder>

        <!-- Configuration files that should be installed inside
             /etc, and for linux only -->
        <folder>
            <name>linuxconfigfiles</name>
            <description>Linux Configuration Files</description>
            <destination>/etc</destination>
            <platforms>linux</platforms>
            <distributionFileList>
                ...
            </distributionFileList>
        </folder>
    </folderList>
    ...
</component>
...

Notice the <distributionFileList> element inside each <folder>: inside you can include as many <distributionFile> and <distributionDirectory> tags as you need. You will notice each <folder> element has a <platforms> property: this allows you to specify the platforms for which this destination folder should be installed. Allowed values for the <platforms> property are:

Value	Platform
all	All platforms
linux	Linux
linux-x64	Linux x86 64 bits
linux-ia64	Linux IA64
osx	MacOS X
linux-ppc	Linux PPC
linux-s390	Linux s390
windows	Windows
solaris-sparc	Solaris Sparc
solaris-intel	Solaris Intel
freebsd	FreeBSD 5.x
freebsd6	FreeBSD 6.x
freebsd6-x64	FreeBSD 6.x 64 bits
freebsd4	FreeBSD 4.x
hpux	HP-UX
aix	AIX
irix-n32	IRIX

Adding files and directories to a destination folder

You can use the <distributionFile> tag to include a file inside a destination folder's <distributionFileList>. In the same fashion, you can use the <distributionDirectory> tag to include a directory inside a destination folder.

The following example defines a component which includes one destination folder. This folder includes a file and a directory.

<project>
    ...
    <componentList>
        ...
        <component>
            <name>default</name>
            ...
            <folderList>
                <!-- One destination folder, intended to install its contents into ${installdir} -->
                           <folder>
                    <name>programfiles</name>
                    <description>Program files</description>
                    <destination>${installdir}</destination>
                    <platforms>all</platforms>
                    <!-- The distributionFileList contains a list of the files and
                         directories that will be packed inside this folder -->
                    <distributionFileList>
                        ...
                        <distributionFile>
                            <origin>/path/to/file.txt</origin>
                        </distributionFile>
                        ...
                        <distributionDirectory>
                            <origin>/path/to/directory</origin>
                        </distributionDirectory>
                        ...
                    </distributionFileList>
                           </folder>
                ...
                <!-- Additional destination folders can be defined here. 
                     Remember each folder can be limited to a specific platform
                     by setting the <platforms> folder property. For additional 
                     restrictions, you can set a <ruleList> inside the <folder> tag.
                -->
                ...
            </folderList>
        </component>
        ...
    </componentList>
    ...
</project>

Adding shortcuts to the desktop / quick launch / start menu

Each component has three shortcut lists which can be used to create shortcuts:

<desktopShortcutList>: This shortcut list allows you to create shortcuts in the desktop. <startMenuShortcutList>: This shortcut list allows you to create shortcuts in the Windows start menu. <quickLaunchShortcutList>: This shortcut list allows you to create shortcuts in the Windows quick launch menu.

Each shortcut list can include one or more shortcuts. There are three shortcut types:

<shortcut>: This shortcut is meant to launch an application. <linkShortcut>: This shortcut is meant to launch a web browser pointing to a specific url. <fileShortcut>: This shortcut is meant to launch a viewer for a specific file.

The following example creates one of each shortcut type in the desktop:

<project>
    ...
    <componentList>
        ...
        <component>
            <name>default</name>
            ...
            <desktopShortcutList>
                <shortcut>
                    <comment>Launch My Program</comment>
                    <exec>${installdir}/bin/myprogram</exec>
                    <icon></icon>
                    <name>My Program</name>
                    <path>${installdir}/bin</path>
                    <platforms>all</platforms>
                    <runInTerminal>0</runInTerminal>
                    <windowsExec>${installdir}/bin/myprogram.exe</windowsExec>
                    <windowsExecArgs></windowsExecArgs>
                    <windowsIcon></windowsIcon>
                    <windowsPath>${installdir}/bin</windowsPath>
                </shortcut>
                ...

                <linkShortcut>
                    <comment>Launch a web browser pointing to My Program website</comment>
                    <icon></icon>
                    <name>Visit My Program website</name>
                    <platforms>all</platforms>
                    <runInTerminal>0</runInTerminal>
                    <url>http://my.company/myprogram</url>
                    <windowsIcon></windowsIcon>
                </linkShortcut>
                ...

                <fileShortcut>
                    <comment>Check the user guide</comment>
                    <filePath>${installdir}/doc/userguide.txt</filePath>
                    <icon></icon>
                    <name>My Program User Guide</name>
                    <platforms>all</platforms>
                    <runInTerminal>0</runInTerminal>
                    <windowsIcon></windowsIcon>
                </fileShortcut>
                ...
            </desktopShortcutList>
            ...

        </component>
        ...
    </componentList>
    ...
</project>

The <shortcut>, <linkShortcut> and <fileShortcut> tags in the example above will not help if you are trying to use the <startMenuShortcutList> to create shortcuts in the start menu. The following example will create the same three shortcuts in the Windows start menu group created by the installer. Notice you will need to use <startMenuShortcut>, <startMenuLinkShortcut> and <startMenuFileShortcut> instead:

<project>
    ...
    <componentList>
        ...
        <component>
            <name>default</name>
            ...
            <startMenuShortcutList>
                ...
                <startMenuShortcut>
                    <comment>Launch My Program</comment>
                    <exec>${installdir}/bin/myprogram</exec>
                    <icon></icon>
                    <name>My Program</name>
                    <path>${installdir}/bin</path>
                    <platforms>all</platforms>
                    <runInTerminal>0</runInTerminal>
                    <windowsExec>${installdir}/bin/myprogram.exe</windowsExec>
                    <windowsExecArgs></windowsExecArgs>
                    <windowsIcon></windowsIcon>
                    <windowsPath>${installdir}/bin</windowsPath>
                </startMenuShortcut>
                ...
                <startMenuLinkShortcut>
                    <comment>Launch a web browser pointing to My Program website</comment>
                    <icon></icon>
                    <name>Visit My Program website</name>
                    <platforms>all</platforms>
                    <runInTerminal>0</runInTerminal>
                    <url>http://my.company/myprogram</url>
                    <windowsIcon></windowsIcon>
                </startMenuLinkShortcut>
                ...
                <startMenuFileShortcut>
                    <comment>Check the user guide</comment>
                    <filePath>${installdir}/doc/userguide.txt</filePath>
                    <icon></icon>
                    <name>My Program User Guide</name>
                    <platforms>all</platforms>
                    <runInTerminal>0</runInTerminal>
                    <windowsIcon></windowsIcon>
                </startMenuFileShortcut>
                ...
            </startMenuShortcutList>
            ...

        </component>
        ...
    </componentList>
    ...
</project>

In the same fashion, to create shortcuts in the Windows quick launch menu you will need to use the <quickLaunchShortcutList> and replace the <shortcut>, <linkShortcut> and <fileShortcut> tags with <quickLaunchShortcut>, <quickLaunchLinkShortcut> and <quickLaunchFileShortcut> respectively.

<project>
    ...
    <componentList>
        ...
        <component>
            <name>default</name>
            ...
            <quickLaunchShortcutList>
                ...
                <quickLaunchShortcut>
                    <comment>Launch My Program</comment>
                    <exec>${installdir}/bin/myprogram</exec>
                    <icon></icon>
                    <name>My Program</name>
                    <path>${installdir}/bin</path>
                    <platforms>all</platforms>
                    <runInTerminal>0</runInTerminal>
                    <windowsExec>${installdir}/bin/myprogram.exe</windowsExec>
                    <windowsExecArgs></windowsExecArgs>
                    <windowsIcon></windowsIcon>
                    <windowsPath>${installdir}/bin</windowsPath>
                </quickLaunchShortcut>
                ...
                <quickLaunchLinkShortcut>
                    <comment>Launch a web browser pointing to My Program website</comment>
                    <icon></icon>
                    <name>Visit My Program website</name>
                    <platforms>all</platforms>
                    <runInTerminal>0</runInTerminal>
                    <url>http://my.company/myprogram</url>
                    <windowsIcon></windowsIcon>
                </quickLaunchLinkShortcut>
                ...
                <quickLaunchFileShortcut>
                    <comment>Check the user guide</comment>
                    <filePath>${installdir}/doc/userguide.txt</filePath>
                    <icon></icon>
                    <name>My Program User Guide</name>
                    <platforms>all</platforms>
                    <runInTerminal>0</runInTerminal>
                    <windowsIcon></windowsIcon>
                </quickLaunchFileShortcut>
                ...
            </quickLaunchShortcutList>
            ...
        </component>
        ...
    </componentList>
    ...
</project>