diff options
Diffstat (limited to 'doc/installerfw.qdoc')
| -rw-r--r-- | doc/installerfw.qdoc | 291 |
1 files changed, 236 insertions, 55 deletions
diff --git a/doc/installerfw.qdoc b/doc/installerfw.qdoc index e4927f316..4c55c6d43 100644 --- a/doc/installerfw.qdoc +++ b/doc/installerfw.qdoc @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2022 The Qt Company Ltd. +** 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 @@ -252,6 +258,13 @@ 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 @@ -310,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. @@ -322,18 +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 @@ -494,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 @@ -504,17 +535,17 @@ 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 maintenance tool that will be created to the - Applications directory. Defaults to \e {MaintenanceToolName}. Only used on macOS. + \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. @@ -535,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 @@ -546,6 +582,11 @@ \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 @@ -590,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 @@ -621,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 @@ -763,12 +881,32 @@ 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 @@ -869,8 +1007,12 @@ 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. @@ -881,8 +1023,9 @@ 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 @@ -906,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 @@ -944,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 @@ -970,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. @@ -1395,9 +1549,9 @@ \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: @@ -1426,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. @@ -1504,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, @@ -1726,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. @@ -1782,22 +1936,22 @@ \section1 Promoting Updates for the Maintenance Tool Without additional configuration, both online and offline installers install the - \e {maintenance tool}, that can be later used to add, update, and remove components. - Online installers also have an option to install the maintenance tool from an online repository. - This makes it possible to promote updates for the maintenance tool to take the advantage of latest + \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 - maintenance tool, you can use the tools that were used to create the original installer. + \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 maintenance tool update installable for end users, you need to prepare an installer - component for the maintenance tool and create a repository for that component. + 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 maintenance tool available in a repository, you + \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 @@ -1808,10 +1962,10 @@ \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 maintenance tool, you need to create an update resource file. + 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 maintenance tool + First, you need to compile the resource file that will contain the new \MT configuration and related files: \code @@ -1821,26 +1975,43 @@ 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 maintenance tool configuration. This can be the same - file that was used for creating the online installer that is going to consume the maintenance tool + 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 - The \c installerbase executable from Qt Installer Framework's install folder and \c update.rcc - generated in the \l{Compiling the Update Resource} step should be copied to the component's data - directory. 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 + 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 maintenance tool component, copy and overwrite the + \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. @@ -1857,11 +2028,21 @@ Component.prototype.onInstallationStarted = function() { if (component.updateRequested() || component.installationRequested()) { - if (installer.value("os") == "win") + if (installer.value("os") == "win") { component.installerbaseBinaryPath = "@TargetDir@/installerbase.exe"; - else if (installer.value("os") == "x11" || installer.value("os") == "mac") + } 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"; @@ -1878,7 +2059,7 @@ 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 - maintenance tool update. + \MT update. */ /*! |