> ## 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

> 搭配 Microsoft Game Development Kit (GDK) 使用 Clang/LLVM

使用 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++ 程式庫](https://github.com/microsoft/STL)。

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

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

如果已安裝 **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/](https://walbourn.github.io/directxmath-3.14/)

## 搭配 msbuild 使用 Clang/LLVM

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

<img src="https://mintcdn.com/microsoft-4404708b/NsRUQ49ZRpXgoZ9R/images/gdk/tools/vs_gr_clang_msbuild_property.png?fit=max&auto=format&n=NsRUQ49ZRpXgoZ9R&q=85&s=7b0a16b440e2f0e2aa2aebdae361e799" alt="Clang/LLVM msbuild 屬性" width="826" height="548" data-path="images/gdk/tools/vs_gr_clang_msbuild_property.png" />

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

```xml theme={null}

<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) 範例](/zh-TW/home/setup-install/samples)。

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

### 使用 CMakeExample

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

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

CMakeExample 已於 2022 年 3 月更新為使用 `CMakePresets.json`，而不是較舊的 `CMakeSettings.json` 解決方案。CMake 預設與 Visual Studio 2019 16.10 或更新版本整合。請參閱[此部落格文章](https://devblogs.microsoft.com/cppblog/cmake-presets-integration-in-visual-studio-and-visual-studio-code/)。

### CMakePresets.json 整合

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

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

```
"cacheVariables": {
  "XdkEditionTarget": "250400",
  "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. 按一下 "Edit Json"，然後從其他組態剪下並貼上 variables 區段至新的 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. 在方案總管中按兩下 CMakePresets.json 檔案。

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

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

3. 選取 `x64-Desktop-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 值設為 &#x22;clang_cl_x64&#x22;" width="920" height="608" data-path="images/gdk/tools/vs_clang_cmake_set_toolsset_cmakegdkexample.png" />

4. 對於 XBOX One 與 XBOX Series X|S 組態，選取 **Edit Json**，並確定 XdkEditionTarget 變數符合您的 GDK 版本與 QFE 層級。

5. 從組態下拉式清單中選取所需的值，然後從 **建置** 功能表選擇 **全部重建**。

6. 使用 檔案 -> 開啟 -> 專案/方案 選取產生的方案/專案。例如：

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

您現在已準備好建置與部署您的專案。

## 取得支援

若要回報 Visual C++ 編譯器的錯誤，請使用 [Visual Studio 中的回報問題…](https://learn.microsoft.com/visualstudio/ide/how-to-report-a-problem-with-visual-studio)

若要回報 clang/LLVM 編譯器的錯誤，請使用 [https://bugs.llvm.org/](https://bugs.llvm.org/)

若要回報 Microsoft 標準 C++ 程式庫 (又稱 STL) 的錯誤，請使用 [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
```

* 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](/zh-TW/tools/tools-pc/visualstudio/gr-visualstudio-toc)

[搭配 Clang/LLVM 使用 CMake](https://learn.microsoft.com/cpp/build/clang-support-cmake)

[搭配 Clang/LLVM 使用 MSBuild](https://learn.microsoft.com/cpp/build/clang-support-msbuild)


## Related topics

- [在主機上搭配 GDK 使用 Clang/LLVM](/zh-TW/tools/tools-console/visualstudio/vs-clang.md)
- [搭配 Godot 使用 GDK](/zh-TW/build/gdk-and-engines/godot.md)
- [搭配 Unity 使用 GDK](/zh-TW/build/gdk-and-engines/unity/unity.md)
- [搭配 Unreal Engine 使用 GDK](/zh-TW/build/gdk-and-engines/unreal/unreal.md)
- [搭配 GameMaker 使用 GDK](/zh-TW/build/gdk-and-engines/gamemaker.md)