Package Directory | Qt Installer Framework Manual

Qt Installer Framework Manual | Package Directory

Configuration File ◦ Controller Scripting

# 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`.

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>
          <Essential>false</Essential>
          <Replaces>com.vendor.root.component2old</Replaces>
      </Package>

### Summary of Package Information File Elements

Element | Description
--- | ---
DisplayName | 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.
Description | 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.
Version | 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.
ReleaseDate | Date when this component version was released. Required.
Name | Domain-like identification for this component. Required.
Dependencies | 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 Component Dependencies.
AutoDependOn | 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. 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.
Virtual | Set to `true` to hide the component from the installer. Note that setting this on a root component does not work.
SortingPriority | Priority of the component in the tree. The tree is sorted from highest to lowest priority, with the highest priority on the top.
Licenses | List 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`. 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).
Script | File name of a script being loaded. Optional. For more information, see Adding Operations.
UserInterfaces | List 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.
Translations | List 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.
UpdateText | Description added to the component description if this is an update to the component. Optional.
Default | Possible 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.
Essential | Marks 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.
ForcedInstallation | Determines that the package must always be installed. End users cannot deselect it in the installer.
Replaces | Comma-separated list of components to replace. Optional.
DownloadableArchives | 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.
RequiresAdminRights | Set to `true` if the package needs to be installed with elevated permissions. Optional.
Checkable | Set 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.

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

Configuration File ◦ Controller Scripting