将 Clang/LLVM 与 Microsoft 游戏开发工具包 (GDK) 结合使用
本文内容
所需的 Visual Studio 版本和组件
编译程序和链接器开关
支持的 CPU 内部函数
将 Clang/LLMS 与 msbuild 一起使用
将 Clang/LLMS 与 cmake 一起使用
使用 CMakeGDKExample
获取支持
已知问题
另请参阅
显示另外 5 个
现已正式支持使用 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++ 库 。
展开表
Clang 版本
Visual Studio 更新
clang v12
Visual Studio 2019 (16.11)
clang v12
Visual Studio 2022 (17.0)
clang v13
Visual Studio 2022 (17.1)
clang v13.0.1
Visual Studio 2022 (17.2)
clang v14
Visual Studio 2022 (17.3)
clang v15.0.1
Visual Studio 2022 (17.4)
clang v16.0.5
Visual Studio 2022 (17.7)
clang v17.0.3
Visual Studio 2022 (17.9)
clang v18.1.8
Visual Studio 2022 (17.12) 预览版
需要 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)
备注
如果在安装 Microsoft 游戏开发工具包 (GDK) 后修改现有 Visual Studio 安装,以添加适用于 Windows 的 C++ Clang 工具,则需要先修复 Microsoft 游戏开发工具包 (GDK) 安装,然后才能使用 Clang/LLVM。
如果已安装适用于 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
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,已修复了此错误。
将 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) 示例 。
备注
在尝试向 cmake 项目添加 Clang/LLMS 支持之前,请确保已安装“适用于 Windows 的 C++ CMake 工具” Visual Studio 组件。 Visual Studio 2019 (16.11) 随 CMake 3.20 一起提供。 Visual Studio 2022 附带 CMake 3.21 或更高版本。
使用以下步骤来启用 CMakeExample 项目的 Clang/LLVM。
使用 Visual Studio 的“打开本地文件夹” 选项,在根 CMpleExample 文件夹中打开“桌面”文件夹。
CMakeExample 已于 2022 年 3 月更新为使用 CMakePresets.json
,而不是旧的 CMakeSettings.json
解决方案。 CMake 预设与 Visual Studio 2019 16.10 或更高版本集成。 请参阅 此博客文章 。
在解决方案资源管理器中双击 CMsettingPresets.json 文件。
编辑 XdkEditionTarget
变量以匹配当前 GDK 版本。
"cacheVariables": {
"XdkEditionTarget": "230300",
"CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}"
}
选择 x64-Debug-Clang
或 x64-Release-Clang
预设。
在解决方案资源管理器中双击 CMsettingSettings.json 文件。
选择“加号”图标,然后选择“x64-Clang-Debug”和/或“x64-Clang-Release”,如下图所示。 保存更改。
点按“编辑 Json”,然后将变量部分从另一个配置剪切并粘贴到新的 Clang 配置,如下面的示例所示。 将 XDKEditionTarget 值设置为适用于 GDK 版本(包括 QFE 级别)的值。
"variables": [
{
"name": "XdkEditionTarget",
"value": "210400",
"type": "STRING"
}
]
保存所有更改后,从编译配置下拉列表中选择 x64-Clang-Debug 或 x64-Clang-Release 并进行编译。
使用以下步骤来启用 CMakeGDKExample 项目的 Clang/LLVM。
使用 Visual Studio 的打开本地文件夹 选项打开 CMakeGDKExample 文件夹。
在解决方案资源管理器中双击 CMsettingPresets.json 文件。
编辑 XdkEditionTarget
变量以匹配当前 GDK 版本。
"cacheVariables": {
"XdkEditionTarget": "230300",
"CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}"
}
选择 x64-Desktop-Clang
预设。
在解决方案资源管理器中双击 CMsettingSettings.json 文件。
选择要编辑的配置,将 Toolset 值设置为“clang_cl_x64”。 保存并关闭。
对于 Xbox One 和 Xbox Series X|S 配置,请选择“编辑 Json ”,并确保 XdkEditionTarget 变量与你的 GDK 版本和 QFE 级别匹配。
从配置下拉菜单中选择所需的值,并从编译 菜单中选择编译全部 。
使用“文件”->“打开”->“项目/解决方案”选择生成的解决方案/项目。 例如:
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 一起使用