Qt安装程序框架指南
Qt安装程序框架指南
该文是主要介绍Qt安装程序框架使用。
Qt安装程序框架指南
1. 框架安装
QIF下载：https://download.qt.io/archive/qt-installer-framework/
选择最新版本安装即可。安装后设置环境变量。
2. 示例
在默认安装目录 C:\Qt\QtIFW-4.8.0\examples 中包含各种示例，以 startmenu 为示例解释。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
startmenu
| installer.exe
| README
| startmenu.pro
|
+---config
| config.xml
|
\---packages
\---org.qtproject.ifw.example
+---data
| README.txt
|
\---meta
installscript.qs
package.xml
进入目录，执行以下命令即可生成 YourInstaller.exe 安装程序。
1
binarycreator.exe -c config\config.xml -p packages YourInstaller.exe
默认安装界面如下：
3. 自定义安装程序
3.1. 配置文件
3.1.1. 示例
配置文件可自定义安装程序的用户界面和行为。 该文件通常称为 config.xml，位于 config 目录中。 一个最小的配置文件由
1
2
3
4
5
6
7
8
9
10
<?xml version="1.0" encoding="UTF-8"?>
<Installer>
<Name>测试程序</Name>
<Version>1.0.0</Version>
<Title>安装测试程序</Title>
<Publisher>com.vendor.root</Publisher>
<StartMenuDir>测试程序</StartMenuDir>
<TargetDir>@HomeDir@/qif_test</TargetDir>
<ControlScript>controller.qs</ControlScript>
</Installer>
值得注意的是控制器脚本 controller.qs。
3.1.2. 说明
下表总结了配置文件中的元素。
注意： 我们建议您将配置文件中引用的所有文件放在config目录中。 但是，您也可以使用相对路径，工具相对于config.xml文件的位置进行解析。
| 元素 | 是否必需 | 描述 |
|---|---|---|
| Name | 必需 | 正在安装的产品名称 |
| Version | 必需 | 安装软件的版本 |
| Title | 可选 | 标题栏上显示的安装程序的名称 |
| Publisher | 可选 | 软件发行商(如Windows控制面板中所示) |
| ProductUrl | 可选 | 指向包含您网站上产品信息的网页的网址 |
| InstallerApplicationIcon | 可选 | 自定义安装程序图标的文件名。 |
| InstallerWindowIcon | 可选 | 安装程序应用程序的自定义窗口图标的文件名(PNG格式) |
| Logo | 可选 | 用作QWizard::LogoPixmap的徽标的文件名 |
| Watermark | 可选 | 用作QWizard::WatermarkPixmap的水印的文件名 |
| Banner | 可选 | 用作QWizard::BannerPixmap(横幅)的文件名(仅由ModernStyle使用) |
| Background | 可选 | 用作QWizard::BackgroundPixmap的图像的文件名(仅由MacStyle使用) |
| WizardStyle | 可选 | 设置要使用的向导样式 (“Modern”(现代), “Mac”, “Aero”或”Classic”(经典)) |
| WizardDefaultWidth | 可选 | 设置向导的默认宽度（以像素为单位）。 |
| WizardDefaultHeight | 可选 | 设置向导的默认高度（以像素为单位）。 |
| WizardMinimumWidth | 可选 | 设置向导的最小宽度（以像素为单位）。 |
| WizardMinimumHeight | 可选 | 设置向导的最小高度（以像素为单位）。 |
| TitleColor | 可选 | 设置标题和字幕的颜色(采用HTML颜色代码，例如“＃88FF33”) |
| RunProgram | 可选 | 如果用户接受操作，则在安装程序完成后执行命令。要提供应用程序的完整路径 |
| RunProgramArguments | 可选 | 传递给<RunProgram>中指定的程序的参数。 |
| RunProgramDescription | 可选 | 安装后运行程序的复选框旁边显示的文本。 |
| StartMenuDir | 可选 | Windows开始菜单中产品的默认程序组名称 |
| TargetDir | 可选 | 安装的默认目标目录。在Linux上，这通常是用户的主目录(/home/username/) |
| AdminTargetDir | 可选 | 具有管理员权限的安装的默认目标目录。 |
| RemoteRepositories | 可选 | 远程存储库列表。 |
| MaintenanceToolName | 可选 | 生成的维护工具的文件名。默认为maintenancetool。 |
| MaintenanceToolIniFile | 可选 | 用于生成维护工具配置的文件名。默认为MaintenanceToolName.ini |
| RemoveTargetDir | 可选 | 如果卸载时不删除目标目录(TargetDir)，请设置为false |
| AllowNonAsciiCharacters | 可选 | 如果安装路径可以包含 非ASCII字符 ，请设置为true |
| RepositorySettingsPageVisible | 可选 | 设置为false来 隐藏 设置对话框中的 存储库设置页面 |
| AllowSpaceInPath | 可选 | 如果安装路径 不能包含空格字符 ，请设置为false |
| DependsOnLocalInstallerBinary | 可选 | 如果要禁止从外部资源(如网络驱动器)安装，请设置为true。 |
| TargetConfigurationFile | 可选 | 目标的配置文件名。默认是components.xml |
| Translations | 可选 | 用于翻译用户界面的语言代码列表。 |
| UrlQueryString | 可选 | 此字符串必须采用key = value形式，并且将附加到存档下载请求。 |
| ControlScript | 可选 | 自定义安装程序控制脚本的文件名。 |
| CreateLocalRepository | 可选 | 如果要在安装目录中 创建本地存储库 ，请设置为true。 |
3.2. 控制安装脚本controller.qs
3.2.1. 预定义安装程序页面
QInstaller JavaScript 对象提供对以下预定义安装程序页面的访问：
Introduction介绍TargetDirectory安装目录ComponentSelection组件选择LicenseCheck许可证检查StartMenuSelection开始菜单选择ReadyForInstallation准备安装PerformInstallation执行安装InstallationFinished安装完成
实现 Controller.prototype.{}PageCallback() 函数与目标目录选择页面上的窗口小部件交互。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
function Controller()
{
installer.autoRejectMessageBoxes;
installer.setMessageBoxAutomaticAnswer("OverwriteTargetDirectory", QMessageBox.Yes);
installer.setMessageBoxAutomaticAnswer("stopProcessesForUpdates", QMessageBox.Ignore);
}
Controller.prototype.IntroductionPageCallback = function()
{
}
Controller.prototype.ComponentSelectionPageCallback = function()
{
}
Controller.prototype.TargetDirectoryPageCallback = function()
{
}
Controller.prototype.LicenseAgreementPageCallback = function()
{
}
3.3. 包目录
3.4. 包目录结构
将所有组件放在同一根目录中，这称为包目录。目录名称用作 域标识符 ，其标识所有组件。例如 com.vendor.root。在根目录中，创建称data和meta子目录。
1
2
3
4
-packages
- com.vendor.root
- data
- meta
- 数据目录：数据目录包含安装程序在安装过程中提取的内容。 数据必须打包成归档文件。
- 元信息目录：元目录包含指定部署和安装过程设置的文件。 安装程序不会提取这些文件。 该目录必须至少包含一个软件包信息文件和软件包信息文件中提到的所有文件，如脚本、用户界面文件和翻译。
注意：如果安装程序框架工具是在不支持 libarchive 的情况下构建的，则只支持 7z 格式。
3.4.1. 示例
读取同目录下的 LICENSE 协议显示，以及安装脚本 installscript.qs。
1
2
3
4
5
6
7
8
9
10
11
12
<?xml version="1.0"?>
<Package>
<DisplayName>Root Component</DisplayName>
<Description>This component handles the errors in the other components.</Description>
<Version>1.0.1</Version>
<ReleaseDate>2024-08-12</ReleaseDate>
<Licenses>
<License name="License Agreement" file="LICENSE" />
</Licenses>
<Default>true</Default>
<Script>installscript.qs</Script>
</Package>
3.4.2. 说明
| 元素 | 是否必需 | 描述 |
|---|---|---|
| DisplayName | 必需 | 组件的可读名称 |
| Description | 必需 | 组件的可读描述。 |
| Version | 必需 | 组件的版本号 |
| ReleaseDate | 必需 | 此组件版本发布的日期 |
| Name | 必需（？） | 此组件的域标识 |
| Dependencies | 可选 | 此组件依赖的组件的标识符列表(使用逗号分割)。 |
| AutoDependOn | 可选 | 此组件具有自动依赖性的组件的标识符列表(逗号分隔)。 |
| Virtual | 可选 | 设置为true可从安装程序中隐藏组件。 |
| SortingPriority | 可选 | 组件在组件树中的优先级。 |
| Licenses | 可选 | 安装用户接受的许可协议列表。 |
| Script | 可选 | 被加载的脚本文件名。 |
| UserInterfaces | 可选 | 要加载的页面列表。 |
| Translations | 可选 | 要加载的翻译文件的列表。 |
| UpdateText | 可选 | 如果这是一个更新组件，则将说明添加到组件描述中 |
| Default | 可选 | 可以设置为true、false、脚本名。 |
| Essential | 可选 | 将包标记为必须去强制重启MaintenanceTool程序的。 |
| ForcedInstallation | 可选 | 确定必须安装的包。 最终用户无法在安装程序中取消选择它 |
| Replaces | 可选 | 要替换的组件列表(逗号分隔) |
| DownloadableArchives | 可选 | 列出数据文件(逗号分隔)，供在线安装程序下载。 |
| RequiresAdminRights | 可选 | 如果程序包需要提升权限进行安装，请设置为true |
3.5. 组件脚本installscript.qs
对于每个组件，您可以准备一个脚本来指定由安装程序执行的操作。脚本必须包含安装程序在 加载脚本时 创建的Component对象。
以下代码片段将ErrorPage（它是从errorpage.ui加载的用户界面文件的类名）放在 准备安装页面 的前面，并将其完整性设置为false。
1
2
3
4
5
6
function Component()
{
// Add a user interface file called ErrorPage, which should not be complete
installer.addWizardPage( component, "ErrorPage", QInstaller.ReadyForInstallation );
component.userInterface( "ErrorPage" ).complete = false;
}
3.5.1. 自定义组件操作
例如，您可能需要在解压缩内容后，在复制文件或修补文件内容时添加自定义操作。 您可以使用component::addOperation()从脚本中创建和添加更新操作到安装。 如果需要运行需要管理权限的操作，请改用component::addElevatedOperation()。
操作需要在实际安装步骤之前添加。 重写component::createOperations()来注册组件的自定义操作。
每个操作都有一个用于识别的唯一键，最多可以占用五个参数。在参数值中，可以使用在installer::setValue()中设置的变量。
3.5.2. 预定义变量
| 名称 | 描述 |
|---|---|
| ProductName | 要安装的产品的名称，在config.xml中定义的 |
| ProductVersion | 要安装的产品的版本号，在config.xml中所定义 |
| Title | 安装程序的标题，在config.xml中定义 |
| Publisher | 安装程序的发布者，如config.xml中所定义 |
| Url | 产品URL，如config.xml中所定义 |
| StartMenuDir | 开始菜单组，如config.xml中所定义。 仅在Windows上可用 |
| TargetDir | 目标安装目录，由用户选择 |
| DesktopDir | 用户桌面目录名(路径)。 仅在Windows上可用 |
| os | 当前平台:”X11”,”Win”或”Mac”。 不建议使用此变量：请改用systemInfo |
| RootDir | 文件系统根目录 |
| HomeDir | 当前用户的home目录 |
| ApplicationsDir | 应用程序目录。 |
| InstallerDirPath | 包含安装程序可执行文件的目录 |
| InstallerFilePath | 安装程序可执行文件的文件路径 |
| UserStartMenuProgramsPath | 包含在(当前)用户的开始菜单中的项目文件夹的路径。 仅在Windows上可用 |
| AllUsersStartMenuProgramsPath | 包含在所有用户的开始菜单中的项目文件夹的路径。仅在Windows上可用 |
例如，在 Windows 上应用程序目录如下：
| OS (Windows) | Qt Installer Framework | Variable | Example Path |
|---|---|---|---|
| 32bit | 32bit | ApplicationsDir | C:\Program Files |
| ApplicationsDirX86 | C:\Program Files | ||
| ApplicationsDirX64 | C:\Program Files | ||
| 64bit | 32bit | ApplicationsDir | C:\Program Files (x86) |
| ApplicationsDirX86 | C:\Program Files (x86) | ||
| ApplicationsDirX64 | C:\Program Files | ||
| 64bit | ApplicationsDir | C:\Program Files | |
| ApplicationsDirX86 | C:\Program Files (x86) | ||
| ApplicationsDirX64 | C:\Program Files |
3.5.3. 操作概要
3.5.3.1. 操作类型
| Operation | 语法 | 用法 |
|---|---|---|
| Copy | “Copy” source target | 从source复制一个文件到target |
| Move | “Move” source target | 从source移动一个文件到target |
| SimpleMoveFile | “SimpleMoveFile” source target | 从source移动一个文件到target |
| Delete | “Delete” filename | 删除filename.指定的文件 |
| Mkdir | “Mkdir” path | 创建path目录 |
| Rmdir | “Rmdir” path | 删除path目录 |
| CopyDirectory | “CopyDirectory” sourcePath targetPath | 复制sourcePath目录到targetPath |
| AppendFile | “AppendFile” filename text | 将text追加到filename指定的文件。text被视为ASCII文本 |
| PrependFile | “PrependFile” filename text | 将text添加到filename指定的文件。text被视为ASCII文本 |
| Replace | “Replace” file search replace | 打开文件去查找search字符串，并替换为replace字符串 |
| LineReplace | “LineReplace” file search replace | 打开文件以查找以search字符串开头的行，并用replace字符串替换它。 |
| Execute | “Execute” [{exitcodes}] command [parameter1 [parameter… [parameter10]]] | 执行命令指定的命令。 最多可以传递10个参数。 |
| CreateShortcut | “CreateShortcut” filename linkname [arguments] | 为filename指定的文件创建一个名为linkname的快捷方式。 |
| CreateDesktopEntry | “CreateDesktopEntry” filename “key=value[ key2=value2[ key3=value3]]]” | 创建一个.desktop初始化文件， |
| InstallIcons | “InstallIcons” directory [Vendorprefix] | 将目录的内容安装到由freedesktop.org指定的位置。 |
| Extract | “Extract” archive targetdirectory | 提前archive内容到targetdirectory |
| GlobalConfig | “GlobalConfig” company application key value | 在配置文件中存储键的值。 |
| EnvironmentVariable | “EnvironmentVariable” key value [persistent [system]] | 设置环境变量key为value 如果persistent设置为true，那么将永久设置该变量。 |
| RegisterFileType | “RegisterFileType” extension command [description [contentType [icon]]] | 注册要通过命令打开的扩展名的文件类型。 |
| ConsumeOutput | “ConsumeOutput” installerKeyName executablePath processArguments | 保存运行带有参数processArguments的executablePath的可执行文件的输出到installerKeyName指定的安装程序键。 |
| CreateLink | “CreateLink” linkPath targetPath | 创建从linkPath指定的位置到由targetPath指定的位置的链接 |
| CreateLocalRepository | “CreateLocalRepository” binaryPath repoPath | 创建一个本地存储库在repoPath指定的目录。 |
| FakeStopProcessForUpdate | “FakeStopProcessForUpdate” processlist | 在卸载期间匹配运行进程与processlist中的条目(逗号分隔)。 |
| License | “License” licenses | 将licenses指定的许可证文件复制到目标目录中名为Licenses的子文件夹。 |
| MinimumProgress | “MinimumProgress” | 将进度值增加1 |
| SelfRestart | “SelfRestart” core | 重新启动由core指定的updater或软件包管理器 |
| Settings | “Settings” path method key aValue | 设置或删除位于path的settings文件或注册表中key的值aValue |
3.5.3.2. 示例
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
function Component()
{
if(!installer.isCommandLineInstance())
{
gui.pageWidgetByObjectName("LicenseAgreementPage").entered.connect(changeLicenseLabels);
installer.setDefaultPageVisible(QInstaller.Introduction, false);
installer.setDefaultPageVisible(QInstaller.TargetDirectory, false);
installer.setDefaultPageVisible(QInstaller.ComponentSelection, false);
installer.setDefaultPageVisible(QInstaller.LicenseCheck, true);
installer.setDefaultPageVisible(QInstaller.ReadyForInstallation, false);
installer.setDefaultPageVisible(QInstaller.StartMenuSelection, false);
installer.setDefaultPageVisible(QInstaller.PerformInstallation, true);
}
}
Component.prototype.createOperations = function()
{
component.createOperations();
if(systemInfo.productType === "windows")
{
component.addOperation("EnvironmentVariable", "TEST_HOME", "@ApplicationsDirX86@\\test\\", true, true);
component.addOperation("Execute", "@RootDir@\\windows\\system32\\reg.exe", "add", "HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Policies\\System", "/v", "PromptOnSecureDesktop", "/t", "REG_DWORD", "/d", "0", "/f");
}
}
参考
本文由作者按照 CC BY 4.0 进行授权