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:

-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

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"?>
<Package>
    <DisplayName>QtGui</DisplayName>
    <Description>Qt gui libraries</Description>
    <Description xml:lang="de_de">Qt GUI Bibliotheken</Description>
    <Version>1.2.3</Version>
    <ReleaseDate>2009-04-23</ReleaseDate>
    <Name>com.vendor.root.component2</Name>
    <Dependencies>com.vendor.root.component1</Dependencies>
    <Virtual>false</Virtual>
    <Licenses>
        <License name="License Agreement" file="license.txt" />
    </Licenses>
    <Script>installscript.qs</Script>
    <UserInterfaces>
        <UserInterface>specialpage.ui</UserInterface>
        <UserInterface>errorpage.ui</UserInterface>
    </UserInterfaces>
    <Translations>
        <Translation>sv_se.qm</Translation>
        <Translation>de_de.qm</Translation>
    </Translations>
    <DownloadableArchives>component2.7z, component2a.7z</DownloadableArchives>
    <AutoDependOn>com.vendor.root.component3</AutoDependOn>
    <SortingPriority>123</SortingPriority>
    <UpdateText>This changed compared to the last release</UpdateText>
    <Default>false</Default>
    <ForcedInstallation>false</ForcedInstallation>
    <ForcedUpdate>false</ForcedUpdate>
    <Essential>false</Essential>
    <Replaces>com.vendor.root.component2old</Replaces>
    <Operations>
        <Operation name="AppendFile">
            <Argument>@TargetDir@/A.txt</Argument>
            <Argument>lorem ipsum</Argument>
        </Operation>
        <Operation name="Extract">
            <Argument>@TargetDir@/Folder1</Argument>
            <Argument>content.7z</Argument>
        </Operation>
        <Operation name="Extract">
            <Argument>@TargetDir@/Folder2</Argument>
        </Operation>
    </Operations>
    <TreeName moveChildren="true">com.vendor.subcomponent</TreeName>
</Package>

Summary of Package Information File Elements

ElementDescription
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}='https://www.qt.io/'. 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, 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 maintenance tool 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 Component Dependencies.

VirtualSet to 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.
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. Specifying the 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 Adding Operations and Using postLoad in component script.
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. 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 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. When updating components, the component can still be deselected from an update.
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. When updating components, the checkbox is still visible to allow toggling the component for update. 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.

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

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. The data must be packaged into archive files. This is either done automatically by binarycreator and 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 archivegen tool that is delivered with the Qt Installer Framework or some other tool that generates archives in any of the file formats: 7z, zip, tar.gz, tar.bz2 and tar.xz.

Note: If the Installer Framework tools were built without libarchive support, only 7z format is supported.

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