Qt Installer Framework 使用说明（二）

目录

• 4、教程: 创建一个安装程序
  • 创建软件包目录
  • 创建配置文件
  • 创建程序包信息文件
  • 指定组件信息
  • 指定安装程序版本
  • 添加许可证
  • 选择默认内容
  • 创建安装程序内容
  • 创建安装程序二进制文件
• 5、创建安装程序 Creating Installers
  • 创建离线安装程序 Creating Offline Installers
  • 创建在线安装程序 Creating Online Installers
    • 创建存储库 Creating Repositories
    • 配置存储库 Configuring Repositories
    • 创建安装程序二进制文件 Creating Installer Binaries
    • 减少安装程序文件大小 Reducing Installer Size
  • 促进更新 Promoting Updates
    • 配置更新 Configuring Updates
    • 重新创建存储库 Recreating Repositories
    • 部分更新存储库
    • 创建部分更新 Creating Partial Updates
    • 上传部分更新 Uploading Partial Updates
    • 更改存储库 Changing Repositories
      • 添加存储库 Adding Repositories
      • 删除存储库 Removing Repositories
      • 替换存储库 Replacing Repositories
  • 自定义安装程序 Customizing Installers
    • 添加操作 Adding Operations
    • 添加页面 Adding Pages
      • 使用组件脚本添加页面 Using Component Scripts to Add Pages
      • 使用控制脚本添加页面 Using Control Scripts to Add Pages
    • 添加小部件 Adding Widgets
    • 与安装程序功能交互
    • 翻译页面 Translating Pages

4、教程: 创建一个安装程序

本教程介绍如何为小项目创建简单的安装程序：

本节介绍以下创建安装程序 必须 完成的任务：

1. 创建一个包(package)目录，其中将包含所有配置文件和可安装的包。
2. 创建包含有关如何构建安装程序二进制文件和联机存储库的信息的配置文件。
3. 创建包信息文件，其中包含有关可安装组件的信息。
4. 创建安装程序内容并将其复制到软件包(package)目录中。
5. 使用binarycreator工具创建安装程序。
   安装程序页面是使用您在配置和程序包信息文件中提供的信息创建的。

示例文件位于Qt Installer Framework资源库中的examples\tutorial目录中。

创建软件包目录

创建一个反映安装程序设计的目录结构，并允许将来扩展安装程序。 该目录必须包含config和packages的子目录。

有关软件包目录的详细信息，请参阅Package Directory。

创建配置文件

在config目录中，创建一个名为config.xml的文件，其中包含以下内容：

<?xml version="1.0" encoding="UTF-8"?>
<Installer>
    <Name>Your application</Name>
    <Version>1.0.0</Version>
    <Title>Your application Installer</Title>
    <Publisher>Your vendor</Publisher>
    <StartMenuDir>Super App</StartMenuDir>
    <TargetDir>@HomeDir@/InstallationDirectory</TargetDir>
</Installer>

该配置文件指定介绍页面上显示以下信息：

<Title元素指定显示在标题栏 (下图[1]) 上的安装程序名称。

<Name元素指定添加到页面名称和简介文本 (下图[2]) 的应用程序名称。

其他元素用于自定义安装程序的行为：

• <Version>元素指定应用程序版本号。
• <Publisher>元素指定软件的发布者（例如，在Windows控制面板中所示）。
• <StartMenuDir>元素指定Windows开始菜单中产品的默认程序组的名称。
• <TargetDir>元素指定显示给用户的默认目标目录是当前用户的主目录中的InstallationDirectory（因为预定义变量@HomeDir@用作值的一部分）。 有关详细信息，请参阅预定义变量。

有关配置文件格式和可用元素的详细信息，请参阅Configuration File。

创建程序包信息文件

在这种简单的情况下，安装程序只处理一个名为com.vendor.product的组件。 要向安装程序提供有关组件的信息，请创建一个名为package.xml的文件，其中包含以下内容，并将其放在meta目录中：

<?xml version="1.0" encoding="UTF-8"?>
<Package>
    <DisplayName>The root component</DisplayName>
    <Description>Install this example.</Description>
    <Version>0.1.0-1</Version>
    <ReleaseDate>2010-09-21</ReleaseDate>
    <Licenses>
        <License name="Beer Public License Agreement" file="license.txt" />
    </Licenses>
    <Default>script</Default>
    <Script>installscript.qs</Script>
    <UserInterfaces>
        <UserInterface>page.ui</UserInterface>
    </UserInterfaces>
</Package>

下面更详细地描述示例文件中的元素。

有关软件包信息文件的详细信息，请参阅Package Information File Syntax

指定组件信息

来自以下元素的信息显示在组件选择页面上：

<DisplayName>元素指定组件列表中组件的名称 (下图[1]) 。

<Description>元素指定在选择组件时显示的文本 (下图[2]) 。

指定安装程序版本

<Versionss>元素使您能够在用户有可用更新时提醒用户进行更新。

添加许可证

<License>元素指定包含许可协议文本 (下图[1]) 的文件名称，该文本显示在许可检查页上：

选择默认内容

<Default>元素指定默认情况下是否选择组件。值为true的组件将设置为选定。 在此示例中，我们使用脚本在运行时解析值。 JavaScript脚本文件installscript.qs的名称在<Script>元素中指定。

创建安装程序内容

要安装的内容存储在组件的data目录中。 因为只有一个组件，请将数据放在packages/com.vendor.product/data目录中。 该示例已包含用于测试目的的文件，但您基本上可以将任何文件放在目录中。

有关打包规则和选项的详细信息，请参阅数据目录。

创建安装程序二进制文件

您现在可以创建您的第一个安装程序。 在命令行上切换到examples\tutorial目录。 要创建一个名为YourInstaller.exe一个安装程序，其中包含com.vendor.product标识的包，输入以下命令：

在Windows上:

..\..\bin\binarycreator.exe -c config\config.xml -p packages YourInstaller.exe

在Linux 或 OS 上:

../../bin/binarycreator -c config/config.xml -p packages YourInstaller

安装程序会在当前目录中创建，你可以提供给最终用户。

有关使用binarycreator工具的更多信息，请参阅binarycreator。

注意：如果在运行教程安装程序时显示错误消息，请检查是否使用静态构建的Qt创建安装程序。 有关更多信息，请参阅Configuring Qt。

5、创建安装程序 Creating Installers

创建离线和联机安装程序需要以下步骤：

• 1. 为可安装组件创建包目录。相关相信信息，请参阅Package Directory
• 1. 在config目录中创建一个名为config.xml的配置文件。 它包含有关如何构建安装程序二进制文件和联机存储库的信息。 有关文件格式和可用设置的详细信息，请参阅Configuration File
• 1. 在config\meta目录中创建一个名为package.xml的包信息文件。 它包含部署和安装过程的设置。 有关详细信息，请参阅Meta Directory
• 1. 创建安装程序内容并将其复制到软件包目录中。 有关详细信息，请参阅Data Directory
• 1. 对于联机安装程序，请使用repogen工具创建包含可安装内容的存储库，并将存储库上载到Web服务器。
• 1. 使用binarycreator工具创建安装程序。 有关详细信息，请参阅Tools

有关如何创建使用预定义安装程序页面的简单安装程序的示例，请参阅Tutorial: Creating an Installer

以下部分介绍如何创建不同类型的安装程序：

创建离线安装程序 Creating Offline Installers

在安装期间， 离线安装程序 根本不尝试连接到联机存储库。 但是，元数据配置（config.xml）中可以设置允许用户在线添加和更新组件。

离线安装程序在公司防火墙不允许最终用户连接到Web服务器的情况下尤其有用。 网络管理员可以在网络中设置本地更新服务。

要创建离线安装程序，请使用binarycreator工具的--offline-only选项。

要在Windows中创建离线安装程序，请输入以下命令：

<location-of-ifw>\binarycreator.exe --offline-only -t <location-of-ifw>\installerbase.exe -p <package_directory> -c <config_directory>\<config_file> <installer_name>

译注:<location-of-ifw>表示binarycreator程序所在目录。

某些选项具有默认值，所以，可以忽略它们。例如，输入以下命令来创建名为SDKInstaller.exe的安装程序二进制文件，其中包含由org.qt-project.sdk标识的软件包及其依赖关系：

binarycreator.exe --offline-only -c installer-config -p installer-packes SDKInstaller.exe

创建在线安装程序 Creating Online Installers

联机安装程序获取一个不在二进制文件中的存储库描述(Update.xml)。创建存储库并将其上传到Web服务器。 然后在用于创建安装程序的config.xml文件中指定存储库的位置。

创建存储库 Creating Repositories

使用repogen工具创建一个软件包目录的所有软件包的联机存储库：

repogen.exe -p <package_directory> <repository_directory>

例如，要创建只包含org.qt-project.sdk.qt和org.qt-project.sdk.qtcreator的存储库，请输入以下命令：

`

repogen.exe -p packages -i org.qt-project.sdk.qt,org.qt-project.sdk.qtcreator repository

创建存储库后，将其上传到Web服务器。 您必须在安装程序配置文件(config.xml)中指定存储库的位置。

配置存储库 Configuring Repositories

安装程序配置文件(config.xml)中的<RemoteRepositories>元素可以包含多个存储库列表。 每个存储库都可以有以下设置项：

• <Url>, 指向可用组件列表。
• <Enabled>, 0表示禁用此存储库。
• <Username>, 用于受保护存储库验证的用户名。
• <Password>, 用于受保护存储库验证的密码。
• <DisplayName>, 可选，设置要显示的字符串，而不是URL。

URL需要指向列出可用组件的Updates.xml文件。 例如：

<RemoteRepositories>
     <Repository>
             <Url>http://www.example.com/packages</Url>
             <Enabled>1</Enabled>
             <Username>user</Username>
             <Password>password</Password>
             <DisplayName>Example repository</DisplayName>
     </Repository>
</RemoteRepositories>

仅当安装程序 可以访问存储库 时，安装程序才会继续。 如果在安装后访问存储库，维护工具将拒绝安装。 但是，卸载后可再次安装。 默认情况下可以启用或禁用存储库。 对于需要验证的存储库，也可以在此处设置详细信息，但在此输入密码通常不可取，因为它以纯文本保存。 若此处未设置身份验证详细信息，将在 运行时通过对话框获取 。 用户可以在运行时解决这些设置。

创建安装程序二进制文件 Creating Installer Binaries

要使用binarycreator工具创建联机安装程序，请输入以下命令：

<location-of-ifw>\binarycreator.exe -t <location-of-ifw>\installerbase.exe -p <package_directory> -c <config_directory>\<config_file> -e <packages> <installer_name>

例如，输入以下命令以创建名为SDKInstaller.exe的安装程序二进制文件，其中 不包含 org.qt-project.sdk.qt和org.qt-project.qtcreator的数据，因为这些软件包是 从远程存储库下载 的：

binarycreator.exe -p installer-packages -c installer-config\config.xml -e org.qt-project.sdk.qt,org.qt-project.qtcreator SDKInstaller.exe

减少安装程序文件大小 Reducing Installer Size

即使组件从Web服务器获取，binarycreator 仍然会将它们添加到安装程序二进制文件 中。 但是，当安装程序检查Web服务器上的更新时，如果新版本不可用，则最终用户可以免于下载。

或者，您可以创建不包含任何数据仅从Web服务器获取所有数据的联机安装程序。 使用binarycreator工具的-n参数，并且只将根(root)组件添加到安装程序。 通常根(root)组件是空的，因此只添加根(root)的XML描述。

更多相关选项的详细信息，请参阅Summary of binarycreator Parameters

促进更新 Promoting Updates

促进更新这是一个很别扭的翻译，这里的意思是在运行联机安装程序的时候，会去读取存储库中的Update.xml文件来判断是否需要下载更新。

创建在联机程序，以便能够向最终安装产品用户促进更新。

需要以下步骤来促进更新：

• 1. 复制要更新的内容到软件包目录。
• 1. 增加package.xml文件中已更新组件的<Version>元素的值。
• 1. 使用repogen工具重新创建具有更新内容的联机存储库，并在存储库的根目录中生成Updates.xml文件。
• 1. 将存储库上传到Web服务器。
• 1. 使用binarycreator工具创建安装程序。

配置更新 Configuring Updates

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

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

重新创建存储库 Recreating Repositories

提供更新的最简单方法是重新创建资源库，并上传到Web服务器。 有关更多信息，请参阅创建存储库 Creating Repositories

部分更新存储库

整个库完全更新可能不是最优的，如果：

• 存储库非常大，因为上传需要很长时间。
• 你想只提供更新的组件。

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

创建部分更新 Creating Partial Updates

在重新创建联机存储库时，请使用--update参数。 它将现有存储库作为输入，并仅更改附加参数指定的组件。 那些SHA值在全局配置中也被改变。

上传部分更新 Uploading Partial Updates

上传下列项目到Web服务器：

• 组件目录（通常类似于com.vendor.product.updatedpart）。
• 全局Updates.xml存储在联机存储库的根目录中。

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

更改存储库 Changing Repositories

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

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

添加存储库 Adding Repositories

要更新(原文是Update，猜测应该是添加)存储库，请将 具有以下选项 <Repository>子元素添加到<RepositoryUpdate>元素中：

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

删除存储库 Removing Repositories

要删除存储库，请将 具有以下选项 <Repository>子元素添加到<RepositoryUpdate>元素中：

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

替换存储库 Replacing Repositories

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

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

自定义安装程序 Customizing Installers

您可以使用脚本通过以下方式自定义安装程序：

• 添加由脚本编译的Qt Installer Framework 操作，并由安装程序来执行。
• 在package.xml文件中指定添加的新页面，并存放到package目录中。
• 通过修改现有页面，将自定义的用户界面元素作为单个widgets小部件插入其中。
• 添加语言(variants)

您可以使用组件脚本(component scripts)和控制脚本(control script)来自定义安装程序。组件脚本在组件的package.xml文件的<Script>元素中指定，与特定组件相关联。在 获取组件的元数据时加载脚本 。有关组件脚本的更多信息，请参阅组件脚本Controller Scripting。

有关可在组件和控制脚本中使用的全局JavaScript对象的更多信息，请参阅Scripting API。

添加操作 Adding Operations

您可以使用组件脚本在安装过程中执行Qt Installer Framework操作。 通常，通过移动，复制或修补来操作文件。 使用QInstaller::Component::addOperation或QInstaller::Component::addElevatedOperation函数添加操作。 有关更多信息，请参阅向组件添加操作 Adding Operations to Components。

此外，您可以通过派生KDUpdater::UpdateOperation来实现在安装程序中注册自定义安装操作的方法。 有关详细信息，请参阅注册自定义操作 Registering Custom Operations。

有关可用操作的信息，请参阅操作Operations。

添加页面 Adding Pages

组件可以包含一个或多个用户界面文件，这些文件由组件或控制脚本放置到安装程序中(在安装程序执行时加载)。 安装程序将自动加载package.xml文件的UserInterfaces元素中列出的所有用户界面文件。

使用组件脚本添加页面 Using Component Scripts to Add Pages

要向安装程序添加新页面，请使用installer::addWizardPage()方法并指定新页面的位置。 例如，以下代码在 准备安装页面 之前添加了一个MyPage的实例：

installer.addWizardPage( component, "MyPage", QInstaller.ReadyForInstallation );

您可以使用组件脚本通过调用component::userInterface()方法访问加载的小部件的类名，如下面的代码段所示：

component.userInterface( "MyPage" ).checkbox.checked = true;

使用控制脚本添加页面 Using Control Scripts to Add Pages

要注册自定义页面，请使用installer::addWizardPage()方法和U并文件中设置的对象名称（例如“MyPage”）。 然后调用Dynamic${ObjectName}Callback()函数（例如，DynamicMyPageCallback()）：

function Controller()
{
    installer.addWizardPage(component, "MyPage", QInstaller.TargetDirectory)
}

Controller.prototype.DynamicMyPageCallback()
{
    var page = gui.pageWidgetByObjectName("DynamicMyPage");
    page.myButton.click,
    page.myWidget.subWidget.setText("hello")
}

您可以通过使用在UI文件中设置的对象名称来访问窗口小部件。 例如，在上面的代码中myButton和myWidget就是控件对象名称。

添加小部件 Adding Widgets

您可以使用组件或控制脚本将自定义用户界面元素作为单个窗口小部件（例如复选框）插入到安装程序中。

要插入单个窗口小部件，请使用installer::addWizardPageItem方法。 例如，以下代码片段从脚本中将MyWidget的实例添加到 组件选择页面 ：

installer.addWizardPageItem( component, "MyWidget", QInstaller.ComponentSelection );

与安装程序功能交互

例如，您可以使用控制脚本在测试中自动执行安装程序功能。 以下代码段说明如何自动单击目标目录选择页上的 下一步(Next) 按钮：

Controller.prototype.TargetDirectoryPageCallback = function()
{
    gui.clickButton(buttons.NextButton);
}

翻译页面 Translating Pages

安装程序使用Qt Translation系统支持将用户可读输出转换为多种语言。 要向最终用户提供组件脚本和用户界面中包含的字符串的 本地化版本 ，请创建随组件一起加载的QTranslator文件。 安装程序加载与当前系统区域设置匹配的翻译文件。 例如，如果系统语言环境是德语，则会加载de.qm文件。 此外，如果找到，将显示本地化license_de.txt而不是默认的license.txt。

需要将翻译添加到激活组件的package.xml文件中：

<Translations>
    <Translation>de.qm</Translation>
</Translations>

对脚本中的文本文本使用qsTr()函数。 此外，您可以将Component.prototype.retranslateUi方法添加到脚本。 当安装程序的语言更改并加载翻译文件时调用。

当在翻译用户界面时使用qsTr或UI文件的类名,用于翻译的上下文是脚本文件的基本名称。例如，如果脚本文件被称为installscript.qs，上下文将是installscript。

注意：翻译系统也可用于自定义UI。 使用例如一个en.ts文件作为自定义英语版本替换安装程序中的任何文本。