将 Clang/LLVM 与 Microsoft 游戏开发工具包 (GDK) 结合使用

现已正式支持使用 Clang/LLVM 开发 GDK 游戏，前提是要使用 Visual Studio 2019 或 2022 以及clang/LLVM for Windows 工具集 v12 或更高版本。 此工具集使用 Visual C/C++ 运行时（通用 CRT 库 + Microsoft STL）。 其他工具集和运行时的组合可能成功（或无法成功）运行或通过标题认证。

具有 LLVM (clang-cl) (即 ClangCL) 平台工具集的适用于 Windows 的 Clang/LLMS 使用 Microsoft 标准 C++ 库。

所需的 Visual Studio 版本和组件

需要 Visual Studio 版本 16.11 或更高版本才能将 Clang/LLMS 与 Microsoft 游戏开发工具包 (GDK) 结合使用。 安装 Visual Studio 2019 时，必须选择使用 C ++进行桌面开发下的适用于 Windows 的 C++ Clang 工具组件。

根据使用的 Visual Studio 的版本，所需的 Clang/LLMS 组件名称可能为适用于 Windows 的 C++ Clang 编译程序和 v142 编译工具的 C++ Clang-cl (x64/x86)

如果已安装适用于 Windows 的 C++ Clang 工具组件，则 Microsoft 游戏开发工具包 (GDK) 安装程序将安装对 Gaming.Desktop.x64 平台的 ClangCl 平台工具集的支持。

编译程序和链接器开关

对于 Gaming.Desktop.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

支持的 CPU 内部函数

Clang/LLVM 和 GNUC 处理 SSE SIMD 类型的方式不同于 Visual C++ 和 Intel 编译器。 具体而言，__m128、__m128i、__m128d 类型被视为不透明类型而非结构，因此不能使用这些类型创建 C++ 重载函数。 这也意味着通过 __m128.m128_f32[] 进行直接元素访问不会在 clang 上编译。

请注意，对于 Clang/LLMS 上的 DirectXMath，这会导致禁用所有 XMVECTOR C++ 重载。 还可以通过在包含 DirectXMath 标头之前定义预处理器符号 XM_NO_XMVECTOR_OVERLOADS 来选择在 Visual C++ 上使用此行为，以实现更好的可移植性。

对于电脑开发，可以将 SSE 和 SSE2 视为受所有 x64 本机 CPU 支持，因为这是体系结构定义的一部分。 你还可以安全地要求 SSE3，因为 Windows 10 支持的所有新式 CPU 都支持此功能。 对于 DirectXMath，这意味着可以定义预处理器符号 _XM_SSE3_INTRINSICS_，并且必须使用 -march=sse3 通过 clang/LLVM 进行编译。

即使你当前没有使用 /arch:AVX 或 /arch:AVX2 进行编译，Visual C ++ 仍允许你使用高级指令内部函数，但是在这种情况下，如果没有合适的编译程序开关，则 clang/LLVM 将无法编译。 请务必对在电脑上使用的 SSE2 之外的任何内容执行运行时 CPU 支持检查。

Windows 10 SDK（18363）或更早版本中的 DirectXMath 使用错误的 CPUID 内部函数来实现 Clang/LLVM 的 XMVerifyCPUSupport。 对于 Window 10 SDK (19041) 或更高版本中的 DirectXMath 3.14，已修复了此错误。

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

将 Clang/LLMS 与 msbuild 一起使用

若要将 Clang/LLMS 与 msbuild 项目一并使用，请将平台工具集设为“LLVM (clang-cl)”。 平台工具集在 Visual C++ 项目属性对话框的常规选项卡下，如下图所示。

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

<PlatformToolset>ClangCl</PlatformToolset>

默认情况下，与 MSVC 相比，Clang/LLMS 编译程序生成更多信息警告。 因此，在“TODO”位置，你将同时看到 -W#pragma-messages 输出和 -Messagesnused-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/LLMS 与 cmake 一起使用

CMlangExample 和 CMlangGDKExample Microsoft 游戏开发工具包 (GDK) 示例为将 Clang/LLCM 集成到 cmake 项目提供了一个很好的起始点。 有关下载说明，请参阅 Microsoft 游戏开发工具包 (GDK) 示例。

使用 CMpleExample

使用以下步骤来启用 CMakeExample 项目的 Clang/LLVM。

1. 使用 Visual Studio 的“打开本地文件夹”选项，在根 CMpleExample 文件夹中打开“桌面”文件夹。

CMakeExample 已于 2022 年 3 月更新为使用 CMakePresets.json ，而不是旧的 CMakeSettings.json 解决方案。 CMake 预设与 Visual Studio 2019 16.10 或更高版本集成。 请参阅 此博客文章。

CMakePresets.json 集成

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

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

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

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

CMakeSettings.json 集成

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

3. 选择“加号”图标，然后选择“x64-Clang-Debug”和/或“x64-Clang-Release”，如下图所示。 保存更改。

4. 点按“编辑 Json”，然后将变量部分从另一个配置剪切并粘贴到新的 Clang 配置，如下面的示例所示。 将 XDKEditionTarget 值设置为适用于 GDK 版本（包括 QFE 级别）的值。

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

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

使用 CMakeGDKExample

使用以下步骤来启用 CMakeGDKExample 项目的 Clang/LLVM。

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

CMakePresets.json 集成

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

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

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

3. 选择 x64-Desktop-Clang 预设。

CMakeSettings.json 集成

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

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

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

5. 从配置下拉菜单中选择所需的值，并从编译菜单中选择编译全部。

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

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

现在即可编译和部署项目。

获取支持

有关 Visual C++ 编译程序的错误报告，请使用在 Visual Studio 中报告问题…

有关 clang/LLVM 编译程序的错误报告，请使用 https://bugs.llvm.org/

有关 Microsoft Standard C++ 库（亦称 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

• Microsoft 游戏开发工具包 (GDK) 工具仅适用于用来调试符号 Microsoft PDB，不支持 LLVM .ld 文件中发出的 CodeView 或 DWARF 调试信息。

• Clang/LLMS 实现的链接-时间代码生成方法与 Microsoft Visual C++ 解决方案明显不同。 使用链接-时间代码生成的代码不能在 MSVC 和 clang/LLMS 之间混用。

• 自 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

另请参阅

Visual Studio

将 CMake 与 Clang/LLVM 一起使用

将 MSBuild 与 Clang/LLMS 一起使用