Tutorial: Creating an Installer

This tutorial describes how to create a simple installer for a small project:

This section describes the following tasks that you must accomplish to create the installer:

1. Create a package directory that will contain all the configuration files and installable packages.
2. Create a configuration file that contains information about how to build the installer binaries and online repositories.
3. Create a package information file that contains information about the installable components.
4. Create installer content and copy it to the package directory.
5. Use the binarycreator tool to create the installer.

   The installer pages are created by using the information you provide in the configuration and package information file.

The example files are located in the examples\tutorial directory in the Qt Installer Framework repository.

Creating a Package Directory

Create a directory structure that reflects the design of the installer and allows the installer to be extended in the future. The directory must contain subdirectories called config and packages.

For more information about the package directory, see Package Directory.

Creating a Configuration File

In the config directory, create a file called config.xml with the following contents:

<?xml version="1.0" encoding="UTF-8"?>
<Installer>
    <Name>Your application</Name>
    <Version>1.0.0</Version>
    <Title>Your application Installer</Title>
    <Publisher>Your vendor</Publisher>
    <StartMenuDir>Super App</StartMenuDir>
    <TargetDir>@HomeDir@/InstallationDirectory</TargetDir>
</Installer>

The configuration file specifies the following information that is displayed on the introduction page:

• The <Title> element specifies the installer name displayed on the title bar (1).
• The <Name> element specifies the application name that is added to the page name and introduction text (2).

The other elements are used to customize the behavior of the installer:

• The <Version> element specifies the application version number.
• The <Publisher> element specifies the publisher of the software (as shown in the Windows Control Panel, for example).
• The <StartMenuDir> element specifies the name of the default program group for the product in the Windows Start menu.
• The <TargetDir> element specifies that the default target directory displayed to users is InstallationDirectory in the home directory of the current user (because the predefined variable @HomeDir@ is used as a part of the value). For more information, see Predefined Variables.

For more information about the configuration file format and the available elements, see Configuration File.

Creating a Package Information File

In this easy scenario, the installer handles only one component that is called com.vendor.product. To provide the installer with information about the component, create a file called package.xml with the following contents and place it in the meta directory:

<?xml version="1.0" encoding="UTF-8"?>
<Package>
    <DisplayName>The root component</DisplayName>
    <Description>Install this example.</Description>
    <Version>0.1.0-1</Version>
    <ReleaseDate>2010-09-21</ReleaseDate>
    <Licenses>
        <License name="Beer Public License Agreement" file="license.txt" />
    </Licenses>
    <Default>script</Default>
    <Script>installscript.qs</Script>
    <UserInterfaces>
        <UserInterface>page.ui</UserInterface>
    </UserInterfaces>
</Package>

The elements in the example file are described in more detail below.

For more information about the package information file, see Package Information File Syntax.

Specifying Component Information

The information from the following elements is displayed on the component selection page:

• The <DisplayName> element specifies the name of the component in the list of components (1).
• The <Description> element specifies the text that is displayed when the component is selected (2).

Specifying Installer Version

The <Version> element enables you to promote updates to users when they become available.

Adding Licenses

The <License> element specifies the name of the file that contains the text for the license agreement (1) that is displayed on the license check page:

Selecting Default Contents

The <Default> element specifies whether the component is selected by default. The value true sets the component as selected. In this example, we use the value script to resolve the value during runtime. The name of the JavaScript script file, installscript.qs, is specified in the <Script> element.

Creating Installer Content

Content to be installed is stored in the data directory of a component. As there is only one component, place the data in the packages/com.vendor.product/data directory. The example already contains a file for testing purposes, but you can place basically any files in the directory.

For more information about packaging rules and options, see Data Directory.

Creating the Installer Binary

You are now ready to create your first installer. Switch to the examples\tutorial directory on the command line. To create an installer called YourInstaller.exe that contains the packages identified by com.vendor.product, enter the following command:

• On Windows:

  ..\..\bin\binarycreator.exe -c config\config.xml -p packages YourInstaller.exe

• On Linux or macOS:

  ../../bin/binarycreator -c config/config.xml -p packages YourInstaller

The installer is created in the current directory and you can deliver it to end users.

For more information about using the binarycreator tool, see binarycreator.