搭配 GDK 使用 Clang/LLVM - XBOX Game Development Documentation

使用 Visual Studio 2019 或 2022 以及 clang/LLVM for Windows 工具組 v12 或更新版本開發 GDK 遊戲已獲得正式支援。此工具組使用 Visual C/C++ Runtime (Universal CRT 程式庫 + Microsoft STL)。其他工具組與執行階段組合不一定能成功執行或通過遊戲認證。搭配 LLVM (clang-cl) (即 ClangCL) 平台工具組的 Clang/LLVM for Windows 會使用 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)
clang v19.1.1	Visual Studio 2022 (17.13)
clang v19.1.5	Visual Studio 2022 (17.14)

必要的 Visual Studio 版本與元件

若要搭配 Microsoft Game Development Kit (GDK) 使用 Clang/LLVM，需要 Visual Studio 16.11 版或更新版本。安裝 Visual Studio 2019 時，必須選取 使用 C++ 的桌面開發 底下的 C++ Clang Tools for Windows 元件。

視您使用的 Visual Studio 版本而定，必要的 Clang/LLVM 元件可能名為 C++ Clang Compiler for Windows 與 C++ Clang-cl for v142 build tools (x64/x86)。

如果您在安裝 Microsoft Game Development Kit (GDK) 之後修改現有的 Visual Studio 安裝以新增 C++ Clang Tools for Windows，則在使用 Clang/LLVM 之前，您需要修復 Microsoft Game Development Kit (GDK) 安裝。

如果已安裝 C++ Clang Tools for Windows 元件，Microsoft Game Development Kit (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 Compiler 不同。具體來說，__m128、__m128i、__m128d 類型被視為不透明類型而非結構，因此您無法使用這些類型建立 C++ 多載函式。這也表示透過 __m128.m128_f32[] 直接存取元素的程式碼將無法在 clang 上編譯。請注意，對於 Clang/LLVM 上的 DirectXMath，這會導致所有 XMVECTOR C++ 多載都被停用。您也可以在 Visual C++ 上選擇採用此行為以獲得更好的可攜性，方法是在包含 DirectXMath 標頭之前定義前置處理器符號 XM_NO_XMVECTOR_OVERLOADS。對於 PC，您可以確信所有 x64 原生 CPU 都支援 SSE 與 SSE2，因為這是架構定義的一部分。您也可以放心要求 SSE3，因為所有 Windows 10 支援的現代 CPU 都支援 SSE3。對於 DirectXMath，這表示您可以定義前置處理器定義 _XM_SSE3_INTRINSICS_，且必須使用 -march=sse3 以 clang/LLVM 建置。即使您目前未使用 /arch:AVX 或 /arch:AVX2 建置，Visual C++ 也允許您使用進階指令內建函式，但在此情境下，如果沒有適當的編譯器參數，clang/LLVM 將無法建置。對於 PC 上 SSE2 以外使用的任何功能，請務必進行執行階段 CPU 支援檢查。 Windows 10 SDK (18363) 或更早版本中的 DirectXMath，對 Clang/LLVM 使用了錯誤的 CPUID 內建函式來實作 XMVerifyCPUSupport。此問題已在 Windows 10 SDK (19041) 或更新版本中的 DirectXMath 3.14 修正。

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

搭配 msbuild 使用 Clang/LLVM

若要在 msbuild 專案中使用 Clang/LLVM，請將 平台工具組 設為 “LLVM (clang-cl)“。平台工具組 位於 Visual C++ 專案屬性對話方塊的一般索引標籤底下，如下圖所示。

也可以直接將 PlatformToolset msbuild 屬性設為 ClangCl 來設定 Clang/LLVM 工具組，如下列範例所示。


<PlatformToolset>ClangCl</PlatformToolset>

根據預設，Clang/LLVM 編譯器產生的資訊性警告會比 MSVC 多出許多。因此，對於 ‘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]

搭配 cmake 使用 Clang/LLVM

CMakeExample 與 CMakeGDKExample Microsoft Game Development Kit (GDK) 範例是將 Clang/LLVM 整合至 cmake 專案的良好起點。如需下載指示，請參閱 Microsoft Game Development Kit (GDK) 範例。

嘗試將 Clang/LLVM 支援新增至 cmake 專案之前，請確定已安裝 適用於 Windows 的 C++ CMake 工具 Visual Studio 元件。Visual Studio 2019 (16.11) 隨附 CMake 3.20。Visual Studio 2022 隨附 CMake 3.21 或更新版本。

使用 CMakeExample

使用下列步驟為 CMakeExample 專案啟用 Clang/LLVM。

使用 Visual Studio 的 開啟本機資料夾 選項，開啟 CMakeExample 根資料夾中的 Desktop 資料夾。

CMakeExample 已於 2022 年 3 月更新為使用 CMakePresets.json，而不是較舊的 CMakeSettings.json 解決方案。CMake 預設與 Visual Studio 2019 16.10 或更新版本整合。請參閱此部落格文章。

CMakePresets.json 整合

在方案總管中按兩下 CMakePresets.json 檔案。

編輯 XdkEditionTarget 變數，使其符合您目前的 GDK 版本。

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

選取 x64-Debug-Clang 或 x64-Release-Clang 預設。

CMakeSettings.json 整合

在方案總管中按兩下 CMakeSettings.json 檔案。
選取「加號」圖示，然後選擇 “x64-Clang-Debug” 和/或 “x64-Clang-Release”，如下圖所示。儲存變更。

按一下 “Edit Json”，然後從其他組態剪下並貼上 variables 區段至新的 Clang 組態，如下列範例所示。將 XDKEditionTarget 值設為適合您 GDK 版本 (包括 QFE 層級) 的值。

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

儲存所有變更後，從建置組態下拉式清單中選取 x64-Clang-Debug 或 x64-Clang-Release 並建置。

使用 CMakeGDKExample

使用下列步驟為 CMakeGDKExample 專案啟用 Clang/LLVM。

使用 Visual Studio 的 開啟本機資料夾 選項開啟 CMakeGDKExample 資料夾。

CMakePresets.json 整合

在方案總管中按兩下 CMakePresets.json 檔案。

編輯 XdkEditionTarget 變數，使其符合您目前的 GDK 版本。

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

選取 x64-Desktop-Clang 預設。

CMakeSettings.json 整合

在方案總管中按兩下 CMakeSettings.json 檔案。
選取您要編輯的組態，並將 Toolset 值設為 “clang_cl_x64”。儲存並關閉。

對於 XBOX One 與 XBOX Series X|S 組態，選取 Edit Json，並確定 XdkEditionTarget 變數符合您的 GDK 版本與 QFE 層級。
從組態下拉式清單中選取所需的值，然後從建置功能表選擇 全部重建。
使用檔案 -> 開啟 -> 專案/方案選取產生的方案/專案。例如：

CMakeGDKExample\out\build\GamingXboxOne-Debug\CMakeGDKExample.sln 您現在已準備好建置與部署您的專案。

取得支援

若要回報 Visual C++ 編譯器的錯誤，請使用 Visual Studio 中的回報問題… 若要回報 clang/LLVM 編譯器的錯誤，請使用 https://bugs.llvm.org/ 若要回報 Microsoft 標準 C++ 程式庫 (又稱 STL) 的錯誤，請使用 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 Game Development Kit (GDK) 工具只能搭配 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

另請參閱

Visual Studio 搭配 Clang/LLVM 使用 CMake 搭配 Clang/LLVM 使用 MSBuild

​必要的 Visual Studio 版本與元件

​編譯器與連結器參數

​支援的 CPU 內建函式

​搭配 msbuild 使用 Clang/LLVM

​搭配 cmake 使用 Clang/LLVM

​使用 CMakeExample

​CMakePresets.json 整合

​CMakeSettings.json 整合

​使用 CMakeGDKExample

​CMakePresets.json 整合

​CMakeSettings.json 整合

​取得支援

​已知問題

​另請參閱

必要的 Visual Studio 版本與元件

編譯器與連結器參數

支援的 CPU 內建函式

搭配 msbuild 使用 Clang/LLVM

搭配 cmake 使用 Clang/LLVM

使用 CMakeExample

CMakePresets.json 整合

CMakeSettings.json 整合

使用 CMakeGDKExample

CMakePresets.json 整合

CMakeSettings.json 整合

取得支援

已知問題

另請參閱