Component Alias Example

Using installer's aliases.xml file to define component aliases and their relations to other aliases and components.

Component Alias illustrates how to specify component aliases and how they influence the installation and maintenance processes for command line usage.

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 <AliasDefinitionsFile> element is set to aliases.xml to tell the installer the source for the alias definitions.

<?xml version="1.0" encoding="UTF-8"?>
<Installer>
    <Name>Component Alias Example</Name>
    <Version>1.0.0</Version>
    <Title>Component Alias Example</Title>
    <Publisher>Qt-Project</Publisher>
    <StartMenuDir>Qt IFW Examples</StartMenuDir>
    <TargetDir>@HomeDir@/IfwExamples/componentalias</TargetDir>
    <AliasDefinitionsFile>aliases.xml</AliasDefinitionsFile>
</Installer>

In this example, the aliases.xml file declares three component aliases. Two aliases, set1 and set2 require a subset of available components, while set-full requires the former two aliases, thus all available components.

<?xml version="1.0"?>
<Aliases>
    <Alias>
        <Name>set1</Name>
        <DisplayName>Component Set 1</DisplayName>
        <Description>Alias for components A, B, and C</Description>
        <Version>1.0.0</Version>
        <Virtual>false</Virtual>
        <RequiredComponents>componentA,componentB,componentC</RequiredComponents>
    </Alias>
    <Alias>
        <Name>set2</Name>
        <DisplayName>Component Set 2</DisplayName>
        <Description>Alias for components D, and E</Description>
        <Version>1.0.0</Version>
        <Virtual>false</Virtual>
        <RequiredComponents>componentD,componentE</RequiredComponents>
    </Alias>
    <Alias>
        <Name>set-full</Name>
        <DisplayName>Full Component Set</DisplayName>
        <Description>Alias for full installation</Description>
        <Version>1.0.0</Version>
        <Virtual>false</Virtual>
        <RequiredAliases>set1,set2</RequiredAliases>
    </Alias>
</Aliases>

For full reference of the alias definitions file syntax, see Alias Definition File.

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.

Referring to Component Aliases from Command Line

The declared component aliases can be used from the installer's command line interface with the search and install commands.

Searching Available Component Aliases

The search command will by default search available aliases first, and then normal components:

$ installer search

The command will print a table of aliases that were declared in the alias definition file:

Name: set-full
Display name: Full Component Set
Description: Alias for full installation
Version: 1.0.0
Components:
Required aliases: set1,set2
========================================
Name: set1
Display name: Component Set 1
Description: Alias for components A, B, and C
Version: 1.0.0
Components: componentA,componentB,componentC
Required aliases:
========================================
Name: set2
Display name: Component Set 2
Description: Alias for components D, and E
Version: 1.0.0
Components: componentD,componentE
Required aliases:

Installing Available Component Aliases

The install command can be used to install the components referred by a component alias:

$ installer install set1

This command is practically equivalent to selecting the components explicitly by their names:

$ installer install componentA componentB componentC

When selecting aliases for installation, the component changes summary will show separate sections for components selected by a aliases, to differentiate from manual selection:

$ installer install set1 componentD

This will output the following component changes summary:

Components selected by alias "set1":
componentA
componentB
componentC
Selected components without dependencies:
componentD

The <RequiredComponents> property does not declare a hard dependency for components, and those can be later on updated or uninstalled individually from the alias:

$ maintenancetool remove componentA

After this, selecting the set1 alias for installation again would also select componentA for reinstallation.

Virtual Component Aliases

Component aliases may be declared <Virtual>. This works similarly with virtual components, so that they cannot be manually selected by the user and do not show in component search results. Such aliases must be included by other aliases with the <RequiredAliases> property.

Optional Dependencies for Component Aliases

In addition to dependencies declared with <RequiredComponents> and <RequiredAliases> as shown in this example, aliases may have optional dependencies declared with <OptionalComponents> and <OptionalAliases> properties. The latter properties differ from the requirements in that they do not cause the alias declaring the requirement to become unselectable, in case the referenced components or aliases are not known to the installer.

This provides the packager some flexibility for declaring the dependencies. For example, an installer may be expected to use an optional repository, which contains components that a component alias optionally depends on, but the alias should be also available for installation when the repository is disabled.

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.