installer-framework/doc/tutorial.qdoc

/****************************************************************************
**
** Copyright (C) 2017 The Qt Company Ltd.
** Contact: http://www.qt.io/licensing/
**
** This file is part of the Qt Installer Framework.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see http://www.qt.io/terms-conditions. For further
** information use the contact form at http://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \contentspage {index.html}{Qt Installer Framework}
    \previouspage ifw-use-cases-settings.html
    \page ifw-tutorial.html
    \nextpage ifw-creating-installers.html

    \title Tutorial: Creating an Installer

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

    \image ifw-introduction-page.png "Introduction page"

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

    \list 1

        \li Create a \e {package directory} that will contain all the
            configuration files and installable packages.

        \li Create a \e {configuration file} that contains information about how
            to build the installer binaries and online repositories.

        \li Create a \e {package information file} that contains information
            about the installable components.

        \li Create installer content and copy it to the package directory.

        \li Use the \c binarycreator tool to create the \e installer.

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

    \endlist

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

    \section1 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 \c config and \c packages.

    \image ifw-tutorial-files.png

    For more information about the package directory, see \l{Package Directory}.

    \section1 Creating a Configuration File

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

    \quotefile ../examples/tutorial/config/config.xml

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

    \list

        \li The \c <Title> element specifies the installer name displayed on the
            title bar (1).

        \li The \c <Name> element specifies the application name that is added to
            the page name and introduction text (2).

    \endlist

    \image ifw-tutorial-introduction-page.png "Introduction page"

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

    \list

        \li The \c <Version> element specifies the application version number.

        \li The \c <Publisher> element specifies the publisher of the software
            (as shown in the Windows Control Panel, for example).

        \li The \c <StartMenuDir> element specifies the name of the default
            program group for the product in the Windows \gui Start menu.

        \li The \c <TargetDir> element specifies that the default target
            directory displayed to users is \c InstallationDirectory in the home
            directory of the current user (because the predefined variable
            \c @HomeDir@ is used as a part of the value). For more information,
            see \l{Predefined Variables}.

    \endlist

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

    \section1 Creating a Package Information File

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

    \quotefile ../examples/tutorial/packages/com.vendor.product/meta/package.xml

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

    For more information about the package information file, see
    \l{Package Information File Syntax}.

    \section2 Specifying Component Information

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

    \list

        \li The \c <DisplayName> element specifies the name of the component in
            the list of components (1).

        \li The \c <Description> element specifies the text that is displayed when
            the component is selected (2).

    \endlist

    \image ifw-tutorial-select-components.png

    \section2 Specifying Installer Version

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

    \section2 Adding Licenses

    The \c <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:

    \image ifw-tutorial-license-check.png "License check page"

    \section2 Selecting Default Contents

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

    \section1 Creating Installer Content

    Content to be installed is stored in the \c data directory of a component.
    As there is only one component, place the data in the
    \c{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
    \l{Data Directory}.

    \section1 Creating the Installer Binary

    You are now ready to create your first installer. Switch to the
    \c 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:

    \list

    \li On Windows:
    \code
    ..\..\bin\binarycreator.exe -c config\config.xml -p packages YourInstaller.exe
    \endcode

    \li On Linux or macOS:
    \code
    ../../bin/binarycreator -c config/config.xml -p packages YourInstaller
    \endcode

    \endlist

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

    For more information about using the \c binarycreator tool, see
    \l{binarycreator}.

    \note If an error message is displayed when you run the tutorial installer,
    check that you used a statically built Qt to create the installer. For more
    information, see \l{Configuring Qt}.
*/