在主機上搭配 GDK 使用 Clang/LLVM - XBOX Game Development Documentation

您可以搭配 Visual Studio 2019、Visual Studio 2022 或 Visual Studio 2026 以及 clang/LLVM for Windows 工具組 v12 或更新版本，使用 Clang/LLVM 開發 Microsoft Game Development Kit (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 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 Compiler 不同。具體來說，__m128、__m128i 與 __m128d 類型是不透明類型而非結構，因此您無法建立使用這些類型的 C++ 多載函式。此差異也表示透過 __m128.m128_f32[] 直接存取元素的程式碼無法在 clang 上編譯。對於 Clang/LLVM 上的 DirectXMath，此差異會導致所有 XMVECTOR C++ 多載都被停用。您也可以在 Visual C++ 上選擇採用此行為以獲得更好的可攜性，方法是在包含 DirectXMath 標頭之前定義前置處理器符號 XM_NO_XMVECTOR_OVERLOADS。即使您目前未使用 /arch:AVX 或 /arch:AVX2 建置，Visual C++ 也可讓您使用進階指令內建函式，但在此情境下，如果沒有適當的編譯器參數，clang/LLVM 將無法建置。使用 Clang/LLVM 時，您必須新增 -march=btver2、-march=znver1、-march=znver2 或 -mf16c 編譯器參數，才能使用 F16C 半精度轉換內建函式 _mm_cvtph_ps 或 _mm_cvtps_ph。 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 GDK 範例是將 Clang/LLVM 整合至 cmake 專案的良好起點。您可以從 XBOX 開發人員下載頁面下載這些範例。

嘗試將 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。 CMakeExample 已於 2022 年 3 月更新為使用 CMakePresets.json，而不是較舊的 CMakeSettings.json 解決方案。CMake 預設與 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 檔案。
選取 PLUS 圖示，然後選擇 x64-Clang-Debug 與 x64-Clang-Release，如下圖所示。儲存變更。

選取 Edit 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 組態，選取 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

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++ 編譯器與連結器參數建議搭配 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 整合

取得支援

已知問題

另請參閱