CPack WIX 生成器¶

使用 WiX 工具集生成 Windows Installer .msi 数据库。

在 3.7 版本中新增：变量 CPACK_COMPONENT_<compName>_DISABLED 现在受支持。

WiX 工具集¶

CPack 根据 CPACK_WIX_VERSION 变量选择以下 WiX 工具集变体之一

WiX .NET 工具
WiX 工具集 v3

WiX .NET 工具¶

使用以下工具执行打包

wix build

将 WiX 源文件直接构建到 Windows Installer .msi 数据库。

可以使用特定于工具的变量来自定义调用

CPACK_WIX_BUILD_EXTENSIONS
CPACK_WIX_BUILD_EXTRA_FLAGS

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 工具集 v3¶

使用以下工具执行打包

candle

将 WiX 源文件编译为 .wixobj 文件。

可以使用特定于工具的变量来自定义调用

CPACK_WIX_CANDLE_EXTENSIONS
CPACK_WIX_CANDLE_EXTRA_FLAGS

light

将 .wixobj 文件链接到 Windows Installer .msi 数据库。

可以使用特定于工具的变量来自定义调用

CPACK_WIX_LIGHT_EXTENSIONS
CPACK_WIX_LIGHT_EXTRA_FLAGS

CPack 按需调用这两个工具。中间 .wixobj 文件被视为实现细节。

WiX 扩展必须命名为 Wix<Name>Extension 形式。

CPack 预期上述工具可通过 PATH 命令行使用。或者，如果设置了 WIX 环境变量，CPack 会在 %WIX% 和 %WIX%\bin 中查找工具。

特定于 CPack WIX 生成器的变量¶

下列变量特定于在 Windows 上使用 WiX 构建的安装程序。

CPACK_WIX_VERSION¶

3.30 版中添加。

指定 WiX 工具集的版本，为此编写了配置。值必须是以下之一

4: 使用 WiX .NET 工具的软件包。
3: 使用 WiX 工具集 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_WIX_LICENSE_RTF 时，在 CPACK_RESOURCE_FILE_LICENSE 格式不受支持或 .txt -> .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://wixtoolset.org/docs/v3/wixui/wixui_localization/

CPACK_WIX_TEMPLATE¶

用于 WiX 生成的模板文件

如果设置此变量，则将使用指定的模板生成 WiX wxs 文件。如果需要进一步自定义输出，则应使用此方法。模板内容会覆盖大多数 CPACK_WIX_ 变量的影响。

如果未设置此变量，则将使用 CMake 包含的默认 MSI 模板。

CPACK_WIX_PATCH_FILE¶

可插入到生成的 WiX 源中的片段的 XML 文件的可选列表。

在版本 3.5 中新增：支持列出多个 patch 文件。

此可选变量可用于指定一个 XML 文件，WIX 生成器将使用该文件将其片段注入其生成的源文件。

CPack WIX 生成器理解的 patch 文件大致遵循此 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 patch 文件将 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_EXTENSIONS¶: 为 WiX 工具指定附加扩展列表。请参见 WiX 工具集，了解扩展命名模式。

CPACK_WIX_<TOOL>_EXTENSIONS¶: 为特定 WiX 工具指定附加扩展列表。请参见 WiX 工具集，了解可能的 <TOOL> 名称。

CPACK_WIX_<TOOL>_EXTRA_FLAGS¶

为特定 WiX 工具指定附加命令行标志的列表。请参见 WiX 工具集，了解可能的 <TOOL> 名称。

使用时风险自负。未来版本的 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 - 帮助和支持信息网址
ARPURLINFOABOUT - 常规信息网址
ARPURLUPDATEINFO - 更新信息网址
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。可用用于 32 位和 64 位变量的生成器特定 <64> 令牌。在 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://wixtoolset.org/docs/v3/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，后一个安装程序应与指示手动卸载所有旧版本的说明一起发布。

请参见 https://wixtoolset.org/docs/v3/xsd/wix/package/

CPack WIX 生成器¶

WiX 工具集¶

WiX .NET 工具¶

WiX 工具集 v3¶

特定于 CPack WIX 生成器的变量¶

目录

前一个主题

下一个主题

此页面