From c1c943fa0141def4aafba0b4cba48ce21a308da5 Mon Sep 17 00:00:00 2001 From: Arttu Tarkiainen Date: Fri, 22 Sep 2023 14:59:06 +0300 Subject: [PATCH] Add example for component aliases Add example project and related documentation for component aliases concept. Change-Id: I6937116a32c3a2abde8dc86a503ce8410d43f9e0 Reviewed-by: Katja Marttila Reviewed-by: Leena Miettinen --- examples/componentalias/README | 5 + examples/componentalias/componentalias.pro | 13 ++ examples/componentalias/config/aliases.xml | 28 +++ examples/componentalias/config/config.xml | 10 ++ .../componentA/data/installcontentA.txt | 2 + .../packages/componentA/meta/package.xml | 8 + .../componentB/data/installcontentB.txt | 2 + .../packages/componentB/meta/package.xml | 8 + .../componentC/data/installcontentC.txt | 2 + .../packages/componentC/meta/package.xml | 8 + .../componentD/data/installcontentD.txt | 2 + .../packages/componentD/meta/package.xml | 8 + .../componentE/data/installcontentE.txt | 2 + .../packages/componentE/meta/package.xml | 8 + examples/doc/componentalias.qdoc | 160 ++++++++++++++++++ examples/examples.pro | 1 + 16 files changed, 267 insertions(+) create mode 100644 examples/componentalias/README create mode 100644 examples/componentalias/componentalias.pro create mode 100644 examples/componentalias/config/aliases.xml create mode 100644 examples/componentalias/config/config.xml create mode 100644 examples/componentalias/packages/componentA/data/installcontentA.txt create mode 100644 examples/componentalias/packages/componentA/meta/package.xml create mode 100644 examples/componentalias/packages/componentB/data/installcontentB.txt create mode 100644 examples/componentalias/packages/componentB/meta/package.xml create mode 100644 examples/componentalias/packages/componentC/data/installcontentC.txt create mode 100644 examples/componentalias/packages/componentC/meta/package.xml create mode 100644 examples/componentalias/packages/componentD/data/installcontentD.txt create mode 100644 examples/componentalias/packages/componentD/meta/package.xml create mode 100644 examples/componentalias/packages/componentE/data/installcontentE.txt create mode 100644 examples/componentalias/packages/componentE/meta/package.xml create mode 100644 examples/doc/componentalias.qdoc 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 @@ + + + + set1 + Component Set 1 + Alias for components A, B, and C + 1.0.0 + false + componentA,componentB,componentC + + + set2 + Component Set 2 + Alias for components D, and E + 1.0.0 + false + componentD,componentE + + + set-full + Full Component Set + Alias for full installation + 1.0.0 + false + set1,set2 + + + 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 @@ + + + Component Alias Example + 1.0.0 + Component Alias Example + Qt-Project + Qt IFW Examples + @HomeDir@/IfwExamples/componentalias + aliases.xml + 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 @@ + + + Component A + This component is a part of a component alias. + 1.0.0 + 2014-08-25 + 100 + 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 @@ + + + Component B + This component is a part of a component alias. + 1.0.0 + 2014-08-25 + 90 + 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 @@ + + + Component C + This component is a part of a component alias. + 1.0.0 + 2014-08-25 + 80 + 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 @@ + + + Component D + This component is a part of a component alias. + 1.0.0 + 2014-08-25 + 70 + 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 @@ + + + Component E + This component is a part of a component alias. + 1.0.0 + 2014-08-25 + 60 + 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 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 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 . 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 property. + + \section1 Optional Dependencies for Component Aliases + + In addition to dependencies declared with \c and \c as + shown in this example, aliases may have optional dependencies declared with \c + and \c 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 \