diff options
Diffstat (limited to 'examples')
19 files changed, 274 insertions, 5 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..9a1e4de43 --- /dev/null +++ b/examples/doc/componentalias.qdoc @@ -0,0 +1,162 @@ +/**************************************************************************** +** +** 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. + + \image qtifw-examples-componentalias.png + + \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/doc/images/qtifw-examples-componentalias.png b/examples/doc/images/qtifw-examples-componentalias.png Binary files differnew file mode 100644 index 000000000..8195a241d --- /dev/null +++ b/examples/doc/images/qtifw-examples-componentalias.png diff --git a/examples/doc/online.qdoc b/examples/doc/online.qdoc index f901c3445..0c14a8c26 100644 --- a/examples/doc/online.qdoc +++ b/examples/doc/online.qdoc @@ -150,7 +150,7 @@ only updates packages that are new, or have a higher version number. See also the \l{Summary of repogen Parameters}. - If you then run the maintenance tool from the previous installation and + If you then run the \MT from the previous installation and select \gui {Update Components}, you should see that an update of package \c A is available. diff --git a/examples/doc/treename.qdoc b/examples/doc/treename.qdoc index 22acb8e08..774b6e1fa 100644 --- a/examples/doc/treename.qdoc +++ b/examples/doc/treename.qdoc @@ -106,7 +106,7 @@ \section2 Multiple Tree Names in One Component Branch Components in a single branch (\e A, \e{A.sub1}, \e{A.sub1.sub1}, \e{A.sub1.sub1.sub2} and so - on) may each declare a separate tree name. The installer or maintenance tool calculates the + on) may each declare a separate tree name. The installer or \MT calculates the new locations for components in an ascending order from leaf components to root components, so that \e{A.sub1.sub1.sub2} is moved first and \e A last. @@ -120,18 +120,18 @@ of the installer has installed component \e A with tree name \e ANewName1, and the repository is updated with a new version of component \e A that declares tree name \e ANewName2, the new location is only applied when the user updates the component - locally with the maintenance tool. + locally with the \MT. \li The automatic tree names of children of components with tree name and \c moveChildren set to \c true are moved with the parent regardless if installed or not. Therefore, if the user has installed component \e{A.sub1} but not component \e A, and \e A is updated in the repository with a new tree name, the \e{A.sub1} uses also the new tree name in - maintenance tool's component tree. + \MT's component tree. \endlist \section2 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 + the installer or \MT is configured to allow unstable components with \c <AllowUnstableComponents> configuration file element, the offending components are either registered as unstable components with their original name or not registered at all. 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 \ |
