/****************************************************************************
**
** Copyright (C) 2023 The Qt Company Ltd.
** Contact: https://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 https://www.qt.io/terms-conditions. For further
** information use the contact form at https://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: https://www.gnu.org/licenses/fdl-1.3.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.
// **********************************************************************

/*!
    \page index.html
    \nextpage ifw-overview.html

    \title Qt Installer Framework Manual

    \section1 Version \ifwversion

    Qt Installer Framework is a robust toolset for creating custom online
    and offline installers. It’s highly configurable and customizable and works for all
    supported Qt platforms: Linux, Microsoft Windows, and macOS.

    Here are some examples to illustrate the versatility
    of Qt Installer Framework.



    \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}
            \li \l{Using From Command Line}
        \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{Command Line Interface}
            \li \l{Configuration File}
            \li \l{Package Directory}
            \li \l{Alias Definition File}
            \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
*/

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

    \title Creating Installers

    To create offline and online installers, do the following:

    \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 has 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 {packages\{component}\meta} directory. It has 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 has 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
*/

/*!
    \previouspage ifw-reference.html
    \page ifw-cli.html
    \nextpage ifw-globalconfig.html

    \title Command Line Interface

    Installers created with the Qt Installer Framework have the following command
    line interface syntax:

    \code
    installer.exe [options] command <args> <key=value>
    \endcode

    Here \c [options] is one or a combination of supported options in either short
    or long form. In addition some options may require mandatory value(s) that can
    be passed using the assignment operator or space.

    The \c command is one of the supported command line installer operations to be
    run headless in text mode. Some commands may be provided with optional \c <args>
    separated by space. The \c <key=value> list is used to set internal key-value
    pairs by the framework.

    Installer will return an exit code after it is executed. Exit code can be used
    to determine whether the installation was successful, if the installation has
    an mandatory update etc. See \c PackagemanagerCore::Status.

    \section1 Summary of Options

    Options marked with \c CLI are only available when running in headless mode,
    the rest of the options can be used also in graphical mode. For the most
    up-to-date list of available options with a specific version of Qt Installer
    Framework, refer \c --help option output of \l installerbase.

    \table
        \header
            \li Option
            \li Usage
        \row
            \li -?, -h, --help
            \li Displays help.
        \row
            \li -v, --version
            \li Displays version information.
        \row
            \li -d, --verbose
            \li Verbose mode. Prints out more information.
        \row
            \li -g, --logging-rules <rules>
            \li Enables logging according to passed rules. Comma separated logging rules
                have the following syntax: \c{loggingCategory=true/false}. Passing empty logging
                rules enables all logging categories. The following rules enable a single
                category: \c{ifw.*=false, ifw.category=true}. The available logging categories
                can be referenced with --help option.
        \row
            \li --ar, --add-repository <URI,...>
            \li Add a local or remote repository to the list of user defined repositories.
        \row
            \li --at, --add-temp-repository <URI,...>
            \li Add a local or remote repository to the list of temporary available repositories.
        \row
            \li --st, --set-temp-repository <URI,...>
            \li Set a local or remote repository as temporary repository, it is the only one
                used during fetch. Note: a URI must be prefixed with the protocol, i.e. file:///,
                https://, http:// or ftp://.
        \row
            \li --sp, --system-proxy
            \li Use system proxy on Windows and Linux. This option has no effect on macOS. (Default)
        \row
            \li --np, --no-proxy
            \li Do not use system proxy.
        \row
            \li --su, --start-updater
            \li Start application in updater mode. This will override the internal marker that is used
                to distinguish which kind of binary is currently running.
        \row
            \li --sm, --start-package-manager
            \li Start application in package manager mode. This will override the internal marker
                that is used to distinguish which kind of binary is currently running.
        \row
            \li --sr, --start-uninstaller
            \li Start application in uninstaller mode. This will override the internal marker
                that is used to distinguish which kind of binary is currently running.
        \row
            \li -t, --root <directory>
            \li [CLI] Set the installation root directory.
        \row
            \li --oi, --offline-installer-name <filename>
            \li [CLI] Set custom filename for the generated offline installer. Without this
                the original filename is used with an added "_offline-yyyy-MM-dd" suffix.
        \row
            \li -p, --platform <plugin>
            \li Use the specified platform plugin.
        \row
            \li --nf, --no-force-installations
            \li Allow deselecting components that are marked as forced.
        \row
            \li --nd, --no-default-installations
            \li Deselects components that are marked as default.
        \row
            \li --ns, --no-size-checking
            \li Disable checking of free space for the installation target.
        \row
            \li --sv, --show-virtual-components
            \li Show virtual components in the installer and the package manager.
        \row
            \li -i, --install-compressed-repository <file,...>
            \li Installs a QBSP or a 7z file. The QBSP (Board Support Package) file must be a .7z file
                which contains a valid repository.
        \row
            \li -c, --create-local-repository
            \li Create a local repository inside the installation directory. This option has no
                effect on online installers.
        \row
            \li --fp, --filter-packages <element=regex,...>
            \li [CLI] Comma separated list of additional key-value pair filters used to query packages with the
                search command. The keys can be any of the possible package information elements, like
                \c DisplayName and \c Description.
        \row
            \li --cp, --cache-path <path>
            \li Sets the path used for local metadata cache. The path must be writable by the current user.
        \row
            \li --type package|alias
            \li [CLI] Sets the type of the given arguments for commands supporting multiple argument types,
                like search. Defaults to alias.
        \row
            \li --am, --accept-messages
            \li [CLI] Accepts all message queries without user input.
        \row
            \li --rm, --reject-messages
            \li [CLI] Rejects all message queries without user input.
        \row
            \li --aa, --auto-answer <identifier=value>
            \li [CLI] Automatically answers the message queries with the message identifier and a button
                value. Several \c{identifier=value} pairs can be given separated with a comma, for example
                \c{--auto-answer message.id=Ok,message.id2=Cancel}.
        \row
            \li --da, --default-answer
            \li [CLI] Automatically answers to message queries with their default values.
        \row
            \li --al, --accept-licenses
            \li [CLI] Accepts all licenses without user input.
        \row
            \li --file-query <identifier=value>
            \li [CLI] Automatically sets the QFileDialog values getExistingDirectory() or
                getOpenFileName() requested by the install script. Several \c{identifier=value} pairs can be
                given separated with a comma, for example \c{--file-query filedialog.id=C:Temp,filedialog.id2=C:Temp2}.
        \row
            \li -c, --confirm-command
            \li [CLI] Confirms starting of installation, update or removal of components without user input.
        \row
            \li -s, --script <file>
            \li Execute the script given as an argument.
        \row
            \li --ss, --start-server <mode, socketname, key>
            \li Starts the application as headless process waiting for commands to execute. Mode can
                be DEBUG or PRODUCTION. In the DEBUG mode, the option values can be omitted. Note: The
                server will not shutdown on its own, you need to quit the process by hand.
        \row
            \li --sc, --start-client <socketname, key>
            \li Starts the application to debug the client-server communication. If a value is
                omitted, the client will use a default instead. Note: The server process is not started
                by the client application in that case, you need to start it on your own.
        \row
            \li -q, --squish-port <port number>
            \li Give a port where Squish can connect to. If no port is given, default port 11233 is used.
                Note: To enable Squish support, you first need to build IFW with SQUISH_PATH parameter
                where SQUISH_PATH is pointing to your Squish installation folder:
                \c{<path_to_qt>/bin/qmake -r SQUISH_PATH=<pat_to_squish>}.
        \row
            \li --mco, --max-concurrent-operations <threads>
            \li Specifies the maximum number of threads used to perform concurrent operations in the
                unpacking phase of components. Set to a positive number, or 0 (default) to let the
                application determine the ideal thread count from the amount of logical processor
                cores in the system.
    \endtable

    \section1 Summary of Commands

    \table
        \header
            \li Command
            \li Usage
        \row
            \li in, install <pkg|alias ...>
            \li Install packages and aliases given as an argument. If no arguments are given, install the default package set.
        \row
            \li ch, check-updates
            \li Show information about available updates on the \MT.
        \row
            \li up, update <pkg ...>
            \li Update packages given as an argument. If no packages are given, install all available updates.
        \row
            \li rm, remove <pkg ...>
            \li Uninstall selected packages and their child components.
        \row
            \li li, list <regexp for pkg>
            \li List information about currently installed packages.
        \row
            \li se, search <regexp for pkg|alias>
            \li Search available aliases or packages. If no search pattern is given, show all available packages.

                \note The \c --filter-packages option can be used to specify additional filters for
                the search operation. See \l{Summary of Options}.

                \note The \c --type option can be used to specify the content type to search.
                See \l{Summary of Options}.
        \row
            \li co, create-offline <pkg ...>
            \li Create offline installer from selected packages.
        \row
            \li cc, clear-cache
            \li Clear contents of the local metadata cache.
        \row
            \li pr, purge
            \li Uninstall all packages and remove the program directory.
    \endtable
*/

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

    \note The filenames of the referred files must be unique. That is, if you
    want to use the same image for both \c <Logo> and \c <Watermark>, you
    must add two copies of the image file with different filenames.

    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 InstallerApplicationIcon
            \li Filename for a custom installer icon. The actual file is looked up by attaching
                a '.icns' (macOS), '.ico' (Windows) suffix. No functionality on Unix.
        \row
            \li InstallerWindowIcon
            \li Filename for a custom window icon in PNG format for the Installer application.
                Used on Windows and Linux, no functionality on macOS.
        \row
            \li Logo
            \li Filename for a logo in PNG format used as \c QWizard::LogoPixmap.
        \row
            \li Watermark
            \li Filename for a watermark in PNG format used as \c QWizard::WatermarkPixmap. If
                \c <WizardShowPageList> is set to \c true, the watermark is hidden.
        \row
            \li Banner
            \li Filename for a banner in PNG format used as \c QWizard::BannerPixmap (only used by ModernStyle).
        \row
            \li Background
            \li Filename for an image in PNG format used as \c QWizard::BackgroundPixmap (only used by MacStyle).
                If \c <WizardShowPageList> is set to \c true, the background is hidden.
        \row
            \li PageListPixmap
            \li Filename for an image in PNG format shown on top of installer page list. The image is shown
                only if \c <WizardShowPageList> is also set to \c true.
        \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 WizardMinimumWidth
            \li Sets the minimum width of the wizard in pixels. 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 WizardMinimumHeight
            \li Sets the minimum height of the wizard in pixels. 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 WizardShowPageList
            \li Set to \c false if the widget listing installer pages on the left side of the
                wizard should not be shown. Defaults to \c true. If visible, this widget hides
                \c QWizard::WatermarkPixmap on \c QWizard::ClassicStyle and \c QWizard::ModernStyle,
                and \c QWizard::BackgroundPixmap on \c QWizard::MacStyle.
        \row
            \li ProductImages
            \li A list of images to be shown on \c PerformInstallationPage. This element can have
                one or several \c <ProductImage> child elements that contain an \c <Image> child
                element and an optional \c <Url> child element. The \c <Image> element specifies a
                filename for an image in PNG format. Optional \c <Url> can be specified for each
                image. Clicking on the image will open the \c <Url> in a browser. If the \c <Url>
                is a reference to a file, it will be opened with a suitable application
                instead of a Web browser.
        \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 LocalCacheDir
            \li Directory name for storing the metadata cache. This does not include
                the leading directories, which are determined automatically based on a suitable
                platform specific location for storing cache files. The user may override the path
                from the installer settings. The default value is a UUID generated from the
                name of the product being installed.
        \row
            \li PersistentLocalCache
            \li Set to \c false if the fetched metadata should be removed from the local cache when
                the installer exits. Otherwise the contents of the cache are kept to speed up
                subsequent fetches. Defaults to \c true.
        \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 \MT. Defaults to
                \e maintenancetool. The platform-specific executable file extension is
                appended.
        \row
            \li MaintenanceToolIniFile
            \li Filename for the configuration of the generated \MT. Defaults to
                \e {MaintenanceToolName}.ini.
        \row
            \li MaintenanceToolAlias
            \li Filename for an alias of the \MT that will be created to the
                Applications directory. Optional. Only used on macOS.
        \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 DisableCommandLineInterface
            \li Set to \c true if command line interface features should be disabled. This prevents
                the user from passing any consumer command to installer, like \c install, \c update
                and \c remove. Other options can still be used normally. Defaults to \c false.
        \row
            \li RepositorySettingsPageVisible
            \li Set to \c false to hide the repository settings page inside the settings dialog.
        \row
            \li AllowRepositoriesForOfflineInstaller
            \li Set to \c false to disable usage of any temporary or user configured repositories
                set for offline installers. The maintenance tool written by an offline installer
                can still access the repositories. Defaults to \c true.
        \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 AliasDefinitionsFile
            \li Filename for a XML document containing the definitions for component aliases.
                For more information about how to declare component aliases in the file,
                see \l{Alias Definition File}.
        \row
            \li Translations
            \li List of translation files to be used for translating the user interface. To add
                several translation files, specify several \c <Translation> child elements that
                each specify the name of the translation. Optional. For more information, see
                \l{Translating Pages} and \l{Configuring and Overwriting Default Translations}.
        \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

*/

/*!
    \previouspage ifw-globalconfig.html
    \page ifw-aliasconfig.html
    \nextpage noninteractive.html

    \title Alias Definition File

    The alias definition file defines the available component aliases and their
    properties. The file is typically called \c aliases.xml and located in the
    \c config directory.

    The component names of the Qt Installer Framework follow a domain-like
    identifier syntax, for example \c com.vendor.root, \c com.vendor.root.subcomponent,
    and so on. While this allows an easy way to construct a tree from the components when
    running the installer in graphical mode, the names can be unintuitive for command line usage,
    where the components are not displayed in a tree view.

    Instead of relying on the domain-like names for CLI usage, the packager can also define component
    aliases for existing components. An alias is another name for a single component or a collection
    of components. It can be used to declare alternative names for existing components that are
    easier to type and combine multiple components under the same alias name, for easier selection.

    The following example shows a possible alias definition file:

    \quotefile examples/aliases.xml

    \section1 Summary of Alias Definition File Elements

    The following table summarizes the elements in the alias definition file.

    \table
        \header
            \li Element
            \li Description
        \row
            \li Name
            \li Name of component alias.
        \row
            \li DisplayName
            \li Human-readable name of the component alias.
        \row
            \li Description
            \li Human-readable description of the component alias.
        \row
            \li Version
            \li Version number of the component alias.
        \row
            \li Virtual
            \li Set to \c true to hide the component alias from the installer. This also
                makes the alias unselectable by the user.
        \row
            \li RequiredComponents
            \li Comma-separated list of identifiers of components that this
                component alias requires. The components are selected for installation
                when the component alias is selected. Note that the components must be
                selectable by the user, so virtual or otherwise unselectable components
                cannot be listed as a requirement.
        \row
            \li RequiredAliases
            \li Comma-separated list of aliases that this component alias requires. The
                required aliases are selected for installation when this component alias
                is selected.
        \row
            \li OptionalComponents
            \li Comma-separated list of identifiers of components that this component alias
                optionally depends on. The components are selected for installation when the
                component alias is selected, if the components exists and are user selectable.
                Even if the components cannot be found in the installer, this alias is not marked unstable.
        \row
            \li OptionalAliases
            \li Comma-separated list of aliases that this component alias optionally depends on. The
                listed aliases are selected for installation when this component alias is selected,
                if the aliases exist. Even if the aliases don't exists in the installer,
                this alias is not marked unstable.
    \endtable
*/

/*!
    \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 config.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 {qsTranslate()} 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.

    \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.

    \section1 Configuring and Overwriting Default Translations

    The installer has been localized into several languages. System language is used to define the
    loaded language. In case you want to define the used language for your installer, define the
    languages in \c config.xml using the \c <Translations> element. For example, using only German
    translations:

    \code
        <Translations>
            <Translation>ifw_de</Translation>
            <Translation>qt_de</Translation>
        </Translations>
    \endcode

    The default translations can be also overwritten. Write your own translation file and add
    it to a custom resource called \c :/translations_new. This custom resource can be added to
    the installer using \c binarycreator option \c -r. For more information, see
    \l{Summary of binarycreator Parameters}.

    If the translated language is not already part of the existing translations
    of Qt Installer Framework, you need to also include the Qt Base translation for that language
    in the resource file. For this you need to point to the \c qtbase_*.qm for your language from
    the location of \c QT_INSTALL_TRANSLATIONS and alias it in the resource file.

    For example, for the Czech translation a custom \c translations_new.qrc should look
    like this:

    \code
    <!DOCTYPE RCC><RCC version="1.0">
    <qresource prefix="/translations_new">
        <file>ifw_cs.qm</file>
        <file alias="qt_cs.qm">%QT_INSTALL_TRANSLATIONS%/qtbase_cs.qm</file>
    </qresource>
    </RCC>
    \endcode

    The path for replacing \c QT_INSTALL_TRANSLATIONS can be retrieved from the
    output of \c{qmake -query} of your Qt installation.
*/

/*!
    \previouspage ifw-globalconfig.html
    \page ifw-component-description.html
    \nextpage ifw-aliasconfig.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. The directory
    name must not contain \c : or \c - characters as those are reserved for separating
    the version number from the identifier.

    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,
                but this does not change the visibility of the check box in the updater view
                where the end user may still manually select the component for update.

                When running an installer or a \MT in package manager
                mode, 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 or for update when at least one
                of the components from this list is also selected for
                uninstallation or for update.
                For more information, see \l{Component Dependencies}.
        \row
            \li Virtual
            \li Set to \c true to hide the component from the installer. This also
                hides any child components this component may have, including their
                descendants. 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 and,
                optionally, \c priority.
                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.
                Specifying the \c {postLoad="true"} attribute will cause the script
                to be loaded only to the component that is selected for update or
                install. With the attribute, the script is loaded right before the
                component installation starts. This will speed up the installer
                if there are large amounts of components with install scripts in the
                repository. Make sure the script does not contain anything that needs
                to be evaluated before the install tree view is shown.
                For more information, see \l{Adding Operations} and
                \l{Using postLoad in component script}.
        \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. 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. 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. When updating components, the
                component can still be deselected from an update.
        \row
            \li ForcedUpdate
            \li Marks the package as \c ForcedUpdate to force a restart of the
                \c MaintenanceTool. If there are updates available
                for a \c ForcedUpdate component, the package manager stays
                disabled until that component is updated.
        \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. When updating
                components, the checkbox is still visible to allow toggling the component for
                update. Optional.
        \row
            \li ExpandedByDefault
            \li Set to \c true if you want this item to be expanded by default. Optional.

        \row
            \li Operations
            \li List of operations that are performed when component is installed. To add
                several operations, specify several \c <Operation> child elements that each
                specify the operation \c name. \c Operation can have several \c <Argument>
                child elements depending on the operation to be run. Adding \c <Operations>
                is an alternative way of defining operations to defining them in scripts.
                For more information, see \l{Adding Operations}. For a
                summary of available operations, see \l {Operations}.

        \row
            \li TreeName
            \li Specifies the component location in the install tree view. Overwrites the original
                location which is calculated from component name. Component names and tree names
                must be unique. Optional.

                Specifying \c{moveChildren="true"} attribute will also change the location of any
                child components this component has. Children will move to the overwritten tree name,
                keeping the relative location to their parent component.

                One component branch in the install tree view can have multiple components
                specifying a tree name. The order in which the location of components is changed
                is from leaf to root components.

    \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. The data must be packaged into archive files. This is either
    done automatically by \l binarycreator and \l repogen when creating an installer or
    a repository, respectively, or you can do this beforehand for more control.

    For manual archive creation you can use either the \l archivegen tool that is
    delivered with the Qt Installer Framework or some other tool that generates archives in
    any of the file formats: \c{7z}, \c{zip}, \c{tar.gz}, \c{tar.bz2} and \c{tar.xz}.

    \note If the Installer Framework tools were built without libarchive support,
    only \c{7z} format is supported.
*/

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

    \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 macOS

    \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 macOS. Allows specifying a code signing identity to be
                used for signing the generated app bundle.
        \row
            \li --af or --archive-format 7z|zip|tar|tar.gz|tar.bz2|tar.xz
            \li Set the format used when packaging new component data archives. If
                you omit this option, the 7z format will be used as a default.
                \note If the Installer Framework tools were built without libarchive
                support, only \c{7z} format is supported.
        \row
            \li --ac or --compression <5>
            \li Defaults to 5 (Normal compression). \note Some formats do not support
                all the possible values, for example bzip2 compression only supports
                values from 1 to 9.
                \list
                    \li 0 (No compression)
                    \li 1 (Fastest compressing)
                    \li 3 (Fast compressing)
                    \li 5 (Normal compressing)
                    \li 7 (Maximum compressing)
                    \li 9 (Ultra compressing)
                \endlist
    \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 macOS, if the target binary is suffixed with .app, a macOS
    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.

    Repositories contain compressed metadata that can be packaged as a separate 7z archive
    for each component, or combined into a single 7z archive for the repository entirety.
    By default, repogen packages the metadata in both formats for backward compatibility
    with older installers not supporting the unified meta-format. This can be changed with
    the \c --unite-metadata and \c --component-metadata options.

    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.
        \row
            \li --unite-metadata
            \li Combine all metadata into one 7z. This speeds up metadata download phase.
        \row
            \li --component-metadata
            \li Creates one metadata 7z per component.
         \row
            \li -s or --sha-update p1,...,pn
            \li Comma-separated list of packages to be updated based on the component sha
                checksum instead of the version number. This parameter adds a new \c <ContentSha1>
                node to the \c Updates.xml.
         \row
            \li --af or --archive-format 7z|zip|tar|tar.gz|tar.bz2|tar.xz
            \li Set the format used when packaging new component data archives. If
                you omit this option, the 7z format will be used as a default.
                \note If the Installer Framework tools were built without libarchive
                support, only \c{7z} format is supported.
        \row
            \li --ac, --compression <5>
            \li Defaults to 5 (Normal compression). \note Some formats do not support
                all the possible values, for example bzip2 compression only supports
                values from 1 to 9.
                \list
                    \li 0 (No compression)
                    \li 1 (Fastest compressing)
                    \li 3 (Fast compressing)
                    \li 5 (Normal compressing)
                    \li 7 (Maximum compressing)
                    \li 9 (Ultra compressing)
                \endlist
    \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 archives.

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

    \code
    archivegen <archive_name> <data>
    \endcode

    Where \e <archive_name> 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.

    \section2 Summary of archivegen Parameters

    \table
        \header
            \li Parameter
            \li Use
        \row
            \li -h, --help
            \li Displays this help.
        \row
            \li -v, --version
            \li Displays version information.
        \row
            \li -f, --format <format>
            \li Format for the archive. Defaults to 7z.
                \note If the Installer Framework tools were built without libarchive
                support, only \c{7z} format is supported.
                \list
                    \li 7z (7z archive)
                    \li zip (ZIP archive)
                    \li tar (uncompressed tar archive)
                    \li tar.gz (gzip compressed tar archive)
                    \li tar.bz2 (bzip2 compressed tar archive)
                    \li tar.xz (xz compressed tar archive)
                \endlist
        \row
            \li -c, --compression <5>
            \li Defaults to 5 (Normal compression). \note Some formats do not support
                all the possible values, for example bzip2 compression only supports
                values from 1 to 9.
                \list
                    \li 0 (No compression)
                    \li 1 (Fastest compressing)
                    \li 3 (Fast compressing)
                    \li 5 (Normal compressing)
                    \li 7 (Maximum compressing)
                    \li 9 (Ultra compressing)
                \endlist
    \endtable

    \section1 devtool

    You can use \c devtool to update an existing installer or \MT
    with a new installer base, to dump binary content from an installer or
    \MT 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 <binary> <installerbase>
            \li Update an existing installer or \MT with a new
                installer base.
        \row
            \li dump <binary> <folder>
            \li Dump the binary content that belongs to an installer or
                \MT 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
*/

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

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

*/

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

    \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.

    \section1 Promoting Updates for the Maintenance Tool

    Without additional configuration, both online and offline installers install the
    \e {\MT}, that can be later used to add, update, and remove components.
    Online installers also have an option to install the \MT from an online repository.
    This makes it possible to promote updates for the \MT to take the advantage of latest
    new features and fixes to the Qt Installer Framework.

    You should download the latest release of the Installer Framework distribution that
    includes new versions of \l{binarycreator} and \l{installerbase} tools. However, to only
    update vendor specific configuration like \c <Name>, \c <Title>, and \c <Publisher> to the new
    \MT, you can use the tools that were used to create the original installer.

    \section2 Creating the Component Directory Structure for Maintenance Tool

    To make the \MT update installable for end users, you need to prepare an installer
    component for the \MT and create a repository for that component.

    \note If you already have a component for the \MT available in a repository, you
    can skip the instructions in this section.

    A common convention is to create a \c packages directory containing the metadata and data for
    your installer components. Inside that directory, you need to create a subdirectory for the maintenance
    tool component with a name of your choice, for example \c org.qtproject.ifw.maintenancetool,
    with \c meta and \c data subdirectories. These directories will be populated later.

    \section2 Compiling the Update Resource

    If you want to apply configuration changes, like updating the title, publisher, or product URL
    when the end user updates the \MT, you need to create an update resource file.
    Otherwise this step is optional.

    First, you need to compile the resource file that will contain the new \MT
    configuration and related files:

    \code
    binarycreator -c config/config.xml -p packages -rcc
    \endcode

    The command outputs the result into \c update.rcc in the current path.

    The \c packages directory argument refers to the previously created directory for the maintenance
    tool component. \c config.xml contains the \MT configuration. This can be the same
    file that was used for creating the online installer that is going to consume the \MT
    repository, or you could make modifications to change some configuration elements like the window
    title and product version.

    For full reference of elements supported by the configuration file, see \l{Configuration File}.

    \section2 Getting the Maintenance Tool

    The \MT for Linux and Windows is the same as the \c installerbase
    executable located in your Qt Installer Framework's installation \c bin folder.
    For macOS the \MT app bundle can be created using the \c binarycreator
    tool with the command line switch \c --mt or \c --create-maintenancetool. The
    name of the macOS app bundle can be configured in config.xml using
    the \c <MaintenanceToolName> element. The app bundle can be later signed and
    notarized if needed.

    \code
    binarycreator -c config/config.xml --mt
    \endcode

    \section2 Populating the Maintenance Tool Component

    In Linux and in Windows the \c installerbase executable from Qt Installer
    Framework's installation folder, or in macOS the \MT app bundle,
    should be copied to the component's data directory. If you generated the
    \c update.rcc in the \l{Compiling the Update Resource} step, copy that to
    the data directory as well. The meta directory should contain a \c package.xml
    file with the package information elements of your choice. However, it is a
    good idea to mark the component \c <Essential> so that it gets automatically
    installed when running the updater. You may also want to mark the component
    \c <Virtual> to hide it from the component selection.

    For further information about the \c package.xml file, see
    \l{Summary of Package Information File Elements}.

    \note If you are providing an update for an existing \MT component, copy and overwrite the
    existing files with the updated content to the package directory and increase the value of the
    \c <Version> element in the \c package.xml file.

    The meta directory should also contain an installation script that tells the installer that
    there are replacements for the default \c installerbase and update resource files. A minimal
    \c installscript.qs for this purpose could look like this:

    \code
    function Component()
    {
        installer.installationStarted.connect(this, Component.prototype.onInstallationStarted);
    }

    Component.prototype.onInstallationStarted = function()
    {
        if (component.updateRequested() || component.installationRequested()) {
            if (installer.value("os") == "win") {
                component.installerbaseBinaryPath = "@TargetDir@/installerbase.exe";
            } else if (installer.value("os") == "x11") {
                component.installerbaseBinaryPath = "@TargetDir@/installerbase";
            } else if (installer.value("os") == "mac") {
                // In macOs maintenance tool can be either installerbase from Qt Installer
                // Framework's install folder, or app bundle created by binarycreator
                // with --create-maintenancetool switch. "MaintenanceTool.app" -name
                // may differ depending on what has been defined in config.xml while
                // creating the maintenance tool.
                // Use either of the following (not both):

                // component.installerbaseBinaryPath = "@TargetDir@/installerbase";
                component.installerbaseBinaryPath = "@TargetDir@/MaintenanceTool.app";
            }
            installer.setInstallerBaseBinary(component.installerbaseBinaryPath);

            var updateResourceFilePath = installer.value("TargetDir") + "/update.rcc";
            installer.setValue("DefaultResourceReplacement", updateResourceFilePath);
        }
    }
    \endcode

    You must include the installation script in the \c package.xml by specifying the filename in
    the \c <Script> element.

    \section2 Publishing Maintenance Tool Updates

    After preparation the component should be uploaded to an existing or a new online repository
    to make it available for end users. The instructions on how to create repositories on
    this page and \l{Creating Repositories} apply also for the component containing the
    \MT update.
*/

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