在主机 GDK 中使用 Clang/LLVM - XBOX Game Development Documentation

你可以使用 Clang/LLVM 结合 Visual Studio 2019、Visual Studio 2022 或 Visual Studio 2026 以及 clang/LLVM for Windows 工具集 v12 或更高版本开发 Microsoft Game Development Kit (GDK) 游戏。此工具集使用 Visual C/C++ 运行时（Universal CRT 库 + Microsoft STL）。其他工具集与运行时的组合可能无法成功运行或通过游戏认证。结合 LLVM (clang-cl)（即 ClangCL）平台工具集使用的 Clang/LLVM for Windows 使用 Microsoft Standard C++ Library。

Clang 版本	Visual Studio 更新
clang v12	Visual Studio 2019 (16.11)
clang v18.1.8	Visual Studio 2022 (17.12)
clang v19.1.5	Visual Studio 2022 (17.14)
clang v20.1.8	Visual Studio 2026 (18.0)

所需的 Visual Studio 版本与组件

要在 GDK 中使用 Clang/LLVM，需要 Visual Studio 16.11 或更高版本。在安装 Visual Studio 时，请在 单个组件 下选择 C++ Clang Compiler for Windows 组件。根据你使用的 Visual Studio 版本，所需的 Clang/LLVM 组件的名称可能是 C++ Clang Compiler for Windows 与 C++ Clang-cl for v142 build tools (x64/x86)。

如果在安装 GDK 之后修改了现有的 Visual Studio 安装以添加 C++ Clang Compiler for Windows，则在使用 Clang/LLVM 之前，需要修复 GDK 安装。

如果安装了 C++ Clang Compiler for Windows 组件，GDK 安装程序会为 Gaming.Xbox.*.x64 平台安装 ClangCl 平台工具集的支持。

编译器与链接器开关

对于 Gaming.Xbox.*.x64 平台，与 clang-cl.exe 一起使用的 clang/LLVM 命令行始终包含以下参数：

  -Wno-c++98-compat -Wno-c++98-compat-pedantic -Wno-reserved-id-macro
  -Wno-pragma-pack -Wno-unknown-pragmas
  -Wno-unused-command-line-argument

对于 Gaming.Xbox.Scarlett.x64，还会加上 -march=znver2。此开关会启用 AVX2 以及 Hercules CPU 特有的一些其他功能。对于 Gaming.Xbox.XboxOne.x64，还会加上 -march=btver2。此开关会启用 AVX、F16C 以及 Jaguar CPU 特有的一些其他功能。有关为 GDK 开发推荐的开关的更多信息，请参阅 Visual C++ 编译器与链接器开关建议。

支持的 CPU 内在函数

Clang/LLVM 与 GNUC 处理 SSE SIMD 类型的方式与 Visual C++ 及 Intel 编译器不同。具体而言，__m128、__m128i 和 __m128d 类型是不透明类型而非结构体，因此你不能创建使用这些类型的 C++ 重载函数。这一差异还意味着通过 __m128.m128_f32[] 进行直接元素访问在 clang 上无法编译。对于 Clang/LLVM 上的 DirectXMath，这一差异导致所有 XMVECTOR 的 C++ 重载都被禁用。为了提高可移植性，你也可以在 Visual C++ 上选择加入此行为，方法是在包含 DirectXMath 头文件之前定义预处理器符号 XM_NO_XMVECTOR_OVERLOADS。 Visual C++ 允许在没有当前使用 /arch:AVX 或 /arch:AVX2 构建的情况下使用高级指令内在函数，但 clang/LLVM 在这种情形下若没有正确的编译器开关就无法构建。使用 Clang/LLVM 时，必须添加 -march=btver2、-march=znver1、-march=znver2 或 -mf16c 编译器开关，才能使用 F16C 半精度转换内在函数 _mm_cvtph_ps 或 _mm_cvtps_ph。 Windows 10 SDK (18363) 及更早版本中的 DirectXMath 使用了错误的 CPUID 内在函数来为 Clang/LLVM 实现 XMVerifyCPUSupport。此问题已在 Windows 10 SDK (19041) 或更高版本中的 DirectXMath 3.14 中修复。

https://walbourn.github.io/directxmath-3.14/

将 Clang/LLVM 与 msbuild 一起使用

要将 Clang/LLVM 用于 msbuild 项目，请将 平台工具集 设置为 “LLVM (clang-cl)”。你可以在 Visual C++ 项目属性对话框中的常规选项卡下找到 平台工具集，如下图所示。也可以直接将 PlatformToolset msbuild 属性设置为 ClangCl 来设置 Clang/LLVM 工具集，如下例所示。


<PlatformToolset>ClangCl</PlatformToolset>

默认情况下，与 MSVC 相比，Clang/LLVM 编译器会生成显著更多的信息性警告。因此，对于 ‘TODO’ 位置，你会同时看到作为警告输出的 -W#pragma-messages 和 -Wunused-value 警告：

1>Game.cpp(56,13): warning : Game.cpp: TODO in Update [-W#pragma-messages]
1>Game.cpp(58,5): warning : expression result unused [-Wunused-value]
1>Game.cpp(79,13): warning : Game.cpp: TODO in Render [-W#pragma-messages]
1>Game.cpp(81,5): warning : expression result unused [-Wunused-value]
1>Game.cpp(137,13): warning : Game.cpp: TODO in CreateDeviceDependentResources [-W#pragma-messages]
1>Game.cpp(139,5): warning : expression result unused [-Wunused-value]
1>Game.cpp(145,13): warning : Game.cpp: TODO in CreateWindowSizeDependentResources [-W#pragma-messages]

将 Clang/LLVM 与 cmake 一起使用

CMakeExample 和 CMakeGDKExample 这两个 GDK 示例为将 Clang/LLVM 集成到你的 cmake 项目中提供了良好的起点。可以从 XBOX Developer Downloads 页面下载这些示例。

在尝试为 cmake 项目添加 Clang/LLVM 支持之前，请确保已安装 C++ CMake tools for Windows Visual Studio 组件。Visual Studio 2019 (16.11) 随附 CMake 3.20。Visual Studio 2022 随附 CMake 3.21 或更高版本。

使用 CMakeExample

按以下步骤在 CMakeExample 项目中启用 Clang/LLVM。 CMakeExample 于 2022 年 3 月更新为使用 CMakePresets.json，而不再使用较早的 CMakeSettings.json 方案。CMake Presets 已集成到 Visual Studio 2019 16.10 或更高版本。请参阅这篇博客文章。

使用 Visual Studio 的 打开本地文件夹 选项打开根 CMakeExample 文件夹中的 Desktop、XBOX Series X|S 或 XboxOne 文件夹。

CMakePresets.json 集成

在解决方案资源管理器中双击 CMakePresets.json 文件。

编辑 XdkEditionTarget 变量以匹配你当前的 GDK 版本。

"cacheVariables": {
  "XdkEditionTarget": "260400",
  "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}"
}

选择 x64-Debug-Clang 或 x64-Release-Clang 预设。

CMakeSettings.json 集成

在解决方案资源管理器中双击 CMakeSettings.json 文件。
选择加号图标，选择 x64-Clang-Debug 和 x64-Clang-Release，如下图所示。保存更改。

选择 编辑 Json，然后将另一个配置中的 variables 部分剪切并粘贴到新的 Clang 配置中，如下例所示。将 XDKEditionTarget 的值设置为与你的 GDK 版本（包括 QFE 级别）相匹配的值。

"variables": [
  {
    "name": "XdkEditionTarget",
    "value": "260400",
    "type": "STRING"
  }
]

保存所有更改后，从生成配置下拉列表中选择 x64-Clang-Debug 或 x64-Clang-Release 并进行生成。

使用 CMakeGDKExample

按以下步骤在 CMakeGDKExample 项目中启用 Clang/LLVM。

使用 Visual Studio 的 打开本地文件夹 选项打开 CMakeGDKExample 文件夹。

CMakePresets.json 集成

在解决方案资源管理器中双击 CMakePresets.json 文件。

编辑 XdkEditionTarget 变量以匹配你当前的 GDK 版本。

"cacheVariables": {
  "XdkEditionTarget": "260400",
  "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}"
}

选择 x64-Scarlett-Clang 或 x64-XboxOne-Clang 预设。

CMakeSettings.json 集成

在解决方案资源管理器中双击 CMakeSettings.json 文件。
选择要编辑的配置。将 Toolset 值设置为 clang_cl_x64。保存并关闭。

对于 XBOX One 和 XBOX Series X|S 配置，选择 编辑 Json，并确保 XdkEditionTarget 变量与你的 GDK 版本和 QFE 级别匹配。
从配置下拉列表中选择所需的值，然后从生成菜单中选择 全部重新生成。
使用文件 -> 打开 -> 项目/解决方案 选择生成的解决方案和项目。例如：

CMakeGDKExample\out\build\GamingXboxOne-Debug\CMakeGDKExample.sln 现在你可以开始生成并部署项目。

获取支持

对于 Visual C++ 编译器的 Bug 报告，请使用 Visual Studio 中的“报告问题…” 对于 clang/LLVM 编译器的 Bug 报告，请使用 https://bugs.llvm.org/ 对于 Microsoft Standard C++ Library（也称为 STL）的 Bug 报告，请使用 https://github.com/microsoft/STL/issues

已知问题

Clang/LLVM 工具集比 Visual C++ 要冗长得多，尤其是在使用 -Wall -Wextra -Wpedantic 时。至少应该在命令行或通过 #pragma 抑制以下警告：

#ifdef __clang__
#pragma clang diagnostic ignored "-Wc++98-compat"
#pragma clang diagnostic ignored "-Wc++98-compat-pedantic"
#pragma clang diagnostic ignored "-Wgnu-anonymous-struct"
#pragma clang diagnostic ignored "-Wlanguage-extension-token"
#pragma clang diagnostic ignored "-Wnested-anon-types"
#pragma clang diagnostic ignored "-Wreserved-id-macro"
#pragma clang diagnostic ignored "-Wunknown-pragmas"
#endif

XBOX 工具链仅使用 Microsoft PDB 作为调试符号，不支持 LLVM .ld 文件生成的 CodeView 或 DWARF 调试信息。
Clang/LLVM 的链接期代码生成实现与 Microsoft Visual C++ 方案有明显不同。你不能在 MSVC 与 clang/LLVM 之间混用使用了链接期代码生成的代码。
从 2022 年 10 月发行版和 Windows SDK (10.0.22621) 起，C++ 静态库包含 eXtended Flow Control Guard (XFG) 元数据。v15 版本之前的 ld 链接器在使用这些库时会始终发出一个无害警告：

lld-link: warning/error: ignoring unknown debug$S subsection kind 0xFF in file xgameruntime.lib

vcpkg 包管理器的 MSBuild 集成与 lld-link 不能正常协作，因为它在库文件名中使用通配符。你可以在 vcxproj 中设置 <UseLldLink>false</UseLldLink> 来解决此问题。此问题不会影响使用 VS 项目生成器的 vcpkg CMake 集成。
在 C++20 模式下使用 clang v18 为 XBOX 构建时，由于模板求值发生了变化，使用 WRL 头文件会有两个符号未定义。

wrl\implements.h(115,11): error : no member named 'RoOriginateError' in the global namespace
wrl/event.h(681,17): error : no member named 'RoTransformError' in the global namespace
wrl/event.h(712,18): error : no member named 'RoTransformError' in the global namespace

以下变通方法可解决此问题：

#include <wrl/client.h>

#if (__cplusplus >= 202002L) && (WINAPI_FAMILY == WINAPI_FAMILY_GAMES)
inline BOOL RoOriginateError(HRESULT, HSTRING) { return TRUE; }
inline BOOL RoTransformError(HRESULT, HRESULT, HSTRING) { return TRUE; }
#endif

#include <wrl/event.h>

另请参阅

Visual Studio Visual C++ 编译器与链接器开关建议将 CMake 与 Clang/LLVM 一起使用将 MSBuild 与 Clang/LLVM 一起使用

​所需的 Visual Studio 版本与组件

​编译器与链接器开关

​支持的 CPU 内在函数

​将 Clang/LLVM 与 msbuild 一起使用

​将 Clang/LLVM 与 cmake 一起使用

​使用 CMakeExample

​CMakePresets.json 集成

​CMakeSettings.json 集成

​使用 CMakeGDKExample

​CMakePresets.json 集成

​CMakeSettings.json 集成

​获取支持

​已知问题

​另请参阅

所需的 Visual Studio 版本与组件

编译器与链接器开关

支持的 CPU 内在函数

将 Clang/LLVM 与 msbuild 一起使用

将 Clang/LLVM 与 cmake 一起使用

使用 CMakeExample

CMakePresets.json 集成

CMakeSettings.json 集成

使用 CMakeGDKExample

CMakePresets.json 集成

CMakeSettings.json 集成

获取支持

已知问题

另请参阅