> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 在主机 GDK 中使用 Clang/LLVM

> 为主机开发使用 Clang/LLVM 与 Microsoft Game Development Kit (GDK)

你可以使用 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](https://github.com/microsoft/STL)。

| 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** 组件。

<img src="https://mintcdn.com/microsoft-4404708b/6TXzXmujKayly5Sf/images/gdk/tools/vs_clang_install_options.png?fit=max&auto=format&n=6TXzXmujKayly5Sf&q=85&s=c70a80a7305443c1b6a2dd9d1ef8efae" alt="Clang Tools for Windows" width="630" height="378" data-path="images/gdk/tools/vs_clang_install_options.png" />

根据你使用的 Visual Studio 版本，所需的 Clang/LLVM 组件的名称可能是 **C++ Clang Compiler for Windows** 与 **C++ Clang-cl for v142 build tools (x64/x86)**。

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

如果安装了 **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++ 编译器与链接器开关建议](/tools/tools-console/visualstudio/compiler-switch-recommendations)。

## 支持的 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/](https://walbourn.github.io/directxmath-3.14/)

## 将 Clang/LLVM 与 msbuild 一起使用

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

<img src="https://mintcdn.com/microsoft-4404708b/6TXzXmujKayly5Sf/images/gdk/tools/vs_clang_msbuild_property.png?fit=max&auto=format&n=6TXzXmujKayly5Sf&q=85&s=260bbf1445110c95ef709030e4561d22" alt="Clang/LLVM msbuild 属性" width="783" height="513" data-path="images/gdk/tools/vs_clang_msbuild_property.png" />

也可以直接将 **PlatformToolset** msbuild 属性设置为 **ClangCl** 来设置 Clang/LLVM 工具集，如下例所示。

```xml theme={null}

<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 页面](https://aka.ms/gdkdl) 下载这些示例。

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

### 使用 CMakeExample

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

CMakeExample 于 2022 年 3 月更新为使用 `CMakePresets.json`，而不再使用较早的 `CMakeSettings.json` 方案。CMake Presets 已集成到 Visual Studio 2019 16.10 或更高版本。请参阅[这篇博客文章](https://devblogs.microsoft.com/cppblog/cmake-presets-integration-in-visual-studio-and-visual-studio-code/)。

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

### CMakePresets.json 集成

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

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

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

3. 选择 `x64-Debug-Clang` 或 `x64-Release-Clang` 预设。

### CMakeSettings.json 集成

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

3. 选择 **加号** 图标，选择 **x64-Clang-Debug** 和 **x64-Clang-Release**，如下图所示。保存更改。

<img src="https://mintcdn.com/microsoft-4404708b/6TXzXmujKayly5Sf/images/gdk/tools/vs_clang_cmake_add_config_cmakeexample.png?fit=max&auto=format&n=6TXzXmujKayly5Sf&q=85&s=94202af0a719e19ce9573f71e1b925a5" alt="在 cmake 项目中添加 Clang 配置" width="634" height="612" data-path="images/gdk/tools/vs_clang_cmake_add_config_cmakeexample.png" />

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

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

```

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

## 使用 CMakeGDKExample

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

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

### CMakePresets.json 集成

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

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

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

3. 选择 `x64-Scarlett-Clang` 或 `x64-XboxOne-Clang` 预设。

### CMakeSettings.json 集成

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

3. 选择要编辑的配置。将 Toolset 值设置为 `clang_cl_x64`。保存并关闭。

<img src="https://mintcdn.com/microsoft-4404708b/6TXzXmujKayly5Sf/images/gdk/tools/vs_clang_cmake_set_toolsset_cmakegdkexample.png?fit=max&auto=format&n=6TXzXmujKayly5Sf&q=85&s=dd9392aa02da7d03720e745201a921a1" alt="将 Toolset 值设置为 “clang_cl_x64”" width="920" height="608" data-path="images/gdk/tools/vs_clang_cmake_set_toolsset_cmakegdkexample.png" />

4. 对于 XBOX One 和 XBOX Series X|S 配置，选择 **编辑 Json**，并确保 `XdkEditionTarget` 变量与你的 GDK 版本和 QFE 级别匹配。

5. 从配置下拉列表中选择所需的值，然后从 **生成** 菜单中选择 **全部重新生成**。

6. 使用 **文件** -> **打开** -> **项目/解决方案** 选择生成的解决方案和项目。例如：

CMakeGDKExample\out\build\GamingXboxOne-Debug\CMakeGDKExample.sln

现在你可以开始生成并部署项目。

## 获取支持

对于 Visual C++ 编译器的 Bug 报告，请使用 [Visual Studio 中的“报告问题…”](https://learn.microsoft.com/visualstudio/ide/how-to-report-a-problem-with-visual-studio)

对于 clang/LLVM 编译器的 Bug 报告，请使用 [https://bugs.llvm.org/](https://bugs.llvm.org/)

对于 Microsoft Standard C++ Library（也称为 STL）的 Bug 报告，请使用 [https://github.com/microsoft/STL/issues](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
```

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

```cpp theme={null}
#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](/tools/tools-console/visualstudio/visualstudio)

[Visual C++ 编译器与链接器开关建议](/tools/tools-console/visualstudio/compiler-switch-recommendations)

[将 CMake 与 Clang/LLVM 一起使用](https://learn.microsoft.com/cpp/build/clang-support-cmake)

[将 MSBuild 与 Clang/LLVM 一起使用](https://learn.microsoft.com/cpp/build/clang-support-msbuild)


## Related topics

- [在 GDK 中使用 Clang/LLVM](/zh-CN/tools/tools-pc/visualstudio/gr-vs-clang.md)
- [Visual Studio(目录)](/zh-CN/tools/tools-pc/visualstudio/gr-visualstudio-toc.md)
- [Visual Studio 2019 GDK 支持说明](/zh-CN/tools/tools-console/visualstudio/vs-2019-support-notes.md)
- [Visual Studio 2019 支持说明](/zh-CN/tools/tools-pc/visualstudio/gr-vs-2019-support-notes.md)
- [Visual Studio](/zh-CN/tools/tools-pc/visualstudio/index.md)