/****************************************************************************
**
** 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$
**
****************************************************************************/

// **********************************************************************
// 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 StyleSheet
            \li Set the stylesheet file.
        \row
            \li WizardDefaultWidth
            \li Sets the default width of the wizard in pixels. Setting a banner image will
                override this. You can add the \c em or \c ex suffix to the specified value to
                use the \e em or \e ex unit, as in a CSS file.
        \row
            \li WizardDefaultHeight
            \li Sets the default height of the wizard in pixels. Setting a watermark image will
                override this. You can add the \c em or \c ex suffix to the specified value to
                use the \e em or \e ex unit, as in a CSS file.
        \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 RepositoryCategories
            \li Name of a category that can contain a list of \c <RemoteRepositories> child elements.
                For more information,  see \l{Configuring Repository Categories}.
        \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 DisableAuthorizationFallback
            \li Set to \c true if the installation should not ask users to run the authorization
                fallback in case of authorization errors. Instead abort the installation immediately.
        \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.
        \row
            \li InstallActionColumnVisible
            \li Set to \c true if you want to add an extra column into component tree showing install actions.
                This extra column indicates whether a component is going to be installed or uninstalled,
                or just stay installed or uninstalled.
        \row
            \li SupportsModify
            \li Set to \c false if the product does not support modifying an existing installation.
         \row
            \li SaveDefaultRepositories
            \li Set to \c false if default repositories \c <RemoteRepositories> should not be saved to \e {MaintenanceToolName}.ini.
                By default default repositories are saved. Not saving the repositories means than when you run  \e maintenancetool
                there are no default repositories in use.
         \row
            \li AllowUnstableComponents
            \li Set to \c true if other components are allowed to be installed
                although there are unstable components. A component is \e unstable
                if it is missing a dependency, has errors in scripts, and so on.
                Unstable components are grayed in the component tree, and therefore
                cannot be selected. By default, the value is \c false  which means
                that the installation will be aborted if unstable components are found.

    \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

    You can also have a callback for the page that is added. To access it,
    use the object name set in the UI file (for example, \c "MyPage"). Then
    create the \c{Dynamic${ObjectName}Callback} function (for example,
    \c {DynamicMyPageCallback}):

    \code
    Component.prototype.DynamicMyPageCallback = function()
    {
        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.
                Specify translations for the name of the component as values of additional
                DisplayName tags, with the xml:lang attribute set to the correct locale.
        \row
            \li Description
            \li Human-readable description of the component. Required.
                Translations may be specified similarly to DisplayName tag.
                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. User clickable external links, for example a component's
                homepage, can be included in component description by specifying a URL
                address like this: {external-link}='https://www.qt.io/'. The URL must be valid
                and contain a full path to the desired resource.
        \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.
                ASCII and UTF8 file formats are supported for license files.

                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.
        \row
            \li Checkable
            \li Set to \c false if you want to hide the checkbox for an item. This is useful
                when only a few subcomponents should be selected instead of all. Optional.
        \row
            \li ExpandedByDefault
            \li Set to \c true if you want this item to be expanded by default. 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

        \li \l devtool

    \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
    \l {Reducing Installer Size}.

    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 --repository directory
            \li Use \c directory as the repository directory
                with packages to repack.
                This entry can be given multiple times.
        \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 --ignore-invalid-repositories
            \li Ignore repository directories that do not have valid
                metadata information (Updates.xml) instead of aborting.
        \row
            \li -v or --verbose
            \li Display debug output.

        \row
            \li -s or --sign identity
            \li Only available on OS X. Allows specifying a code signing identity to be
                used for signing the generated app bundle.
    \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.

    In the optional resource files specified via the \c --resources parameter, a
    special \c fonts/ path can be used to ship custom fonts. These fonts will
    be loaded automatically and thus become available in a stylesheet which can
    be specified via the \c StyleSheet variable.

    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.

    You can use an existing repository to repack packages to another
    repository or offline installer.

    \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 Use \c directory as the repository directory
                with packages to repack (not to confuse with the mandatory target
                repository directory).
                This entry can be given multiple times.
        \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-components
            \li Update only components 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.

    \section1 devtool

    You can use \c devtool to update an existing installer or maintenance tool
    with a new installer base, to dump binary content from an installer or
    maintenance tool to a target, and to execute operations. For a summary of
    available operations, see \l {Operations}.

    \c devtool expects the following parameters in the following order:

    \code
    devtool [options] binary
    \endcode

    Where \e binary is the path and name of an existing installer or maintenance
    tool.

    \section2 Summary of devtool Parameters

    \table
        \header
            \li Parameter
            \li Use
        \row
            \li -?, -h, --help
            \li Display help.
        \row
            \li -v, --version
            \li Display version information.
        \row
            \li --verbose
            \li Display additional information.
        \row
            \li --update <file>
            \li Update an existing installer or maintenance tool with a new
                installer base.
        \row
            \li --dump <folder>
            \li Dump the binary content that belongs to an installer or
                maintenance tool into the target.
        \row
            \li --operation <mode,name,args,...>
            \li Execute an operation with a list of arguments.

                \c mode can be \c DO or \c UNDO, depending on whether the step
                contains instructions for the installer or uninstaller.
    \endtable
*/

/*!
    \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 Configuring Repository Categories

    The \c <RepositoryCategory> element in the installer configuration file
    (config.xml) can contain a list of several \c <RemoteRepositories> elements. Each \c <RemoteRepositories>
    element within the \c <RepositoryCagetory> element is considered a category. Each catecory can have
    a \c <DisplayName>, a \c <Tooltip>, a \c <Preselected> element and several \c <Repository> elements.
    Repository categories are shown in the component selection page,
    on the left side of the component selection widget:

    \image ifw-repository-categories.png "Component selection Page"

    By default, only repositories with no category are shown in the component selection widget. Checking one or
    several repositories and pressing \uicontrol Fetch will update the widget to show content also
    from the selected categorized repositories. Components in the repository
    categories are marked as \e unstable meaning that you can install other
    components although some components have missing dependencies, script
    errors and so on. For more information about \e unstable components, see
    \l {Summary of Configuration File Elements}.

    Example of creating a repository category:

    \code
    <RepositoryCategories>
        <RemoteRepositories>
             <Displayname>Category 1</Displayname>
             <Preselected>true</Preselected>
             <Tooltip>Tooltip for category 1</Tooltip>
             <Repository>
                     <Url>http://www.example.com/packages</Url>
                     <Enabled>1</Enabled>
                     <Username>user</Username>
                     <Password>password</Password>
                     <DisplayName>Example repository</DisplayName>
             </Repository>
        </RemoteRepositories>
    </RepositoryCategories>
    \endcode

    \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

    \c{url} will be used as a base URL to resolve an \c{Updates.xml} file against.
    If \c{url} is itself relative, it will be resolved against the base URL of the current document.

    \c{displayname} specifies how the repository should be named in the \gui Settings page
    of the Maintenance Tool.

    \c{name} and \c{password} optionally specify credentials for a protected repository.

    \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

    \c{url} must match exactly the URL that is to be removed.

    \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

    \c{oldUrl} must match exactly the URL that is to be replaced.

    \c{newUrl} must match exactly the URL that it is replaced with.

    \section1 Relocatable Repositories

    Some projects contain multiple repositories. To create a relocatable set
    of repositories you should use relative paths.

    So if the generic repository available at the address
    \c{http://www.example.com/repositories/generic} and \c{Updates.xml}
    contains \c <Repository> element with the following options:

    \code
    <Repository action="add" url="../module" name="user" password="password"
                 displayname="Module Repository" />
    \endcode

    Then the resolved address of the added repository will be
    \c{http://www.example.com/repositories/module}, so that the repository does
    not contain information about their absolute location.

    If you want to change the address, you can simply copy a set of repositories as is.
    It is recommended to maintain the old generic repository for some time and replace the addresses
    as described above. You can also provide the updated installer with the new generic address.

    You can use relative paths for the arguments \c url, \c oldUrl, and \c newUrl in
    the \c <Repository> element.
*/

/*!
    \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.
*/