Add example for component aliases

Add example project and related documentation for component aliases
concept.

Change-Id: I6937116a32c3a2abde8dc86a503ce8410d43f9e0
Reviewed-by: Katja Marttila <katja.marttila@qt.io>
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>

16 files changed, 267 insertions, 0 deletions

diff --git a/examples/componentalias/README b/examples/componentalias/README
new file mode 100644
index 000000000..8253c6701
--- /dev/null
+++ b/examples/componentalias/README
@@ -0,0 +1,5 @@
+Create an installer that shows how component aliases work
+
+Generate installer with:
+
+binarycreator -c config/config.xml -p packages installer
diff --git a/examples/componentalias/componentalias.pro b/examples/componentalias/componentalias.pro
new file mode 100644
index 000000000..415df49d5
--- /dev/null
+++ b/examples/componentalias/componentalias.pro
@@ -0,0 +1,13 @@
+TEMPLATE = aux
+
+INSTALLER = installer
+
+INPUT = $$PWD/config/config.xml $$PWD/packages
+example.input = INPUT
+example.output = $$INSTALLER
+example.commands = ../../bin/binarycreator -c $$PWD/config/config.xml -p $$PWD/packages ${QMAKE_FILE_OUT}
+example.CONFIG += target_predeps no_link combine
+
+QMAKE_EXTRA_COMPILERS += example
+
+OTHER_FILES = README
diff --git a/examples/componentalias/config/aliases.xml b/examples/componentalias/config/aliases.xml
new file mode 100644
index 000000000..baf89f9b1
--- /dev/null
+++ b/examples/componentalias/config/aliases.xml
@@ -0,0 +1,28 @@
+<?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>
+
diff --git a/examples/componentalias/config/config.xml b/examples/componentalias/config/config.xml
new file mode 100644
index 000000000..440930355
--- /dev/null
+++ b/examples/componentalias/config/config.xml
@@ -0,0 +1,10 @@
+<?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>
diff --git a/examples/componentalias/packages/componentA/data/installcontentA.txt b/examples/componentalias/packages/componentA/data/installcontentA.txt
new file mode 100644
index 000000000..f40001983
--- /dev/null
+++ b/examples/componentalias/packages/componentA/data/installcontentA.txt
@@ -0,0 +1,2 @@
+This file will be installed into the target directory....
+
diff --git a/examples/componentalias/packages/componentA/meta/package.xml b/examples/componentalias/packages/componentA/meta/package.xml
new file mode 100644
index 000000000..729989fd9
--- /dev/null
+++ b/examples/componentalias/packages/componentA/meta/package.xml
@@ -0,0 +1,8 @@
+<?xml version="1.0"?>
+<Package>
+    <DisplayName>Component A</DisplayName>
+    <Description>This component is a part of a component alias.</Description>
+    <Version>1.0.0</Version>
+    <ReleaseDate>2014-08-25</ReleaseDate>
+    <SortingPriority>100</SortingPriority>
+</Package>
diff --git a/examples/componentalias/packages/componentB/data/installcontentB.txt b/examples/componentalias/packages/componentB/data/installcontentB.txt
new file mode 100644
index 000000000..f40001983
--- /dev/null
+++ b/examples/componentalias/packages/componentB/data/installcontentB.txt
@@ -0,0 +1,2 @@
+This file will be installed into the target directory....
+
diff --git a/examples/componentalias/packages/componentB/meta/package.xml b/examples/componentalias/packages/componentB/meta/package.xml
new file mode 100644
index 000000000..c6eba4223
--- /dev/null
+++ b/examples/componentalias/packages/componentB/meta/package.xml
@@ -0,0 +1,8 @@
+<?xml version="1.0"?>
+<Package>
+    <DisplayName>Component B</DisplayName>
+    <Description>This component is a part of a component alias.</Description>
+    <Version>1.0.0</Version>
+    <ReleaseDate>2014-08-25</ReleaseDate>
+    <SortingPriority>90</SortingPriority>
+</Package>
diff --git a/examples/componentalias/packages/componentC/data/installcontentC.txt b/examples/componentalias/packages/componentC/data/installcontentC.txt
new file mode 100644
index 000000000..f40001983
--- /dev/null
+++ b/examples/componentalias/packages/componentC/data/installcontentC.txt
@@ -0,0 +1,2 @@
+This file will be installed into the target directory....
+
diff --git a/examples/componentalias/packages/componentC/meta/package.xml b/examples/componentalias/packages/componentC/meta/package.xml
new file mode 100644
index 000000000..59af43132
--- /dev/null
+++ b/examples/componentalias/packages/componentC/meta/package.xml
@@ -0,0 +1,8 @@
+<?xml version="1.0"?>
+<Package>
+    <DisplayName>Component C</DisplayName>
+    <Description>This component is a part of a component alias.</Description>
+    <Version>1.0.0</Version>
+    <ReleaseDate>2014-08-25</ReleaseDate>
+    <SortingPriority>80</SortingPriority>
+</Package>
diff --git a/examples/componentalias/packages/componentD/data/installcontentD.txt b/examples/componentalias/packages/componentD/data/installcontentD.txt
new file mode 100644
index 000000000..f40001983
--- /dev/null
+++ b/examples/componentalias/packages/componentD/data/installcontentD.txt
@@ -0,0 +1,2 @@
+This file will be installed into the target directory....
+
diff --git a/examples/componentalias/packages/componentD/meta/package.xml b/examples/componentalias/packages/componentD/meta/package.xml
new file mode 100644
index 000000000..eccbd8d4a
--- /dev/null
+++ b/examples/componentalias/packages/componentD/meta/package.xml
@@ -0,0 +1,8 @@
+<?xml version="1.0"?>
+<Package>
+    <DisplayName>Component D</DisplayName>
+    <Description>This component is a part of a component alias.</Description>
+    <Version>1.0.0</Version>
+    <ReleaseDate>2014-08-25</ReleaseDate>
+    <SortingPriority>70</SortingPriority>
+</Package>
diff --git a/examples/componentalias/packages/componentE/data/installcontentE.txt b/examples/componentalias/packages/componentE/data/installcontentE.txt
new file mode 100644
index 000000000..f40001983
--- /dev/null
+++ b/examples/componentalias/packages/componentE/data/installcontentE.txt
@@ -0,0 +1,2 @@
+This file will be installed into the target directory....
+
diff --git a/examples/componentalias/packages/componentE/meta/package.xml b/examples/componentalias/packages/componentE/meta/package.xml
new file mode 100644
index 000000000..95b4ebd72
--- /dev/null
+++ b/examples/componentalias/packages/componentE/meta/package.xml
@@ -0,0 +1,8 @@
+<?xml version="1.0"?>
+<Package>
+    <DisplayName>Component E</DisplayName>
+    <Description>This component is a part of a component alias.</Description>
+    <Version>1.0.0</Version>
+    <ReleaseDate>2014-08-25</ReleaseDate>
+    <SortingPriority>60</SortingPriority>
+</Package>
diff --git a/examples/doc/componentalias.qdoc b/examples/doc/componentalias.qdoc
new file mode 100644
index 000000000..c4e7c8e99
--- /dev/null
+++ b/examples/doc/componentalias.qdoc
@@ -0,0 +1,160 @@
+/****************************************************************************
+**
+** Copyright (C) 2023 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Qt Installer Framework.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example componentalias
+    \ingroup qtifwexamples
+    \title Component Alias Example
+
+    \brief Using installer's aliases.xml file to define component aliases and their
+           relations to other aliases and components.
+
+    \e{Component Alias} illustrates how to specify component aliases and how they influence
+    the installation and maintenance processes for command line usage.
+
+    \include installerfw-examples-configuring.qdocinc
+
+    \list
+        \li The \c <AliasDefinitionsFile> element is set to \c aliases.xml to
+            tell the installer the source for the alias definitions.
+    \endlist
+
+    \quotefile componentalias/config/config.xml
+
+    In this example, the aliases.xml file declares three component aliases. Two aliases,
+    \c set1 and \c set2 require a subset of available components, while \c set-full
+    requires the former two aliases, thus all available components.
+
+    \quotefile componentalias/config/aliases.xml
+
+    For full reference of the alias definitions file syntax, see \l{Alias Definition File}.
+
+    \include installerfw-examples-packaging.qdocinc
+
+    \section1 Referring to Component Aliases from Command Line
+
+    The declared component aliases can be used from the installer's command line interface
+    with the \c search and \c install commands.
+
+    \section2 Searching Available Component Aliases
+
+    The \c search command will by default search available aliases first, and then normal
+    components:
+
+    \code
+    $ installer search
+    \endcode
+
+    The command will print a table of aliases that were declared in the alias definition file:
+
+    \code
+    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:
+    \endcode
+
+    \section2 Installing Available Component Aliases
+
+    The \c install command can be used to install the components referred by a component alias:
+
+    \code
+    $ installer install set1
+    \endcode
+
+    This command is practically equivalent to selecting the components explicitly by their names:
+
+    \code
+    $ installer install componentA componentB componentC
+    \endcode
+
+    When selecting aliases for installation, the component changes summary will show
+    separate sections for components selected by a aliases, to differentiate from manual
+    selection:
+
+    \code
+    $ installer install set1 componentD
+    \endcode
+
+    This will output the following component changes summary:
+
+    \code
+    Components selected by alias "set1":
+    componentA
+    componentB
+    componentC
+    Selected components without dependencies:
+    componentD
+    \endcode
+
+    The \c <RequiredComponents> property does not declare a hard dependency for components,
+    and those can be later on updated or uninstalled individually from the alias:
+
+    \code
+    $ maintenancetool remove componentA
+    \endcode
+
+    After this, selecting the \c set1 alias for installation again would also select
+    \c componentA for reinstallation.
+
+    \section1 Virtual Component Aliases
+
+    Component aliases may be declared \c <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 \c <RequiredAliases> property.
+
+    \section1 Optional Dependencies for Component Aliases
+
+    In addition to dependencies declared with \c <RequiredComponents> and \c <RequiredAliases> as
+    shown in this example, aliases may have optional dependencies declared with \c <OptionalComponents>
+    and \c <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.
+
+    \include installerfw-examples-generating.qdocinc
+*/
diff --git a/examples/examples.pro b/examples/examples.pro
index 283f81abe..eca806812 100644
--- a/examples/examples.pro
+++ b/examples/examples.pro
@@ -2,6 +2,7 @@ TEMPLATE = subdirs
 
 SUBDIRS += \
   changeuserinterface \
+  componentalias \
   componenterror \
   dependencies \
   dynamicpage \