Qt Installer Framework发布更新

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:

推广更新需要以下步骤：

1.Copy the updated content to the package directory.

1.将更新的内容复制到包目录。

2.Increase the value of the <Version> element for the updated components in the package.xml file.

2.增加package.xml文件中更新组件的<Version>元素的值。

3.Use the 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.

3.使用repogen工具使用更新的内容重新创建在线存储库，并在存储库的根目录中生成Updates.xml文件。

4.Upload the repository to the web server.

4.将存储库上传到web服务器。

5.Use the binarycreator tool to create the installer.

5.使用binarycreator工具创建安装程序。

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.

安装程序在启动时下载Updates.xml文件，并将安装的版本与文件中的版本进行比较。如果文件中的联机版本号大于本地版本号，安装程序会将其显示在可用更新列表中。

Increase the value of the <Version> element for the component in the package.xml file.

增加package.xml文件中组件的<Version>元素的值。

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 Creating Repositories.

​提供更新的最简单方法是重新创建存储库并将其上传到web服务器。有关详细信息，请参见创建存储库。

Partially Updating Repositories

部分更新存储库

A full update of the whole repository might not be optimal if:

在以下情况下，完整更新整个存储库可能不是最佳选择：

• The repository is very large, as uploading would take a long time.
• 存储库非常大，因为上传需要很长时间。
• You want to deliver only the changed components.
• 只想交付更改后的组件。

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 --update option of repogen.

注意：repogen每次调用时都会重新创建7zip存档。由于7zip存储了所包含文件的时间戳（在此过程中移动或复制），因此每个存档的SHA总和都会发生变化。SHA总和用于验证存档的下载，因此SHA需要与7zip相匹配。由于SHA存储在Updates.xml文件中，将被迫上传完整的存储库。这可以通过使用repogen的--update选项来规避。

Creating Partial Updates

创建部分更新

When recreating the online repository, use the --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.

重新创建联机存储库时，请使用--update参数。它以现有的存储库作为输入，只更改指定为附加参数的组件。只有这些SHA总和在全局配置中也会发生变化。

Uploading Partial Updates

上传部分更新

Upload the following items to the web server:

将以下项目上传到web服务器：

• The component directory (usually something like com.vendor.product.updatedpart).
• 组件目录（通常类似于com.vendor.product.updatedpart）。
• The global Updates.xml stored in the root directory of the online repository.
• 存储在联机存储库根目录中的全局Updates.xml。

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.

注意：上传项目的顺序非常重要。如果在实时服务器上更新存储库，请先更新组件，然后更新Updates.xml。包名称包括版本号，因此，最终用户会收到旧包，直到新包完全上传。

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.

要使当前更新存储库指向其他存储库，请编辑当前存储库中的Updates.xml文件。可以添加、替换或删除存储库。

<RepositoryUpdate>
  <Repository action="..." OPTIONS />
  <Repository action="..." OPTIONS />
</RepositoryUpdate>

Adding Repositories

添加存储库

To update a repository, add a <Repository> child element to the <RepositoryUpdate> element with the following options:

要更新存储库，请使用以下选项将<Repository>子元素添加到<RepositoryUpdate>元素中：

<Repository action="add" url="http://www.example.com/repository" name="user" password="password"
             displayname="Example Repository" />

url will be used as a base URL to resolve an Updates.xml file against. If url is itself relative, it will be resolved against the base URL of the current document.

url将用作解析Updates.xml文件的基本url。如果url本身是相对的，则将根据当前文档的基本url进行解析。

displayname specifies how the repository should be named in the Settings page of the maintenance tool.

displayname指定如何在维护工具的“设置”页面中命名存储库。

name and password optionally specify credentials for a protected repository.

name和password可选地指定受保护存储库的凭据。

Removing Repositories

删除存储库

To remove a repository, add a <Repository> child element to the <RepositoryUpdate> element with the following options:

要删除存储库，请使用以下选项向<RepositoryUpdate>元素添加<Repository>子元素：

<Repository action="remove" url="http://www.example.com/repository" />

url must match exactly the URL that is to be removed.

url必须与要删除的url完全匹配。

Replacing Repositories

替换存储库

To replace one repository with another, add a <Repository> child element to the <RepositoryUpdate> element with the following options:

要将一个存储库替换为另一个，请使用以下选项在<RepositoryUpdate>元素中添加<Repository>子元素：

<Repository action="replace" oldUrl="http://www.example.com/repository"
            newUrl="http://www.example.com/newrepository" name="user" password="password"
            displayname="New Example Repository" />

oldUrl must match exactly the URL that is to be replaced.

oldUrl必须与要替换的URL完全匹配。

newUrl must match exactly the URL that it is replaced with.

newUrl必须与替换它的URL完全匹配。

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 http://www.example.com/repositories/generic and Updates.xml contains <Repository> element with the following options:

因此，如果通用存储库在该地址可用http://www.example.com/repositories/genericUpdates.xml包含具有以下选项的<Repository>元素：

<Repository action="add" url="../module" name="user" password="password"
             displayname="Module Repository" />

Then the resolved address of the added repository will be http://www.example.com/repositories/module, so that the repository does not contain information about their absolute location.

然后，添加的存储库的解析地址将为http://www.example.com/repositories/module，因此存储库不包含有关其绝对位置的信息。

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 url, oldUrl, and newUrl in the <Repository> element.

可以在<Repository>元素中为参数url、oldUrl和newUrl使用相对路径。

Promoting Updates for the Maintenance Tool

发布维护工具的更新

Without additional configuration, both online and offline installers install the maintenance tool, that can be later used to add, update, and remove components. Online installers also have an option to install the maintenance tool from an online repository. This makes it possible to promote updates for the maintenance tool to take the advantage of latest new features and fixes to the Qt Installer Framework. If maintenance tool in offline installer needs signing, you need to provide the maintenance tool as a component, see Populating the Maintenance Tool Component.

​无需额外配置，在线和离线安装程序都会安装维护工具，该工具稍后可用于添加、更新和删除组件。在线安装程序还可以选择从在线存储库安装维护工具。这使得升级维护工具的更新成为可能，以利用Qt安装程序框架的最新新功能和修复。如果离线安装程序中的维护工具需要签名，需要将维护工具作为组件提供，请参阅填充维护工具组件。

You should download the latest release of the Installer Framework distribution that includes new versions of binarycreator and installerbase tools. However, to only update vendor specific configuration like <Name>, <Title>, and <Publisher> to the new maintenance tool, you can use the tools that were used to create the original installer.

​应该下载最新版本的Installer Framework发行版，其中包括新版本的binarycreator和installerbase工具。但是，要仅将特定于供应商的配置（如<Name>、<Title>和<Publisher>）更新到新的维护工具，可以使用用于创建原始安装程序的工具。

Creating the Component Directory Structure for Maintenance Tool

创建维护工具的组件目录结构

To make the maintenance tool update installable for end users, you need to prepare an installer component for the maintenance tool and create a repository for that component.

为了使维护工具更新可供最终用户安装，需要为维护工具准备一个安装程序组件，并为该组件创建一个存储库。

Note: If you already have a component for the maintenance tool available in a repository, you can skip the instructions in this section.

注意：如果存储库中已有维护工具的组件，则可以跳过本节中的说明。

A common convention is to create a 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 org.qtproject.ifw.maintenancetool, with meta and data subdirectories. These directories will be populated later.

一个常见的约定是创建一个packages 目录，其中包含安装程序组件的metadata 和data 。在该目录中，需要为维护工具组件创建一个子目录，并使用选择的名称，例如org.qtproject.ifw.maintenancetool，其中包含meta和data子目录。稍后将填充这些目录。

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 maintenance tool, you need to create an update resource file. Otherwise this step is optional.

如果要应用配置更改，例如在最终用户更新维护工具时更新标题、发布者或产品URL，则需要创建一个更新资源文件。否则，此步骤是可选的。

First, you need to compile the resource file that will contain the new maintenance tool configuration and related files:

首先，需要编译包含新维护工具配置和相关文件的资源文件：

binarycreator -c config/config.xml -p packages -rcc

The command outputs the result into update.rcc in the current path.

该命令将结果输出到当前路径中的update.rcc中。

The packages directory argument refers to the previously created directory for the maintenance tool component. config.xml contains the maintenance tool configuration. This can be the same file that was used for creating the online installer that is going to consume the maintenance tool repository, or you could make modifications to change some configuration elements like the window title and product version.

packages目录参数指的是之前为维护工具组件创建的目录。config.xml包含维护工具配置。这可以是用于创建将使用维护工具存储库的在线安装程序的同一文件，也可以进行修改以更改某些配置元素，如窗口标题和产品版本。

For full reference of elements supported by the configuration file, see Configuration File.

​有关配置文件支持的元素的完整参考，请参阅配置文件。

Getting the Maintenance Tool

获取维护工具

The maintenance tool for Linux and Windows is the same as the installerbase executable located in your Qt Installer Framework's installation bin folder. For macOS the maintenance tool app bundle can be created using the binarycreator tool with the command line switch --mt or --create-maintenancetool. The name of the macOS app bundle can be configured in config.xml using the <MaintenanceToolName> element. The app bundle can be later signed and notarized if needed.

Linux和Windows的维护工具与Qt Installer Framework的bin安装文件夹中的installerbase可执行文件相同。对于macOS，可以使用binarycreator工具和命令行开关--mt或--create-maintenancetool创建维护工具应用程序包。可以使用<MaintenanceToolName>元素在config.xml中配置macOS应用程序包的名称。如果需要，可以稍后对应用程序包进行签名和公证。

binarycreator -c config/config.xml --mt

Populating the Maintenance Tool Component

填充维护工具组件

In Linux and in Windows the installerbase executable from Qt Installer Framework's installation folder, or in macOS the maintenance tool app bundle, should be copied to the component's data directory. For signed maintenance tool, sign the installerbase, or maintenance tool app bundle. If you generated the update.rcc in the Compiling the Update Resource step, copy that to the data directory as well. The meta directory should contain a package.xml file with the package information elements of your choice. However, it is a good idea to mark the component <Essential> so that it gets automatically installed when running the updater. You may also want to mark the component <Virtual> to hide it from the component selection.

​在Linux和Windows中，Qt Installer Framework的安装文件夹中的installerbase可执行文件，或在macOS中的维护工具应用程序包，应复制到组件的数据目录中。对于已签名的维护工具，请在installerbase或维护工具应用程序包上签名。如果在编译更新资源步骤中生成了update.rcc，请将其复制到data目录中。meta目录应包含一个package.xml文件，其中包含选择的包信息元素。但是，最好标记组件<Essential>，以便在运行更新程序时自动安装。可能还想标记组件<Virtual>，以便在组件选择中隐藏它。

For further information about the package.xml file, see Summary of Package Information File Elements.

​有关package.xml文件的更多信息，请参阅包信息文件元素摘要。

Note: If you are providing an update for an existing maintenance tool component, copy and overwrite the existing files with the updated content to the package directory and increase the value of the <Version> element in the package.xml file.

注意：如果要为现有维护工具组件提供更新，请将更新内容复制并覆盖现有文件到包目录，并增加package.xml文件中<Version>元素的值。

The meta directory should also contain an installation script that tells the installer that there are replacements for the default installerbase and update resource files. A minimal installscript.qs for this purpose could look like this:

meta目录还应该包含一个安装脚本，该脚本告诉安装程序有默认安装程序库和更新资源文件的替换。用于此目的的最小installscript.qs可以如下所示：

function Component()
{
    component.ifwVersion = installer.value("FrameworkVersion");
    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";
            if (installer.versionMatches(component.ifwVersion, "<4.8.0"))
                component.installerbaseBinaryPath = "@TargetDir@/MaintenanceTool.app";
            else
                component.installerbaseBinaryPath = "@TargetDir@/tmpMaintenanceToolApp/MaintenanceTool.app";
        }
        installer.setInstallerBaseBinary(component.installerbaseBinaryPath);

        var updateResourceFilePath = installer.value("TargetDir") + "/update.rcc";
        installer.setValue("DefaultResourceReplacement", updateResourceFilePath);
    }
}

Component.prototype.createOperationsForArchive = function(archive)
{
    // IFW versions 4.8.1 onwards supports extracting the maintenance tool to a folder.
    // It is a good practice to extract the maintenance tool to a folder, so it won't
    // interfere the current running maintenance tool. As the last step of the
    // installation, IFW will move the maintenance tool to the root of the installation.
    if (installer.versionMatches(component.ifwVersion, "<4.8.0"))
        component.createOperationsForArchive(archive)
    else
        component.addOperation("Extract", archive, "@TargetDir@/tmpMaintenanceToolApp");
}

You must include the installation script in the package.xml by specifying the filename in the <Script> element.

必须通过在<Script>元素中指定文件名，将安装脚本包含在package.xml中。

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 Creating Repositories apply also for the component containing the maintenance tool update.

​准备完成后，应将组件上传到现有或新的在线存储库，以便最终用户可以使用。关于如何在此页面上创建存储库和创建存储库的说明也适用于包含维护工具更新的组件。

Creating Online InstallersCustomizing Installers

© 2021 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. The Qt Company, Qt and their respective logos are trademarks of The Qt Company Ltd in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.