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.

Package Directory Structure

Place all components in the same root directory, which is called the package directory. The directory name acts as a domain-like identifier, which identifies all components. For example, com.vendor.root. The directory name must not contain : or - characters as those are reserved for separating the version number from the identifier.

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

A package directory can look as follows:

    - com.vendor.root
        - data
        - meta
    - com.vendor.root.component1
        - data
        - meta
    - com.vendor.root.component1.subcomponent1
        - data
        - meta
    - com.vendor.root.component2
        - data
        - meta

Meta Directory

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

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:

<?xml version="1.0"?>
    <Description>Qt gui libraries</Description>
    <Description xml:lang="de_de">Qt GUI Bibliotheken</Description>
        <License name="License Agreement" file="license.txt" />
    <DownloadableArchives>component2.7z, component2a.7z</DownloadableArchives>
    <UpdateText>This changed compared to the last release</UpdateText>
        <Operation name="AppendFile">
            <Argument>lorem ipsum</Argument>
        <Operation name="Extract">
        <Operation name="Extract">

Summary of Package Information File Elements

DisplayNameHuman-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.
DescriptionHuman-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}=''. The URL must be valid and contain a full path to the desired resource.
VersionVersion 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.
ReleaseDateDate when this component version was released. Required.
NameDomain-like identification for this component. Required.
DependenciesComma-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 Component Dependencies.
AutoDependOnComma-separated list of identifiers of components that this component has an automatic dependency on. The component is installed if and only if all of the specified dependencies are fulfilled. If a component has an automatic dependency on other components, the check box will not be visible next to the component in the component tree. The selection will be performed automatically. If the component was not installed before, it will be selected for installation only when all components from this list are also selected for installation. If the component was already installed, it will be selected for uninstallation when at least one of the components from this list is also selected for uninstallation. For more information, see Component Dependencies.
VirtualSet to true to hide the component from the installer. Note that setting this on a root component does not work.
SortingPriorityPriority of the component in the tree. The tree is sorted from highest to lowest priority, with the highest priority on the top.
LicensesList of license agreements to be accepted by the installing user. To add several licenses, add several <License> child elements that each specify the license name and file and, optionally, 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).

ScriptFile name of a script being loaded. Optional. For more information, see Adding Operations.
UserInterfacesList of pages to load. To add several pages, add several <UserInterface> child elements that each specify the filename of a page. Optional. For more information, see Adding Pages.
TranslationsList of translation files to load. To add several language variants, specify several <Translation> child elements that each specify the filename of a language variant. Optional. For more information, see Translating Pages.
UpdateTextDescription added to the component description if this is an update to the component. Optional.
DefaultPossible values are: true, false, and script. Set to 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 script is resolved during runtime. Add the name of the script as a value of the <Script> element in this file. For an example script, see Selecting Default Contents.
EssentialMarks the package as essential to force a restart of the 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.
ForcedInstallationDetermines that the package must always be installed. End users cannot deselect it in the installer.
ForcedUpdateMarks the package as ForcedUpdate to force a restart of the MaintenanceTool. If there are updates available for a ForcedUpdate component, the package manager stays disabled until that component is updated.
ReplacesComma-separated list of components to replace. Optional.
DownloadableArchivesLists 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.
RequiresAdminRightsSet to true if the package needs to be installed with elevated permissions. Optional.
CheckableSet to 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.
ExpandedByDefaultSet to true if you want this item to be expanded by default. Optional.
OperationsList of operations that are performed when component is installed. To add several operations, specify several <Operation> child elements that each specify the operation name. Operation can have several <Argument> child elements depending on the operation to be run. Adding <Operations> is an alternative way of defining operations to defining them in scripts. For more information, see Adding Operations. For a summary of available operations, see Operations.
TreeNameSpecifies 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.

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

Data Directory

The 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 archivegen tool that is delivered with the Qt Installer Framework or some other tool that generates 7zip archives.

© 2021 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. The Qt Company, Qt and their respective logos are trademarks of The Qt Company Ltd in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.