diff options
Diffstat (limited to 'doc')
39 files changed, 1130 insertions, 462 deletions
diff --git a/doc/config/ifw.qdocconf b/doc/config/ifw.qdocconf index 5a1e6cfa5..17440d802 100644 --- a/doc/config/ifw.qdocconf +++ b/doc/config/ifw.qdocconf @@ -2,22 +2,21 @@ include($QT_INSTALL_DOCS/global/qt-cpp-defines.qdocconf) include($QT_INSTALL_DOCS/global/compat.qdocconf) include($QT_INSTALL_DOCS/global/fileextensions.qdocconf) -moduleheader = IFWDoc -includepaths += -I ./includes \ - -I ../src/libs/installer \ - -I ../src/libs/kdtools \ - -I ../src/libs/7zip/unix/CPP \ - -I ../src/libs/7zip/win/CPP +includepaths += \ + ../../src/libs/installer \ + ../../src/libs/3rdparty/7zip/unix/CPP \ + ../../src/libs/3rdparty/7zip/win/CPP \ + ../../src/libs/3rdparty/libarchive language = Cpp project = "QtInstallerFramework" description = "Qt Installer Framework Manual" -url = http://qt-project.org/doc/qtinstallerframework/ +url = https://doc.qt.io/qtinstallerframework/ sourcedirs += ../../src/libs/installer ../../src/libs/kdtools ../includes headerdirs += ../../src/libs/installer ../../src/libs/kdtools -imagedirs = ../images ../templates/images +imagedirs = ../images exampledirs = .. \ ../../examples @@ -49,6 +48,9 @@ qhp.InstallerFramework.subprojects.manual.title = Qt Installer Framework Manual qhp.InstallerFramework.subprojects.manual.indexTitle = Qt Installer Framework Manual qhp.InstallerFramework.subprojects.manual.type = manual +macro.IFW = "Qt Installer Framework" +macro.MT = "maintenance tool" + # For docs, QT_VERSION resolves to IFW version macro.ifwversion = $QT_VERSION diff --git a/doc/doc.pri b/doc/doc.pri new file mode 100644 index 000000000..4f6a07d6f --- /dev/null +++ b/doc/doc.pri @@ -0,0 +1,41 @@ +QT += widgets concurrent network qml xml + +DOC_TARGETDIR = html +INSTALL_DOC_PATH = $$IFW_BUILD_TREE/doc/$$DOC_TARGETDIR + +build_online_docs: \ + DOC_FILES = $$PWD/ifw-online.qdocconf +else: \ + DOC_FILES = $$PWD/ifw.qdocconf + +qtdocs.name = QT_INSTALL_DOCS +qtdocs.value = $$[QT_INSTALL_DOCS/src] +qdocindex.name = QDOC_INDEX_DIR +qdocindex.value = $$[QT_INSTALL_DOCS] +qtver.name = QT_VERSION +qtver.value = $$VERSION +qtvertag.name = QT_VERSION_TAG +qtvertag.value = $$replace(VERSION, \.,) +QDOC_ENV += \ + qtdocs \ + qdocindex \ + qtver \ + qtvertag + +DOC_HTML_INSTALLDIR = $$INSTALL_DOC_PATH +DOC_QCH_OUTDIR = $$IFW_BUILD_TREE/doc +DOC_QCH_INSTALLDIR = $$INSTALL_DOC_PATH + +for (include_path, INCLUDEPATH): \ + DOC_INCLUDES += -I $$shell_quote($$include_path) +for (module, QT) { + MOD = $$replace(module, \-,_) + MOD_INCLUDES = $$eval(QT.$${MOD}.includes) + for (include_path, MOD_INCLUDES): \ + DOC_INCLUDES += -I $$shell_quote($$include_path) +} +for (include_path, QMAKE_DEFAULT_INCDIRS): \ + DOC_INCLUDES += -I $$shell_quote($$include_path) +macos: DOC_INCLUDES += -F $$shell_quote($$[QT_INSTALL_LIBS]) + +include(doc_targets.pri) diff --git a/doc/doc.pro b/doc/doc.pro deleted file mode 100644 index b22f139f0..000000000 --- a/doc/doc.pro +++ /dev/null @@ -1,12 +0,0 @@ -TEMPLATE = aux - -CONFIG += force_qt -QT += core-private widgets concurrent network qml xml - -CONFIG += force_independent -QMAKE_DOCS_TARGETDIR = html - -build_online_docs: \ - QMAKE_DOCS = $$PWD/ifw-online.qdocconf -else: \ - QMAKE_DOCS = $$PWD/ifw.qdocconf diff --git a/doc/doc_targets.pri b/doc/doc_targets.pri new file mode 100644 index 000000000..274cf616a --- /dev/null +++ b/doc/doc_targets.pri @@ -0,0 +1,89 @@ +# Creates targets for building documentation +# (adapted from qt_docs.prf) +# +# Usage: Define variables (details below) and include this pri file afterwards. +# +# QDOC_ENV - environment variables to set for the qdoc call (see example below) +# DOC_INDEX_PATHS - list of paths where qdoc should search for index files of dependent +# modules (Qt index path is included by default) +# DOC_FILES - list of qdocconf files +# DOC_OUTDIR_POSTFIX - html is generated in $$OUT_PWD/<qdocconf_name>$$DOC_OUTDIR_POSTFIX +# DOC_HTML_INSTALLDIR - path to install the directory of html files +# DOC_QCH_OUTDIR - path to generate the qch files +# DOC_QCH_INSTALLDIR - path to install the qch files +# +# Example for QDOC_ENV: +# ver.name = VERSION +# ver.value = 1.0.2 +# foo.name = FOO +# foo.value = foo +# QDOC_ENV = ver foo + +isEmpty(DOC_FILES): error("Set DOC_FILES before including doc_targets.pri") +isEmpty(DOC_HTML_INSTALLDIR): error("Set DOC_HTML_INSTALLDIR before including doc_targets.pri") +isEmpty(DOC_QCH_OUTDIR): error("Set DOC_QCH_OUTDIR before including doc_targets.pri") +isEmpty(DOC_QCH_INSTALLDIR): error("Set DOC_QCH_INSTALLDIR before including doc_targets.pri") + +QT_TOOL_ENV = $$QDOC_ENV +qtPrepareTool(QDOC, qdoc) +QT_TOOL_ENV = + +!build_online_docs: qtPrepareLibExecTool(QHELPGENERATOR, qhelpgenerator) +qtPrepareLibExecTool(QTATTRIBUTIONSSCANNER, qtattributionsscanner) + +DOCS_BASE_OUTDIR = $$OUT_PWD/doc +DOC_INDEXES += -indexdir $$shell_quote($$[QT_INSTALL_DOCS]) +for (index_path, DOC_INDEX_PATHS): \ + DOC_INDEXES += -indexdir $$shell_quote($$index_path) + +for (doc_file, DOC_FILES) { + !exists($$doc_file): error("Cannot find documentation specification file $$doc_file") + DOC_TARGET = $$replace(doc_file, ^(.*/)?(.*)\\.qdocconf$, \\2) + isEmpty(DOC_TARGETDIR): DOC_TARGETDIR = $$DOC_TARGET + DOC_OUTPUTDIR = $${DOCS_BASE_OUTDIR}/$${DOC_TARGETDIR}$${DOC_OUTDIR_POSTFIX} + + html_docs_$${DOC_TARGET}.commands = $$QDOC -outputdir $$shell_quote($$DOC_OUTPUTDIR) $$doc_file $$DOC_INDEXES $$DOC_INCLUDES + QMAKE_EXTRA_TARGETS += html_docs_$${DOC_TARGET} + + !isEmpty(html_docs.commands): html_docs.commands += && + html_docs.commands += $$eval(html_docs_$${DOC_TARGET}.commands) + + inst_html_docs.files += $$DOC_OUTPUTDIR + + !build_online_docs { + qch_docs_$${DOC_TARGET}.commands = $$QHELPGENERATOR $$shell_quote($$DOC_OUTPUTDIR/$${DOC_TARGET}.qhp) -o $$shell_quote($$DOC_QCH_OUTDIR/$${DOC_TARGET}.qch) + qch_docs_$${DOC_TARGET}.depends = html_docs_$${DOC_TARGET} + QMAKE_EXTRA_TARGETS += qch_docs_$${DOC_TARGET} + + !isEmpty(qch_docs.commands): qch_docs.commands += && + qch_docs.commands += $$eval(qch_docs_$${DOC_TARGET}.commands) + + inst_qch_docs.files += $$DOC_QCH_OUTDIR/$${DOC_TARGET}.qch + } +} + +qtattributionsscanner.target = qtattributionsscanner +qtattributionsscanner.commands = $$QTATTRIBUTIONSSCANNER $$shell_quote($$IFW_SOURCE_TREE) \ + --filter "QDocModule=ifw" -o $$shell_quote($$OUT_PWD/doc/codeattributions.qdoc) +qtattributionsscanner.CONFIG += phony +QMAKE_EXTRA_TARGETS += qtattributionsscanner +html_docs.depends = qtattributionsscanner + +!build_online_docs { + qch_docs.depends = html_docs + inst_qch_docs.path = $$DOC_QCH_INSTALLDIR + inst_qch_docs.CONFIG += no_check_exist no_default_install no_build + install_docs.depends = install_inst_qch_docs + docs.depends = qch_docs + INSTALLS += inst_qch_docs + QMAKE_EXTRA_TARGETS += qch_docs install_docs +} else { + docs.depends = html_docs +} + +inst_html_docs.path = $$DOC_HTML_INSTALLDIR +inst_html_docs.CONFIG += no_check_exist no_default_install directory +INSTALLS += inst_html_docs +install_docs.depends += install_inst_html_docs + +QMAKE_EXTRA_TARGETS += html_docs docs diff --git a/doc/examples/aliases.xml b/doc/examples/aliases.xml new file mode 100644 index 000000000..1ce962f1e --- /dev/null +++ b/doc/examples/aliases.xml @@ -0,0 +1,30 @@ +<?xml version="1.0"?> +<Aliases> + <Alias> + <Name>package-full</Name> + <DisplayName>Full installation package</DisplayName> + <Description>Complete installation of the product</Description> + <Version>1.0.0</Version> + <Virtual>false</Virtual> + <RequiredAliases>package-essential</RequiredAliases> + <RequiredComponents>com.vendor.root.extras</RequiredComponents> + <OptionalAliases>package-optional</OptionalAliases> + </Alias> + <Alias> + <Name>package-essential</Name> + <DisplayName>Essential components</DisplayName> + <Description>Essential components for the product</Description> + <Version>1.0.0</Version> + <Virtual>false</Virtual> + <RequiredComponents>com.vendor.root.essential</RequiredComponents> + </Alias> + <Alias> + <Name>package-optional</Name> + <DisplayName>Optional components</DisplayName> + <Description>Optional components for the product</Description> + <Version>1.0.0</Version> + <Virtual>false</Virtual> + <OptionalComponents>com.vendor.root.optional1,com.vendor.root.optional2</OptionalComponents> + </Alias> +</Aliases> + diff --git a/doc/examples/config.xml b/doc/examples/config.xml index ef4598425..b04a413ec 100644 --- a/doc/examples/config.xml +++ b/doc/examples/config.xml @@ -28,4 +28,5 @@ <Url>http://www.your-repo-location/packages/</Url> </Repository> </RemoteRepositories> + <AliasDefinitionsFile>aliases.xml</AliasDefinitionsFile> </Installer> diff --git a/doc/examples/package.xml b/doc/examples/package.xml index 81792416c..216ccadb9 100644 --- a/doc/examples/package.xml +++ b/doc/examples/package.xml @@ -42,5 +42,5 @@ <Argument>@TargetDir@/Folder2</Argument> </Operation> </Operations> - <TreeName>com.vendor.subcomponent</TreeName> + <TreeName moveChildren="true">com.vendor.subcomponent</TreeName> </Package> diff --git a/doc/images/ifw-overview.png b/doc/images/ifw-overview.png Binary files differindex 4aac3cedf..8bda13d8e 100644 --- a/doc/images/ifw-overview.png +++ b/doc/images/ifw-overview.png diff --git a/doc/images/ifw-settings-cache.png b/doc/images/ifw-settings-cache.png Binary files differnew file mode 100644 index 000000000..d8678153a --- /dev/null +++ b/doc/images/ifw-settings-cache.png diff --git a/doc/images/ifw-settings-network.png b/doc/images/ifw-settings-network.png Binary files differindex 25e1c9266..11e27ec6a 100644 --- a/doc/images/ifw-settings-network.png +++ b/doc/images/ifw-settings-network.png diff --git a/doc/images/ifw-settings-repositories.png b/doc/images/ifw-settings-repositories.png Binary files differindex df533fd98..46808eb01 100644 --- a/doc/images/ifw-settings-repositories.png +++ b/doc/images/ifw-settings-repositories.png diff --git a/doc/includes/IFWDoc b/doc/includes/IFWDoc deleted file mode 100644 index 75ed9fb40..000000000 --- a/doc/includes/IFWDoc +++ /dev/null @@ -1,120 +0,0 @@ -#pragma once - -#ifdef Q_CLANG_QDOC - -// installer -#include "abstractfiletask.h" -#include "abstracttask.h" -#include "adminauthorization.h" -#include "binarycontent.h" -#include "binaryformatengine.h" -#include "binaryformatenginehandler.h" -#include "binaryformat.h" -#include "binarylayout.h" -#include "commandlineparser.h" -#include "componentchecker.h" -#include "component.h" -#include "componentmodel.h" -#include "constants.h" -#include "consumeoutputoperation.h" -#include "copydirectoryoperation.h" -#include "copyfiletask.h" -#include "createdesktopentryoperation.h" -#include "createlinkoperation.h" -#include "createlocalrepositoryoperation.h" -#include "createshortcutoperation.h" -#include "downloadarchivesjob.h" -#include "downloadfiletask.h" -#include "elevatedexecuteoperation.h" -#include "environmentvariablesoperation.h" -#include "errors.h" -#include "extractarchiveoperation.h" -#include "fakestopprocessforupdateoperation.h" -#include "fileio.h" -#include "fileutils.h" -#include "globalsettingsoperation.h" -#include "globals.h" -#include "graph.h" -#include "init.h" -#include "installercalculator.h" -#include "installer_global.h" -#include "installiconsoperation.h" -#include "keepaliveobject.h" -#include "lazyplaintextedit.h" -#include "licenseoperation.h" -#include "linereplaceoperation.h" -#include "lib7z_extract.h" -#include "lib7z_list.h" -#include "lib7z_facade.h" -#include "lib7zarchive.h" -#include "libarchivearchive.h" -#include "libarchivewrapper.h" -#include "abstractarchive.h" -#include "archivefactory.h" -#include "directoryguard.h" -#include "link.h" -#include "messageboxhandler.h" -#include "metadatajob.h" -#include "minimumprogressoperation.h" -#include "observer.h" -#include "packagemanagercoredata.h" -#include "packagemanagercore.h" -#include "packagemanagergui.h" -#include "packagemanagerpagefactory.h" -#include "packagemanagerproxyfactory.h" -#include "packagesource.h" -#include "performinstallationform.h" -#include "permissionsettings.h" -#include "productkeycheck.h" -#include "progresscoordinator.h" -#include "protocol.h" -#include "proxycredentialsdialog.h" -#include "qinstallerglobal.h" -#include "qprocesswrapper.h" -#include "qsettingswrapper.h" -#include "qtpatch.h" -#include "range.h" -#include "registerfiletypeoperation.h" -#include "remoteclient.h" -#include "remotefileengine.h" -#include "remoteobject.h" -#include "remoteserverconnection.h" -#include "remoteserver.h" -#include "replaceoperation.h" -#include "repositorycategory.h" -#include "repository.h" -#include "runextensions.h" -#include "scriptengine.h" -#include "selfrestartoperation.h" -#include "serverauthenticationdialog.h" -#include "settings.h" -#include "settingsoperation.h" -#include "simplemovefileoperation.h" -#include "systeminfo.h" -#include "testrepository.h" -#include "uninstallercalculator.h" -#include "unziptask.h" -#include "utils.h" - -//kdtools -#include "environment.h" -#include "filedownloaderfactory.h" -#include "filedownloader.h" -#include "genericfactory.h" -#include "job.h" -#include "kdtoolsglobal.h" -#include "localpackagehub.h" -#include "lockfile.h" -#include "runoncechecker.h" -#include "selfrestarter.h" -#include "sysinfo.h" -#include "task.h" -#include "updatefinder.h" -#include "update.h" -#include "updateoperationfactory.h" -#include "updateoperation.h" -#include "updateoperations.h" -#include "updater.h" - -#endif // Q_CLANG_QDOC - diff --git a/doc/includes/installerfw-examples-configuring.qdocinc b/doc/includes/installerfw-examples-configuring.qdocinc index d89ace6a5..afbeef6a8 100644 --- a/doc/includes/installerfw-examples-configuring.qdocinc +++ b/doc/includes/installerfw-examples-configuring.qdocinc @@ -4,18 +4,18 @@ specifies the text and default values used in the installer: \list - \li The \c <Name> element specifies the application name that is added + \li The \c <Name> element sets the application name and adds it to the page name and introduction text. - \li The \c <Version> element specifies the application version number. - \li The \c <Title> element specifies the installer name displayed on the - title bar. - \li The \c <Publisher> element specifies the publisher of the software + \li The \c <Version> element sets the application version number. + \li The \c <Title> element sets the installer name and displays it on + the title bar. + \li The \c <Publisher> element sets the publisher of the software (as shown in the Windows Control Panel, for example). - \li The \c <StartMenuDir> element specifies the name of the default + \li The \c <StartMenuDir> element sets the name of the default program group for the product in the Windows \gui Start menu. - \li The \c <TargetDir> element specifies that the default target - directory is located in the \c IfwExamples directory in the home directory - of the current user (because the predefined variable\c @HomeDir@ is - used as a part of the value). For more information, see - \l{Predefined Variables}. + \li The \c <TargetDir> element sets the default target directory + location to be within the \c IfwExamples directory in the home + directory of the current user (because it uses the pre-existing + variable \c, @HomeDir@, as part of the value). For more information, + see \l{Predefined Variables}. \endlist diff --git a/doc/includes/installerfw-examples-generating.qdocinc b/doc/includes/installerfw-examples-generating.qdocinc index 65ef313b5..12b0d20b5 100644 --- a/doc/includes/installerfw-examples-generating.qdocinc +++ b/doc/includes/installerfw-examples-generating.qdocinc @@ -14,4 +14,4 @@ \endcode \endlist - The installer is created in the current directory. + This creates the installer to the current directory. diff --git a/doc/includes/installerfw-examples-packaging.qdocinc b/doc/includes/installerfw-examples-packaging.qdocinc index f8111629a..260b7e23e 100644 --- a/doc/includes/installerfw-examples-packaging.qdocinc +++ b/doc/includes/installerfw-examples-packaging.qdocinc @@ -4,12 +4,12 @@ directory specifies the components that are available for installation: \list - \li The \c <DisplayName> element specifies the human-readable name of + \li The \c <DisplayName> element sets the human-readable name of the component. - \li The \c <Description> element specifies the human-readable + \li The \c <Description> element sets the human-readable description of the component. - \li The \c <Version> element specifies the version number of the + \li The \c <Version> element sets the version number of the component. - \li The \c <ReleaseDate> element specifies the date when this component - version was released. + \li The \c <ReleaseDate> element sets the date of release for this + component version. \endlist diff --git a/doc/installerfw-cpp-classes.qdoc b/doc/installerfw-cpp-classes.qdoc index 0658b6dc4..833bf02c8 100644 --- a/doc/installerfw-cpp-classes.qdoc +++ b/doc/installerfw-cpp-classes.qdoc @@ -1,7 +1,7 @@ /**************************************************************************** ** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2022 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Installer Framework. ** diff --git a/doc/installerfw-examples.qdoc b/doc/installerfw-examples.qdoc index 365c8b431..8b425f62a 100644 --- a/doc/installerfw-examples.qdoc +++ b/doc/installerfw-examples.qdoc @@ -1,7 +1,7 @@ /**************************************************************************** ** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2022 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Installer Framework. ** diff --git a/doc/installerfw-getting-started.qdoc b/doc/installerfw-getting-started.qdoc index cfb302544..1a86953a7 100644 --- a/doc/installerfw-getting-started.qdoc +++ b/doc/installerfw-getting-started.qdoc @@ -1,7 +1,7 @@ /**************************************************************************** ** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2024 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Installer Framework. ** @@ -32,22 +32,17 @@ \title Getting Started - Qt Installer Framework is developed as part of the Qt project. The - framework itself uses Qt. However, it can be used to install all kind of - applications, including (but not limited to) applications built with Qt. + You can use the Qt Installer Framework to create installation programs for + all kinds of applications, including (but not limited to) applications built + with Qt. \section1 Supported Platforms You can use the Qt Installer Framework to create installers for all - platforms supported by \l[QtDoc]{Supported Platforms}{desktop Qt}. + platforms supported by \l{https://doc.qt.io/qt-6/supported-platforms.html}{desktop Qt}. - The installers have been tested on the following platforms: - - \list - \li Microsoft Windows 7, and later - \li Ubuntu Linux 16.04, and later - \li macOS 10.12, and later - \endlist + If you use Linux, install also + \l {https://doc.qt.io/qt-6/linux-requirements.html} {Platform Plugin dependencies}. \section1 Building from Sources @@ -57,85 +52,90 @@ \section2 Supported Compilers - The Qt Installer Framework can be compiled with Microsoft Visual Studio - 2013 and newer, GCC 4.7 and newer, and Clang 3.1 and newer. Currently, the - tested combination for Windows is Qt 5.12.4 with MSVC 2015. + You can compile the Qt Installer Framework with Microsoft Visual Studio + 2019 and newer, GCC 9 and newer, and Clang 13.0.0 and newer. Currently, the + tested combination for Windows is Qt 6.6.0 with MSVC 2019 (Windows 10). \section2 Configuring Qt If you use a statically built Qt to build the Qt Installer Framework you do not have to deliver Qt libraries, which enables you to distribute - installers as one file. Please read SSL Import and Export Restrictions - from http://doc.qt.io/qt-5/ssl.html if you are statically linking against - OpenSSL libraries. + installers as one file. For more information about statically linking + against OpenSSL libraries, see \l{http://doc.qt.io/qt-6/ssl.html}{SSL + Import and Export Restrictions}. - The supported Qt version is 5.12.7. + The supported Qt version is 6.6.0. + + Get Qt sources: + \code + \l{https://wiki.qt.io/Building_Qt_6_from_Git}{Get Qt sources from git}. + Call init-repository with --module-subset=qt5compat, qtbase, qtdeclarative, qttools, qttranslations + \endcode \section3 Configuring Qt for Windows - We recommend that you use the following options when you configure Qt for - Windows: + Use the following configuration options for Windows: \code configure -prefix %CD%\qtbase -release -static -static-runtime -accessibility -no-icu -no-sql-sqlite -no-qml-debug -nomake examples -nomake tests \endcode - Build Qt: - \code - nmake (or 'mingw32-make') module-qtbase module-qtdeclarative module-qttools module-qttranslations module-qtwinextras - \endcode - \section3 Configuring Qt for Linux - We recommend that you use the following configuration options for Linux: + Use the following configuration options for Linux: \code - configure -prefix $PWD/qtbase -release -static -accessibility -qt-zlib -qt-libpng -qt-libjpeg -qt-xcb -qt-pcre -no-glib -no-cups -no-sql-sqlite -no-qml-debug -no-opengl -no-egl -no-xinput2 -no-sm -no-icu -nomake examples -nomake tests -no-libudev - \endcode - - Build Qt: - \code - make module-qtbase module-qtdeclarative module-qttools module-qttranslations + configure -prefix $PWD/qtbase -release -static -accessibility -qt-zlib -qt-libpng -qt-libjpeg -qt-pcre -no-glib -no-cups -no-sql-sqlite -no-feature-gssapi -no-qml-debug -no-opengl -no-egl -no-xinput2 -no-sm -no-icu -nomake examples -nomake tests -no-libudev -bundled-xcb-xinput -qt-harfbuzz -qt-doubleconversion \endcode \section3 Configuring Qt for macOS - We recommend that you use the following configuration options for macOS: + Use the following configuration options for macOS: \code - configure -prefix $PWD/qtbase -release -static -no-securetransport -accessibility -qt-zlib -qt-libpng -qt-libjpeg -no-cups -no-sql-sqlite -no-qml-debug -nomake examples -nomake tests -no-freetype + configure -prefix $PWD/qtbase -release -static -accessibility -qt-zlib -qt-libpng -no-cups -no-sql-sqlite -no-qml-debug -nomake examples -nomake tests -no-freetype \endcode Build Qt: \code - make module-qtbase module-qtdeclarative module-qttools module-qttranslations + cmake --build . --parallel + cmake --install . \endcode - \section2 Configuring Support for Archive File Formats + \section2 Third Party Dependencies The Qt Installer Framework sources contain a redistribution of parts of the - libarchive compression and archive library, which requires you to link against - additional libraries; \c liblzma, \c zlib, \c libbzip2, and on macOS, \c libiconv. - - The usage of libarchive is optional and can be enabled by adding the libarchive - configuration feature to the list of values specified by the \c CONFIG variable. Installers - created with this configuration support the (de)compression of 7zip, zip, and tar archive - files, with gzip, bzip2, and xz as available compression methods. - - The \c IFW_ZLIB_LIBRARY, \c IFW_BZIP2_LIBRARY, \c IFW_LZMA_LIBRARY, and \c IFW_ICONV_LIBRARY - variables can be used to specify the exact library files if required. + \c libarchive compression and archive library, which requires you to link + against the following libraries; \c liblzma, \c zlib, \c libbzip2, and on + macOS, \c libiconv. - If you omit the feature, the installation of the additional dependencies can be skipped, - but created installers will only support the 7zip format. + To enable the use of \c libarchive, add the \c libarchive configuration + feature to the list of values specified by the \c CONFIG variable. + Installers created with this configuration support the creating and + extracting of 7zip, zip, and tar archive files, with \c gzip, bzip2, and + \c xz as available compression methods. \code qmake CONFIG+=libarchive \endcode + You can use the \c IFW_ZLIB_LIBRARY, \c IFW_BZIP2_LIBRARY, \c IFW_LZMA_LIBRARY, and \c IFW_ICONV_LIBRARY + variables to specify the exact library files. + + If you add the \c{-qt-zlib} configuration to the Qt version used to build the Qt Installer Framework, and + \c IFW_ZLIB_LIBRARY variable is empty, \c libarchive will try to use the \c zlib library compiled + into the QtCore module, which removes the need for an external library. + + If you do not enable \c libarchive support, the builtin LZMA SDK library will act as a fallback and + installation of the extra dependencies will not occur, but created installers will + only support the 7zip format. + + \note Building IFW with LZMA SDK is deprecated and may not be available in future versions. + \section3 Installing Dependencies for Windows - The source archives for the dependencies can be downloaded from: + You can download the source archives for the dependencies from: \list \li \l https://tukaani.org/xz/ @@ -164,7 +164,7 @@ The easiest way to install the missing libraries is with a third party package manager solution, like Homebrew or MacPorts. On macOS 10.15 you - should only need to additionally install the liblzma library. + should only need to additionally install the \c liblzma library. On Homebrew this would be: @@ -174,9 +174,10 @@ \section3 Troubleshooting - For libarchive related compilation errors, you may need to edit the definitions in - a configuration header file respective to your platform, which can be found from the - 'src/libs/3rdparty/libarchive/config/' directory of the Installer Framework sources. + For \c libarchive related compilation errors, you may need to edit the definitions in + a configuration header file respective to your platform. You can find this file in + the \c src/libs/3rdparty/libarchive/config/ directory of the Installer Framework sources. + \section2 Setting up Qt Installer Framework diff --git a/doc/installerfw-overview.qdoc b/doc/installerfw-overview.qdoc index 45362be3e..b1ad69dc5 100644 --- a/doc/installerfw-overview.qdoc +++ b/doc/installerfw-overview.qdoc @@ -1,7 +1,7 @@ /**************************************************************************** ** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2024 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Installer Framework. ** @@ -32,59 +32,91 @@ \title Overview of Qt Installer Framework - The Qt Installer Framework provides a set of tools and utilities to - create installers once, and deploy them across all the supported desktop - Qt platforms without rewriting the source code. The installers will have the - native look and feel on the platform where they are run: Linux, Microsoft - Windows, and macOS. + With Qt Installer Framework you can create both simple and complex installers + with thousands of components and deploy your installers across all the supported + desktop Qt platforms without rewriting the source code. Your final installers + have the native look and feel of the platform on which they run: Linux, + Microsoft Windows, and macOS. - The Qt Installer Framework tools generate installers with a set of pages + For example Qt installers are made with the Qt Installer Framework. + + Both open-source and commercial users can download Qt Installer Framework from their + Qt Account. + + Qt Installer Framework tools generate installers with a set of pages that guide the users during the installation, update, or uninstallation - process. You provide the installable content and specify information about + process. You supply the installable content and specify information about it, such as the name of the product and the installer and the text for the license agreement. You can customize the installers by adding widgets to the predefined pages - or by adding whole pages to provide users with additional options. You can - create scripts to add operations to the installer. + or by adding whole pages to offer users more options. + + Each installable package in the installer can contain one component script that + gives a comprehensive API to fine-tune how the package should be installed + on the system. You can, for example, add shortcuts to the desktop or register + file extensions for your tool. \section1 Choosing Installer Type - You can provide end users with an \e offline or \e online installer, or + You can offer end users an \e offline or \e online installer, or both, depending on your use cases. \image ifw-overview.png - Both installers install a \e {maintenance tool} that can later be used to - add, update, and remove components. Offline installers contain all the - installable components and do not require network connections during the - installation. Online installers only install the maintenance tool that then - downloads and installs components from an online repository on a web server. - Therefore, the size of an online installer binary is smaller and its - download time is shorter than that of an offline installer binary. The total - time spent downloading and running an online installer might also be shorter - than dowloading and running an offline installer if the end users do not - install all the available components. - - End users can use the maintenance tool to install additional components from + Both installers install a \e {\MT}, which allows your end users to later + add, update, and remove components. + End users can use the \MT to install more components from the server after the initial installation, as well as to receive automatic - updates to content as soon as the updates are published on the server. + updates to content as soon as the updates are available on the server. However, this works for an offline installation only if you specify a repository address in the offline installer configuration or if end users - specify the repository address themselves in the maintenance tool settings. + specify the repository address themselves in the \MT settings. + + \section2 Offline Installers + + Offline installers contain all the installable components and do not require + network connections during the installation. Create an offline installer to enable users to directly download the installation package on a media for installation on a computer later. You can also distribute the installation package on a CD-ROM or USB stick, for example. + \section2 Online installers + + Online installers install the \MT and components from an online + repository on a web server. After installation, the \MT can be used to + modify the installation from an online repository. + + The size of an online installer binary is smaller and its + download time is shorter than that of an offline installer binary. The total + time spent downloading and running an online installer might also be shorter + than downloading and running an offline installer if the end users do not + install all the available components. + Create an online installer to enable users to always install the latest - versions of the content binaries. + versions of the content packages. + \list + \li Online repositories + \li Online installer + \endlist + + \section2 Signing installers + + Signing your installer is an integral step in finalizing your product. Signing + shows that your code is safe and secure. + + Find more information on signing your installer on Windows platform + on \l{https://learn.microsoft.com/en-us/windows/win32/seccrypto/signtool} {Microsoft website}. + For more information on signing your installer in macOS, see Apple website for + \l{https://developer.apple.com/documentation/security/code_signing_services} {code signing} + and \{https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution} {notarizing}. - \section1 Promoting Updates + \section1 Promoting Updates for Online Installers Make online repositories available to promote updates to end users who - install your product. The easiest way to provide an update is to recreate + install your product. The easiest way to offer an update is to recreate the repository and upload it to the web server. For large repositories, you can update only the changed components. diff --git a/doc/installerfw-reference.qdoc b/doc/installerfw-reference.qdoc index e1f3819b9..f129f1218 100644 --- a/doc/installerfw-reference.qdoc +++ b/doc/installerfw-reference.qdoc @@ -1,7 +1,7 @@ /**************************************************************************** ** -** Copyright (C) 2020 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2022 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Installer Framework. ** @@ -39,6 +39,7 @@ \li \l{Command Line Interface} \li \l{Configuration File} \li \l{Package Directory} + \li \l{Alias Definition File} \li \l{Controller Scripting} \li \l{Component Scripting} \li \l{Operations} diff --git a/doc/installerfw-using.qdoc b/doc/installerfw-using.qdoc index 5c5bbbbc4..3cc52fb1a 100644 --- a/doc/installerfw-using.qdoc +++ b/doc/installerfw-using.qdoc @@ -1,7 +1,7 @@ /**************************************************************************** ** -** Copyright (C) 2021 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2022 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Installer Framework. ** @@ -33,12 +33,12 @@ \title End User Workflows The end user experience is similar for offline and online installers. - Along with your application, the installers install a maintenance tool that + Along with your application, the installers install a \MT that consists of a package manager, an updater, and an uninstaller. End users can - use the maintenance tool to add, update, and remove components. The - maintenance tool connects to an external repository to fetch the components + use the \MT to add, update, and remove components. The + \MT connects to an external repository to fetch the components to add or update. You can specify the repository in the configuration file - or end users can specify it in the maintenance tool settings. + or end users can specify it in the \MT settings. You can support the following end user workflows: @@ -177,7 +177,7 @@ If end users did not select all the components available for installation during the initial installation, they can use the package manager to install the remaining components from a repository later. The package manager is - part of a maintenance tool that is installed together with the application + part of a \MT that is installed together with the application during the initial installation. This only works if a repository that contains the components is available either locally or externally. @@ -186,14 +186,14 @@ \image ifw-user-flow-adding.png "Add components workflow" - This section uses the \e {Maintenance Tool} installed by the Qt 5 installer + This section uses the \e {\MT} installed by the Qt 5 installer run on macOS as an example implementation of how end users can add components - after the initial installation. The Maintenance Tool contains the package + after the initial installation. The \MT contains the package manager, updater, and uninstaller. \section1 Starting Package Manager - When end users start the Maintenance Tool, the introduction page opens: + When end users start the \MT, the introduction page opens: \image ifw-add-components-introduction.png "Introduction page" @@ -242,12 +242,12 @@ \image ifw-user-flow-removing.png "Remove components workflow" - This section uses the Qt 5 Maintenance Tool run on macOS as an example + This section uses the Qt 5 \MT run on macOS as an example implementation of how end users can remove all or selected components. \section1 Removing All Components - When end users start the Maintenance Tool, the introduction page opens: + When end users start the \MT, the introduction page opens: \image ifw-add-components-introduction.png "Introduction page" @@ -294,12 +294,12 @@ \image ifw-user-flow-updating.png "Updating workflow" - This section uses the Qt 5 Maintenance Tool run on macOS as an example + This section uses the Qt 5 \MT run on macOS as an example implementation of how end users can update installed components. \section1 Starting Updater - When end users start the Maintenance Tool, the introduction page opens: + When end users start the \MT, the introduction page opens: \image ifw-updating-introduction.png "Introduction page" @@ -339,9 +339,9 @@ \title Specifying Settings - Settings pages enable end users to specify proxy settings or install add-on - components. End users select \gui Settings on the introduction page to - specify the settings. + Settings pages enable end users to specify proxy settings, install add-on + components, and modify local cache parameters. End users select \gui Settings + on the introduction page to specify the settings. \section1 Specifying Proxy Settings @@ -366,6 +366,14 @@ After the installation, only default and user-defined repositories will be available. + \section1 Specifying Local Cache Settings + + The installers use a local cache for the meta information fetched from remote + repositories. This improves loading times when the same metadata is accessed + multiple times. End users can configure the location of the metadata cache and + clear the contents of an existing cache. + + \image ifw-settings-cache.png "Local Cache tab on Settings page" */ /*! @@ -383,7 +391,7 @@ \section1 Installing Components - Both the installer and the maintenance tool support installation of new components from + Both the installer and the \MT support installation of new components from command line. The following will install the components given as an argument and their respective dependencies: @@ -400,10 +408,17 @@ installer.exe --root "C:\Users\MyUser\MyInstallation" install \endcode + The install command can be also used for installing component aliases. If component + aliases are specified, the aliased components are selected for installation: + + \code + maintenancetool.exe install alias1 alias2 + \endcode + \section1 Checking for Available Updates To print information about available component updates, run the \c check-updates - command with the maintenance tool: + command with the \MT: \code maintenancetool.exe check-updates @@ -436,7 +451,7 @@ \section1 Listing Installed Components To get a list and print additional information about currently installed components, run the - \c list command with the maintenance tool. The command also accepts an optional regular + \c list command with the \MT. The command also accepts an optional regular expression argument to filter the shown component list. \code @@ -448,17 +463,36 @@ The \c search command can be used to search components from available repositories, or from integrated binary content in case of an offline installer. It can be used with no arguments to list all available components or with a regular expression to get a list - of only components matching the pattern. The \c --filter-packages option can be - used to specify additional filters for the search operation. For a list of usable - information elements with the option, refer to \l{Summary of Package Information File Elements}. + of only components matching the pattern. + + The \c --filter-packages option can be used to specify additional filters for the search + operation. For a list of usable information elements with the option, refer to + \l{Summary of Package Information File Elements}. + + When the value of the \c{--type} option is set to \c package, the search command will + search for available components only: + + \code + installer.exe --type package --filter-packages "DisplayName=MyComponent, Version=1.0" search "expression" + \endcode + + When the \c{--type} option is omitted, the search command will first search for matching + component aliases, and if none are found, component names: + + \code + installer.exe search "expression" + \endcode + + When the value of the \c{--type} option is set to \c alias, the search command will + search for available component aliases only: \code - installer.exe --filter-packages "DisplayName=MyComponent, Version=1.0" search "expression" + installer.exe --type alias search "expression" \endcode \section1 Performing Full Uninstallation - To uninstall all components and remove the program directory, including maintenance tool, + To uninstall all components and remove the program directory, including \MT, run \c purge command: \code @@ -479,6 +513,19 @@ installer.exe --root "C:\TargetFolder" --offline-installer-name "MyInstaller" create-offline componentA componentB \endcode + \section1 Clearing the Local Cache + + Online installers and maintenance tools created with the Qt Installer Framework cache the + meta information downloaded from remote repositories to local disk. This improves loading + times for subsequent metadata downloads. + + The cache may grow in size over time. To clear the contents of the entire cache, + use the \c clear-cache command: + + \code + maintenancetool.exe clear-cache + \endcode + \section1 Unattended Usage By default, the generated installers may ask for additional information during installation, @@ -497,7 +544,7 @@ \c {--auto-answer OverwriteTargetDirectory=Yes}. Automatic answers are shown on the console output and installation log. - By default, the installer and maintenance tool will print a summary of components to be + By default, the installer and \MT will print a summary of components to be affected by the command and then ask for permission to continue performing the action, to prevent accidental changes. For unattended usage, this can be skipped by using the \c --confirm-command option. diff --git a/doc/installerfw.qdoc b/doc/installerfw.qdoc index 630b86265..4c55c6d43 100644 --- a/doc/installerfw.qdoc +++ b/doc/installerfw.qdoc @@ -1,7 +1,7 @@ /**************************************************************************** ** -** Copyright (C) 2021 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2023 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Installer Framework. ** @@ -39,9 +39,14 @@ \section1 Version \ifwversion - The Qt Installer Framework provides a set of tools and utilities to - create installers for the supported desktop Qt platforms: Linux, Microsoft - Windows, and macOS. + Qt Installer Framework is a robust toolset for creating custom online + and offline installers. It’s highly configurable and customizable and works for all + supported Qt platforms: Linux, Microsoft Windows, and macOS. + + Here are some examples to illustrate the versatility + of Qt Installer Framework. + + \note Report bugs and suggestions for the Qt Installer Framework project in the \l{https://bugreports.qt.io/browse/QTIFW}{Qt Bugtracker}. @@ -72,6 +77,7 @@ \li \l{Command Line Interface} \li \l{Configuration File} \li \l{Package Directory} + \li \l{Alias Definition File} \li \l{Controller Scripting} \li \l{Component Scripting} \li \l{Operations} @@ -90,7 +96,7 @@ \title Creating Installers - The following steps are needed to create offline and online installers: + To create offline and online installers, do the following: \list 1 @@ -98,13 +104,13 @@ For more information, see \l{Package Directory}. \li Create a configuration file called \c config.xml in the \c config - directory. It contains information about how to build the installer + directory. It has information about how to build the installer binaries and online repositories. For more information about the file format and available settings, see \l{Configuration File}. \li Create a package information file called \c package.xml in the - \c {packages\{component}\meta} directory. It contains settings for deployment and + \c {packages\{component}\meta} directory. It has settings for deployment and the installation process. For more information, see \l{Meta Directory}. @@ -112,7 +118,7 @@ For more information, see \l{Data Directory}. \li For online installers, use the \c repogen tool to create the - repository that contains the installable content and upload the + repository that has the installable content and upload the repository to a web server. \li Use the \c binarycreator tool to create the installer. For more @@ -239,7 +245,7 @@ \li --sv, --show-virtual-components \li Show virtual components in the installer and the package manager. \row - \li -i, --install-compressed-repository <URI,...> + \li -i, --install-compressed-repository <file,...> \li Installs a QBSP or a 7z file. The QBSP (Board Support Package) file must be a .7z file which contains a valid repository. \row @@ -252,6 +258,13 @@ search command. The keys can be any of the possible package information elements, like \c DisplayName and \c Description. \row + \li --cp, --cache-path <path> + \li Sets the path used for local metadata cache. The path must be writable by the current user. + \row + \li --type package|alias + \li [CLI] Sets the type of the given arguments for commands supporting multiple argument types, + like search. Defaults to alias. + \row \li --am, --accept-messages \li [CLI] Accepts all message queries without user input. \row @@ -295,6 +308,12 @@ Note: To enable Squish support, you first need to build IFW with SQUISH_PATH parameter where SQUISH_PATH is pointing to your Squish installation folder: \c{<path_to_qt>/bin/qmake -r SQUISH_PATH=<pat_to_squish>}. + \row + \li --mco, --max-concurrent-operations <threads> + \li Specifies the maximum number of threads used to perform concurrent operations in the + unpacking phase of components. Set to a positive number, or 0 (default) to let the + application determine the ideal thread count from the amount of logical processor + cores in the system. \endtable \section1 Summary of Commands @@ -304,11 +323,11 @@ \li Command \li Usage \row - \li in, install <pkg ...> - \li Install packages given as an argument. If no packages are given, install the default package set. + \li in, install <pkg|alias ...> + \li Install packages and aliases given as an argument. If no arguments are given, install the default package set. \row \li ch, check-updates - \li Show information about available updates on the maintenance tool. + \li Show information about available updates on the \MT. \row \li up, update <pkg ...> \li Update packages given as an argument. If no packages are given, install all available updates. @@ -316,18 +335,24 @@ \li rm, remove <pkg ...> \li Uninstall selected packages and their child components. \row - \li li, list <regexp> + \li li, list <regexp for pkg> \li List information about currently installed packages. \row - \li se, search <regexp> - \li Search available packages. If no search pattern is given, show all available packages. + \li se, search <regexp for pkg|alias> + \li Search available aliases or packages. If no search pattern is given, show all available packages. \note The \c --filter-packages option can be used to specify additional filters for the search operation. See \l{Summary of Options}. + + \note The \c --type option can be used to specify the content type to search. + See \l{Summary of Options}. \row \li co, create-offline <pkg ...> \li Create offline installer from selected packages. \row + \li cc, clear-cache + \li Clear contents of the local metadata cache. + \row \li pr, purge \li Uninstall all packages and remove the program directory. \endtable @@ -361,6 +386,10 @@ relative paths, which the tools resolve relative to the location of the config.xml file. + \note The filenames of the referred files must be unique. That is, if you + want to use the same image for both \c <Logo> and \c <Watermark>, you + must add two copies of the image file with different filenames. + You can use predefined variables (embedded in @ characters) as values of the elements. For more information, see \l{Predefined Variables}. @@ -388,35 +417,30 @@ \li URL to a page that contains product information on your web site. \row - \li Icon - \li Filename for a custom installer icon. The actual file is looked up by attaching - a '.icns' (macOS), '.ico' (Windows) or '.png' (Unix) suffix. Deprecated, - use \c <InstallerApplicationIcon> or \c <InstallerWindowIcon> - instead. - \row \li InstallerApplicationIcon \li Filename for a custom installer icon. The actual file is looked up by attaching - a '.icns' (macOS), '.ico' (Windows). No functionality on Unix. + a '.icns' (macOS), '.ico' (Windows) suffix. No functionality on Unix. \row \li InstallerWindowIcon \li Filename for a custom window icon in PNG format for the Installer application. + Used on Windows and Linux, no functionality on macOS. \row \li Logo - \li Filename for a logo used as \c QWizard::LogoPixmap. + \li Filename for a logo in PNG format used as \c QWizard::LogoPixmap. \row \li Watermark - \li Filename for a watermark used as \c QWizard::WatermarkPixmap. If + \li Filename for a watermark in PNG format used as \c QWizard::WatermarkPixmap. If \c <WizardShowPageList> is set to \c true, the watermark is hidden. \row \li Banner - \li Filename for a banner used as \c QWizard::BannerPixmap (only used by ModernStyle). + \li Filename for a banner in PNG format used as \c QWizard::BannerPixmap (only used by ModernStyle). \row \li Background - \li Filename for an image used as \c QWizard::BackgroundPixmap (only used by MacStyle). + \li Filename for an image in PNG format used as \c QWizard::BackgroundPixmap (only used by MacStyle). If \c <WizardShowPageList> is set to \c true, the background is hidden. \row \li PageListPixmap - \li Filename for an image shown on top of installer page list. The image is shown + \li Filename for an image in PNG format shown on top of installer page list. The image is shown only if \c <WizardShowPageList> is also set to \c true. \row \li WizardStyle @@ -451,7 +475,12 @@ \row \li ProductImages \li A list of images to be shown on \c PerformInstallationPage. This element can have - one or several \c <Image> child elements that contain a filename for an image. + one or several \c <ProductImage> child elements that contain an \c <Image> child + element and an optional \c <Url> child element. The \c <Image> element specifies a + filename for an image in PNG format. Optional \c <Url> can be specified for each + image. Clicking on the image will open the \c <Url> in a browser. If the \c <Url> + is a reference to a file, it will be opened with a suitable application + instead of a Web browser. \row \li TitleColor \li Set the color of the titles and subtitles (takes an HTML color code, @@ -484,6 +513,18 @@ rights. Only available on Linux, where you usually do not want to install in the administrator user's home directory. \row + \li LocalCacheDir + \li Directory name for storing the metadata cache. This does not include + the leading directories, which are determined automatically based on a suitable + platform specific location for storing cache files. The user may override the path + from the installer settings. The default value is a UUID generated from the + name of the product being installed. + \row + \li PersistentLocalCache + \li Set to \c false if the fetched metadata should be removed from the local cache when + the installer exits. Otherwise the contents of the cache are kept to speed up + subsequent fetches. Defaults to \c true. + \row \li RemoteRepositories \li List of remote repositories. This element can contain several \c <Repository> child elements that each contain the \c <Url> child element that specifies the URL to @@ -494,14 +535,18 @@ For more information, see \l{Configuring Repository Categories}. \row \li MaintenanceToolName - \li Filename of the generated maintenance tool. Defaults to + \li Filename of the generated \MT. Defaults to \e maintenancetool. The platform-specific executable file extension is appended. \row \li MaintenanceToolIniFile - \li Filename for the configuration of the generated maintenance tool. Defaults to + \li Filename for the configuration of the generated \MT. Defaults to \e {MaintenanceToolName}.ini. \row + \li MaintenanceToolAlias + \li Filename for an alias of the \MT that will be created to the + Applications directory. Optional. Only used on macOS. + \row \li RemoveTargetDir \li Set to \c false if the target directory should not be deleted when uninstalling. \row @@ -521,6 +566,11 @@ \li RepositorySettingsPageVisible \li Set to \c false to hide the repository settings page inside the settings dialog. \row + \li AllowRepositoriesForOfflineInstaller + \li Set to \c false to disable usage of any temporary or user configured repositories + set for offline installers. The maintenance tool written by an offline installer + can still access the repositories. Defaults to \c true. + \row \li AllowSpaceInPath \li Set to \c false if the installation path cannot contain space characters. \row @@ -532,6 +582,11 @@ \li TargetConfigurationFile \li Filename for the configuration file on the target. Default is components.xml. \row + \li AliasDefinitionsFile + \li Filename for a XML document containing the definitions for component aliases. + For more information about how to declare component aliases in the file, + see \l{Alias Definition File}. + \row \li Translations \li List of translation files to be used for translating the user interface. To add several translation files, specify several \c <Translation> child elements that @@ -576,6 +631,83 @@ */ /*! + \previouspage ifw-globalconfig.html + \page ifw-aliasconfig.html + \nextpage noninteractive.html + + \title Alias Definition File + + The alias definition file defines the available component aliases and their + properties. The file is typically called \c aliases.xml and located in the + \c config directory. + + The component names of the Qt Installer Framework follow a domain-like + identifier syntax, for example \c com.vendor.root, \c com.vendor.root.subcomponent, + and so on. While this allows an easy way to construct a tree from the components when + running the installer in graphical mode, the names can be unintuitive for command line usage, + where the components are not displayed in a tree view. + + Instead of relying on the domain-like names for CLI usage, the packager can also define component + aliases for existing components. An alias is another name for a single component or a collection + of components. It can be used to declare alternative names for existing components that are + easier to type and combine multiple components under the same alias name, for easier selection. + + The following example shows a possible alias definition file: + + \quotefile examples/aliases.xml + + \section1 Summary of Alias Definition File Elements + + The following table summarizes the elements in the alias definition file. + + \table + \header + \li Element + \li Description + \row + \li Name + \li Name of component alias. + \row + \li DisplayName + \li Human-readable name of the component alias. + \row + \li Description + \li Human-readable description of the component alias. + \row + \li Version + \li Version number of the component alias. + \row + \li Virtual + \li Set to \c true to hide the component alias from the installer. This also + makes the alias unselectable by the user. + \row + \li RequiredComponents + \li Comma-separated list of identifiers of components that this + component alias requires. The components are selected for installation + when the component alias is selected. Note that the components must be + selectable by the user, so virtual or otherwise unselectable components + cannot be listed as a requirement. + \row + \li RequiredAliases + \li Comma-separated list of aliases that this component alias requires. The + required aliases are selected for installation when this component alias + is selected. + \row + \li OptionalComponents + \li Comma-separated list of identifiers of components that this component alias + optionally depends on. The components are selected for installation when the + component alias is selected, if the components exists and are user selectable. + Even if the components cannot be found in the installer, this alias is not marked unstable. + \row + \li OptionalAliases + \li Comma-separated list of aliases that this component alias optionally depends on. The + listed aliases are selected for installation when this component alias is selected, + if the aliases exist. Even if the aliases don't exists in the installer, + this alias is not marked unstable. + \endtable +*/ + +/*! \previouspage ifw-updates.html \page ifw-customizing-installers.html \nextpage Qt Installer Framework Examples @@ -607,7 +739,7 @@ \l{Component Scripting}. A control script is associated with the whole installer by specifying it - in the \c ControlScript element of the control.xml file of the installer. + in the \c ControlScript element of the config.xml file of the installer. Control scripts can be part of the installer resources or be passed on the command line. They can be used to modify the installer pages that are presented to users before components are loaded. Also, you can use them to @@ -749,12 +881,32 @@ it to a custom resource called \c :/translations_new. This custom resource can be added to the installer using \c binarycreator option \c -r. For more information, see \l{Summary of binarycreator Parameters}. + + If the translated language is not already part of the existing translations + of Qt Installer Framework, you need to also include the Qt Base translation for that language + in the resource file. For this you need to point to the \c qtbase_*.qm for your language from + the location of \c QT_INSTALL_TRANSLATIONS and alias it in the resource file. + + For example, for the Czech translation a custom \c translations_new.qrc should look + like this: + + \code + <!DOCTYPE RCC><RCC version="1.0"> + <qresource prefix="/translations_new"> + <file>ifw_cs.qm</file> + <file alias="qt_cs.qm">%QT_INSTALL_TRANSLATIONS%/qtbase_cs.qm</file> + </qresource> + </RCC> + \endcode + + The path for replacing \c QT_INSTALL_TRANSLATIONS can be retrieved from the + output of \c{qmake -query} of your Qt installation. */ /*! \previouspage ifw-globalconfig.html \page ifw-component-description.html - \nextpage noninteractive.html + \nextpage ifw-aliasconfig.html \title Package Directory @@ -855,19 +1007,25 @@ The component is installed if and only if all of the specified dependencies are fulfilled. If a component has an automatic dependency on other components, - the check box will not be visible next to the component in the component tree. - The selection will be performed automatically. + the check box will not be visible next to the component in the component tree, + but this does not change the visibility of the check box in the updater view + where the end user may still manually select the component for update. + + When running an installer or a \MT in package manager + mode, the selection will be performed automatically. If the component was not installed before, it will be selected for installation only when all components from this list are also selected for installation. If the component was already installed, it will - be selected for uninstallation when at least one of the components - from this list is also selected for uninstallation. + be selected for uninstallation or for update when at least one + of the components from this list is also selected for + uninstallation or for update. For more information, see \l{Component Dependencies}. \row \li Virtual - \li Set to \c true to hide the component from the installer. - Note that setting this on a root component does not work. + \li Set to \c true to hide the component from the installer. This also + hides any child components this component may have, including their + descendants. Note that setting this on a root component does not work. \row \li SortingPriority \li Priority of the component in the tree. The tree is sorted from @@ -891,7 +1049,15 @@ \row \li Script \li File name of a script being loaded. Optional. - For more information, see \l{Adding Operations}. + Specifying the \c {postLoad="true"} attribute will cause the script + to be loaded only to the component that is selected for update or + install. With the attribute, the script is loaded right before the + component installation starts. This will speed up the installer + if there are large amounts of components with install scripts in the + repository. Make sure the script does not contain anything that needs + to be evaluated before the install tree view is shown. + For more information, see \l{Adding Operations} and + \l{Using postLoad in component script}. \row \li UserInterfaces \li List of pages to load. To add several pages, add several @@ -929,7 +1095,8 @@ \row \li ForcedInstallation \li Determines that the package must always be installed. End users - cannot deselect it in the installer. + cannot deselect it in the installer. When updating components, the + component can still be deselected from an update. \row \li ForcedUpdate \li Marks the package as \c ForcedUpdate to force a restart of the @@ -955,7 +1122,9 @@ \row \li Checkable \li Set to \c false if you want to hide the checkbox for an item. This is useful - when only a few subcomponents should be selected instead of all. Optional. + when only a few subcomponents should be selected instead of all. When updating + components, the checkbox is still visible to allow toggling the component for + update. Optional. \row \li ExpandedByDefault \li Set to \c true if you want this item to be expanded by default. Optional. @@ -976,6 +1145,14 @@ location which is calculated from component name. Component names and tree names must be unique. Optional. + Specifying \c{moveChildren="true"} attribute will also change the location of any + child components this component has. Children will move to the overwritten tree name, + keeping the relative location to their parent component. + + One component branch in the install tree view can have multiple components + specifying a tree name. The order in which the location of components is changed + is from leaf to root components. + \endtable \section2 Component Dependencies @@ -1160,7 +1337,7 @@ \li Only available on macOS. Allows specifying a code signing identity to be used for signing the generated app bundle. \row - \li --af or --archive-format 7z|zip|tar.gz|tar.bz2|tar.xz + \li --af or --archive-format 7z|zip|tar|tar.gz|tar.bz2|tar.xz \li Set the format used when packaging new component data archives. If you omit this option, the 7z format will be used as a default. \note If the Installer Framework tools were built without libarchive @@ -1224,6 +1401,12 @@ specify the location in the installer configuration file when creating an installer for it. + Repositories contain compressed metadata that can be packaged as a separate 7z archive + for each component, or combined into a single 7z archive for the repository entirety. + By default, repogen packages the metadata in both formats for backward compatibility + with older installers not supporting the unified meta-format. This can be changed with + the \c --unite-metadata and \c --component-metadata options. + You can use an existing repository to repack packages to another repository or offline installer. @@ -1271,13 +1454,19 @@ \row \li -v or --verbose \li Display debug output. + \row + \li --unite-metadata + \li Combine all metadata into one 7z. This speeds up metadata download phase. + \row + \li --component-metadata + \li Creates one metadata 7z per component. \row \li -s or --sha-update p1,...,pn \li Comma-separated list of packages to be updated based on the component sha checksum instead of the version number. This parameter adds a new \c <ContentSha1> node to the \c Updates.xml. \row - \li --af or --archive-format 7z|zip|tar.gz|tar.bz2|tar.xz + \li --af or --archive-format 7z|zip|tar|tar.gz|tar.bz2|tar.xz \li Set the format used when packaging new component data archives. If you omit this option, the 7z format will be used as a default. \note If the Installer Framework tools were built without libarchive @@ -1338,6 +1527,7 @@ \list \li 7z (7z archive) \li zip (ZIP archive) + \li tar (uncompressed tar archive) \li tar.gz (gzip compressed tar archive) \li tar.bz2 (bzip2 compressed tar archive) \li tar.xz (xz compressed tar archive) @@ -1359,9 +1549,9 @@ \section1 devtool - You can use \c devtool to update an existing installer or maintenance tool + You can use \c devtool to update an existing installer or \MT with a new installer base, to dump binary content from an installer or - maintenance tool to a target, and to execute operations. For a summary of + \MT to a target, and to execute operations. For a summary of available operations, see \l {Operations}. \c devtool expects the following parameters in the following order: @@ -1390,12 +1580,12 @@ \li Display additional information. \row \li update <binary> <installerbase> - \li Update an existing installer or maintenance tool with a new + \li Update an existing installer or \MT with a new installer base. \row \li dump <binary> <folder> \li Dump the binary content that belongs to an installer or - maintenance tool into the target. + \MT into the target. \row \li operation <mode,name,args,...> \li Execute an operation with a list of arguments. @@ -1468,7 +1658,7 @@ \endcode The installer works only if it can access the repository. If the repository is - accessed after the installation, the maintenance tool rejects installation. + accessed after the installation, the \MT rejects installation. However, uninstallation is still possible. A repository can be enabled or disabled by default. For repositories requiring authentication, the details can also be set here, @@ -1690,7 +1880,7 @@ If \c{url} is itself relative, it will be resolved against the base URL of the current document. \c{displayname} specifies how the repository should be named in the \gui Settings page - of the Maintenance Tool. + of the \MT. \c{name} and \c{password} optionally specify credentials for a protected repository. @@ -1742,6 +1932,134 @@ You can use relative paths for the arguments \c url, \c oldUrl, and \c newUrl in the \c <Repository> element. + + \section1 Promoting Updates for the Maintenance Tool + + Without additional configuration, both online and offline installers install the + \e {\MT}, that can be later used to add, update, and remove components. + Online installers also have an option to install the \MT from an online repository. + This makes it possible to promote updates for the \MT to take the advantage of latest + new features and fixes to the Qt Installer Framework. + + You should download the latest release of the Installer Framework distribution that + includes new versions of \l{binarycreator} and \l{installerbase} tools. However, to only + update vendor specific configuration like \c <Name>, \c <Title>, and \c <Publisher> to the new + \MT, you can use the tools that were used to create the original installer. + + \section2 Creating the Component Directory Structure for Maintenance Tool + + To make the \MT update installable for end users, you need to prepare an installer + component for the \MT and create a repository for that component. + + \note If you already have a component for the \MT available in a repository, you + can skip the instructions in this section. + + A common convention is to create a \c packages directory containing the metadata and data for + your installer components. Inside that directory, you need to create a subdirectory for the maintenance + tool component with a name of your choice, for example \c org.qtproject.ifw.maintenancetool, + with \c meta and \c data subdirectories. These directories will be populated later. + + \section2 Compiling the Update Resource + + If you want to apply configuration changes, like updating the title, publisher, or product URL + when the end user updates the \MT, you need to create an update resource file. + Otherwise this step is optional. + + First, you need to compile the resource file that will contain the new \MT + configuration and related files: + + \code + binarycreator -c config/config.xml -p packages -rcc + \endcode + + The command outputs the result into \c update.rcc in the current path. + + The \c packages directory argument refers to the previously created directory for the maintenance + tool component. \c config.xml contains the \MT configuration. This can be the same + file that was used for creating the online installer that is going to consume the \MT + repository, or you could make modifications to change some configuration elements like the window + title and product version. + + For full reference of elements supported by the configuration file, see \l{Configuration File}. + + \section2 Getting the Maintenance Tool + + The \MT for Linux and Windows is the same as the \c installerbase + executable located in your Qt Installer Framework's installation \c bin folder. + For macOS the \MT app bundle can be created using the \c binarycreator + tool with the command line switch \c --mt or \c --create-maintenancetool. The + name of the macOS app bundle can be configured in config.xml using + the \c <MaintenanceToolName> element. The app bundle can be later signed and + notarized if needed. + + \code + binarycreator -c config/config.xml --mt + \endcode + + \section2 Populating the Maintenance Tool Component + + In Linux and in Windows the \c installerbase executable from Qt Installer + Framework's installation folder, or in macOS the \MT app bundle, + should be copied to the component's data directory. If you generated the + \c update.rcc in the \l{Compiling the Update Resource} step, copy that to + the data directory as well. The meta directory should contain a \c package.xml + file with the package information elements of your choice. However, it is a + good idea to mark the component \c <Essential> so that it gets automatically + installed when running the updater. You may also want to mark the component + \c <Virtual> to hide it from the component selection. + + For further information about the \c package.xml file, see + \l{Summary of Package Information File Elements}. + + \note If you are providing an update for an existing \MT component, copy and overwrite the + existing files with the updated content to the package directory and increase the value of the + \c <Version> element in the \c package.xml file. + + The meta directory should also contain an installation script that tells the installer that + there are replacements for the default \c installerbase and update resource files. A minimal + \c installscript.qs for this purpose could look like this: + + \code + function Component() + { + installer.installationStarted.connect(this, Component.prototype.onInstallationStarted); + } + + Component.prototype.onInstallationStarted = function() + { + if (component.updateRequested() || component.installationRequested()) { + if (installer.value("os") == "win") { + component.installerbaseBinaryPath = "@TargetDir@/installerbase.exe"; + } else if (installer.value("os") == "x11") { + component.installerbaseBinaryPath = "@TargetDir@/installerbase"; + } else if (installer.value("os") == "mac") { + // In macOs maintenance tool can be either installerbase from Qt Installer + // Framework's install folder, or app bundle created by binarycreator + // with --create-maintenancetool switch. "MaintenanceTool.app" -name + // may differ depending on what has been defined in config.xml while + // creating the maintenance tool. + // Use either of the following (not both): + + // component.installerbaseBinaryPath = "@TargetDir@/installerbase"; + component.installerbaseBinaryPath = "@TargetDir@/MaintenanceTool.app"; + } + installer.setInstallerBaseBinary(component.installerbaseBinaryPath); + + var updateResourceFilePath = installer.value("TargetDir") + "/update.rcc"; + installer.setValue("DefaultResourceReplacement", updateResourceFilePath); + } + } + \endcode + + You must include the installation script in the \c package.xml by specifying the filename in + the \c <Script> element. + + \section2 Publishing Maintenance Tool Updates + + After preparation the component should be uploaded to an existing or a new online repository + to make it available for end users. The instructions on how to create repositories on + this page and \l{Creating Repositories} apply also for the component containing the + \MT update. */ /*! diff --git a/doc/messageboxhandler.qdoc b/doc/messageboxhandler.qdoc index 30f0b2723..6d6e5a401 100644 --- a/doc/messageboxhandler.qdoc +++ b/doc/messageboxhandler.qdoc @@ -1,7 +1,7 @@ /**************************************************************************** ** -** Copyright (C) 2021 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2022 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Installer Framework. ** @@ -79,30 +79,34 @@ \qmlmethod Button QMessageBox::critical(string identifier, string title, string text, Buttons buttons = QMessageBox.Ok, Button button = QMessageBox.NoButton) - Opens a critical message box with the parent \a parent, identifier \a identifier, - title \a title, and text \a text. + Opens a critical message box with identifier \a identifier, title \a title, + text \a text, default buttons \a buttons and button \a button selected + by default. */ /*! \qmlmethod Button QMessageBox::information(string identifier, string title, string text, Buttons buttons = QMessageBox.Ok, Button button = QMessageBox.NoButton) - Opens an information message box with the parent \a parent, identifier \a identifier, - title \a title, and text \a text. + Opens an information message box with identifier \a identifier, title \a title, + text \a text, default buttons \a buttons and button \a button selected + by default. */ /*! \qmlmethod Button QMessageBox::question(string identifier, string title, string text, Buttons buttons = QMessageBox.Yes | QMessageBox.No, Button button = QMessageBox.NoButton) - Opens a question message box with the parent \a parent, identifier \a identifier, - title \a title, and text \a text. + Opens a question message box with identifier \a identifier, title \a title, + text \a text, default buttons \a buttons and button \a button selected + by default. */ /*! \qmlmethod Button QMessageBox::warning(string identifier, string title, string text, Buttons buttons = QMessageBox.Ok, Button button = QMessageBox.NoButton) - Opens a warning message box with the parent \a parent, identifier \a identifier, - title \a title, and text \a text. + Opens a warning message box with identifier \a identifier, title \a title, + text \a text, default buttons \a buttons and button \a button selected + by default. */ diff --git a/doc/noninteractive.qdoc b/doc/noninteractive.qdoc index 3e0952c12..d22a17800 100644 --- a/doc/noninteractive.qdoc +++ b/doc/noninteractive.qdoc @@ -1,7 +1,7 @@ /**************************************************************************** ** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2022 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Installer Framework. ** @@ -80,6 +80,21 @@ For more information about the JavaScript global objects that you can use in control scripts, see \l{Scripting API}. + In addition to the predefined global objects, the scripting API supports working + with other objects derived from \c QObject. In the above code example the + \c{gui.currentPageWidget()} method returns a widget of type \c QWidget. + + The scripting API makes use of Qt's object trees. Widgets derived from \c QObject export + their named child objects as properties for the JavaScript object, where the name of the + property is the same as the child object's \c{QObject::objectName}. The default properties + and their access functions of objects derived from \c QObject can also be used in the scripts. + + For example, in the above code the \c MessageLabel object from class \c QLabel is a child + of the \c widget. The \c setText() is the setter access function for its \c QLabel::text property. + + In addition to properties, the signals and public slots of objects derived from \c QObject + can be used in both controller and component scripts. + \section1 Predefined Installer Pages The QInstaller JavaScript object provides access to the following predefined @@ -126,7 +141,7 @@ \row \li \c MessageLabel \li Displays a message. By default, it displays the - "Welcome to the \l{ProductNameTarget}{<Name>} Setup Wizard" message. + "Welcome to the \l{ProductNameTarget}{<Name>} Setup" message. \row \li \c InformationLabel @@ -140,15 +155,15 @@ \row \li \c PackageManagerRadioButton - \li The package manager radio button shown on the page while running as maintenance tool. + \li The package manager radio button shown on the page while running as \MT. \row \li \c UpdaterRadioButton - \li The updater radio button shown on the page while running as maintenance tool. + \li The updater radio button shown on the page while running as \MT. \row \li \c UninstallerRadioButton - \li The uninstaller radio button shown on the page while running as maintenance tool. + \li The uninstaller radio button shown on the page while running as \MT. Selected by default. \endtable @@ -169,10 +184,10 @@ \row \li \c packageManagerCoreTypeChanged() - \li Connect to this signal if you want to be notified when the type of maintenance tool + \li Connect to this signal if you want to be notified when the type of \MT changes. \note The signal is only emitted when the user has started the binary as so called - maintenance tool (after the installation) and switches between the radio buttons. + \MT (after the installation) and switches between the radio buttons. \endtable Example code: @@ -552,7 +567,7 @@ \row \li \c WriteError \li OK - \li An error occurred while writing the maintenance tool. + \li An error occurred while writing the \MT. \row \li \c ElevationError diff --git a/doc/operations.qdoc b/doc/operations.qdoc index 7862cdaab..e148d6fc1 100644 --- a/doc/operations.qdoc +++ b/doc/operations.qdoc @@ -1,7 +1,7 @@ /**************************************************************************** ** -** Copyright (C) 2020 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2023 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Installer Framework. ** @@ -40,6 +40,10 @@ the installer and an \e UNDO step that contains instructions for the uninstaller. + Some operations especially in Windows might need native separators. Use + \c installer.toNativeSeparators() to convert separators to ones that are + appropriate for the underlying operating system. + \section1 Summary of Operations The following table summarizes the available operations and their syntax in component @@ -65,10 +69,16 @@ \li Copy \li "Copy" \c source \c target \li Copies a file from \c source to \c target. + \note The file will be restored during unistallation. If you want + to skip the copying, you can overwrite the \e UNDO by passing + \e UNDOOPERATION and \e "", to the end of the argument list. \row \li Move \li "Move" \c source \c target \li Moves a file from \c source to \c target. + \note Files restored during uninstallation. If you want to move the + files persistently, you can overwrite the \e UNDO by passing \e + UNDOOPERATION and \e "", to the end of the argument list. \row \li SimpleMoveFile \li "SimpleMoveFile" \c source \c target @@ -81,14 +91,25 @@ \li Delete \li "Delete" \c filename \li Deletes the file specified by \c filename. + \note File will be restored during uninstallation. If you want to + delete the files persistently, you can overwrite the \e UNDO by + passing \e UNDOOPERATION and \e "", to the end of the argument list. \row \li Mkdir \li "Mkdir" \c path \li Creates the directory path \c path. + \note Directory will be deleted during uninstallation. + If you want to create the directory persistently, you can overwrite the \e UNDO + by passing \e UNDOOPERATION and \e "", to the end of the argument list. Note that + during full uninstall, directory will be deleted if it was created to target directory + and \c RemoveTargetDir is false. \row \li Rmdir \li "Rmdir" \c path \li Removes the directory path \c path. + \note Directory will be recreated during uninstallation. + If you want to remove the directory persistently, you can overwrite the \e UNDO + by passing \e UNDOOPERATION and \e "", to the end of the argument list. \row \li CopyDirectory \li "CopyDirectory" \c sourcePath \c targetPath @@ -101,11 +122,17 @@ \li "AppendFile" \c filename \c text \li Appends \c text to the file specified by \c filename. \c text is treated as ASCII text. + \note Text will be removed from file during unistallation. If you want to append the + text persistently, you can overwrite the \e UNDO by passing \e UNDOOPERATION + and \e "", to the end of the argument list. \row \li PrependFile \li "PrependFile" \c filename \c text \li Prepends \c text to the file specified by \c filename. \c text is treated as ASCII text. + \note Text will be removed from file during unistallation. If you want to append the + text persistently, you can overwrite the \e UNDO by passing \e UNDOOPERATION + and \e "", to the end of the argument list. \row \li Replace \li "Replace" \c file \c search \c replace \c mode @@ -149,12 +176,13 @@ \c linkname. On Windows, this creates a .lnk file which can have \c arguments. Furthermore, \c filename can be - an HTTP or FTP URL in which case a URL shortcut is created. + an HTTP, HTTPS or FTP URL in which case a URL shortcut is created. \note If the \c @AllUsersStartMenuProgramsPath@ is used for placing the shortcut, then due to a problem on Windows, it will drop any arguments to the target and any description set. In this case, you should place the shortcut elsewhere and copy it to the location desired. + \note Creating a shortcut to a network share is not supported. The operation is currently not implemented on other platforms. \row \li CreateDesktopEntry @@ -286,6 +314,7 @@ \li Sets or removes the \c value of \c key in the settings file located at \c path, depending on the value of \c method: \c set, \c remove, \c add_array_value, and \c remove_array_value. + Example: \c{component.addOperation("Settings", "path=settings.ini", "method=add", "key=myKey", "value=myValue")} \endtable The Extract, License, and MinimumProgress operations are automatically added for matching @@ -300,4 +329,15 @@ devtool operation <binary> DO,Copy,<source>,<target> \endcode + \section1 Execution Groups + + The operations owned by a component belong to either of two groups: \e Unpack or \e Install. + The \c Extract operations are performed as part of the \e Unpack group before all other + operations and executed concurrently between all components that are going + to be installed. The rest of the operations are performed in the \e Install group and + executed sequentially for each component at a time. + + Custom operations can define their execution group by calling the \c setGroup() method + in their constructor. For more information about custom operations, see + \l{Registering Custom Operations}. */ diff --git a/doc/scripting-api/buttons.qdoc b/doc/scripting-api/buttons.qdoc index ea43b76f7..36f27b8d9 100644 --- a/doc/scripting-api/buttons.qdoc +++ b/doc/scripting-api/buttons.qdoc @@ -1,7 +1,7 @@ /**************************************************************************** ** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2022 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Installer Framework. ** diff --git a/doc/scripting-api/component.qdoc b/doc/scripting-api/component.qdoc index 00480cd63..51f36ac11 100644 --- a/doc/scripting-api/component.qdoc +++ b/doc/scripting-api/component.qdoc @@ -1,7 +1,7 @@ /**************************************************************************** ** -** Copyright (C) 2021 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2022 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Installer Framework. ** @@ -327,14 +327,16 @@ /*! \qmlmethod boolean component::addOperation(string operation, string parameter1 = "", string parameter2 = "", ..., string parameter10 = "") - Convenience method for calling addOperation(string, stringlist) with up to 10 arguments. + Convenience method for calling addOperation(string, stringlist) with up to + 10 arguments \a parameter1, \a parameter2, ... \a parameter10. Creates and adds an installation operation for \a operation. */ /*! \qmlmethod boolean component::addElevatedOperation(string operation, string parameter1 = "", string parameter2 = "", ..., string parameter10 = "") - Convenience method for calling addElevatedOperation(string, stringlist) with up to 10 arguments. + Convenience method for calling addElevatedOperation(string, stringlist) with up to + 10 arguments \a parameter1, \a parameter2, ... \a parameter10. Creates and adds an installation operation for \a operation. The operation is executed with elevated rights. */ @@ -420,6 +422,12 @@ */ /*! + \qmlmethod boolean component::isUpdateAvailable() + + Determines whether update is available for component. +*/ + +/*! \qmlmethod boolean component::componentChangeRequested() Returns \c true if this component will be changed (update, installation, or diff --git a/doc/scripting-api/console.qdoc b/doc/scripting-api/console.qdoc index 350257820..7785d9223 100644 --- a/doc/scripting-api/console.qdoc +++ b/doc/scripting-api/console.qdoc @@ -1,7 +1,7 @@ /**************************************************************************** ** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2022 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Installer Framework. ** @@ -37,7 +37,7 @@ \l{console::log()}{log} method and \l installer object \l{installer::isUpdater()}, \l{installer::isUninstaller()}, and \l{installer::isPackageManager()} methods to display a message that - indicates whether the maintenance tool is currently being used to update, + indicates whether the \MT is currently being used to update, remove, or add components. \code diff --git a/doc/scripting-api/gui.qdoc b/doc/scripting-api/gui.qdoc index b68d13dee..b9e6c1b5f 100644 --- a/doc/scripting-api/gui.qdoc +++ b/doc/scripting-api/gui.qdoc @@ -1,7 +1,7 @@ /**************************************************************************** ** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2024 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Installer Framework. ** @@ -58,6 +58,13 @@ */ /*! + \qmlsignal gui::aboutApplicationClicked() + + This signal is emitted when the about application menu and dialog + on macOS are shown. +*/ + +/*! \qmlsignal gui::settingsButtonClicked() This signal is emitted when the \uicontrol Settings button is clicked. @@ -119,9 +126,35 @@ */ /*! + \qmlmethod void gui::setWizardPageButtonText(int pageId, int buttonId, string buttonText) + + Sets \a buttonText for button specified by \a buttonId to a installer page \a pageId. + + \note In some pages, installer will change the button text when entering + the page. In that case, you need to connect to \c entered() -signal of the + page to change the \a buttonText. + + \code + function Component() + { + var page = gui.pageByObjectName("FinishedPage"); + page.entered.connect(Component.prototype.finishPageEntered); + } + Component.prototype.finishPageEntered = function() + { + gui.setWizardPageButtonText(QInstaller.InstallationFinished, buttons.CommitButton, "Commit"); + } + \endcode +*/ + +/*! \qmlmethod void gui::showSettingsButton(boolean show) - Shows the \uicontrol Settings button if \a show is \c true. + Shows the \uicontrol Settings button if \a show is \c true. This function + overrides the visibility of the \uicontrol Settings button in all pages. Be + careful when showing the settings button so that users cannot change network + settings while downloading data in the background. Changing the + settings will restart the wizard and switch back to the introduction page. */ /*! @@ -173,10 +206,6 @@ */ /*! - \qmlmethod void gui::setModified(boolean value) -*/ - -/*! \qmlmethod void gui::setTextItems(object control, stringlist items) Updates the model of \a control (which must be a QComboBox or QAbstractItemView) diff --git a/doc/scripting-api/packagemanagercore.qdoc b/doc/scripting-api/packagemanagercore.qdoc index ea32a59b7..ecf4b1eaa 100644 --- a/doc/scripting-api/packagemanagercore.qdoc +++ b/doc/scripting-api/packagemanagercore.qdoc @@ -1,7 +1,7 @@ /**************************************************************************** ** -** Copyright (C) 2021 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2023 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Installer Framework. ** @@ -71,24 +71,6 @@ \qmlsignal installer::componentAdded(Component component) Emitted when a new root \a component is added. - - \sa rootComponentsAdded(), updaterComponentsAdded() -*/ - -/*! - \qmlsignal installer::rootComponentsAdded(list<Component> components) - - Emitted when a new list of root \a components is added. - - \sa componentAdded(), updaterComponentsAdded() -*/ - -/*! - \qmlsignal installer::updaterComponentsAdded(list<Component> components) - - Emitted when a new list of updater \a components is added. - - \sa componentAdded(), rootComponentsAdded() */ /*! @@ -235,6 +217,12 @@ */ /*! + \qmlsignal installer::downloadArchivesFinished() + + Emitted when all data archives for components have been downloaded successfully. +*/ + +/*! \qmlsignal installer::wizardPageInsertionRequested(Widget widget, WizardPage page) Emitted when a custom \a widget is about to be inserted into \a page by addWizardPage. @@ -319,15 +307,25 @@ */ /*! + \qmlmethod boolean installer::recalculateAllComponents() + + Recalculates all components to install and uninstall. Returns \c true + on success, \c false otherwise. +*/ + +/*! \qmlmethod void installer::componentsToInstallNeedsRecalculation() + \deprecated [4.5] Use recalculateAllComponents() instead. Ensures that component dependencies are re-calculated. */ /*! \qmlmethod void installer::clearComponentsToInstallCalculated() - - Forces a recalculation of components to install. + \deprecated [4.5] Installer framework recalculates components each time the calculation + of components to install is requested, so there is no need to call this anymore, and the + method does nothing. On previous versions calling this forced a recalculation of + components to install. */ /*! @@ -445,7 +443,12 @@ On Unix platforms the returned string is the same as the argument. + \note Predefined variables, such as @TargetDir@, are not resolved by + this function. To convert the separators to predefined variables, use + \c installer.value() to resolve the variables first. + \sa fromNativeSeparators() + \sa value() */ /*! @@ -455,7 +458,12 @@ On Unix platforms the returned string is the same as the argument. + \note Predefined variables, such as @TargetDir@, are not resolved by + this function. To convert the separators to predefined variables, use + \c installer.value() to resolve the variables first. + \sa toNativeSeparators() + \sa value() */ /*! @@ -589,6 +597,18 @@ */ /*! + \qmlmethod bool installer::hasAdminRights() + + Returns \c true if the installer has admin rights. For example, if the installer + was started with a root account, or the internal admin rights elevation is active. + + Returns \c false otherwise. + + \sa gainAdminRights() + \sa dropAdminRights() +*/ + +/*! \qmlmethod boolean installer::isProcessRunning(string name) Returns \c true if a process with \a name is running. On Windows, the comparison @@ -607,15 +627,23 @@ /*! \qmlmethod void installer::setAllowedRunningProcesses(stringlist processes) + \deprecated [4.6] The \MT no longer automatically checks for all running processes + in the installation directory for CLI runs. To check for a process to stop, use + \l {component::addStopProcessForUpdateRequest}{component.addStopProcessForUpdateRequest} instead. + Sets additional \a processes that can run when - updating with the maintenance tool. + updating with the \MT. */ /*! \qmlmethod stringlist installer::allowedRunningProcesses() + \deprecated [4.6] The \MT no longer automatically checks for all running processes + in the installation directory for CLI runs. To check for a process to stop, use + \l {component::addStopProcessForUpdateRequest}{component.addStopProcessForUpdateRequest} instead. + Returns processes that are allowed to run when updating with - the maintenance tool. + the \MT. */ /*! @@ -730,7 +758,7 @@ /*! \qmlmethod void installer::setInstallerBaseBinary(string path) - Sets the \c installerbase binary to use when writing the maintenance tool. + Sets the \c installerbase binary to use when writing the \MT. Set the \a path if an update to the binary is available. If not set, the executable segment of the running installer or uninstaller @@ -738,10 +766,16 @@ */ /*! - \qmlmethod string installer::value(string key, string defaultValue = "") + \qmlmethod string installer::value(string key, string defaultValue = "", int format = 0) - Returns the installer value for \a key. If \a key is not known to the system, \a defaultValue is - returned. Additionally, on Windows, \a key can be a registry key. + Returns the installer value for \a key. If \a key is not known to the system, + \a defaultValue is returned. Additionally, on Windows, \a key can be a + registry key. Optionally, you can specify the \a format of the registry key. + By default the \a format is QSettings::NativeFormat. For accessing + the 32-bit system registry from a 64-bit application running on 64-bit + Windows, use QSettings::Registry32Format. For accessing the 64-bit system + registry from a 32-bit application running on 64-bit Windows, use + QSettings::Registry64Format. \sa setValue, containsValue, valueChanged */ diff --git a/doc/scripting-api/print.qdoc b/doc/scripting-api/print.qdoc index 8d609d310..55c7b8fbb 100644 --- a/doc/scripting-api/print.qdoc +++ b/doc/scripting-api/print.qdoc @@ -1,7 +1,7 @@ /**************************************************************************** ** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2022 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Installer Framework. ** diff --git a/doc/scripting-api/qdesktopservices.qdoc b/doc/scripting-api/qdesktopservices.qdoc index 126e0b843..a9c8a149f 100644 --- a/doc/scripting-api/qdesktopservices.qdoc +++ b/doc/scripting-api/qdesktopservices.qdoc @@ -1,7 +1,7 @@ /**************************************************************************** ** -** Copyright (C) 2021 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2022 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Installer Framework. ** @@ -56,14 +56,18 @@ \li DesktopServices.PicturesLocation \li DesktopServices.TempLocation \li DesktopServices.HomeLocation - \li DesktopServices.DataLocation + \li DesktopServices.AppLocalDataLocation \li DesktopServices.CacheLocation + \li DesktopServices.GenericCacheLocation \li DesktopServices.GenericDataLocation \li DesktopServices.RuntimeLocation \li DesktopServices.ConfigLocation \li DesktopServices.DownloadLocation - \li DesktopServices.GenericCacheLocation \li DesktopServices.GenericConfigLocation + \li DesktopServices.AppDataLocation + \li DesktopServices.AppConfigLocation + \li DesktopServices.PublicShareLocation + \li DesktopServices.TemplatesLocation \endlist The enum values correspond to the values of the diff --git a/doc/scripting-api/qfiledialog.qdoc b/doc/scripting-api/qfiledialog.qdoc index e6cdfdb24..6fd01de3d 100644 --- a/doc/scripting-api/qfiledialog.qdoc +++ b/doc/scripting-api/qfiledialog.qdoc @@ -1,7 +1,7 @@ /**************************************************************************** ** -** Copyright (C) 2020 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2022 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Installer Framework. ** @@ -42,17 +42,19 @@ */ /*! - \qmlmethod string QFileDialog::getExistingDirectory(string caption, string dir) + \qmlmethod string QFileDialog::getExistingDirectory(string caption, string dir, string identifier) Returns an existing directory selected by the user. The dialog's working directory is set to \a dir, and the caption is set to \a caption. Either of these may be an empty string, in which case the current directory and a default caption will be used, respectively. + The \a identifier is used in command line interface to allow to identify + specific file dialogs for automatic answer. */ /*! - \qmlmethod string QFileDialog::getOpenFileName(string caption, string dir, string filter) + \qmlmethod string QFileDialog::getOpenFileName(string caption, string dir, string filter, string identifier) Returns an existing file selected by the user. If the user selects \uicontrol Cancel, returns a null string. @@ -64,6 +66,9 @@ file name, the file will be selected. Only files that match the specified \a filter are shown. Either of these may be an empty string. + The \a identifier is used in command line interface to allow to identify + specific file dialogs for automatic answer. + To specify multiple filters, separate them with two semicolons (;;). For example: diff --git a/doc/scripting-api/qinstaller.qdoc b/doc/scripting-api/qinstaller.qdoc index 9fef274ce..440212172 100644 --- a/doc/scripting-api/qinstaller.qdoc +++ b/doc/scripting-api/qinstaller.qdoc @@ -1,7 +1,7 @@ /**************************************************************************** ** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2022 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Installer Framework. ** diff --git a/doc/scripting-api/qsettings.qdoc b/doc/scripting-api/qsettings.qdoc new file mode 100644 index 000000000..04a0fe674 --- /dev/null +++ b/doc/scripting-api/qsettings.qdoc @@ -0,0 +1,57 @@ +/**************************************************************************** +** +** Copyright (C) 2022 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$ +** +****************************************************************************/ + +/*! + \qmltype QSettings + \inqmlmodule scripting + + \brief Provides enums for accessing QSettings format in Windows. + + On Windows, a registry key can be asked using \l{installer::value}. + For accessing the 32-bit system registry from a 64-bit application running + on 64-bit Windows, use \l{QSettings::Registry32Format}{QSettings.Registry32Format}. + For accessing the 64-bit system registry from a 32-bit application running + on 64-bit Windows, use \l{QSettings::Registry64Format}{QSettings.Registry64Format}. + By default the \l{QSettings::NativeFormat}{QSettings.NativeFormat}is used. +*/ + +/*! + \qmlproperty enumeration QSettings::Format + + The \l{installer::value} method can take one of the following enums as an argument: + + \list + \li \l{QSettings::NativeFormat}{QSettings.NativeFormat} + \li \l{QSettings::Registry32Format}{QSettings.Registry32Format} + \li \l{QSettings::Registry64Format}{QSettings.Registry64Format} + \li \l{QSettings::IniFormat}{QSettings.IniFormat} + \li \l{QSettings::InvalidFormat}{QSettings.InvalidFormat} + \endlist + + The enum values correspond to the values of the + \l{QSettings::Format} enum with the same names. +*/ diff --git a/doc/scripting-qmlmodule.qdoc b/doc/scripting-qmlmodule.qdoc index a54db3b99..1bf0cebd7 100644 --- a/doc/scripting-qmlmodule.qdoc +++ b/doc/scripting-qmlmodule.qdoc @@ -1,7 +1,7 @@ /**************************************************************************** ** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2022 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Installer Framework. ** diff --git a/doc/scripting.qdoc b/doc/scripting.qdoc index 1310253a0..1dde6576a 100644 --- a/doc/scripting.qdoc +++ b/doc/scripting.qdoc @@ -1,7 +1,7 @@ /**************************************************************************** ** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2022 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Installer Framework. ** @@ -94,7 +94,7 @@ \li Reference to the \l QInstaller of the component \row \li component - \li Reference to the \l Component of the component + \li Reference to the \l{https://doc.qt.io/qtinstallerframework/qinstaller-component.html}{Component}. of the component \endtable \section1 Message Boxes @@ -147,6 +147,7 @@ CustomOperation() { setName( "CustomOperation" ); + setGroup( Install ); } void backup() @@ -374,4 +375,28 @@ \li ApplicationsDirX64 \li \c {C:\Program Files} \endtable + + \section1 Using postLoad in Component Script + By default, component scripts are evaluated before the install tree view + is shown. This can have performance cost if there is a huge amount of + components with component scripts. The \c postLoad attribute introduces a way + to evaluate the component script right before installation starts, only for + the components that are selected for installation or update: + \code + <Script postLoad="true">my_install_script.qs</Script> + \endcode + Whether \c postLoad can be set to \c true must be considered case by case, + depending on the contents of the script. For example, if the script contents + affect the install tree view, like setting \c <Default> to \c true, setting + new dependencies, or adding new wizard pages, \c postLoad must not be used or + it must be set to \c false. If the script contains only methods + that are run during the installation, \c postLoad can be set to \c true. For + example, all overridden \c operation functions are run during installation. + For more information, see \l {Adding Operations to Components}. If you are not + sure when to use \c postLoad, then don't use it. The performance cost is + huge only when there are thousands of scripts to be evaluated. + + Both \c <Script postLoad="true"> and \c <Script> tags can be used at the same time. + This means that one component can have one script that is evaluated when the installation + starts and another script that is evaluated before the install tree view is shown. */ diff --git a/doc/systeminfo.qdoc b/doc/systeminfo.qdoc index 72670f0df..3695dbc07 100644 --- a/doc/systeminfo.qdoc +++ b/doc/systeminfo.qdoc @@ -1,7 +1,7 @@ /**************************************************************************** ** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2023 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Installer Framework. ** @@ -52,6 +52,25 @@ */ /*! + \qmlproperty string systemInfo::buildCpuArchitecture + + The architecture of the CPU that the application was compiled for, in text format. + + Possible values include: + \list + \li "i386" + \li "x86_64" + \li "arm64" + \endlist + + Note that this may not match the actual CPU that the application is running on if + there's an emulation layer or if the CPU supports multiple architectures (like x86-64 + processors supporting i386 applications). To detect that, use \c installer.currentCpuArchitecture() + + \sa QSysInfo::buildCpuArchitecture() currentCpuArchitecture +*/ + +/*! \qmlproperty string systemInfo::kernelType The type of the operating system kernel the installer was compiled for. It is also the @@ -98,7 +117,7 @@ \list \li "windows" \li "opensuse" (for the Linux openSUSE distribution) - \li "osx" + \li "macos" \endlist \sa QSysInfo::productType() diff --git a/doc/tutorial.qdoc b/doc/tutorial.qdoc index f5e0ee8e1..152f392c4 100644 --- a/doc/tutorial.qdoc +++ b/doc/tutorial.qdoc @@ -1,7 +1,7 @@ /**************************************************************************** ** -** Copyright (C) 2017 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ +** Copyright (C) 2023 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ ** ** This file is part of the Qt Installer Framework. ** @@ -37,37 +37,37 @@ \image ifw-introduction-page.png "Introduction page" - This section describes the following tasks that you must accomplish to + This section describes the following tasks that you must carry out to create the installer: \list 1 - \li Create a \e {package directory} that will contain all the + \li Create a \e {package directory} that will have all the configuration files and installable packages. - \li Create a \e {configuration file} that contains information about how + \li Create a \e {configuration file} that has information about how to build the installer binaries and online repositories. - \li Create a \e {package information file} that contains information + \li Create a \e {package information file} that has information about the installable components. \li Create installer content and copy it to the package directory. \li Use the \c binarycreator tool to create the \e installer. - The installer pages are created by using the information you provide - in the configuration and package information file. + To create the installer pages, use the information set in the + configuration and package information file. \endlist - The example files are located in the \c{examples\tutorial} directory in the + You can find the example files in the \c{examples\tutorial} directory in the Qt Installer Framework repository. \section1 Creating a Package Directory Create a directory structure that reflects the design of the installer and - allows the installer to be extended in the future. The directory must - contain subdirectories called \c config and \c packages. + allows for future extension. The directory must contain subdirectories + called \c config and \c packages. \image ifw-tutorial-files.png @@ -80,37 +80,37 @@ \quotefile ../examples/tutorial/config/config.xml - The configuration file specifies the following information that is - displayed on the introduction page: + The configuration file includes the following information for the + introduction page: \list - \li The \c <Title> element specifies the installer name displayed on the - title bar (1). + \li The \c <Title> element sets the installer name and displays it on + the title bar (1). - \li The \c <Name> element specifies the application name that is added to - the page name and introduction text (2). + \li The \c <Name> element sets the application name and adds it to + the page number and introduction text (2). \endlist \image ifw-tutorial-introduction-page.png "Introduction page" - The other elements are used to customize the behavior of the installer: + The other elements customize the behavior of the installer: \list - \li The \c <Version> element specifies the application version number. + \li The \c <Version> element sets the application version number. - \li The \c <Publisher> element specifies the publisher of the software + \li The \c <Publisher> element sets the publisher of the software (as shown in the Windows Control Panel, for example). - \li The \c <StartMenuDir> element specifies the name of the default + \li The \c <StartMenuDir> element sets the name of the default program group for the product in the Windows \gui Start menu. - \li The \c <TargetDir> element specifies that the default target - directory displayed to users is \c InstallationDirectory in the home - directory of the current user (because the predefined variable - \c @HomeDir@ is used as a part of the value). For more information, + \li The \c <TargetDir> element sets and displays \c InstallationDirectory + in the home directory of the current user as the default target + directory displayed to users (because it uses the predefined + variable \c @HomeDir@ as part of the value). For more information, see \l{Predefined Variables}. \endlist @@ -120,30 +120,28 @@ \section1 Creating a Package Information File - In this easy scenario, the installer handles only one component that is - called \c{com.vendor.product}. To provide the installer with information + In this easy scenario, the installer handles only one component, + \c{com.vendor.product}. To give the installer information about the component, create a file called \c package.xml with the following contents and place it in the \c meta directory: \quotefile ../examples/tutorial/packages/com.vendor.product/meta/package.xml - The elements in the example file are described in more detail below. - + Below is a more detailed description of the elements in the example file. For more information about the package information file, see \l{Package Information File Syntax}. \section2 Specifying Component Information - The information from the following elements is displayed on the component - selection page: + The component selection page displays information from the following elements: \list - \li The \c <DisplayName> element specifies the name of the component in - the list of components (1). + \li The \c <DisplayName> element sets the name of the component in the + component list (1). - \li The \c <Description> element specifies the text that is displayed when - the component is selected (2). + \li The \c <Description> element sets and displays text based on the + selected component (2). \endlist @@ -151,29 +149,31 @@ \section2 Specifying Installer Version - The \c <Version> element enables you to promote updates to users when they - become available. + The \c <Version> element offers updates to users when they become + available. \section2 Adding Licenses - The \c <License> element specifies the name of the file that contains the text - for the license agreement (1) that is displayed on the license check page: + The \c <License> element sets the name of the file, which has the + license agreement text (1). The license check page displays this license + text. \image ifw-tutorial-license-check.png "License check page" \section2 Selecting Default Contents - The \c <Default> element specifies whether the component is selected by - default. The value \c true sets the component as selected. In this example, - we use the value \c script to resolve the value during runtime. The - name of the JavaScript script file, installscript.qs, is specified in the - \c <Script> element. + The \c <Default> element specifies whether the selected component + is a default value. The value \c true sets the component as selected. This + example uses the value \c script to resolve the value during runtime. The + \c <Script> element sets the name of the JavaScript script file, + installscript.qs. \section1 Creating Installer Content - Content to be installed is stored in the \c data directory of a component. + The \c data directory of a component can store content available for + installation. As there is only one component, place the data in the - \c{packages/com.vendor.product/data} directory. The example already contains + \c{packages/com.vendor.product/data} directory. The example already has a file for testing purposes, but you can place basically any files in the directory. @@ -184,7 +184,7 @@ You are now ready to create your first installer. Switch to the \c examples\tutorial directory on the command line. To create an installer called - YourInstaller.exe that contains the packages identified by + YourInstaller.exe that has the packages identified by com.vendor.product, enter the following command: \list @@ -201,15 +201,13 @@ \endlist - The installer is created in the current directory and you can deliver it to - end users. + \IFW creates the installer in the current directory and you can deliver it + to end users. For more information about using the \c binarycreator tool, see \l{binarycreator}. - \note If an error message is displayed when you run the tutorial installer, + \note If an error message appears when you run the tutorial installer, check that you used a statically built Qt to create the installer. For more information, see \l{Configuring Qt}. */ - - |
