path: root/doc/installerfw.qdoc

/****************************************************************************
**
** Copyright (C) 2015 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://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$
**
****************************************************************************/

// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************

/*!
    \contentspage{index.html}{Qt Installer Framework}
    \page index.html
    \nextpage ifw-overview.html

    \title Qt Installer Framework Manual

    \section1 Version \ifwversion

    The Qt Installer Framework provides a set of tools and utilities to
    create installers for the supported desktop Qt platforms: Linux, Microsoft
    Windows, and OS X.

    \note Report bugs and suggestions for the Qt Installer Framework project
    in the \l{https://bugreports.qt.io/browse/QTIFW}{Qt Bugtracker}.

    \list
        \li \l{Overview of Qt Installer Framework}
        \li \l{Getting Started}
        \li \l{End User Workflows}
        \list
            \li \l{Initial Installation}
            \li \l{Adding Components}
            \li \l{Removing Components}
            \li \l{Updating Components}
            \li \l{Specifying Settings}
        \endlist
        \li \l{Tutorial: Creating an Installer}
        \li \l{Creating Installers}
        \list
            \li \l{Creating Offline Installers}
            \li \l{Creating Online Installers}
            \li \l{Promoting Updates}
            \li \l{Customizing Installers}
        \endlist
        \li \l{Qt Installer Framework Examples}
        \li \l{Reference}
        \list
            \li \l{Configuration File}
            \li \l{Package Directory}
            \li \l{Controller Scripting}
            \li \l{Component Scripting}
            \li \l{Operations}
            \li \l{Tools}
            \li \l{Scripting API}
            \li \l{C++ API}
        \endlist
        \li \l{Known Issues}
    \endlist
*/

/*!
    \contentspage index.html
    \previouspage ifw-tutorial.html
    \page ifw-creating-installers.html
    \nextpage ifw-offline-installers.html

    \title Creating Installers

    The following steps are needed to create offline and online installers:

    \list 1

        \li Create a \e {package directory} for the installable components.
            For more information, see \l{Package Directory}.

        \li Create a configuration file called \c config.xml in the \c config
            directory. It contains information about how to build the installer
            binaries and online repositories. For more information about the
            file format and available settings, see
            \l{Configuration File}.

        \li Create a package information file called \c package.xml in the
            \c {config\meta} directory. It contains settings for deployment and
            the installation process. For more information, see
            \l{Meta Directory}.

        \li Create installer content and copy it to the package directory.
            For more information, see \l{Data Directory}.

        \li For online installers, use the \c repogen tool to create the
            repository that contains the installable content and upload the
            repository to a web server.

        \li Use the \c binarycreator tool to create the installer. For more
            information, see \l{Tools}.

    \endlist

    For an example of how to create a simple installer that uses the predefined
    installer pages, see \l{Tutorial: Creating an Installer}.

    The following sections describe how to create different types of installers:

    \list
        \li \l{Creating Offline Installers}
        \li \l{Creating Online Installers}
        \li \l{Promoting Updates}
        \li \l{Customizing Installers}
    \endlist
*/

/*!
    \contentspage index.html
    \previouspage ifw-reference.html
    \page ifw-globalconfig.html
    \nextpage ifw-component-description.html

    \title Configuration File

    The configuration file customizes the UI and behavior of an installer.
    The file is typically called \c config.xml and located in the
    \c config directory.

    A minimal configuration file consists of an \c <Installer> root element
    with \c <Name> and \c <Version> elements as children. All other elements
    are optional, and can appear in arbitrary order.

    The following example shows a typical configuration file:

    \quotefile examples/config.xml

    \section1 Summary of Configuration File Elements

    The following table summarizes the elements in the configuration file.

    \note We recommend that you place all files that you refer to in the
    configuration file in the \c config directory. However, you can also use
    relative paths, which the tools resolve relative to the location of
    the config.xml file.

    You can use predefined variables (embedded in @ characters) as values of the
    elements. For more information, see \l{Predefined Variables}.

    \table
        \header
            \li Element
            \li Description
        \row
            \li Name
            \target ProductNameTarget
            \li Name of the product being installed. This is mandatory.
        \row
            \li Version
            \li Version of the product being installed in the following format:
                [0-9]+((\\.|-)[0-9]+)* such as 1-1; 1.2-2; 3.4.7. This is
                mandatory.
        \row
            \li Title
            \li Name of the installer as displayed on the title bar.
        \row
            \li Publisher
            \li Publisher of the software (as shown in the Windows Control Panel).
        \row
            \li ProductUrl
            \li URL to a page that contains product information on your web
                site.
        \row
            \li Icon
            \li Filename for a custom installer icon. The actual file is looked up by attaching
                a '.icns' (OS X), '.ico' (Windows) or '.png' (Unix) suffix. Deprecated,
                use \c <InstallerApplicationIcon> or \c <InstallerWindowIcon>
                instead.
        \row
            \li InstallerApplicationIcon
            \li Filename for a custom installer icon. The actual file is looked up by attaching
                a '.icns' (OS X), '.ico' (Windows). No functionality on Unix.
        \row
            \li InstallerWindowIcon
            \li Filename for a custom window icon in PNG format for the Installer application.
        \row
            \li Logo
            \li Filename for a logo used as \c QWizard::LogoPixmap.
        \row
            \li Watermark
            \li Filename for a watermark used as \c QWizard::WatermarkPixmap.
        \row
            \li Banner
            \li Filename for a banner used as \c QWizard::BannerPixmap (only used by ModernStyle).
        \row
            \li Background
            \li Filename for an image used as \c QWizard::BackgroundPixmap (only used by MacStyle).
        \row
            \li WizardStyle
            \li Set the wizard style to be used ("Modern", "Mac", "Aero" or "Classic").
        \row
            \li WizardDefaultWidth
            \li Sets the default width of the wizard in pixels. Setting a banner image will
                override this.
        \row
            \li WizardDefaultHeight
            \li Sets the default height of the wizard in pixels. Setting a watermark image will
                override this.
        \row
            \li TitleColor
            \li Set the color of the titles and subtitles (takes an HTML color code,
                such as "#88FF33").
        \row
            \li RunProgram
            \li Command executed after the installer is done if the user accepts
                the action. Provide the full path to the application.
        \row
            \li RunProgramArguments
            \li Arguments passed to the program specified in \c <RunProgram>.
                You can add several \c <Argument> child elements that each specify an
                argument to \c <RunProgram>.
        \row
            \li RunProgramDescription
            \li Text shown next to the check box for running the program after
                the installation. If \c <RunProgram> is set but no description provided,
                the UI will display \uicontrol {Run <Name> now.} instead.
        \row
            \li StartMenuDir
            \li Name of the default program group for the product in the Windows
                \uicontrol Start menu.
        \row
            \li TargetDir
            \li Default target directory for installation. On Linux, this is
                usually the user's home directory.
        \row
            \li AdminTargetDir
            \li Default target directory for installation with administrator
                rights. Only available on Linux, where you usually do not want
                to install in the administrator user's home directory.
        \row
            \li RemoteRepositories
            \li List of remote repositories. This element can contain several \c <Repository> child
                elements that each contain the \c <Url> child element that specifies the URL to
                access the repository. For more information,  see \l{Configuring Repositories}.
        \row
            \li MaintenanceToolName
            \li Filename of the generated maintenance tool. Defaults to
                \e maintenancetool. The platform-specific executable file extension is
                appended.
        \row
            \li MaintenanceToolIniFile
            \li Filename for the configuration of the generated maintenance tool. Defaults to
                \e {MaintenanceToolName}.ini.
        \row
            \li RemoveTargetDir
            \li Set to \c false if the target directory should not be deleted when uninstalling.
        \row
            \li AllowNonAsciiCharacters
            \li Set to \c true if the installation path can contain non-ASCII
                characters.
        \row
            \li RepositorySettingsPageVisible
            \li Set to \c false to hide the repository settings page inside the settings dialog.
        \row
            \li AllowSpaceInPath
            \li Set to \c false if the installation path cannot contain space characters.
        \row
            \li DependsOnLocalInstallerBinary
            \li Set to \c true if you want to prohibit installation from an external resource, such
                as a network drive. This might make sense for e.g. very big installers.
                The option is only used on Windows.
        \row
            \li TargetConfigurationFile
            \li Filename for the configuration file on the target. Default is components.xml.
        \row
            \li Translations
            \li List of language codes to be used for translating the user interface. To add several language
                variants, specify several \c <Translation> child elements that each specify the name
                of a language variant. Optional. For more information, see \l{Translating Pages}.
        \row
            \li UrlQueryString
            \li This string needs to be in the form "key=value" and will be appended to archive download
                requests. This can be used to transmit information to the webserver hosting the repository.
        \row
            \li ControlScript
            \li Filename for a custom installer control script. See \l{Controller Scripting}.
        \row
            \li CreateLocalRepository
            \li Set to \c true if you want to create a local repository inside the installation directory.
                This option has no effect on online installers. The repository will be automatically added
                to the list of default repositories.

    \endtable

*/

/*!
    \contentspage index.html
    \previouspage ifw-updates.html
    \page ifw-customizing-installers.html
    \nextpage Qt Installer Framework Examples

    \title Customizing Installers

    You can use scripting to customize installers by:

    \list

        \li Adding Qt Installer Framework \e operations that are prepared by the
            scripts and performed by the installer.

        \li Adding new pages that you specify in the package.xml file and place
            in the \c packages directory.

        \li Modifying existing pages by inserting custom user interface
            elements into them as single widgets.

        \li Adding language variants.

    \endlist

    You can use both \e {component scripts} and a \e {control script} to
    customize installers. A component script is associated with a particular
    component by specifying it in the \c Script element of the package.xml
    file of the component. The script is loaded when the component's metadata is
    fetched. For more information about component scripts, see
    \l{Component Scripting}.

    A control script is associated with the whole installer by specifying it
    in the \c ControlScript element of the control.xml file of the installer.
    Control scripts can be part of the installer resources or be passed on the
    command line. They can be used to modify the installer pages that are
    presented to users before components are loaded. Also, you can use them to
    modify pages in the uninstaller. For more information, see
    \l{Controller Scripting}.

    For more information about the global JavaScript objects that can be used in
    component and control scripts, see \l{Scripting API}.

    \section1 Adding Operations

    You can use component scripts to perform Qt Installer Framework operations
    during the installation process. Typically, operations manipulate files by
    moving, copying, or patching them. Use the
    QInstaller::Component::addOperation or
    QInstaller::Component::addElevatedOperation function to add operations. For
    more information, see \l {Adding Operations to Components}.

    In addition, you can implement methods to register custom installation
    operations in the installer by deriving KDUpdater::UpdateOperation. For
    more information, see \l {Registering Custom Operations}.

    For a summary of available operations, see \l {Operations}.

    \section1 Adding Pages

    A component can contain one or more user interface files, which are placed
    into the installer by a component or control script. The installer
    automatically loads all user interface files listed in the
    \c UserInterfaces element of the package.xml file.

    \section2 Using Component Scripts to Add Pages

    To add a new page to the installer, use
    the installer::addWizardPage() method and specify the location
    of the new page. For example, the following code adds an instance of
    \c MyPage before the ready for installation page:

    \code
    installer.addWizardPage( component, "MyPage", QInstaller.ReadyForInstallation );
    \endcode

    You can use component scripts to access the loaded widgets
    by calling the \l component::userInterface() method with the class name of
    the widget, as illustrated by the following code snippet:

    \code
    component.userInterface( "MyPage" ).checkbox.checked = true;
    \endcode

    \section2 Using Control Scripts to Add Pages

    To register a custom page, use the installer::addWizardPage() method
    and the object name set in the UI file (for example, \c "MyPage"). Then
    call the \c{Dynamic${ObjectName}Callback()} function (for example,
    \c {DynamicMyPageCallback()}):

    \code
    function Controller()
    {
        installer.addWizardPage(component, "MyPage", QInstaller.TargetDirectory)
    }

    Controller.prototype.DynamicMyPageCallback()
    {
        var page = gui.pageWidgetByObjectName("DynamicMyPage");
        page.myButton.click,
        page.myWidget.subWidget.setText("hello")
    }
    \endcode

    You can access widgets by using their object names that are set in the UI
    file. For example, \c myButton and \c myWidget are widget object names in
    the code above.

    \section1 Adding Widgets

    You can use component or control scripts to insert custom user interface
    elements into the installer as single widgets (such as a check box).

    To insert a single widget, use the installer::addWizardPageItem method.
    For example, the following code snippet adds an instance of \c MyWidget to
    the component selection page from within a script:

    \code
    installer.addWizardPageItem( component, "MyWidget", QInstaller.ComponentSelection );
    \endcode

    \section1 Interacting with Installer Functionality

    You can use control scripts to execute installer functions automatically in
    tests, for example. The following snippet illustrates how to automatically
    click the \uicontrol Next button on the target directory selection page:

    \code
        Controller.prototype.TargetDirectoryPageCallback = function()
        {
            gui.clickButton(buttons.NextButton);
        }
    \endcode

    \section1 Translating Pages

    The installer uses the Qt Translation system to support the translation of
    user-readable output to several languages. To provide end users with
    localized versions of strings contained in the component scripts and user
    interfaces, create QTranslator files that the installation system loads
    along with the component. The installer loads the translation file that
    matches the current system locale. For example, if the system locale is
    German, the de.qm file is loaded. In addition, a localized \c license_de.txt
    is shown instead of the default \c license.txt if it is found.

    Translations need to be added to the \c package.xml file to be activated for
    a component:

    \code
        <Translations>
            <Translation>de.qm</Translation>
        </Translations>
    \endcode

    Use the \c {qsTr()} function for literal text within scripts. Additionally,
    you can add the \c Component.prototype.retranslateUi method to the script.
    It is called when the language of the installer changes and the translation
    file is loaded.

    The context being used for translation is the basename of the script file
    when using \c qsTr or the class name of the UI file when translating a user
    interface. For example, if the script file is called \c installscript.qs, the
    context will be installscript.

    \note The translation system can also be used to customize the UI. Use e.g.
    an \c en.ts file to replace any text in the installer with a custom English
    version.
*/

/*!
    \contentspage index.html
    \previouspage ifw-globalconfig.html
    \page ifw-component-description.html
    \nextpage noninteractive.html

    \title Package Directory

    Installers contain components that are either embedded to the installer
    or loaded from a remote repository. In both cases, you need to use a file
    format and structure for the components that the installer can read.

    \section1 Package Directory Structure

    Place all components in the same root directory, which is called the
    \e {package directory}. The directory name acts as a domain-like identifier,
    which identifies all components. For example, \c com.vendor.root.

    Within the root directory, create subdirectories called \c data and \c meta.

    A package directory can look as follows:
    \code
    -packages
        - com.vendor.root
            - data
            - meta
        - com.vendor.root.component1
            - data
            - meta
        - com.vendor.root.component1.subcomponent1
            - data
            - meta
        - com.vendor.root.component2
            - data
            - meta
    \endcode

    \section1 Meta Directory

    The \c meta directory contains files that specify settings for deployment
    and the installation process. The files are not extracted by the installer.
    The directory must contain at least a package information file and all files
    that you refer to in the package information file, such as scripts,
    user interface files, and translations.

    \section2 Package Information File Syntax

    The package.xml file is the main source of information about a component.
    The following is an example of a package file:

    \quotefile examples/package.xml

    \section2 Summary of Package Information File Elements

    \table
        \header
            \li Element
            \li Description
        \row
            \li DisplayName
            \li Human-readable name of the component. Required.
        \row
            \li Description
            \li Human-readable description of the component. Required.
                Specify translations for the description as values of additional
                Description tags, with the xml:lang attribute set to the correct locale.
                If a localization that matches the locale is not found and an untranslated
                version exists, that one will be used. Otherwise no Description will be
                shown for that locale.
        \row
            \li Version
            \li Version number of the component in the following format:
                [0-9]+((\\.|-)[0-9]+)* such as 1-1; 1.2-2; 3.4.7. Required.
                If a package needs to show the version number from a child rather than it's own (due to
                grouping of child packages) one can specify the attribute inheritVersionFrom with the package
                name the version needs to be inherited from.
        \row
            \li ReleaseDate
            \li Date when this component version was released. Required.
        \row
            \li Name
            \li Domain-like identification for this component. Required.
        \row
            \li Dependencies
            \li Comma-separated list of identifiers of components that this
                component depends on. Optionally, you can specify version
                numbers, separated by a dash (-). You can prefix version numbers
                with a comparison operator (=, >, <, >= or  <=). Keep in mind
                that you have to use the character reference "&lt;" to escape
                the left angle bracket (use "&lt;" instead of "<" and "&lt;="
                instead of "<="). Optional. For more information, see
                \l{Component Dependencies}.
        \row
            \li AutoDependOn
            \li Comma-separated list of identifiers of components that
                this component has an automatic dependency on.
                The component is installed if and only if
                all of the specified dependencies are fulfilled.
                If a component has an automatic dependency on other components,
                the check box will not be visible next to the component in the component tree.
                The selection will be performed automatically.
                If the component was not installed before, it will
                be selected for installation only when all components
                from this list are also selected for installation.
                If the component was already installed, it will
                be selected for uninstallation when at least one of the components
                from this list is also selected for uninstallation.
                For more information, see \l{Component Dependencies}.
        \row
            \li Virtual
            \li Set to \c true to hide the component from the installer.
                Note that setting this on a root component does not work.
        \row
            \li SortingPriority
            \li Priority of the component in the tree. The tree is sorted from
                highest to lowest priority, with the highest priority on the top.
        \row
            \li Licenses
            \li List of license agreements to be accepted by the installing
                user. To add several licenses, add several \c <License> child
                elements that each specify the license \c name and \c file.
                If there are translations listed for this component, the installer
                will also look for translated licenses. These need to have the
                same name as the original license file but with an added
                locale identifier.
                If for example the license file is called license.txt and there is
                German translation specified, the installer will also include
                a license_de_de.txt file (and show that when installing on a
                German system).
        \row
            \li Script
            \li File name of a script being loaded. Optional.
                For more information, see \l{Adding Operations}.
        \row
            \li UserInterfaces
            \li List of pages to load. To add several pages, add several
                \c <UserInterface> child elements that each specify the filename of a
                page. Optional. For more information, see \l{Adding Pages}.
        \row
            \li Translations
            \li List of translation files to load. To add several language
                variants, specify several \c <Translation> child elements that each
                specify the filename of a language variant. Optional. For more
                information, see \l{Translating Pages}.
        \row
            \li UpdateText
            \li Description added to the component description if this is an
                update to the component. Optional.
        \row
            \li Default
            \li Possible values are: \c true, \c false, and \c script. Set to
                \c true to preselect the component in the installer.
                This takes effect only on components that have no visible
                child components.
                The boolean values are evaluated directly, while \c script is
                resolved during runtime. Add the name of the script as a value
                of the \c <Script> element in this file. For an example script,
                see \l{Selecting Default Contents}.
        \row
            \li Essential
            \li Marks the package as essential to force a restart of the
                \c MaintenanceTool. If there are updates available
                for an essential component, the package manager stays disabled
                until that component is updated. Newly introduced essential components
                are automatically installed when running the updater.
        \row
            \li ForcedInstallation
            \li Determines that the package must always be installed. End users
                cannot deselect it in the installer.
        \row
            \li Replaces
            \li Comma-separated list of components to replace. Optional.

        \row
            \li DownloadableArchives
            \li Lists the data files (separated by commas) for an online
                installer to download.
                If there is some data inside the component and the package.xml
                and/or the script has no DownloadableArchives value, the
                repogen tool registers the found data automatically.

        \row
            \li RequiresAdminRights
            \li Set to \c true if the package needs to be installed with elevated permissions.
                Optional.
    \endtable

    \section2 Component Dependencies

    Components can depend on one or several real or virtual components.
    Dependencies are defined by using the component identifier and, optionally,
    component version. Use a dash (-) to separate version numbers from
    identifiers.

    You can prefix version numbers with a comparison operator (=, >, &lt; (<), >= or
    &lt;= (<=)) to indicate that the version number of the package is compared to the
    required version and has to be equal to, greater than, less than, greater
    than or equal to, or less than or equal to the version number specified in
    the dependency. If no comparison operator is given, it defaults to =.

    \section1 Data Directory

    The \c data directory contains the content that the installer extracts
    during the installation. You must package the data as a 7zip archive (.7z).
    You can use either the \l archivegen tool that is delivered with the Qt
    Installer Framework or some other tool that generates 7zip archives.
*/

/*!
    \contentspage index.html
    \previouspage operations.html
    \page ifw-tools.html
    \nextpage Scripting API

    \title Tools

    The Qt Installer Framework contains the following tools:

    \list

        \li \l installerbase

        \li \l binarycreator

        \li \l repogen

        \li \l archivegen

    \endlist

    \section1 installerbase
    The \c installerbase tool describes the core installer itself. All data and
    meta information will be packed to this binary. For the installer creation
    process you will not need to call it directly.

    \section1 binarycreator
    Use the \c binarycreator tool to create offline and online installers.
    Component information and data are appended to the offline installer binary,
    which enables the file extraction and post installation scripts to work
    without an Internet connection.

    Online installers store the location of the repository that contains the
    data. On startup, they load the component information, not the data.

    You can also create hybrid installers that store some components locally
    and receive others via a network connection. For more information, see
    ###TODO insert link here.

    For information about how to implement data integration into the
    installer binary, see QInstaller::BinaryContent.

    \note If you change this configuration, you must recompile the
    \c installerbase tool.

    \section2 Using binarycreator

    You can use the \c binarycreator tool to create offline and online
    installers. Some options have default values, and therefore, you can omit
    them.

    To create an offline installer (in Windows), enter the following command:

    \list

        \li On Windows:
    \code
    <location-of-ifw>\binarycreator.exe -t <location-of-ifw>\installerbase.exe -p <package_directory> -c <config_directory>\<config_file> <installer_name>
    \endcode

        \li On Linux and OS X

    \code
    <location-of-ifw>/binarycreator -t <location-of-ifw>/installerbase -p <package_directory> -c <config_directory>/<config_file> <installer_name>
    \endcode

    \endlist

    To create an online only installer, you can use the --online-only which defines all
    packages to install from an online repository on a web server:

    \list

        \li On Windows:
    \code
    <location-of-ifw>\binarycreator.exe -t <location-of-ifw>\installerbase.exe -p <package_directory> -c <config_directory>\<config_file> -e <packages> <installer_name>
    \endcode

        \li On Linux and OS X

    \code
    <location-of-ifw>/binarycreator -t <location-of-ifw>/installerbase -p <package_directory> -c <config_directory>/<config_file> -e <packages> <installer_name>
    \endcode

    \endlist

    \section2 Summary of binarycreator Parameters

    The \c binarycreator tool accepts the following parameters:
    \table
        \header
            \li Parameter
            \li Use
        \row
            \li -t or --template file
            \li Use \c file as an installer template binary to which the
                component information is appended. If you omit this parameter,
                the \c installerbase template is used.
        \row
            \li -p or --packages directory
            \li Use \c directory as the \l{Package Directory Structure}
                {package directory}.
                Defaults to the current working directory.
        \row
            \li -n or --online-only
            \li Compile without any component in the installer binary.
        \row
            \li -f or --offline-only
            \li Create an offline installer that never accesses online
                repositories.
        \row
            \li -c or --config file
            \li Use \c file as the \l{Configuration File}
                {config file}.
        \row
            \li -e or --exclude p1,...,pn
            \li Comma-separated list of packages to retrieve from an online
                repository. The packages are not included in the installer
                binary.
        \row
            \li -i or --include p1,...,pn
            \li Comma-separated list of packages to retrieve from the installer
                binary. You cannot combine or merge \c {--include} and \c {--exclude}.
        \row
            \li -r or --resources
            \li Comma-separated list of resources to include in the installer
                binary.
        \row
            \li --ignore-translations
            \li Disable the use of translation files to make testing faster.
        \row
            \li --ignore-invalid-packages
            \li Ignore component or package directories that do not have valid
                metadata information (package.xml) to make testing faster.
        \row
            \li -v or --verbose
            \li Display debug output.
    \endtable

    These parameters are followed by the name of the target binary and a list
    of packages to be available for installation.

    \note The listed packages are included in the installer, as well as all
    their dependencies and all packages that share the same prefix, unless you
    specify the \c --nodeps parameter.

    On Windows, the name of the target binary is automatically extended with
    .exe, if you do not specify the extension. On Mac, the target is
    created as an application bundle with the extension .app, which is automatically
    added, if not supplied. Additionally, you can specify the .dmg extension,
    which creates a DMG disk image that contains an .app bundle.

    \section2 Using Icons

    On OS X, if the target binary is suffixed with .app, a OS X
    application bundle is created. The icon that you specify in config.xml is
    extended with .icns and used as the icon for the created bundle.

    On Windows, the icon that you specify in config.xml is extended with .ico
    and used as the application icon for the .exe file.

    On Linux, the icon that you specify in config.xml is extended with .png and
    used as the window icon.

    \section1 repogen

    Use the \c repogen tool to generate online repositories.

    The \c repogen tool expects the following parameters in the following order:

    \code
    repogen.exe -p <package_directory> <repository_directory>
    \endcode

    When the repository has been created, you can upload it anywhere. You must
    specify the location in the installer configuration file when creating an
    installer for it.

    \section2 Summary of repogen Parameters

    \table
        \header
            \li Parameter
            \li Use
        \row
            \li -p or --packages directory
            \li Use \c directory as the \l{Package Directory Structure}
                {package directory}. This is mandatory.
        \row
            \li repository directory
            \li Target directory for the repository. During an initial installation, the directory
                must not yet exist. When updating, the directory may exist and its contents may be
                overwritten or removed. This is mandatory.
        \row
            \li -e or --exclude p1,...,pn
            \li Comma-separated list of packages to be ignored from the set of
                all packages in the packages directory.
        \row
            \li -i or --include p1,...,pn
            \li Comma-separated list of packages to be used from the set of
                all packages in the packages directory.
        \row
            \li --update
            \li Update all packages in the packages directory. The list can be further
                filtered with the \c {-i}, \c {-e} parameters.
        \row
            \li --update-new-packages
            \li Update only packages that are new or have a newer version. The
                list can be further filtered with the \c {-i}, \c{-e}
                parameters.
        \row
            \li -r or --remove
            \li Force removal of existing target directory before generating it again.
        \row
            \li -v or --verbose
            \li Display debug output.
    \endtable
    \note We recommend that you use the \c {--update-new-packages} parameter
          to update an existing repository, especially if you have a content delivery
          system. This helps you avoid updating components that have not changed and
          this makes it much easier for a content delivery system to distribute only
          new files, because only the updated components are assigned new SHA
          checksums.

    \section1 archivegen

    You can use \c archivegen to package files and directories into 7zip (.7z)
    archives.

    The \c archivegen tool expects the following parameters in the following
    order:

    \code
    archivegen <name.7z> <data>
    \endcode

    Where \e <name.7z> is the path and file name of the archive to create and
    \e <data> contains the paths and names of the files or directories to
    package into the archive, separated by spaces.
*/

/*!
    \contentspage index.html
    \previouspage ifw-offline-installers.html
    \page ifw-online-installers.html
    \nextpage ifw-updates.html

    \title Creating Online Installers

    Online installers fetch the repository description (Updates.xml), in
    addition to the one stored inside of the binary. Create a repository and
    upload it to a web server. Then specify the location of the repository in
    the config.xml file that you use to create the installer.

    \section1 Creating Repositories

    Use the \c repogen tool to create online repositories of all packages of one package directory:

    repogen.exe -p <package_directory> <repository_directory>

    For example, to create a repository that contains only org.qt-project.sdk.qt and
    org.qt-project.sdk.qtcreator, enter the following
    command:

    \code
    repogen.exe -p packages -i org.qt-project.sdk.qt,org.qt-project.sdk.qtcreator repository
    \endcode

    When the repository has been created, upload it to a web server. You must
    specify the location of the repository in the installer configuration file.

    \section1 Configuring Repositories

    The \c <RemoteRepositories> element in the installer configuration file
    (config.xml) can contain a list of several repositories. Each of them can
    have the following settings:

    \list

        \li \c <Url>, which points to a list of available components.
        \li \c <Enabled>, with 0 disabling this repository.
        \li \c <Username>, which is used as user on a protected repository.
        \li \c <Password>, which sets the password to use on a protected
            repository.
        \li \c <DisplayName>, which optionally sets a string to display instead
            of the URL.

    \endlist

    The URL needs to point to the Updates.xml file that lists the available
    components. For example:

    \code
    <RemoteRepositories>
         <Repository>
                 <Url>http://www.example.com/packages</Url>
                 <Enabled>1</Enabled>
                 <Username>user</Username>
                 <Password>password</Password>
                 <DisplayName>Example repository</DisplayName>
         </Repository>
    </RemoteRepositories>
    \endcode

    The installer works only if it can access the repository. If the repository is
    accessed after the installation, the maintenance tool rejects installation.
    However, uninstallation is still possible.
    A repository can be enabled or disabled by default.
    For repositories requiring authentication, the details can also be set here,
    although entering a password here is usually not advisable as it is saved in plain
    text. Authentication details not set here will be gotten at runtime using a dialog.
    The user can work around these settings at runtime.


    \section1 Creating Installer Binaries

    To create an online installer by using the \c binarycreator tool, enter the
    following command:

    \code
    <location-of-ifw>\binarycreator.exe -t <location-of-ifw>\installerbase.exe -p <package_directory> -c <config_directory>\<config_file> -e <packages> <installer_name>
    \endcode

    For example, enter the following command to create an installer binary
    called SDKInstaller.exe that will not contain data for org.qt-project.sdk.qt and
    org.qt-project.qtcreator, because those packages are downloaded from a remote
    repository:

    \code
    binarycreator.exe -p installer-packages -c installer-config\config.xml -e org.qt-project.sdk.qt,org.qt-project.qtcreator SDKInstaller.exe
    \endcode

    \section1 Reducing Installer Size
    Even if the components are fetched from a web server, \c binarycreator adds
    them to the installer binary by default. However, when the installer checks
    the web server for updates, end users are spared a download if new versions
    are not available.

    Alternatively, you can create online installers that do not contain any data
    and that fetch all the data from the web server. Use the \c{-n} parameter
    of the \c binarycreator tool and only add the root component to the
    installer. Usually the root component is empty and hence only adds the XML
    description of the root.

    For more information about the options that you have, see
    \l{Summary of binarycreator Parameters}.
*/

/*!
    \contentspage index.html
    \previouspage ifw-creating-installers.html
    \page ifw-offline-installers.html
    \nextpage ifw-online-installers.html

    \title Creating Offline Installers

    Offline installers do not try to connect to an online repository at all
    during installation. However, the metadata configuration (config.xml)
    enables users to add and update components online.

    Offline installers are especially useful in cases where a corporate firewall
    does not allow end users to connect to web servers. The network
    administrator can set up a local update service within the network.

    To create offline installers, use the \c{--offline-only} option of the
    \c binarycreator tool.

    To create an offline installer in Windows, enter the following command:

    \code
    <location-of-ifw>\binarycreator.exe --offline-only -t <location-of-ifw>\installerbase.exe -p <package_directory> -c <config_directory>\<config_file> <installer_name>
    \endcode

    Some options have default values, and therefore, you can omit them.
    For example, enter the following command to create an installer binary
    called SDKInstaller.exe that contains the packages identified by
    org.qt-project.sdk and their dependencies:

    \code
    binarycreator.exe --offline-only -c installer-config -p installer-packes SDKInstaller.exe
    \endcode

*/

/*!
    \contentspage index.html
    \previouspage ifw-online-installers.html
    \page ifw-updates.html
    \nextpage ifw-customizing-installers.html

    \title Promoting Updates

    Create online installers to be able to promote updates to end users who
    install your product.

    The following steps are needed to promote updates:

    \list 1

        \li Copy the updated content to the package directory.

        \li Increase the value of the \c <Version> element for the updated
            components in the package.xml file.

        \li Use the \c repogen tool to recreate the online repository with the
            updated contents and to generate the Updates.xml file in the root
            directory of the repository.

        \li Upload the repository to the web server.

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

    \endlist

    \section1 Configuring Updates

    The installer downloads the Updates.xml file on
    startup and compares the installed version with the version in the file. If
    the online version number in the file is greater than the local one, the
    installer displays it in the list of available updates.

    Increase the value of the \c <Version> element for the component in the
    package.xml file.

    \section1 Recreating Repositories

    The easiest way to provide an update is to recreate the repository and
    upload it to the web server. For more information, see
    \l{Creating Repositories}.

    \section1 Partially Updating Repositories

    A full update of the whole repository might not be optimal if:
    \list
        \li The repository is very large, as uploading would take a long time.
        \li You want to deliver only the changed components.
    \endlist

    \note repogen recreates the 7zip archives each time it is being called. As
    7zip stores the timestamps of the included files (which are moved or copied
    during this process), the SHA sum of each archive changes. SHA sums are used
    to verify the download of the archive and hence the SHA needs to match the
    7zip. As the SHAs are stored in the Updates.xml file you will be
    forced to upload the full repository. This can be circumvented by using the
    \c{--update} option of repogen.

    \section2 Creating Partial Updates
    When recreating the online repository, use the \c{--update} parameter. It
    takes an existing repository as input and only changes the components that
    are specified as additional parameters. Only those SHA sums are
    changed in the global configuration as well.

    \section2 Uploading Partial Updates
    Upload the following items to the web server:
    \list
    \li The component directory (usually something like
    \c{com.vendor.product.updatedpart}).
    \li The global \c{Updates.xml} stored in the root directory of the online
    repository.
    \endlist

    \note The order of uploading items is very important. If you update the
    repository on a live server, first update the component and
    then Updates.xml. The package names include version numbers, and therefore,
    end users receive old packages until the new ones are fully uploaded.

    \section1 Changing Repositories

    To have the current update repository point to other repositories, edit the
    Updates.xml file in the current repository. You can add, replace, or remove
    repositories.

    \code
    <RepositoryUpdate>
      <Repository action="..." OPTIONS />
      <Repository action="..." OPTIONS />
    </RepositoryUpdate>
    \endcode

    \section2 Adding Repositories
    To update a repository, add a \c <Repository> child element to the
    \c <RepositoryUpdate> element with the following options:

    \code
    <Repository action="add" url="http://www.example.com/repository" name="user" password="password"
                 displayname="Example Repository" />
    \endcode

    \section2 Removing Repositories
    To remove a repository, add a \c <Repository> child element to the
    \c <RepositoryUpdate> element with the following options:

    \code
    <Repository action="remove" url="http://www.example.com/repository" />
    \endcode

    \section2 Replacing Repositories
    To replace one repository with another, add a \c <Repository> child element to the
    \c <RepositoryUpdate> element with the following options:

    \code
    <Repository action="replace" oldurl="http://www.example.com/repository"
                newurl="http://www.example.com/newrepository" name="user" password="password"
                displayname="New Example Repository" />
    \endcode
*/

/*!
    \contentspage index.html
    \previouspage ifw-cpp-classes.html
    \page ifw-knownissues.html
    \nextpage index.html

    \title Known Issues

    Check the \l{https://bugreports.qt.io/browse/QTIFW}{Qt Bugtracker}
    for known issues in the Qt Installer Framework project. If you cannot find
    the issue there, create a bug report.
*/