diff options
Diffstat (limited to 'doc/installerfw.qdoc')
| -rw-r--r-- | doc/installerfw.qdoc | 556 |
1 files changed, 496 insertions, 60 deletions
diff --git a/doc/installerfw.qdoc b/doc/installerfw.qdoc index e9a6463bc..4c55c6d43 100644 --- a/doc/installerfw.qdoc +++ b/doc/installerfw.qdoc @@ -1,7 +1,7 @@ /**************************************************************************** ** -** Copyright (C) 2020 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2023 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Installer Framework. ** @@ -39,9 +39,14 @@ \section1 Version \ifwversion - The Qt Installer Framework provides a set of tools and utilities to - create installers for the supported desktop Qt platforms: Linux, Microsoft - Windows, and macOS. + 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}. @@ -72,6 +77,7 @@ \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} @@ -90,7 +96,7 @@ \title Creating Installers - The following steps are needed to create offline and online installers: + To create offline and online installers, do the following: \list 1 @@ -98,13 +104,13 @@ For more information, see \l{Package Directory}. \li Create a configuration file called \c config.xml in the \c config - directory. It contains information about how to build the installer + 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 contains settings for deployment and + \c {packages\{component}\meta} directory. It has settings for deployment and the installation process. For more information, see \l{Meta Directory}. @@ -112,7 +118,7 @@ For more information, see \l{Data Directory}. \li For online installers, use the \c repogen tool to create the - repository that contains the installable content and upload the + repository 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 @@ -239,7 +245,7 @@ \li --sv, --show-virtual-components \li Show virtual components in the installer and the package manager. \row - \li -i, --install-compressed-repository <URI,...> + \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 @@ -247,6 +253,18 @@ \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 @@ -290,6 +308,12 @@ 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 @@ -299,11 +323,11 @@ \li Command \li Usage \row - \li in, install <pkg ...> - \li Install packages given as an argument. If no packages are given, install the default package set. + \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 maintenance tool. + \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. @@ -311,15 +335,24 @@ \li rm, remove <pkg ...> \li Uninstall selected packages and their child components. \row - \li li, list <regexp> + \li li, list <regexp for pkg> \li List information about currently installed packages. \row - \li se, search <regexp> - \li Search available packages. If no search pattern is given, show all available packages. + \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 @@ -353,6 +386,10 @@ 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}. @@ -380,35 +417,30 @@ \li URL to a page that contains product information on your web site. \row - \li Icon - \li Filename for a custom installer icon. The actual file is looked up by attaching - a '.icns' (macOS), '.ico' (Windows) or '.png' (Unix) suffix. Deprecated, - use \c <InstallerApplicationIcon> or \c <InstallerWindowIcon> - instead. - \row \li InstallerApplicationIcon \li Filename for a custom installer icon. The actual file is looked up by attaching - a '.icns' (macOS), '.ico' (Windows). No functionality on Unix. + 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 used as \c QWizard::LogoPixmap. + \li Filename for a logo in PNG format used as \c QWizard::LogoPixmap. \row \li Watermark - \li Filename for a watermark used as \c QWizard::WatermarkPixmap. If + \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 used as \c QWizard::BannerPixmap (only used by ModernStyle). + \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 used as \c QWizard::BackgroundPixmap (only used by MacStyle). + \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 shown on top of installer page list. The image is shown + \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 @@ -443,7 +475,12 @@ \row \li ProductImages \li A list of images to be shown on \c PerformInstallationPage. This element can have - one or several \c <Image> child elements that contain a filename for an image. + 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, @@ -476,6 +513,18 @@ 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 @@ -486,14 +535,18 @@ For more information, see \l{Configuring Repository Categories}. \row \li MaintenanceToolName - \li Filename of the generated maintenance tool. Defaults to + \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 maintenance tool. Defaults to + \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 @@ -513,6 +566,11 @@ \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 @@ -524,10 +582,16 @@ \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 language codes to be used for translating the user interface. To add several language - variants, specify several \c <Translation> child elements that each specify the name - of a language variant. Optional. For more information, see \l{Translating Pages}. + \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 @@ -567,6 +631,83 @@ */ /*! + \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 @@ -598,7 +739,7 @@ \l{Component Scripting}. A control script is associated with the whole installer by specifying it - in the \c ControlScript element of the control.xml file of the installer. + 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 @@ -721,12 +862,51 @@ \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 noninteractive.html + \nextpage ifw-aliasconfig.html \title Package Directory @@ -827,19 +1007,25 @@ The component is installed if and only if all of the specified dependencies are fulfilled. If a component has an automatic dependency on other components, - the check box will not be visible next to the component in the component tree. - The selection will be performed automatically. + 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 when at least one of the components - from this list is also selected for uninstallation. + 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. - Note that setting this on a root component does not work. + \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 @@ -863,7 +1049,15 @@ \row \li Script \li File name of a script being loaded. Optional. - For more information, see \l{Adding Operations}. + 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 @@ -873,8 +1067,10 @@ \li Translations \li List of translation files to load. To add several language variants, specify several \c <Translation> child elements that each - specify the filename of a language variant. Optional. For more - information, see \l{Translating Pages}. + 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 @@ -899,7 +1095,8 @@ \row \li ForcedInstallation \li Determines that the package must always be installed. End users - cannot deselect it in the installer. + 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 @@ -925,7 +1122,9 @@ \row \li Checkable \li Set to \c false if you want to hide the checkbox for an item. This is useful - when only a few subcomponents should be selected instead of all. Optional. + 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. @@ -946,6 +1145,14 @@ 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 @@ -964,9 +1171,16 @@ \section1 Data Directory The \c data directory contains the content that the installer extracts - during the installation. You must package the data as a 7zip archive (.7z). - You can use either the \l archivegen tool that is delivered with the Qt - Installer Framework or some other tool that generates 7zip archives. + 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. */ /*! @@ -1122,6 +1336,25 @@ \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 @@ -1168,6 +1401,12 @@ 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. @@ -1215,6 +1454,36 @@ \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 @@ -1225,25 +1494,64 @@ \section1 archivegen - You can use \c archivegen to package files and directories into 7zip (.7z) - archives. + 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 <name.7z> <data> + archivegen <archive_name> <data> \endcode - Where \e <name.7z> is the path and file name of the archive to create and + 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 maintenance tool + 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 - maintenance tool to a target, and to execute operations. For a summary of + \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: @@ -1272,12 +1580,12 @@ \li Display additional information. \row \li update <binary> <installerbase> - \li Update an existing installer or maintenance tool with a new + \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 - maintenance tool into the target. + \MT into the target. \row \li operation <mode,name,args,...> \li Execute an operation with a list of arguments. @@ -1350,7 +1658,7 @@ \endcode The installer works only if it can access the repository. If the repository is - accessed after the installation, the maintenance tool rejects installation. + 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, @@ -1572,7 +1880,7 @@ If \c{url} is itself relative, it will be resolved against the base URL of the current document. \c{displayname} specifies how the repository should be named in the \gui Settings page - of the Maintenance Tool. + of the \MT. \c{name} and \c{password} optionally specify credentials for a protected repository. @@ -1624,6 +1932,134 @@ 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. */ /*! |