mirror of
https://github.com/QuasarApp/installer-framework.git
synced 2025-04-28 06:24:32 +00:00
c7066c9dc2
Replace deprecated Q_OS_OSX macro used in several places with the newer Q_OS_MACOS. Old style reference of Apple's desktop operating system name as "OS X" in documentation and files are also replaced with "macOS" where applicable. Task-number: QTIFW-1406 Change-Id: I0561d5e0d964917ac4fca0702d58a06b85d30e57 Reviewed-by: Katja Marttila <katja.marttila@qt.io>
1408 lines
57 KiB
Plaintext
1408 lines
57 KiB
Plaintext
/****************************************************************************
|
|
**
|
|
** Copyright (C) 2017 The Qt Company Ltd.
|
|
** Contact: http://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 http://www.qt.io/terms-conditions. For further
|
|
** information use the contact form at http://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: http://www.gnu.org/copyleft/fdl.html.
|
|
** $QT_END_LICENSE$
|
|
**
|
|
****************************************************************************/
|
|
|
|
// **********************************************************************
|
|
// NOTE: the sections are not ordered by their logical order to avoid
|
|
// reshuffling the file each time the index order changes (i.e., often).
|
|
// Run the fixnavi.pl script to adjust the links to the index order.
|
|
// **********************************************************************
|
|
|
|
/*!
|
|
\contentspage{index.html}{Qt Installer Framework}
|
|
\page index.html
|
|
\nextpage ifw-overview.html
|
|
|
|
\title Qt Installer Framework Manual
|
|
|
|
\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.
|
|
|
|
\note Report bugs and suggestions for the Qt Installer Framework project
|
|
in the \l{https://bugreports.qt.io/browse/QTIFW}{Qt Bugtracker}.
|
|
|
|
\list
|
|
\li \l{Overview of Qt Installer Framework}
|
|
\li \l{Getting Started}
|
|
\li \l{End User Workflows}
|
|
\list
|
|
\li \l{Initial Installation}
|
|
\li \l{Adding Components}
|
|
\li \l{Removing Components}
|
|
\li \l{Updating Components}
|
|
\li \l{Specifying Settings}
|
|
\endlist
|
|
\li \l{Tutorial: Creating an Installer}
|
|
\li \l{Creating Installers}
|
|
\list
|
|
\li \l{Creating Offline Installers}
|
|
\li \l{Creating Online Installers}
|
|
\li \l{Promoting Updates}
|
|
\li \l{Customizing Installers}
|
|
\endlist
|
|
\li \l{Qt Installer Framework Examples}
|
|
\li \l{Reference}
|
|
\list
|
|
\li \l{Configuration File}
|
|
\li \l{Package Directory}
|
|
\li \l{Controller Scripting}
|
|
\li \l{Component Scripting}
|
|
\li \l{Operations}
|
|
\li \l{Tools}
|
|
\li \l{Scripting API}
|
|
\li \l{C++ API}
|
|
\endlist
|
|
\li \l{Known Issues}
|
|
\endlist
|
|
*/
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage ifw-tutorial.html
|
|
\page ifw-creating-installers.html
|
|
\nextpage ifw-offline-installers.html
|
|
|
|
\title Creating Installers
|
|
|
|
The following steps are needed to create offline and online installers:
|
|
|
|
\list 1
|
|
|
|
\li Create a \e {package directory} for the installable components.
|
|
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
|
|
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 {config\meta} directory. It contains settings for deployment and
|
|
the installation process. For more information, see
|
|
\l{Meta Directory}.
|
|
|
|
\li Create installer content and copy it to the package directory.
|
|
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 to a web server.
|
|
|
|
\li Use the \c binarycreator tool to create the installer. For more
|
|
information, see \l{Tools}.
|
|
|
|
\endlist
|
|
|
|
For an example of how to create a simple installer that uses the predefined
|
|
installer pages, see \l{Tutorial: Creating an Installer}.
|
|
|
|
The following sections describe how to create different types of installers:
|
|
|
|
\list
|
|
\li \l{Creating Offline Installers}
|
|
\li \l{Creating Online Installers}
|
|
\li \l{Promoting Updates}
|
|
\li \l{Customizing Installers}
|
|
\endlist
|
|
*/
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage ifw-reference.html
|
|
\page ifw-globalconfig.html
|
|
\nextpage ifw-component-description.html
|
|
|
|
\title Configuration File
|
|
|
|
The configuration file customizes the UI and behavior of an installer.
|
|
The file is typically called \c config.xml and located in the
|
|
\c config directory.
|
|
|
|
A minimal configuration file consists of an \c <Installer> root element
|
|
with \c <Name> and \c <Version> elements as children. All other elements
|
|
are optional, and can appear in arbitrary order.
|
|
|
|
The following example shows a typical configuration file:
|
|
|
|
\quotefile examples/config.xml
|
|
|
|
\section1 Summary of Configuration File Elements
|
|
|
|
The following table summarizes the elements in the configuration file.
|
|
|
|
\note We recommend that you place all files that you refer to in the
|
|
configuration file in the \c config directory. However, you can also use
|
|
relative paths, which the tools resolve relative to the location of
|
|
the config.xml file.
|
|
|
|
You can use predefined variables (embedded in @ characters) as values of the
|
|
elements. For more information, see \l{Predefined Variables}.
|
|
|
|
\table
|
|
\header
|
|
\li Element
|
|
\li Description
|
|
\row
|
|
\li Name
|
|
\target ProductNameTarget
|
|
\li Name of the product being installed. This is mandatory.
|
|
\row
|
|
\li Version
|
|
\li Version of the product being installed in the following format:
|
|
[0-9]+((\\.|-)[0-9]+)* such as 1-1; 1.2-2; 3.4.7. This is
|
|
mandatory.
|
|
\row
|
|
\li Title
|
|
\li Name of the installer as displayed on the title bar.
|
|
\row
|
|
\li Publisher
|
|
\li Publisher of the software (as shown in the Windows Control Panel).
|
|
\row
|
|
\li ProductUrl
|
|
\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.
|
|
\row
|
|
\li InstallerWindowIcon
|
|
\li Filename for a custom window icon in PNG format for the Installer application.
|
|
\row
|
|
\li Logo
|
|
\li Filename for a logo used as \c QWizard::LogoPixmap.
|
|
\row
|
|
\li Watermark
|
|
\li Filename for a watermark used as \c QWizard::WatermarkPixmap.
|
|
\row
|
|
\li Banner
|
|
\li Filename for a banner 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).
|
|
\row
|
|
\li WizardStyle
|
|
\li Set the wizard style to be used ("Modern", "Mac", "Aero" or "Classic").
|
|
\row
|
|
\li StyleSheet
|
|
\li Set the stylesheet file.
|
|
\row
|
|
\li WizardDefaultWidth
|
|
\li Sets the default width of the wizard in pixels. Setting a banner image will
|
|
override this. You can add the \c em or \c ex suffix to the specified value to
|
|
use the \e em or \e ex unit, as in a CSS file.
|
|
\row
|
|
\li WizardDefaultHeight
|
|
\li Sets the default height of the wizard in pixels. Setting a watermark image will
|
|
override this. You can add the \c em or \c ex suffix to the specified value to
|
|
use the \e em or \e ex unit, as in a CSS file.
|
|
\row
|
|
\li TitleColor
|
|
\li Set the color of the titles and subtitles (takes an HTML color code,
|
|
such as "#88FF33").
|
|
\row
|
|
\li RunProgram
|
|
\li Command executed after the installer is done if the user accepts
|
|
the action. Provide the full path to the application.
|
|
\row
|
|
\li RunProgramArguments
|
|
\li Arguments passed to the program specified in \c <RunProgram>.
|
|
You can add several \c <Argument> child elements that each specify an
|
|
argument to \c <RunProgram>.
|
|
\row
|
|
\li RunProgramDescription
|
|
\li Text shown next to the check box for running the program after
|
|
the installation. If \c <RunProgram> is set but no description provided,
|
|
the UI will display \uicontrol {Run <Name> now.} instead.
|
|
\row
|
|
\li StartMenuDir
|
|
\li Name of the default program group for the product in the Windows
|
|
\uicontrol Start menu.
|
|
\row
|
|
\li TargetDir
|
|
\li Default target directory for installation. On Linux, this is
|
|
usually the user's home directory.
|
|
\row
|
|
\li AdminTargetDir
|
|
\li Default target directory for installation with administrator
|
|
rights. Only available on Linux, where you usually do not want
|
|
to install in the administrator user's home directory.
|
|
\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
|
|
access the repository. For more information, see \l{Configuring Repositories}.
|
|
\row
|
|
\li RepositoryCategories
|
|
\li Name of a category that can contain a list of \c <RemoteRepositories> child elements.
|
|
For more information, see \l{Configuring Repository Categories}.
|
|
\row
|
|
\li MaintenanceToolName
|
|
\li Filename of the generated maintenance tool. 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
|
|
\e {MaintenanceToolName}.ini.
|
|
\row
|
|
\li RemoveTargetDir
|
|
\li Set to \c false if the target directory should not be deleted when uninstalling.
|
|
\row
|
|
\li AllowNonAsciiCharacters
|
|
\li Set to \c true if the installation path can contain non-ASCII
|
|
characters.
|
|
\row
|
|
\li DisableAuthorizationFallback
|
|
\li Set to \c true if the installation should not ask users to run the authorization
|
|
fallback in case of authorization errors. Instead abort the installation immediately.
|
|
\row
|
|
\li RepositorySettingsPageVisible
|
|
\li Set to \c false to hide the repository settings page inside the settings dialog.
|
|
\row
|
|
\li AllowSpaceInPath
|
|
\li Set to \c false if the installation path cannot contain space characters.
|
|
\row
|
|
\li DependsOnLocalInstallerBinary
|
|
\li Set to \c true if you want to prohibit installation from an external resource, such
|
|
as a network drive. This might make sense for e.g. very big installers.
|
|
The option is only used on Windows.
|
|
\row
|
|
\li TargetConfigurationFile
|
|
\li Filename for the configuration file on the target. Default is components.xml.
|
|
\row
|
|
\li Translations
|
|
\li List of language codes to be used for translating the user interface. To add several language
|
|
variants, specify several \c <Translation> child elements that each specify the name
|
|
of a language variant. Optional. For more information, see \l{Translating Pages}.
|
|
\row
|
|
\li UrlQueryString
|
|
\li This string needs to be in the form "key=value" and will be appended to archive download
|
|
requests. This can be used to transmit information to the webserver hosting the repository.
|
|
\row
|
|
\li ControlScript
|
|
\li Filename for a custom installer control script. See \l{Controller Scripting}.
|
|
\row
|
|
\li CreateLocalRepository
|
|
\li Set to \c true if you want to create a local repository inside the installation directory.
|
|
This option has no effect on online installers. The repository will be automatically added
|
|
to the list of default repositories.
|
|
\row
|
|
\li InstallActionColumnVisible
|
|
\li Set to \c true if you want to add an extra column into component tree showing install actions.
|
|
This extra column indicates whether a component is going to be installed or uninstalled,
|
|
or just stay installed or uninstalled.
|
|
\row
|
|
\li SupportsModify
|
|
\li Set to \c false if the product does not support modifying an existing installation.
|
|
\row
|
|
\li SaveDefaultRepositories
|
|
\li Set to \c false if default repositories \c <RemoteRepositories> should not be saved to \e {MaintenanceToolName}.ini.
|
|
By default default repositories are saved. Not saving the repositories means than when you run \e maintenancetool
|
|
there are no default repositories in use.
|
|
\row
|
|
\li AllowUnstableComponents
|
|
\li Set to \c true if other components are allowed to be installed
|
|
although there are unstable components. A component is \e unstable
|
|
if it is missing a dependency, has errors in scripts, and so on.
|
|
Unstable components are grayed in the component tree, and therefore
|
|
cannot be selected. By default, the value is \c false which means
|
|
that the installation will be aborted if unstable components are found.
|
|
|
|
\endtable
|
|
|
|
*/
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage ifw-updates.html
|
|
\page ifw-customizing-installers.html
|
|
\nextpage Qt Installer Framework Examples
|
|
|
|
\title Customizing Installers
|
|
|
|
You can use scripting to customize installers by:
|
|
|
|
\list
|
|
|
|
\li Adding Qt Installer Framework \e operations that are prepared by the
|
|
scripts and performed by the installer.
|
|
|
|
\li Adding new pages that you specify in the package.xml file and place
|
|
in the \c packages directory.
|
|
|
|
\li Modifying existing pages by inserting custom user interface
|
|
elements into them as single widgets.
|
|
|
|
\li Adding language variants.
|
|
|
|
\endlist
|
|
|
|
You can use both \e {component scripts} and a \e {control script} to
|
|
customize installers. A component script is associated with a particular
|
|
component by specifying it in the \c Script element of the package.xml
|
|
file of the component. The script is loaded when the component's metadata is
|
|
fetched. For more information about component scripts, see
|
|
\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.
|
|
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
|
|
modify pages in the uninstaller. For more information, see
|
|
\l{Controller Scripting}.
|
|
|
|
For more information about the global JavaScript objects that can be used in
|
|
component and control scripts, see \l{Scripting API}.
|
|
|
|
\section1 Adding Operations
|
|
|
|
You can use component scripts to perform Qt Installer Framework operations
|
|
during the installation process. Typically, operations manipulate files by
|
|
moving, copying, or patching them. Use the
|
|
QInstaller::Component::addOperation or
|
|
QInstaller::Component::addElevatedOperation function to add operations. For
|
|
more information, see \l {Adding Operations to Components}.
|
|
|
|
In addition, you can implement methods to register custom installation
|
|
operations in the installer by deriving KDUpdater::UpdateOperation. For
|
|
more information, see \l {Registering Custom Operations}.
|
|
|
|
For a summary of available operations, see \l {Operations}.
|
|
|
|
\section1 Adding Pages
|
|
|
|
A component can contain one or more user interface files, which are placed
|
|
into the installer by a component or control script. The installer
|
|
automatically loads all user interface files listed in the
|
|
\c UserInterfaces element of the package.xml file.
|
|
|
|
\section2 Using Component Scripts to Add Pages
|
|
|
|
To add a new page to the installer, use
|
|
the installer::addWizardPage() method and specify the location
|
|
of the new page. For example, the following code adds an instance of
|
|
\c MyPage before the ready for installation page:
|
|
|
|
\code
|
|
installer.addWizardPage( component, "MyPage", QInstaller.ReadyForInstallation );
|
|
\endcode
|
|
|
|
You can use component scripts to access the loaded widgets
|
|
by calling the \l component::userInterface() method with the class name of
|
|
the widget, as illustrated by the following code snippet:
|
|
|
|
\code
|
|
component.userInterface( "MyPage" ).checkbox.checked = true;
|
|
\endcode
|
|
|
|
You can also have a callback for the page that is added. To access it,
|
|
use the object name set in the UI file (for example, \c "MyPage"). Then
|
|
create the \c{Dynamic${ObjectName}Callback} function (for example,
|
|
\c {DynamicMyPageCallback}):
|
|
|
|
\code
|
|
Component.prototype.DynamicMyPageCallback = function()
|
|
{
|
|
var page = gui.pageWidgetByObjectName("DynamicMyPage");
|
|
page.myButton.click,
|
|
page.myWidget.subWidget.setText("hello")
|
|
}
|
|
\endcode
|
|
|
|
You can access widgets by using their object names that are set in the UI
|
|
file. For example, \c myButton and \c myWidget are widget object names in
|
|
the code above.
|
|
|
|
\section1 Adding Widgets
|
|
|
|
You can use component or control scripts to insert custom user interface
|
|
elements into the installer as single widgets (such as a check box).
|
|
|
|
To insert a single widget, use the installer::addWizardPageItem method.
|
|
For example, the following code snippet adds an instance of \c MyWidget to
|
|
the component selection page from within a script:
|
|
|
|
\code
|
|
installer.addWizardPageItem( component, "MyWidget", QInstaller.ComponentSelection );
|
|
\endcode
|
|
|
|
\section1 Interacting with Installer Functionality
|
|
|
|
You can use control scripts to execute installer functions automatically in
|
|
tests, for example. The following snippet illustrates how to automatically
|
|
click the \uicontrol Next button on the target directory selection page:
|
|
|
|
\code
|
|
Controller.prototype.TargetDirectoryPageCallback = function()
|
|
{
|
|
gui.clickButton(buttons.NextButton);
|
|
}
|
|
\endcode
|
|
|
|
\section1 Translating Pages
|
|
|
|
The installer uses the Qt Translation system to support the translation of
|
|
user-readable output to several languages. To provide end users with
|
|
localized versions of strings contained in the component scripts and user
|
|
interfaces, create QTranslator files that the installation system loads
|
|
along with the component. The installer loads the translation file that
|
|
matches the current system locale. For example, if the system locale is
|
|
German, the de.qm file is loaded. In addition, a localized \c license_de.txt
|
|
is shown instead of the default \c license.txt if it is found.
|
|
|
|
Translations need to be added to the \c package.xml file to be activated for
|
|
a component:
|
|
|
|
\code
|
|
<Translations>
|
|
<Translation>de.qm</Translation>
|
|
</Translations>
|
|
\endcode
|
|
|
|
Use the \c {qsTr()} function for literal text within scripts. Additionally,
|
|
you can add the \c Component.prototype.retranslateUi method to the script.
|
|
It is called when the language of the installer changes and the translation
|
|
file is loaded.
|
|
|
|
The context being used for translation is the basename of the script file
|
|
when using \c qsTr or the class name of the UI file when translating a user
|
|
interface. For example, if the script file is called \c installscript.qs, the
|
|
context will be installscript.
|
|
|
|
\note The translation system can also be used to customize the UI. Use e.g.
|
|
an \c en.ts file to replace any text in the installer with a custom English
|
|
version.
|
|
*/
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage ifw-globalconfig.html
|
|
\page ifw-component-description.html
|
|
\nextpage noninteractive.html
|
|
|
|
\title Package Directory
|
|
|
|
Installers contain components that are either embedded to the installer
|
|
or loaded from a remote repository. In both cases, you need to use a file
|
|
format and structure for the components that the installer can read.
|
|
|
|
\section1 Package Directory Structure
|
|
|
|
Place all components in the same root directory, which is called the
|
|
\e {package directory}. The directory name acts as a domain-like identifier,
|
|
which identifies all components. For example, \c com.vendor.root.
|
|
|
|
Within the root directory, create subdirectories called \c data and \c meta.
|
|
|
|
A package directory can look as follows:
|
|
\code
|
|
-packages
|
|
- com.vendor.root
|
|
- data
|
|
- meta
|
|
- com.vendor.root.component1
|
|
- data
|
|
- meta
|
|
- com.vendor.root.component1.subcomponent1
|
|
- data
|
|
- meta
|
|
- com.vendor.root.component2
|
|
- data
|
|
- meta
|
|
\endcode
|
|
|
|
\section1 Meta Directory
|
|
|
|
The \c meta directory contains files that specify settings for deployment
|
|
and the installation process. The files are not extracted by the installer.
|
|
The directory must contain at least a package information file and all files
|
|
that you refer to in the package information file, such as scripts,
|
|
user interface files, and translations.
|
|
|
|
\section2 Package Information File Syntax
|
|
|
|
The package.xml file is the main source of information about a component.
|
|
The following is an example of a package file:
|
|
|
|
\quotefile examples/package.xml
|
|
|
|
\section2 Summary of Package Information File Elements
|
|
|
|
\table
|
|
\header
|
|
\li Element
|
|
\li Description
|
|
\row
|
|
\li DisplayName
|
|
\li Human-readable name of the component. Required.
|
|
Specify translations for the name of the component as values of additional
|
|
DisplayName tags, with the xml:lang attribute set to the correct locale.
|
|
\row
|
|
\li Description
|
|
\li Human-readable description of the component. Required.
|
|
Translations may be specified similarly to DisplayName tag.
|
|
If a localization that matches the locale is not found and an untranslated
|
|
version exists, that one will be used. Otherwise no Description will be
|
|
shown for that locale. User clickable external links, for example a component's
|
|
homepage, can be included in component description by specifying a URL
|
|
address like this: {external-link}='https://www.qt.io/'. The URL must be valid
|
|
and contain a full path to the desired resource.
|
|
\row
|
|
\li Version
|
|
\li Version number of the component in the following format:
|
|
[0-9]+((\\.|-)[0-9]+)* such as 1-1; 1.2-2; 3.4.7. Required.
|
|
If a package needs to show the version number from a child rather than it's own (due to
|
|
grouping of child packages) one can specify the attribute inheritVersionFrom with the package
|
|
name the version needs to be inherited from.
|
|
\row
|
|
\li ReleaseDate
|
|
\li Date when this component version was released. Required.
|
|
\row
|
|
\li Name
|
|
\li Domain-like identification for this component. Required.
|
|
\row
|
|
\li Dependencies
|
|
\li Comma-separated list of identifiers of components that this
|
|
component depends on. Optionally, you can specify version
|
|
numbers, separated by a dash (-). You can prefix version numbers
|
|
with a comparison operator (=, >, <, >= or <=). Keep in mind
|
|
that you have to use the character reference "<" to escape
|
|
the left angle bracket (use "<" instead of "<" and "<="
|
|
instead of "<="). Optional. For more information, see
|
|
\l{Component Dependencies}.
|
|
\row
|
|
\li AutoDependOn
|
|
\li Comma-separated list of identifiers of components that
|
|
this component has an automatic dependency on.
|
|
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.
|
|
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.
|
|
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.
|
|
\row
|
|
\li SortingPriority
|
|
\li Priority of the component in the tree. The tree is sorted from
|
|
highest to lowest priority, with the highest priority on the top.
|
|
\row
|
|
\li Licenses
|
|
\li List of license agreements to be accepted by the installing
|
|
user. To add several licenses, add several \c <License> child
|
|
elements that each specify the license \c name and \c file.
|
|
ASCII and UTF8 file formats are supported for license files.
|
|
|
|
If there are translations listed for this component, the installer
|
|
will also look for translated licenses. These need to have the
|
|
same name as the original license file but with an added
|
|
locale identifier.
|
|
If for example the license file is called license.txt and there is
|
|
German translation specified, the installer will also include
|
|
a license_de_de.txt file (and show that when installing on a
|
|
German system).
|
|
\row
|
|
\li Script
|
|
\li File name of a script being loaded. Optional.
|
|
For more information, see \l{Adding Operations}.
|
|
\row
|
|
\li UserInterfaces
|
|
\li List of pages to load. To add several pages, add several
|
|
\c <UserInterface> child elements that each specify the filename of a
|
|
page. Optional. For more information, see \l{Adding Pages}.
|
|
\row
|
|
\li Translations
|
|
\li List of translation files to load. To add several language
|
|
variants, specify several \c <Translation> child elements that each
|
|
specify the filename of a language variant. Optional. For more
|
|
information, see \l{Translating Pages}.
|
|
\row
|
|
\li UpdateText
|
|
\li Description added to the component description if this is an
|
|
update to the component. Optional.
|
|
\row
|
|
\li Default
|
|
\li Possible values are: \c true, \c false, and \c script. Set to
|
|
\c true to preselect the component in the installer.
|
|
This takes effect only on components that have no visible
|
|
child components.
|
|
The boolean values are evaluated directly, while \c script is
|
|
resolved during runtime. Add the name of the script as a value
|
|
of the \c <Script> element in this file. For an example script,
|
|
see \l{Selecting Default Contents}.
|
|
\row
|
|
\li Essential
|
|
\li Marks the package as essential to force a restart of the
|
|
\c MaintenanceTool. If there are updates available
|
|
for an essential component, the package manager stays disabled
|
|
until that component is updated. Newly introduced essential components
|
|
are automatically installed when running the updater.
|
|
\row
|
|
\li ForcedInstallation
|
|
\li Determines that the package must always be installed. End users
|
|
cannot deselect it in the installer.
|
|
\row
|
|
\li Replaces
|
|
\li Comma-separated list of components to replace. Optional.
|
|
|
|
\row
|
|
\li DownloadableArchives
|
|
\li Lists the data files (separated by commas) for an online
|
|
installer to download.
|
|
If there is some data inside the component and the package.xml
|
|
and/or the script has no DownloadableArchives value, the
|
|
repogen tool registers the found data automatically.
|
|
|
|
\row
|
|
\li RequiresAdminRights
|
|
\li Set to \c true if the package needs to be installed with elevated permissions.
|
|
Optional.
|
|
\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.
|
|
\row
|
|
\li ExpandedByDefault
|
|
\li Set to \c true if you want this item to be expanded by default. Optional.
|
|
|
|
\endtable
|
|
|
|
\section2 Component Dependencies
|
|
|
|
Components can depend on one or several real or virtual components.
|
|
Dependencies are defined by using the component identifier and, optionally,
|
|
component version. Use a dash (-) to separate version numbers from
|
|
identifiers.
|
|
|
|
You can prefix version numbers with a comparison operator (=, >, < (<), >= or
|
|
<= (<=)) to indicate that the version number of the package is compared to the
|
|
required version and has to be equal to, greater than, less than, greater
|
|
than or equal to, or less than or equal to the version number specified in
|
|
the dependency. If no comparison operator is given, it defaults to =.
|
|
|
|
\section1 Data Directory
|
|
|
|
The \c data directory contains the content that the installer extracts
|
|
during the installation. You must package the data as a 7zip archive (.7z).
|
|
You can use either the \l archivegen tool that is delivered with the Qt
|
|
Installer Framework or some other tool that generates 7zip archives.
|
|
*/
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage operations.html
|
|
\page ifw-tools.html
|
|
\nextpage Scripting API
|
|
|
|
\title Tools
|
|
|
|
The Qt Installer Framework contains the following tools:
|
|
|
|
\list
|
|
|
|
\li \l installerbase
|
|
|
|
\li \l binarycreator
|
|
|
|
\li \l repogen
|
|
|
|
\li \l archivegen
|
|
|
|
\li \l devtool
|
|
|
|
\endlist
|
|
|
|
\section1 installerbase
|
|
The \c installerbase tool describes the core installer itself. All data and
|
|
meta information will be packed to this binary. For the installer creation
|
|
process you will not need to call it directly.
|
|
|
|
\section1 binarycreator
|
|
Use the \c binarycreator tool to create offline and online installers.
|
|
Component information and data are appended to the offline installer binary,
|
|
which enables the file extraction and post installation scripts to work
|
|
without an Internet connection.
|
|
|
|
Online installers store the location of the repository that contains the
|
|
data. On startup, they load the component information, not the data.
|
|
|
|
You can also create hybrid installers that store some components locally
|
|
and receive others via a network connection. For more information, see
|
|
\l {Reducing Installer Size}.
|
|
|
|
For information about how to implement data integration into the
|
|
installer binary, see QInstaller::BinaryContent.
|
|
|
|
\note If you change this configuration, you must recompile the
|
|
\c installerbase tool.
|
|
|
|
\section2 Using binarycreator
|
|
|
|
You can use the \c binarycreator tool to create offline and online
|
|
installers. Some options have default values, and therefore, you can omit
|
|
them.
|
|
|
|
To create an offline installer (in Windows), enter the following command:
|
|
|
|
\list
|
|
|
|
\li On Windows:
|
|
\code
|
|
<location-of-ifw>\binarycreator.exe -t <location-of-ifw>\installerbase.exe -p <package_directory> -c <config_directory>\<config_file> <installer_name>
|
|
\endcode
|
|
|
|
\li On Linux and macOS
|
|
|
|
\code
|
|
<location-of-ifw>/binarycreator -t <location-of-ifw>/installerbase -p <package_directory> -c <config_directory>/<config_file> <installer_name>
|
|
\endcode
|
|
|
|
\endlist
|
|
|
|
To create an online only installer, you can use the --online-only which defines all
|
|
packages to install from an online repository on a web server:
|
|
|
|
\list
|
|
|
|
\li On Windows:
|
|
\code
|
|
<location-of-ifw>\binarycreator.exe -t <location-of-ifw>\installerbase.exe -p <package_directory> -c <config_directory>\<config_file> -e <packages> <installer_name>
|
|
\endcode
|
|
|
|
\li On Linux and macOS
|
|
|
|
\code
|
|
<location-of-ifw>/binarycreator -t <location-of-ifw>/installerbase -p <package_directory> -c <config_directory>/<config_file> -e <packages> <installer_name>
|
|
\endcode
|
|
|
|
\endlist
|
|
|
|
\section2 Summary of binarycreator Parameters
|
|
|
|
The \c binarycreator tool accepts the following parameters:
|
|
\table
|
|
\header
|
|
\li Parameter
|
|
\li Use
|
|
\row
|
|
\li -t or --template file
|
|
\li Use \c file as an installer template binary to which the
|
|
component information is appended. If you omit this parameter,
|
|
the \c installerbase template is used.
|
|
\row
|
|
\li -p or --packages directory
|
|
\li Use \c directory as the \l{Package Directory Structure}
|
|
{package directory}.
|
|
Defaults to the current working directory.
|
|
\row
|
|
\li --repository directory
|
|
\li Use \c directory as the repository directory
|
|
with packages to repack.
|
|
This entry can be given multiple times.
|
|
\row
|
|
\li -n or --online-only
|
|
\li Compile without any component in the installer binary.
|
|
\row
|
|
\li -f or --offline-only
|
|
\li Create an offline installer that never accesses online
|
|
repositories.
|
|
\row
|
|
\li -c or --config file
|
|
\li Use \c file as the \l{Configuration File}
|
|
{config file}.
|
|
\row
|
|
\li -e or --exclude p1,...,pn
|
|
\li Comma-separated list of packages to retrieve from an online
|
|
repository. The packages are not included in the installer
|
|
binary.
|
|
\row
|
|
\li -i or --include p1,...,pn
|
|
\li Comma-separated list of packages to retrieve from the installer
|
|
binary. You cannot combine or merge \c {--include} and \c {--exclude}.
|
|
\row
|
|
\li -r or --resources
|
|
\li Comma-separated list of resources to include in the installer
|
|
binary.
|
|
\row
|
|
\li --ignore-translations
|
|
\li Disable the use of translation files to make testing faster.
|
|
\row
|
|
\li --ignore-invalid-packages
|
|
\li Ignore component or package directories that do not have valid
|
|
metadata information (package.xml) to make testing faster.
|
|
\row
|
|
\li --ignore-invalid-repositories
|
|
\li Ignore repository directories that do not have valid
|
|
metadata information (Updates.xml) instead of aborting.
|
|
\row
|
|
\li -v or --verbose
|
|
\li Display debug output.
|
|
|
|
\row
|
|
\li -s or --sign identity
|
|
\li Only available on macOS. Allows specifying a code signing identity to be
|
|
used for signing the generated app bundle.
|
|
\endtable
|
|
|
|
These parameters are followed by the name of the target binary and a list
|
|
of packages to be available for installation.
|
|
|
|
\note The listed packages are included in the installer, as well as all
|
|
their dependencies and all packages that share the same prefix, unless you
|
|
specify the \c --nodeps parameter.
|
|
|
|
In the optional resource files specified via the \c --resources parameter, a
|
|
special \c fonts/ path can be used to ship custom fonts. These fonts will
|
|
be loaded automatically and thus become available in a stylesheet which can
|
|
be specified via the \c StyleSheet variable.
|
|
|
|
On Windows, the name of the target binary is automatically extended with
|
|
.exe, if you do not specify the extension. On Mac, the target is
|
|
created as an application bundle with the extension .app, which is automatically
|
|
added, if not supplied. Additionally, you can specify the .dmg extension,
|
|
which creates a DMG disk image that contains an .app bundle.
|
|
|
|
\section2 Using Icons
|
|
|
|
On macOS, if the target binary is suffixed with .app, a macOS
|
|
application bundle is created. The icon that you specify in config.xml is
|
|
extended with .icns and used as the icon for the created bundle.
|
|
|
|
On Windows, the icon that you specify in config.xml is extended with .ico
|
|
and used as the application icon for the .exe file.
|
|
|
|
On Linux, the icon that you specify in config.xml is extended with .png and
|
|
used as the window icon.
|
|
|
|
\section1 repogen
|
|
|
|
Use the \c repogen tool to generate online repositories.
|
|
|
|
The \c repogen tool expects the following parameters in the following order:
|
|
|
|
\code
|
|
repogen.exe -p <package_directory> <repository_directory>
|
|
\endcode
|
|
|
|
When the repository has been created, you can upload it anywhere. You must
|
|
specify the location in the installer configuration file when creating an
|
|
installer for it.
|
|
|
|
You can use an existing repository to repack packages to another
|
|
repository or offline installer.
|
|
|
|
\section2 Summary of repogen Parameters
|
|
|
|
\table
|
|
\header
|
|
\li Parameter
|
|
\li Use
|
|
\row
|
|
\li -p or --packages directory
|
|
\li Use \c directory as the \l{Package Directory Structure}
|
|
{package directory}. This is mandatory.
|
|
\row
|
|
\li --repository directory
|
|
\li Use \c directory as the repository directory
|
|
with packages to repack (not to confuse with the mandatory target
|
|
repository directory).
|
|
This entry can be given multiple times.
|
|
\row
|
|
\li repository directory
|
|
\li Target directory for the repository. During an initial installation, the directory
|
|
must not yet exist. When updating, the directory may exist and its contents may be
|
|
overwritten or removed. This is mandatory.
|
|
\row
|
|
\li -e or --exclude p1,...,pn
|
|
\li Comma-separated list of packages to be ignored from the set of
|
|
all packages in the packages directory.
|
|
\row
|
|
\li -i or --include p1,...,pn
|
|
\li Comma-separated list of packages to be used from the set of
|
|
all packages in the packages directory.
|
|
\row
|
|
\li --update
|
|
\li Update all packages in the packages directory. The list can be further
|
|
filtered with the \c {-i}, \c {-e} parameters.
|
|
\row
|
|
\li --update-new-components
|
|
\li Update only components that are new or have a newer version. The
|
|
list can be further filtered with the \c {-i}, \c{-e}
|
|
parameters.
|
|
\row
|
|
\li -r or --remove
|
|
\li Force removal of existing target directory before generating it again.
|
|
\row
|
|
\li -v or --verbose
|
|
\li Display debug output.
|
|
\endtable
|
|
\note We recommend that you use the \c {--update-new-packages} parameter
|
|
to update an existing repository, especially if you have a content delivery
|
|
system. This helps you avoid updating components that have not changed and
|
|
this makes it much easier for a content delivery system to distribute only
|
|
new files, because only the updated components are assigned new SHA
|
|
checksums.
|
|
|
|
\section1 archivegen
|
|
|
|
You can use \c archivegen to package files and directories into 7zip (.7z)
|
|
archives.
|
|
|
|
The \c archivegen tool expects the following parameters in the following
|
|
order:
|
|
|
|
\code
|
|
archivegen <name.7z> <data>
|
|
\endcode
|
|
|
|
Where \e <name.7z> is the path and file name of the archive to create and
|
|
\e <data> contains the paths and names of the files or directories to
|
|
package into the archive, separated by spaces.
|
|
|
|
\section1 devtool
|
|
|
|
You can use \c devtool to update an existing installer or maintenance tool
|
|
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
|
|
available operations, see \l {Operations}.
|
|
|
|
\c devtool expects the following parameters in the following order:
|
|
|
|
\code
|
|
devtool [options] binary
|
|
\endcode
|
|
|
|
Where \e binary is the path and name of an existing installer or maintenance
|
|
tool.
|
|
|
|
\section2 Summary of devtool Parameters
|
|
|
|
\table
|
|
\header
|
|
\li Parameter
|
|
\li Use
|
|
\row
|
|
\li -?, -h, --help
|
|
\li Display help.
|
|
\row
|
|
\li -v, --version
|
|
\li Display version information.
|
|
\row
|
|
\li --verbose
|
|
\li Display additional information.
|
|
\row
|
|
\li --update <file>
|
|
\li Update an existing installer or maintenance tool with a new
|
|
installer base.
|
|
\row
|
|
\li --dump <folder>
|
|
\li Dump the binary content that belongs to an installer or
|
|
maintenance tool into the target.
|
|
\row
|
|
\li --operation <mode,name,args,...>
|
|
\li Execute an operation with a list of arguments.
|
|
|
|
\c mode can be \c DO or \c UNDO, depending on whether the step
|
|
contains instructions for the installer or uninstaller.
|
|
\endtable
|
|
*/
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage ifw-offline-installers.html
|
|
\page ifw-online-installers.html
|
|
\nextpage ifw-updates.html
|
|
|
|
\title Creating Online Installers
|
|
|
|
Online installers fetch the repository description (Updates.xml), in
|
|
addition to the one stored inside of the binary. Create a repository and
|
|
upload it to a web server. Then specify the location of the repository in
|
|
the config.xml file that you use to create the installer.
|
|
|
|
\section1 Creating Repositories
|
|
|
|
Use the \c repogen tool to create online repositories of all packages of one package directory:
|
|
|
|
repogen.exe -p <package_directory> <repository_directory>
|
|
|
|
For example, to create a repository that contains only org.qt-project.sdk.qt and
|
|
org.qt-project.sdk.qtcreator, enter the following
|
|
command:
|
|
|
|
\code
|
|
repogen.exe -p packages -i org.qt-project.sdk.qt,org.qt-project.sdk.qtcreator repository
|
|
\endcode
|
|
|
|
When the repository has been created, upload it to a web server. You must
|
|
specify the location of the repository in the installer configuration file.
|
|
|
|
\section1 Configuring Repositories
|
|
|
|
The \c <RemoteRepositories> element in the installer configuration file
|
|
(config.xml) can contain a list of several repositories. Each of them can
|
|
have the following settings:
|
|
|
|
\list
|
|
|
|
\li \c <Url>, which points to a list of available components.
|
|
\li \c <Enabled>, with 0 disabling this repository.
|
|
\li \c <Username>, which is used as user on a protected repository.
|
|
\li \c <Password>, which sets the password to use on a protected
|
|
repository.
|
|
\li \c <DisplayName>, which optionally sets a string to display instead
|
|
of the URL.
|
|
|
|
\endlist
|
|
|
|
The URL needs to point to the Updates.xml file that lists the available
|
|
components. For example:
|
|
|
|
\code
|
|
<RemoteRepositories>
|
|
<Repository>
|
|
<Url>http://www.example.com/packages</Url>
|
|
<Enabled>1</Enabled>
|
|
<Username>user</Username>
|
|
<Password>password</Password>
|
|
<DisplayName>Example repository</DisplayName>
|
|
</Repository>
|
|
</RemoteRepositories>
|
|
\endcode
|
|
|
|
The installer works only if it can access the repository. If the repository is
|
|
accessed after the installation, the maintenance tool 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,
|
|
although entering a password here is usually not advisable as it is saved in plain
|
|
text. Authentication details not set here will be gotten at runtime using a dialog.
|
|
The user can work around these settings at runtime.
|
|
|
|
\section1 Configuring Repository Categories
|
|
|
|
The \c <RepositoryCategory> element in the installer configuration file
|
|
(config.xml) can contain a list of several \c <RemoteRepositories> elements. Each \c <RemoteRepositories>
|
|
element within the \c <RepositoryCagetory> element is considered a category. Each catecory can have
|
|
a \c <DisplayName>, a \c <Tooltip>, a \c <Preselected> element and several \c <Repository> elements.
|
|
Repository categories are shown in the component selection page,
|
|
on the left side of the component selection widget:
|
|
|
|
\image ifw-repository-categories.png "Component selection Page"
|
|
|
|
By default, only repositories with no category are shown in the component selection widget. Checking one or
|
|
several repositories and pressing \uicontrol Fetch will update the widget to show content also
|
|
from the selected categorized repositories. Components in the repository
|
|
categories are marked as \e unstable meaning that you can install other
|
|
components although some components have missing dependencies, script
|
|
errors and so on. For more information about \e unstable components, see
|
|
\l {Summary of Configuration File Elements}.
|
|
|
|
Example of creating a repository category:
|
|
|
|
\code
|
|
<RepositoryCategories>
|
|
<RemoteRepositories>
|
|
<Displayname>Category 1</Displayname>
|
|
<Preselected>true</Preselected>
|
|
<Tooltip>Tooltip for category 1</Tooltip>
|
|
<Repository>
|
|
<Url>http://www.example.com/packages</Url>
|
|
<Enabled>1</Enabled>
|
|
<Username>user</Username>
|
|
<Password>password</Password>
|
|
<DisplayName>Example repository</DisplayName>
|
|
</Repository>
|
|
</RemoteRepositories>
|
|
</RepositoryCategories>
|
|
\endcode
|
|
|
|
\section1 Creating Installer Binaries
|
|
|
|
To create an online installer by using the \c binarycreator tool, enter the
|
|
following command:
|
|
|
|
\code
|
|
<location-of-ifw>\binarycreator.exe -t <location-of-ifw>\installerbase.exe -p <package_directory> -c <config_directory>\<config_file> -e <packages> <installer_name>
|
|
\endcode
|
|
|
|
For example, enter the following command to create an installer binary
|
|
called SDKInstaller.exe that will not contain data for org.qt-project.sdk.qt and
|
|
org.qt-project.qtcreator, because those packages are downloaded from a remote
|
|
repository:
|
|
|
|
\code
|
|
binarycreator.exe -p installer-packages -c installer-config\config.xml -e org.qt-project.sdk.qt,org.qt-project.qtcreator SDKInstaller.exe
|
|
\endcode
|
|
|
|
\section1 Reducing Installer Size
|
|
Even if the components are fetched from a web server, \c binarycreator adds
|
|
them to the installer binary by default. However, when the installer checks
|
|
the web server for updates, end users are spared a download if new versions
|
|
are not available.
|
|
|
|
Alternatively, you can create online installers that do not contain any data
|
|
and that fetch all the data from the web server. Use the \c{-n} parameter
|
|
of the \c binarycreator tool and only add the root component to the
|
|
installer. Usually the root component is empty and hence only adds the XML
|
|
description of the root.
|
|
|
|
For more information about the options that you have, see
|
|
\l{Summary of binarycreator Parameters}.
|
|
*/
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage ifw-creating-installers.html
|
|
\page ifw-offline-installers.html
|
|
\nextpage ifw-online-installers.html
|
|
|
|
\title Creating Offline Installers
|
|
|
|
Offline installers do not try to connect to an online repository at all
|
|
during installation. However, the metadata configuration (config.xml)
|
|
enables users to add and update components online.
|
|
|
|
Offline installers are especially useful in cases where a corporate firewall
|
|
does not allow end users to connect to web servers. The network
|
|
administrator can set up a local update service within the network.
|
|
|
|
To create offline installers, use the \c{--offline-only} option of the
|
|
\c binarycreator tool.
|
|
|
|
To create an offline installer in Windows, enter the following command:
|
|
|
|
\code
|
|
<location-of-ifw>\binarycreator.exe --offline-only -t <location-of-ifw>\installerbase.exe -p <package_directory> -c <config_directory>\<config_file> <installer_name>
|
|
\endcode
|
|
|
|
Some options have default values, and therefore, you can omit them.
|
|
For example, enter the following command to create an installer binary
|
|
called SDKInstaller.exe that contains the packages identified by
|
|
org.qt-project.sdk and their dependencies:
|
|
|
|
\code
|
|
binarycreator.exe --offline-only -c installer-config -p installer-packes SDKInstaller.exe
|
|
\endcode
|
|
|
|
*/
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage ifw-online-installers.html
|
|
\page ifw-updates.html
|
|
\nextpage ifw-customizing-installers.html
|
|
|
|
\title Promoting Updates
|
|
|
|
Create online installers to be able to promote updates to end users who
|
|
install your product.
|
|
|
|
The following steps are needed to promote updates:
|
|
|
|
\list 1
|
|
|
|
\li Copy the updated content to the package directory.
|
|
|
|
\li Increase the value of the \c <Version> element for the updated
|
|
components in the package.xml file.
|
|
|
|
\li Use the \c repogen tool to recreate the online repository with the
|
|
updated contents and to generate the Updates.xml file in the root
|
|
directory of the repository.
|
|
|
|
\li Upload the repository to the web server.
|
|
|
|
\li Use the \c binarycreator tool to create the installer.
|
|
|
|
\endlist
|
|
|
|
\section1 Configuring Updates
|
|
|
|
The installer downloads the Updates.xml file on
|
|
startup and compares the installed version with the version in the file. If
|
|
the online version number in the file is greater than the local one, the
|
|
installer displays it in the list of available updates.
|
|
|
|
Increase the value of the \c <Version> element for the component in the
|
|
package.xml file.
|
|
|
|
\section1 Recreating Repositories
|
|
|
|
The easiest way to provide an update is to recreate the repository and
|
|
upload it to the web server. For more information, see
|
|
\l{Creating Repositories}.
|
|
|
|
\section1 Partially Updating Repositories
|
|
|
|
A full update of the whole repository might not be optimal if:
|
|
\list
|
|
\li The repository is very large, as uploading would take a long time.
|
|
\li You want to deliver only the changed components.
|
|
\endlist
|
|
|
|
\note repogen recreates the 7zip archives each time it is being called. As
|
|
7zip stores the timestamps of the included files (which are moved or copied
|
|
during this process), the SHA sum of each archive changes. SHA sums are used
|
|
to verify the download of the archive and hence the SHA needs to match the
|
|
7zip. As the SHAs are stored in the Updates.xml file you will be
|
|
forced to upload the full repository. This can be circumvented by using the
|
|
\c{--update} option of repogen.
|
|
|
|
\section2 Creating Partial Updates
|
|
When recreating the online repository, use the \c{--update} parameter. It
|
|
takes an existing repository as input and only changes the components that
|
|
are specified as additional parameters. Only those SHA sums are
|
|
changed in the global configuration as well.
|
|
|
|
\section2 Uploading Partial Updates
|
|
Upload the following items to the web server:
|
|
\list
|
|
\li The component directory (usually something like
|
|
\c{com.vendor.product.updatedpart}).
|
|
\li The global \c{Updates.xml} stored in the root directory of the online
|
|
repository.
|
|
\endlist
|
|
|
|
\note The order of uploading items is very important. If you update the
|
|
repository on a live server, first update the component and
|
|
then Updates.xml. The package names include version numbers, and therefore,
|
|
end users receive old packages until the new ones are fully uploaded.
|
|
|
|
\section1 Changing Repositories
|
|
|
|
To have the current update repository point to other repositories, edit the
|
|
Updates.xml file in the current repository. You can add, replace, or remove
|
|
repositories.
|
|
|
|
\code
|
|
<RepositoryUpdate>
|
|
<Repository action="..." OPTIONS />
|
|
<Repository action="..." OPTIONS />
|
|
</RepositoryUpdate>
|
|
\endcode
|
|
|
|
\section2 Adding Repositories
|
|
To update a repository, add a \c <Repository> child element to the
|
|
\c <RepositoryUpdate> element with the following options:
|
|
|
|
\code
|
|
<Repository action="add" url="http://www.example.com/repository" name="user" password="password"
|
|
displayname="Example Repository" />
|
|
\endcode
|
|
|
|
\c{url} will be used as a base URL to resolve an \c{Updates.xml} file against.
|
|
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.
|
|
|
|
\c{name} and \c{password} optionally specify credentials for a protected repository.
|
|
|
|
\section2 Removing Repositories
|
|
To remove a repository, add a \c <Repository> child element to the
|
|
\c <RepositoryUpdate> element with the following options:
|
|
|
|
\code
|
|
<Repository action="remove" url="http://www.example.com/repository" />
|
|
\endcode
|
|
|
|
\c{url} must match exactly the URL that is to be removed.
|
|
|
|
\section2 Replacing Repositories
|
|
To replace one repository with another, add a \c <Repository> child element to the
|
|
\c <RepositoryUpdate> element with the following options:
|
|
|
|
\code
|
|
<Repository action="replace" oldUrl="http://www.example.com/repository"
|
|
newUrl="http://www.example.com/newrepository" name="user" password="password"
|
|
displayname="New Example Repository" />
|
|
\endcode
|
|
|
|
\c{oldUrl} must match exactly the URL that is to be replaced.
|
|
|
|
\c{newUrl} must match exactly the URL that it is replaced with.
|
|
|
|
\section1 Relocatable Repositories
|
|
|
|
Some projects contain multiple repositories. To create a relocatable set
|
|
of repositories you should use relative paths.
|
|
|
|
So if the generic repository available at the address
|
|
\c{http://www.example.com/repositories/generic} and \c{Updates.xml}
|
|
contains \c <Repository> element with the following options:
|
|
|
|
\code
|
|
<Repository action="add" url="../module" name="user" password="password"
|
|
displayname="Module Repository" />
|
|
\endcode
|
|
|
|
Then the resolved address of the added repository will be
|
|
\c{http://www.example.com/repositories/module}, so that the repository does
|
|
not contain information about their absolute location.
|
|
|
|
If you want to change the address, you can simply copy a set of repositories as is.
|
|
It is recommended to maintain the old generic repository for some time and replace the addresses
|
|
as described above. You can also provide the updated installer with the new generic address.
|
|
|
|
You can use relative paths for the arguments \c url, \c oldUrl, and \c newUrl in
|
|
the \c <Repository> element.
|
|
*/
|
|
|
|
/*!
|
|
\contentspage index.html
|
|
\previouspage ifw-cpp-classes.html
|
|
\page ifw-knownissues.html
|
|
\nextpage index.html
|
|
|
|
\title Known Issues
|
|
|
|
Check the \l{https://bugreports.qt.io/browse/QTIFW}{Qt Bugtracker}
|
|
for known issues in the Qt Installer Framework project. If you cannot find
|
|
the issue there, create a bug report.
|
|
*/
|
|
|