CPack WIX 生成器¶
使用 WiX Toolset 生成 Windows Installer .msi
数据库。
版本 3.7 新增:现在支持 CPACK_COMPONENT_<compName>_DISABLED
变量。
WiX 工具集¶
CPack 根据 CPACK_WIX_VERSION
变量选择以下 WiX 工具集变体之一
WiX .NET 工具¶
打包使用以下工具进行
wix build
直接将 WiX 源文件构建为 Windows Installer
.msi
数据库。可以使用工具特定变量自定义调用
WiX 扩展名必须是 WixToolset.<Name>.wixext
形式。
CPack 期望 wix
.NET 工具可用于命令行使用,并已安装所有必需的 WiX 扩展。确保 wix
版本与 CPACK_WIX_VERSION
兼容,并且 WiX 扩展版本与 wix
工具版本匹配。例如
使用
dotnet
安装wix
命令行工具。
为当前用户全局安装
wix
dotnet tool install --global wix --version 4.0.4这会将
wix.exe
放在%USERPROFILE%\.dotnet\tools
中,并将该目录添加到当前用户的PATH
环境变量中。或者,要在特定路径安装
wix
,例如在c:\WiX
中dotnet tool install --tool-path c:\WiX wix --version 4.0.4这会将
wix.exe
放在c:\WiX
中,但不会将其添加到当前用户的PATH
环境变量中。可以设置WIX
环境变量以告诉 CPack 在哪里找到该工具,例如set WIX=c:\WiX
。
添加 WiX
UI
扩展,CPack 的默认 WiX 模板需要它
wix extension add --global WixToolset.UI.wixext/4.0.4全局添加的扩展存储在
%USERPROFILE%\.wix
中,或者如果设置了WIX_EXTENSIONS
环境变量,则存储在%WIX_EXTENSIONS%\.wix
中。
WiX Toolset v3¶
打包使用以下工具进行
candle
将 WiX 源文件编译为
.wixobj
文件。可以使用工具特定变量自定义调用
light
将
.wixobj
文件链接到 Windows Installer.msi
数据库中。可以使用工具特定变量自定义调用
CPack 根据需要调用这两个工具。中间的 .wixobj
文件被视为实现细节。
WiX 扩展名必须是 Wix<Name>Extension
形式。
CPack 期望上述工具通过 PATH
可用于命令行使用。或者,如果设置了 WIX
环境变量,CPack 会在 %WIX%
和 %WIX%\bin
中查找工具。
CPack WIX 生成器特有的变量¶
以下变量是使用 WiX 在 Windows 上构建的安装程序特有的。
- CPACK_WIX_VERSION¶
3.30 版本新增。
指定配置所写入的 WiX Toolset 版本。值必须是以下之一
4
使用 WiX .NET 工具打包。
3
使用 WiX Toolset v3 打包。这是默认值。
- CPACK_WIX_UPGRADE_GUID¶
升级 GUID (
Product/@UpgradeCode
)除非明确提供,否则将自动生成。
应将其明确设置为一个常量生成的全局唯一标识符 (GUID),以允许安装程序替换使用相同 GUID 的现有安装。
例如,您可以在 CMakeLists.txt 中将此变量显式设置为默认生成的值。您不应使用您自己未生成或可能属于其他项目的 GUID。
GUID 应具有以下固定长度语法
XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
(每个 X 代表一个大写十六进制数字)
- CPACK_WIX_PRODUCT_GUID¶
产品 GUID (
Product/@Id
)除非明确提供,否则将自动生成。
如果明确提供,这将设置安装程序的产品 ID。
如果安装程序检测到使用相同 GUID 的预安装,则会中止。
GUID 应使用为 CPACK_WIX_UPGRADE_GUID 描述的语法。
- CPACK_WIX_LICENSE_RTF¶
RTF 许可证文件
如果 CPACK_RESOURCE_FILE_LICENSE 具有 .rtf 扩展名,则按原样使用。
如果 CPACK_RESOURCE_FILE_LICENSE 具有 .txt 扩展名,则 WIX 生成器会将其隐式转换为 RTF。预期 .txt 文件的编码为 UTF-8。
如果 CPACK_RESOURCE_FILE_LICENSE 格式不受支持或 .txt -> .rtf 转换未按预期工作,您可以使用 CPACK_WIX_LICENSE_RTF 覆盖 WIX 生成器使用的许可证文件。
- CPACK_WIX_PRODUCT_ICON¶
在“添加/删除程序”中程序名称旁边显示的图标。
如果设置,此图标将替换默认图标。
- CPACK_WIX_UI_REF¶
指定 WiX
UI
扩展的对话框集对于 WiX .NET 工具,这是默认 WiX 模板中
<ui:WixUI>
元素的 Id。对于 WiX Toolset v3,这是默认 WiX 模板中
<UIRef>
元素的 Id。
如果未定义 CPack 组件,则默认值为
WixUI_InstallDir
,否则为WixUI_FeatureTree
。
- CPACK_WIX_UI_BANNER¶
位图将出现在除欢迎和完成对话框之外的所有安装程序页面的顶部。
如果设置,此图像将替换默认横幅图像。
此图像必须为 493 x 58 像素。
- CPACK_WIX_UI_DIALOG¶
欢迎和完成对话框上使用的背景位图。
如果设置此变量,安装程序将替换默认对话框图像。
此图像必须为 493 x 312 像素。
- CPACK_WIX_PROGRAM_MENU_FOLDER¶
启动器在“开始”菜单中的文件夹名称。
如果未设置此变量,则将其初始化为 CPACK_PACKAGE_NAME。
版本 3.16 新增:如果此变量设置为
.
,则应用程序快捷方式将直接在“开始”菜单中创建,并省略卸载程序快捷方式。
- CPACK_WIX_CULTURES¶
安装程序的语言
语言被编译到 Wix
UI
扩展库中。要使用它们,只需提供文化的名称。如果您在逗号或分号分隔列表中指定多个文化标识符,则将使用第一个找到的标识符。您可以在以下位置找到支持的语言列表:https://docs.firegiant.com/wix3/wixui/wixui_localization/
- CPACK_WIX_TEMPLATE¶
WiX 生成的模板文件
如果设置此变量,则将使用指定的模板生成 WiX wxs 文件。如果需要进一步自定义输出,则应使用此变量。模板内容将覆盖大多数
CPACK_WIX_
变量的效果。如果未设置此变量,将使用 CMake 中包含的默认 MSI 模板。
- CPACK_WIX_PATCH_FILE¶
可选的 XML 文件列表,其中包含要插入到生成的 WiX 源中的片段。
版本 3.5 新增:支持列出多个补丁文件。
此可选变量可用于指定 WIX 生成器将用于向其生成的源文件注入片段的 XML 文件。
CPack WIX 生成器理解的补丁文件大致遵循此 RELAX NG 紧凑模式
start = CPackWiXPatch CPackWiXPatch = element CPackWiXPatch { CPackWiXFragment* } CPackWiXFragment = element CPackWiXFragment { attribute Id { string }, fragmentContent* } fragmentContent = element * - CPackWiXFragment { (attribute * { text } | text | fragmentContent)* }
目前,片段可以注入到大多数 Component、File、Directory 和 Feature 元素中。
版本 3.3 新增:可以使用以下附加特殊 ID
#PRODUCT
用于<Product>
元素。#PRODUCTFEATURE
用于根<Feature>
元素。
版本 3.7 新增:支持修补任意
<Feature>
元素。版本 3.9 新增:允许设置附加属性。
以下示例说明了这是如何工作的。
鉴于 WIX 生成器创建以下 XML 元素
<Component Id="CM_CP_applications.bin.my_libapp.exe" Guid="*"/>
以下 XML 补丁文件可用于向其中注入 Environment 元素
<CPackWiXPatch> <CPackWiXFragment Id="CM_CP_applications.bin.my_libapp.exe"> <Environment Id="MyEnvironment" Action="set" Name="MyVariableName" Value="MyVariableValue"/> </CPackWiXFragment> </CPackWiXPatch>
- CPACK_WIX_EXTRA_SOURCES¶
额外的 WiX 源文件
此变量提供了一个可选的额外 WiX 源文件 (
.wxs
) 列表,这些文件应被编译和链接。路径必须是绝对路径。
- CPACK_WIX_EXTRA_OBJECTS¶
与 WiX Toolset v3 一起使用的额外 WiX 对象文件或库。
此变量提供了一个可选的额外 WiX 对象 (
.wixobj
) 和/或 WiX 库 (.wixlib
) 文件列表。路径必须是绝对路径。
- CPACK_WIX_<TOOL>_EXTRA_FLAGS¶
为特定的 WiX 工具指定附加命令行标志列表。有关可能的
<TOOL>
名称,请参阅 WiX 工具集。使用风险自负。CPack 的未来版本可能会生成与您自己的标志冲突的标志。
- CPACK_WIX_CMAKE_PACKAGE_REGISTRY¶
如果设置了此变量,生成的安装程序将在 Windows 注册表键
HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<PackageName>
中创建一个条目。<PackageName>
的值由此变量提供。假设您也安装了 CMake 配置文件,这将允许其他 CMake 项目使用
find_package()
命令查找您的包。
- CPACK_WIX_PROPERTY_<PROPERTY>¶
版本 3.1 中新增。
此变量可用于为 Windows Installer 属性
<PROPERTY>
提供值以下列表包含一些可用于自定义“程序和功能”(也称为“添加或删除程序”)下信息的示例属性
ARPCOMMENTS - 注释
ARPHELPLINK - 帮助和支持信息 URL
ARPURLINFOABOUT - 一般信息 URL
ARPURLUPDATEINFO - 更新信息 URL
ARPHELPTELEPHONE - 帮助和支持电话号码
ARPSIZE - 应用程序大小(千字节)
- CPACK_WIX_ROOT_FEATURE_TITLE¶
3.7 版本中新增。
设置 WIX 安装程序中根安装功能的名称。与组件的 CPACK_COMPONENT_<compName>_DISPLAY_NAME 相同。
- CPACK_WIX_ROOT_FEATURE_DESCRIPTION¶
3.7 版本中新增。
设置 WIX 安装程序中根安装功能的描述。与组件的 CPACK_COMPONENT_<compName>_DESCRIPTION 相同。
- CPACK_WIX_SKIP_PROGRAM_FOLDER¶
3.7 版本中新增。
如果此变量设置为 true,则生成的包的默认安装位置将直接为 CPACK_PACKAGE_INSTALL_DIRECTORY。安装位置将不会位于 ProgramFiles 或 ProgramFiles64 下。
注意
使用此功能创建的安装程序不会考虑创建安装程序的系统与使用安装程序的系统之间的差异。
因此,安装程序可能会尝试安装到不可用或非预期的驱动器,或者不遵循执行安装的系统的本地化或约定的路径。
- CPACK_WIX_ROOT_FOLDER_ID¶
版本 3.9 中添加。
此变量允许指定自定义根文件夹 ID。生成器特定的
<64>
令牌可用于具有 32 位和 64 位变体的文件夹 ID。在 32 位构建中,令牌将扩展为空,而在 64 位构建中,它将扩展为64
。当未设置时,生成的安装程序将默认安装到
ProgramFiles<64>Folder
。
- CPACK_WIX_ROOT¶
此变量可选择设置为自定义 WiX Toolset 安装的根目录。
未指定时,CPack 将尝试通过
WIX
环境变量定位 WiX Toolset 安装。
- CPACK_WIX_CUSTOM_XMLNS¶
3.19 版本新增。
此变量提供了一个自定义命名空间声明列表,这些声明对于使用 WiX 扩展是必需的。每个声明都应采用 name=url 的形式,其中 name 是不带通常的 xmlns: 前缀的纯命名空间,url 是未加引号的命名空间 url。常用的 WiX 模式列表可以在这里找到:https://docs.firegiant.com/wix3/xsd/
- CPACK_WIX_SKIP_WIX_UI_EXTENSION¶
在版本 3.23 中添加。
如果此变量设置为 true,则跳过默认包含 WiX
UI
扩展,即,不会将-ext WixUIExtension
或-ext WixToolset.UI.wixext
标志传递给 WiX 工具。
- CPACK_WIX_ARCHITECTURE¶
在 3.24 版本中添加。
此变量可选择用于指定安装程序的目标架构。例如,可设置为
x64
或arm64
。未指定时,CPack 将默认为
x64
或x86
。
- CPACK_WIX_INSTALL_SCOPE¶
在版本 3.29 中添加。
此变量可选择用于指定安装程序的
InstallScope
perMachine
创建一个安装程序,该安装程序安装到所有用户并需要管理员权限。安装程序创建的开始菜单条目对所有用户可见。
这是默认值。请参阅策略
CMP0172
。perUser
尚未支持。此项保留供将来使用。
NONE
创建一个没有
InstallScope
属性的安装程序。仅当未设置
CPACK_WIX_VERSION
,或将其设置为3
时才支持此项。自 3.29 版起已弃用:此值仅用于与 CPack 3.28 及更旧版本使用的不一致行为兼容。生成的安装程序需要管理员权限并安装到系统范围的
ProgramFiles
目录,但开始菜单条目和卸载程序注册仅为当前用户创建。警告
由未设置
InstallScope
的安装程序执行的安装无法被具有InstallScope
的安装程序干净地更新或替换。为了将项目的安装程序从NONE
转换为perMachine
,后者的安装程序应与说明一起分发,以便首先手动卸载任何旧版本。