Tree Name Example

Using components' package.xml files to define custom locations in the component tree.

Tree Name illustrates how to specify custom locations for components in the component tree view and how that influences the installation and maintenance processes.

Configuring the Example Installer

The installer configuration file, config.xml, in the config directory specifies the text and default values used in the installer:

The <Name> element sets the application name and adds it to the page name and introduction text.
The <Version> element sets the application version number.
The <Title> element sets the installer name and displays it on the title bar.
The <Publisher> element sets the publisher of the software (as shown in the Windows Control Panel, for example).
The <StartMenuDir> element sets the name of the default program group for the product in the Windows Start menu.
The <TargetDir> element sets the default target directory location to be within the IfwExamples directory in the home directory of the current user (because it uses the pre-existing variable , @HomeDir@, as part of the value). For more information, see Predefined Variables.

The <WizardShowPageList> element is set to false to hide the page list widget on the left side of the installer wizard window.

<?xml version="1.0" encoding="UTF-8"?>
<Installer>
    <Name>Tree Name Example</Name>
    <Version>1.0.0</Version>
    <Title>Tree Name Example</Title>
    <Publisher>The Qt Company</Publisher>
    <StartMenuDir>Qt IFW Examples</StartMenuDir>
    <TargetDir>@HomeDir@/IfwExamples/treename</TargetDir>
    <WizardShowPageList>false</WizardShowPageList>
</Installer>

Creating the Example Package Information File

The installer package information file, package.xml, in the meta directory specifies the components that are available for installation:

The <DisplayName> element sets the human-readable name of the component.
The <Description> element sets the human-readable description of the component.
The <Version> element sets the version number of the component.
The <ReleaseDate> element sets the date of release for this component version.

The <TreeName> element specifies the location of the component in the component tree. The element accepts an optional moveChildren attribute with a boolean value. If the value is set to true, any child components of this component are also moved to the modified location.

Note: Without this element the identifier of this component decides the location in the component tree.

In this example, the package.xml files for the components contain additional elements that specify the component tree locations. The following sections illustrate how the elements are used.

Specifying Tree Name to Root Node

We define a tree name ASub1ToRoot for component A subcomponent 1. Thus, this child component of A becomes a new root component. By default the children are not moved to the new location, so A sub-subcomponent1 becomes a new direct child of A.

<?xml version="1.0" encoding="UTF-8"?>
<Package>
    <DisplayName>A subcomponent 1 (moved to root)</DisplayName>
    <Description>Subcomponent of component A</Description>
    <Version>1.0.0-1</Version>
    <ReleaseDate>2021-01-01</ReleaseDate>
    <TreeName>ASub1ToRoot</TreeName>
</Package>

Specifying Tree Name and Moving Children

As above, we define a tree name BSub1ToRoot for component B subcomponent 1, but this time we set the moveChildren attribute to true. The component becomes a new root component and the child component B sub-subcomponent 1 of this component moves to the new location with the parent.

<?xml version="1.0" encoding="UTF-8"?>
<Package>
    <DisplayName>B subcomponent 1 (moved to root with children)</DisplayName>
    <Description>Subcomponent of component B</Description>
    <Version>1.0.0-1</Version>
    <ReleaseDate>2021-01-01</ReleaseDate>
    <TreeName moveChildren="true">BSub1ToRoot</TreeName>
</Package>

Specifying Tree Name to Sub Node

We define a tree name A.subC for component C and set the moveChildren attribute to true. Thus, this originally root component is moved as a child component of A. The child components C subcomponent 1 and C subcomponent 2 move to the new location with the parent.

<?xml version="1.0" encoding="UTF-8"?>
<Package>
    <DisplayName>C (moved to sub node with children)</DisplayName>
    <Description>Example component C</Description>
    <Version>1.0.0-1</Version>
    <ReleaseDate>2021-01-01</ReleaseDate>
    <TreeName moveChildren="true">A.subC</TreeName>
</Package>

Specifying Tree Name to Existing Node

We define a tree name D for component E. Node D is already a part of an existing component identifier for D subcomponent 1 (D.sub1), but the packages directory does not contain a component for the identifier, so it is possible to declare a tree name D. The component E becomes a new root component and parent of D subcomponent 1. As the moveChildren attribute is set to true, the child component E subcomponent 2 is moved with the parent.

<?xml version="1.0" encoding="UTF-8"?>
<Package>
    <DisplayName>E (moved to free existing node with children)</DisplayName>
    <Description>Example component E</Description>
    <Version>1.0.0-1</Version>
    <ReleaseDate>2021-01-01</ReleaseDate>
    <TreeName moveChildren="true">D</TreeName>
</Package>

Other Considerations

Multiple Tree Names in One Component Branch

Components in a single branch (A, A.sub1, A.sub1.sub1, A.sub1.sub1.sub2 and so on) may each declare a separate tree name. The installer or maintenance tool calculates the new locations for components in an ascending order from leaf components to root components, so that A.sub1.sub1.sub2 is moved first and A last.

Tree Names of Installed and Remote Components

For online installers, the repositories may declare updated tree names for components, so the following rules apply:

The tree names for components become static after being installed. Therefore, if the user of the installer has installed component A with tree name ANewName1, and the repository is updated with a new version of component A that declares tree name ANewName2, the new location is only applied when the user updates the component locally with the maintenance tool.
The automatic tree names of children of components with tree name and moveChildren set to true are moved with the parent regardless if installed or not. Therefore, if the user has installed component A.sub1 but not component A, and A is updated in the repository with a new tree name, the A.sub1 uses also the new tree name in maintenance tool's component tree.

Tree Name and Name Conflicts

The tree names may conflict with existing component names or other tree names. Depending on whether the installer or maintenance tool is configured to allow unstable components with <AllowUnstableComponents> configuration file element, the offending components are either registered as unstable components with their original name or not registered at all.

Note: Components from remote repositories can never override already installed components in the tree view. If a conflicting remote component cannot be registered with the original name either in case a local component has reserved it with a tree name, the component is not registered.

Generating the Example Installer

To create the example installer, switch to the example source directory on the command line and enter the following command:

On Windows:

..\..\bin\binarycreator.exe -c config\config.xml -p packages installer.exe

On Linux or macOS:

../../bin/binarycreator -c config/config.xml -p packages installer

This creates the installer to the current directory.

Files:

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