> ## 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.
# Usar o Clang com o Microsoft Game Development Kit (GDK) para consoles
> Usar o Clang/LLVM com o Microsoft Game Development Kit (GDK) para consoles
Você pode desenvolver títulos do Microsoft Game Development Kit (GDK) usando o Clang/LLVM com o Visual Studio 2019, o Visual Studio 2022 ou o Visual Studio 2026 e o conjunto de ferramentas *clang/LLVM for Windows* v12 ou posterior. Esse conjunto de ferramentas usa o Visual C/C++ Runtime (a biblioteca Universal CRT + a Microsoft STL). Outras combinações de conjuntos de ferramentas e runtimes podem não ser executadas com êxito ou não passar na certificação de títulos.
O Clang/LLVM for Windows com o conjunto de ferramentas de plataforma **LLVM (clang-cl)** (ou seja, o ClangCL) usa a [Microsoft Standard C++ Library](https://github.com/microsoft/STL).
| Versão do Clang | Atualização do 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) |
## Versões e componentes necessários do Visual Studio
Você precisa do Visual Studio versão 16.11 ou posterior para usar o Clang/LLVM com o GDK. Selecione o componente **C++ Clang Compiler for Windows** em **Individual Components** ao instalar o Visual Studio.
Dependendo da versão do Visual Studio que você está usando, os componentes necessários do Clang/LLVM podem se chamar **C++ Clang Compiler for Windows** e **C++ Clang-cl for v142 build tools (x64/x86)**.
> [!NOTE]
>
> Se você modificar sua instalação existente do Visual Studio para adicionar o **C++ Clang Compiler for Windows** depois que o GDK for instalado, será necessário reparar a instalação do GDK antes de usar o Clang/LLVM.
Se você instalar o componente **C++ Clang Compiler for Windows**, a configuração do GDK instalará o suporte ao conjunto de ferramentas de plataforma **ClangCl** para as plataformas `Gaming.Xbox.*.x64`.
## Opções do compilador e do vinculador
Para as plataformas `Gaming.Xbox.*.x64`, a linha de comando do clang/LLVM usada com o `clang-cl.exe` sempre inclui o seguinte:
```
-Wno-c++98-compat -Wno-c++98-compat-pedantic -Wno-reserved-id-macro
-Wno-pragma-pack -Wno-unknown-pragmas
-Wno-unused-command-line-argument
```
Para `Gaming.Xbox.Scarlett.x64`, ela também adiciona `-march=znver2`. Essa opção define o AVX2 e alguns outros recursos específicos da CPU Hercules.
Para `Gaming.Xbox.XboxOne.x64`, ela também adiciona `-march=btver2`. Essa opção define o AVX, o F16C e alguns outros recursos específicos da CPU Jaguar.
Para obter mais informações sobre as opções recomendadas para o desenvolvimento com o GDK, consulte [Recomendações de opções do compilador e do vinculador do Visual C++](/pt-BR/tools/tools-console/visualstudio/compiler-switch-recommendations).
## Intrínsecos de CPU compatíveis
O Clang/LLVM e o GNUC tratam os tipos SIMD SSE de forma diferente do Visual C++ e do Intel Compiler. Especificamente, os tipos \_\_m128, \_\_m128i e \_\_m128d são tipos opacos em vez de structs, portanto, você não pode criar funções sobrecarregadas em C++ que usem esses tipos. Essa diferença também significa que o acesso direto a elementos por meio de \_\_m128.m128\_f32\[] não é compilado no clang.
Para o DirectXMath no Clang/LLVM, essa diferença faz com que todas as sobrecargas C++ de `XMVECTOR` sejam desabilitadas. Você também pode aceitar esse comportamento no Visual C++ para obter melhor portabilidade definindo o símbolo de pré-processador `XM_NO_XMVECTOR_OVERLOADS` antes de incluir os cabeçalhos do DirectXMath.
O Visual C++ permite que você use intrínsecos de instruções avançadas mesmo que não esteja fazendo o build com /arch:AVX ou /arch:AVX2, mas o build do clang/LLVM falha nesse cenário sem as opções de compilador adequadas.
Ao usar o Clang/LLVM, você deve adicionar a opção de compilador `-march=btver2`, `-march=znver1`, `-march=znver2` ou `-mf16c` para usar os intrínsecos de conversão de meia precisão F16C `_mm_cvtph_ps` ou `_mm_cvtps_ph`.
O DirectXMath no Windows 10 SDK (18363) ou anterior usava os intrínsecos CPUID incorretos para implementar `XMVerifyCPUSupport` para o Clang/LLVM. Esse problema foi corrigido no DirectXMath 3.14 no Windows 10 SDK (19041) ou posterior.
* [https://walbourn.github.io/directxmath-3.14/](https://walbourn.github.io/directxmath-3.14/)
## Usar o Clang/LLVM com o msbuild
Para usar o Clang/LLVM com um projeto do msbuild, defina o **Platform Toolset** como "LLVM (clang-cl)". Você pode encontrar o **Platform Toolset** na guia **General** da caixa de diálogo de propriedades do projeto Visual C++, conforme mostrado na figura a seguir.
Você também pode definir o conjunto de ferramentas Clang/LLVM definindo diretamente a propriedade **PlatformToolset** do msbuild como **ClangCl**, conforme mostrado no exemplo a seguir.
```xml theme={null}
ClangCl
```
Por padrão, o compilador Clang/LLVM gera significativamente mais avisos informativos em comparação com o MSVC. Portanto, nos locais com 'TODO', você vê tanto a saída de `-W#pragma-messages` como um aviso quanto um aviso `-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]
```
## Usar o Clang/LLVM com o cmake
Os exemplos do GDK CMakeExample e CMakeGDKExample são um bom ponto de partida para integrar o Clang/LLVM aos seus projetos do cmake. Você pode baixar esses exemplos na [página XBOX Developer Downloads](https://aka.ms/gdkdl).
> [!NOTE]
>
> Verifique se o componente **C++ CMake tools for Windows** do Visual Studio está instalado antes de tentar adicionar suporte ao Clang/LLVM aos seus projetos do cmake. O Visual Studio 2019 (16.11) é fornecido com o CMake 3.20. O Visual Studio 2022 é fornecido com o CMake 3.21 ou posterior.
### Usar o CMakeExample
Use as etapas a seguir para habilitar o Clang/LLVM no projeto CMakeExample.
O CMakeExample foi atualizado em março de 2022 para usar `CMakePresets.json` em vez da solução mais antiga `CMakeSettings.json`. Os CMake Presets são integrados ao Visual Studio 2019 16.10 ou posterior. Consulte [esta postagem de blog](https://devblogs.microsoft.com/cppblog/cmake-presets-integration-in-visual-studio-and-visual-studio-code/).
1. Use a opção **Open Local Folder** do Visual Studio para abrir a pasta Desktop, XBOX Series X|S ou XboxOne na pasta raiz do CMakeExample.
### Integração com CMakePresets.json
2. No Solution Explorer, clique duas vezes no arquivo CMakePresets.json.
Edite a variável `XdkEditionTarget` para que corresponda à sua edição atual do GDK.
```
"cacheVariables": {
"XdkEditionTarget": "260400",
"CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}"
}
```
3. Selecione a predefinição `x64-Debug-Clang` ou `x64-Release-Clang`.
### Integração com CMakeSettings.json
2. No Solution Explorer, clique duas vezes no arquivo CMakeSettings.json.
3. Selecione o ícone **PLUS** e escolha **x64-Clang-Debug** e **x64-Clang-Release**, conforme mostrado na figura a seguir. Salve as alterações.
4. Selecione **Edit Json** e, em seguida, recorte e cole a seção de variáveis de outra configuração nas novas configurações do Clang, como no exemplo a seguir. Defina o valor de `XDKEditionTarget` como o apropriado para a sua versão do GDK, incluindo o nível de QFE.
```
"variables": [
{
"name": "XdkEditionTarget",
"value": "260400",
"type": "STRING"
}
]
```
5. Depois de salvar todas as alterações, selecione **x64-Clang-Debug** ou **x64-Clang-Release** na lista suspensa de configuração de build e faça o build.
## Usar o CMakeGDKExample
Use as etapas a seguir para habilitar o Clang/LLVM no projeto CMakeGDKExample.
1. Use a opção **Open Local Folder** do Visual Studio para abrir a pasta CMakeGDKExample.
### Integração com CMakePresets.json
2. No Solution Explorer, clique duas vezes no arquivo CMakePresets.json.
Edite a variável `XdkEditionTarget` para que corresponda à sua edição atual do GDK.
```
"cacheVariables": {
"XdkEditionTarget": "260400",
"CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}"
}
```
3. Selecione a predefinição `x64-Scarlett-Clang` ou `x64-XboxOne-Clang`.
### Integração com CMakeSettings.json
2. No Solution Explorer, clique duas vezes no arquivo CMakeSettings.json.
3. Selecione a configuração que deseja editar. Defina o valor de Toolset como `clang_cl_x64`. Salve e feche.
4. Para as configurações de XBOX One e XBOX Series X|S, selecione **Edit Json** e verifique se a variável `XdkEditionTarget` corresponde à sua edição do GDK e ao nível de QFE.
5. Selecione o valor desejado na lista suspensa de configuração e escolha **Rebuild All** no menu **Build**.
6. Use **File** -> **Open** -> **Project/Solution** para selecionar a solução e o projeto gerados. Por exemplo:
CMakeGDKExample\out\build\GamingXboxOne-Debug\CMakeGDKExample.sln
Agora você está pronto para fazer o build e implantar seu projeto.
## Obter suporte
Para relatar bugs do compilador Visual C++, use [Report a Problem… in Visual Studio](https://learn.microsoft.com/visualstudio/ide/how-to-report-a-problem-with-visual-studio)
Para relatar bugs do compilador clang/LLVM, use [https://bugs.llvm.org/](https://bugs.llvm.org/)
Para relatar bugs da Microsoft Standard C++ Library (também conhecida como STL), use [https://github.com/microsoft/STL/issues](https://github.com/microsoft/STL/issues)
## Problemas conhecidos
* O conjunto de ferramentas Clang/LLVM é significativamente mais detalhado que o Visual C++, especialmente quando você usa `-Wall -Wextra -Wpedantic`. No mínimo, suprima os seguintes avisos na linha de comando ou como um `#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
```
* As ferramentas do XBOX funcionam apenas com PDBs da Microsoft para símbolos de depuração e não oferecem suporte às informações de depuração CodeView ou DWARF emitidas pelos arquivos `.ld` do LLVM.
* A implementação da Geração de Código em Tempo de Vinculação do Clang/LLVM é nitidamente diferente da solução do Microsoft Visual C++. Não é possível misturar código que usa a Geração de Código em Tempo de Vinculação entre o MSVC e o clang/LLVM.
* A partir da versão de outubro de 2022 e do Windows SDK (10.0.22621), as bibliotecas estáticas C++ incluem metadados do eXtended Flow Control Guard (XFG). O vinculador `ld` anterior à versão v15 sempre emite um aviso inofensivo quando você usa essas bibliotecas:
```
lld-link: warning/error: ignoring unknown debug$S subsection kind 0xFF in file xgameruntime.lib
```
* A integração do gerenciador de pacotes vcpkg com o MSBuild não funciona corretamente com o `lld-link`, pois usa curingas nos nomes de arquivos de biblioteca. Você pode contornar esse problema definindo `false` no vcxproj. Esse problema não afeta a integração do vcpkg com o CMake usando geradores de projeto do VS.
* Ao fazer o build para XBOX com o clang v18 no modo C++20, dois símbolos ficam indefinidos ao usar os cabeçalhos WRL devido a alterações na avaliação de templates.
```
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
```
A solução alternativa a seguir resolve o problema:
```cpp theme={null}
#include
#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
```
## Veja também
[Visual Studio](/pt-BR/tools/tools-console/visualstudio/visualstudio)
[Recomendações de opções do compilador e do vinculador do Visual C++](/pt-BR/tools/tools-console/visualstudio/compiler-switch-recommendations)
[Using CMake with Clang/LLVM](https://learn.microsoft.com/cpp/build/clang-support-cmake)
[Using MSBuild with Clang/LLVM](https://learn.microsoft.com/cpp/build/clang-support-msbuild)
## Related topics
- [Usar o Clang com o Microsoft Game Development Kit (GDK)](/pt-BR/tools/tools-pc/visualstudio/gr-vs-clang.md)
- [Modelos de projeto no Visual Studio para o desenvolvimento de jogos para PC](/pt-BR/tools/tools-pc/visualstudio/gr-vs-templates.md)
- [Utilizando as ferramentas do Microsoft Game Development Kit (GDK) para instalar e iniciar seu título para PC](/pt-BR/tools/tools-pc/launching-on-pc.md)
- [Fiddler no PC com Windows](/pt-BR/build/console-features/networking/tools/fiddler-pc.md)
- [Ferramentas de rede no Microsoft Game Development Kit](/pt-BR/build/console-features/networking/tools/tools-networking-toc.md)