CPack WIX 生成器¶

使用 WiX Toolset 来生成 Windows 安装程序 .msi 数据库。

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

WiX 工具集¶

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

WiX .NET 工具
WiX 工具集 v3

WiX .NET 工具¶

使用以下工具执行打包

wix build

将 WiX 源文件直接构建为 Windows 安装程序 .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。

添加 CPack 默认 WiX 模板所需的 WiX UI 扩展

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 安装程序 .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。

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 工具集 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 版本新增: 支持列出多个补丁文件。

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

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 工具集 v3 一起使用的额外 WiX 对象文件或库。

此变量提供了一个可选的额外 WiX 对象 (.wixobj) 和/或 WiX 库 (.wixlib) 文件列表。路径必须是绝对路径。

CPACK_WIX_EXTENSIONS¶: 指定 WiX 工具的额外扩展列表。有关扩展命名模式，请参阅 WiX 工具集。

CPACK_WIX_<TOOL>_EXTENSIONS¶: 指定特定 WiX 工具的额外扩展列表。有关可能的 <TOOL> 名称，请参阅 WiX 工具集。

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 安装程序属性 <PROPERTY> 提供值

以下列表包含一些可用于自定义“程序和功能”（也称为“添加或删除程序”）下信息的示例属性

ARPCOMMENTS - 注释
ARPHELPLINK - 帮助和支持信息 URL
ARPURLINFOABOUT - 一般信息 URL
ARPURLUPDATEINFO - 更新信息 URL
ARPHELPTELEPHONE - 帮助和支持电话号码
ARPSIZE - 应用程序的大小（以 KB 为单位）

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。

当未设置时，如果 CPACK_WIX_INSTALL_SCOPE 为 perUser，生成的安装程序将安装到 LocalAppDataFolder，否则将安装到 ProgramFiles<64>Folder。

CPACK_WIX_ROOT¶

此变量可选择设置为自定义 WiX 工具集安装的根目录。

当未指定时，CPack 将尝试通过 WIX 环境变量定位 WiX 工具集安装。

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（请参阅 https://docs.firegiant.com/wix3/xsd/wix/package/）

perMachine

创建为所有用户安装并需要管理权限的安装程序。安装程序创建的开始菜单条目对所有用户可见。

这是默认值。请参阅策略 CMP0172。

perUser

创建仅为当前用户安装且不需要管理权限的安装程序。安装程序创建的开始菜单条目仅对当前用户可见。

要启用按用户安装，安装程序必须生成一些额外的注册表条目，作为已安装组件的“关键路径”（请参阅 https://learn.microsoft.com/en-us/windows/win32/msi/ice38）。这些注册表条目是在 HKEY_CURRENT_USER 下创建的，使用 CPACK_WIX_COMPONENT_KEYS_REGISTRY_PATH 变量指定的路径。

4.3 版本更改: 在 CMake 4.3 之前，此值保留供将来使用且不受支持。

NONE

创建一个没有任何 InstallScope 属性的安装程序。

仅当 CPACK_WIX_VERSION 未设置或设置为 3 时才支持此项。

3.29 版本弃用: 此值仅为了与 CPack 3.28 及更早版本使用的一致性行为保持兼容。生成的安装程序需要管理权限并安装到系统范围的 ProgramFiles 目录中，但开始菜单条目和卸载程序注册仅为当前用户创建。

警告

使用不同 InstallScope 值创建的安装程序无法被彼此干净地更新或替换。例如，要将项目的安装程序从 NONE 转换为 perMachine，或从 perMachine 转换为 perUser，应分发较新的安装程序并附带说明，要求用户先手动卸载任何旧版本。

CPACK_WIX_COMPONENT_KEYS_REGISTRY_PATH¶

Added in version 4.3.

如果 CPACK_WIX_INSTALL_SCOPE 设置为 perUser，此变量确定安装程序将在 HKEY_CURRENT_USER 下创建注册表条目以作为组件“关键路径”的注册表路径。

使用正斜杠 (/) 作为路径分隔符以避免转义问题；它们将由 WIX 生成器转换为反斜杠 (\)。

默认值为 Software/<Vendor>/<PackageName>/Components，其中 <Vendor> 取自 CPACK_PACKAGE_VENDOR，<PackageName> 取自 CPACK_PACKAGE_NAME。

示例： Software/MyCompany/MyProduct/Components

CPACK_WIX_CAB_PER_COMPONENT¶

版本 4.2 中添加。

如果将此变量设置为 true，则会为每个组件创建一个 .cab 文件。默认情况是为安装程序中的所有文件创建一个 .cab 文件。

WiX 会并行创建 .cab 文件，因此为了更快的打包速度，多个 .cab 文件可能是理想的。

CPack WIX 生成器¶

WiX 工具集¶

WiX .NET 工具¶

WiX 工具集 v3¶

CPack WIX 生成器特定的变量¶

目录

上一主题

下一主题

本页