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

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

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

如果您安裝 **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++ 編譯器與連結器參數建議](/zh-TW/tools/tools-console/visualstudio/compiler-switch-recommendations)。

## 支援的 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/](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/6TXzXmujKayly5Sf/images/gdk/tools/vs_clang_msbuild_property.png?fit=max&auto=format&n=6TXzXmujKayly5Sf&q=85&s=260bbf1445110c95ef709030e4561d22" alt="Clang/LLVM msbuild 屬性" width="783" height="513" data-path="images/gdk/tools/vs_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 GDK 範例是將 Clang/LLVM 整合至 cmake 專案的良好起點。您可以從 [XBOX 開發人員下載頁面](https://aka.ms/gdkdl)下載這些範例。

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

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/)。

1. 使用 Visual Studio 的 **開啟本機資料夾** 選項，開啟 CMakeExample 根資料夾中的 Desktop、XBOX Series X|S 或 XboxOne 資料夾。

### CMakePresets.json 整合

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

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

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

3. 選取 `x64-Debug-Clang` 或 `x64-Release-Clang` 預設。

### CMakeSettings.json 整合

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

3. 選取 **PLUS** 圖示，然後選擇 **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": "260400",
    "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": "260400",
  "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}"
}
```

3. 選取 `x64-Scarlett-Clang` 或 `x64-XboxOne-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
```

* 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
```

下列因應措施可解決此問題：

```cpp theme={null}
#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](/zh-TW/tools/tools-console/visualstudio/visualstudio)

[Visual C++ 編譯器與連結器參數建議](/zh-TW/tools/tools-console/visualstudio/compiler-switch-recommendations)

[搭配 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-pc/visualstudio/gr-vs-clang.md)
- [CreateReservedResource](/zh-TW/reference/graphics/d3d12/interfaces/id3d12device/methods/id3d12device_createreservedresource_public.md)
- [XBOX 編譯器技術](/zh-TW/tools/tools-console/visualstudio/compiler-technology.md)
- [用於主機開發的 Visual Studio](/zh-TW/tools/tools-console/visualstudio/visualstudio.md)
- [Visual Studio (內容)](/zh-TW/tools/tools-pc/visualstudio/gr-visualstudio-toc.md)