From 76b45b6e6c995e48b2518106d51acbe656df181b Mon Sep 17 00:00:00 2001 From: Chuck Walbourn Date: Thu, 27 Apr 2023 23:10:26 -0700 Subject: [PATCH 1/5] Add clangcl community triplets --- vcpkg/users/platforms/clangcl.md | 67 ++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 vcpkg/users/platforms/clangcl.md diff --git a/vcpkg/users/platforms/clangcl.md b/vcpkg/users/platforms/clangcl.md new file mode 100644 index 00000000..45622741 --- /dev/null +++ b/vcpkg/users/platforms/clangcl.md @@ -0,0 +1,67 @@ +--- +title: clang/LLVM for Windows +description: Use arm64 and x64 community triplets for clang/LLVM +ms.date: 04/27/2023 +--- +# clang/LLVM for Windows + +> [!NOTE] +> Clang/LLVM is not tested as part of vcpkg repository's CI process, so regressions can occur as part of library updates. PRs improving support are welcome! + +## Clang community triplets + +vcpkg includes [community triplets](https://github.com/microsoft/vcpkg/tree/master/triplets/community) for building with clang/LLVM for Windows using the ``clang-cl.exe`` MSVC-like command-line driver. + +There are two variants of each triplet, selecting between static and dynamic linking. + +| Architecture | vcpkg community triplets | Target parameter | +|--------------|----------------------------|------------------------------------| +| x64 | x64-clangcl-dynamic | ``-m64`` | +| | x64-clangcl-static | | +| | x64-clangcl-uwp | | +| arm64 | arm64-clangcl-dynamic | ``--target=arm64-pc-windows-msvc`` | +| | arm64-clangcl-static | | +| | arm64-clangcl-uwp | | + +> Note that clang/LLVM for Windows does not support the C++/CX language extensions (``/ZW``, ``/AU``, ``/FU``, ``/WINMD``, and ``#using``) supported by the MSVC ``uwp`` triplets. You can make use of [C++/WinRT language projections](https://learn.microsoft.com/windows/uwp/cpp-and-winrt-apis/) with clang/LLVM for Windows. + +In addition to triplets for the standard Windows and UWP platforms using clang/LLVM, there are four that target the Xbox platform as well. + +| Console | vcpkg community triplets | +|------------------|------------------------------| +| Xbox One | x64-clangcl-xboxone | +| | x64-clangcl-xboxone-static | +| Xbox Series X\|S | x64-clangcl-scarlett | +| | x64-clangcl-scarlett-static | + +The ``static`` linking triplets are set to use the MSVC Runtime as a DLL (i.e. ``VCPKG_CRT_LINKAGE dynamic``) as that's the recommended usage scenario. + +> The toolchain file can also support x86 and arm architectures as well, if needed, but those triplet files are left as an excercise to the reader to implement. + +## Visual Studio integration of clang/LLVM for Windows + +The easiest way to make use of clang/LLVM for Windows is to install it as part of the Visual Studio product. You can install them by opening the Visual Studio Installer and choosing **C++ Clang tools for Windows** under **Desktop development with C++** optional components (``Microsoft.VisualStudio.Component.VC.Llvm.Clang`` and/or ``Microsoft.VisualStudio.ComponentGroup.NativeDesktop.Llvm.Clang``). + +![Visual Studio 2022 Install UI](https://learn.microsoft.com/en-us/cpp/build/media/clang-install-vs2022.png?view=msvc-170) + +The vcpkg triplets will automatically make use of these tools by default. + +## Selecting a clang/LLVM for Windows Toolset + +If you wish to select a different clang/LLVM for Windows toolset, you can install it and then set the **LLVMInstallDir** environment variable to point to the toolset location. + +``` +set LLVMInstallDir="C:\Program Files\LLVM" +``` + +Note that MSBuild uses the same property variable to set a custom version of clang/LLVM as well. Be sure to also set the **LLVMToolsVersion** property variable to the correct value as well. See [Microsoft Learn](https://learn.microsoft.com/cpp/build/clang-support-msbuild?view=msvc-170#custom_llvm_location). + +The vcpkg triplets will make use of the toolset pointed to by this variable if present. + +## Known Issues + +* Starting with the Windows SDK (22621) or later, platform libraries will generate linker warnings if using clang/LLVM for Windows v14 or earlier. While this warning is harmless, it cannot be suppressed for older toolsets. + +``` +lld-link: warning/error: ignoring unknown debug$S subsection kind 0xFF in file libucrt.lib +``` From 5256a30fc4272083812cd9ddc13b0940f3284ea1 Mon Sep 17 00:00:00 2001 From: Chuck Walbourn Date: Fri, 28 Apr 2023 18:28:09 -0700 Subject: [PATCH 2/5] Code review feedback --- vcpkg/users/platforms/clangcl.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/vcpkg/users/platforms/clangcl.md b/vcpkg/users/platforms/clangcl.md index 45622741..60d3c2fd 100644 --- a/vcpkg/users/platforms/clangcl.md +++ b/vcpkg/users/platforms/clangcl.md @@ -23,7 +23,7 @@ There are two variants of each triplet, selecting between static and dynamic lin | | arm64-clangcl-static | | | | arm64-clangcl-uwp | | -> Note that clang/LLVM for Windows does not support the C++/CX language extensions (``/ZW``, ``/AU``, ``/FU``, ``/WINMD``, and ``#using``) supported by the MSVC ``uwp`` triplets. You can make use of [C++/WinRT language projections](https://learn.microsoft.com/windows/uwp/cpp-and-winrt-apis/) with clang/LLVM for Windows. +> Note that clang/LLVM for Windows does not support the C++/CX language extensions (``/ZW``, ``/AU``, ``/FU``, ``/WINMD``, and ``#using``) supported by the MSVC ``uwp`` triplets. You can make use of [C++/WinRT language projections](/windows/uwp/cpp-and-winrt-apis/) with clang/LLVM for Windows. In addition to triplets for the standard Windows and UWP platforms using clang/LLVM, there are four that target the Xbox platform as well. @@ -42,7 +42,7 @@ The ``static`` linking triplets are set to use the MSVC Runtime as a DLL (i.e. ` The easiest way to make use of clang/LLVM for Windows is to install it as part of the Visual Studio product. You can install them by opening the Visual Studio Installer and choosing **C++ Clang tools for Windows** under **Desktop development with C++** optional components (``Microsoft.VisualStudio.Component.VC.Llvm.Clang`` and/or ``Microsoft.VisualStudio.ComponentGroup.NativeDesktop.Llvm.Clang``). -![Visual Studio 2022 Install UI](https://learn.microsoft.com/en-us/cpp/build/media/clang-install-vs2022.png?view=msvc-170) +![Visual Studio 2022 Install UI](/cpp/build/media/clang-install-vs2022.png) The vcpkg triplets will automatically make use of these tools by default. @@ -54,7 +54,7 @@ If you wish to select a different clang/LLVM for Windows toolset, you can instal set LLVMInstallDir="C:\Program Files\LLVM" ``` -Note that MSBuild uses the same property variable to set a custom version of clang/LLVM as well. Be sure to also set the **LLVMToolsVersion** property variable to the correct value as well. See [Microsoft Learn](https://learn.microsoft.com/cpp/build/clang-support-msbuild?view=msvc-170#custom_llvm_location). +Note that MSBuild uses the same property variable to set a custom version of clang/LLVM as well. Be sure to also set the **LLVMToolsVersion** property variable to the correct value as well. See [Microsoft Learn](/cpp/build/clang-support-msbuild?view=msvc-170#custom_llvm_location). The vcpkg triplets will make use of the toolset pointed to by this variable if present. From 3b6532232cfccf6c57ca1780eca83569da08b8cf Mon Sep 17 00:00:00 2001 From: Chuck Walbourn Date: Fri, 28 Apr 2023 23:43:10 -0700 Subject: [PATCH 3/5] Added maintainers notes --- vcpkg/users/platforms/clangcl.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/vcpkg/users/platforms/clangcl.md b/vcpkg/users/platforms/clangcl.md index 60d3c2fd..2d9df700 100644 --- a/vcpkg/users/platforms/clangcl.md +++ b/vcpkg/users/platforms/clangcl.md @@ -23,8 +23,6 @@ There are two variants of each triplet, selecting between static and dynamic lin | | arm64-clangcl-static | | | | arm64-clangcl-uwp | | -> Note that clang/LLVM for Windows does not support the C++/CX language extensions (``/ZW``, ``/AU``, ``/FU``, ``/WINMD``, and ``#using``) supported by the MSVC ``uwp`` triplets. You can make use of [C++/WinRT language projections](/windows/uwp/cpp-and-winrt-apis/) with clang/LLVM for Windows. - In addition to triplets for the standard Windows and UWP platforms using clang/LLVM, there are four that target the Xbox platform as well. | Console | vcpkg community triplets | @@ -36,7 +34,7 @@ In addition to triplets for the standard Windows and UWP platforms using clang/L The ``static`` linking triplets are set to use the MSVC Runtime as a DLL (i.e. ``VCPKG_CRT_LINKAGE dynamic``) as that's the recommended usage scenario. -> The toolchain file can also support x86 and arm architectures as well, if needed, but those triplet files are left as an excercise to the reader to implement. +> The toolchain file can also support x86 and arm architectures, if needed, but those triplet files are left as an excercise to the reader to implement. ## Visual Studio integration of clang/LLVM for Windows @@ -65,3 +63,15 @@ The vcpkg triplets will make use of the toolset pointed to by this variable if p ``` lld-link: warning/error: ignoring unknown debug$S subsection kind 0xFF in file libucrt.lib ``` + +## Maintainer notes + +The ``clang-cl.exe`` MSVC-like front-end to clang/LLVM for Windows is designed to handle most existing MSVC ``cl.exe`` command-line options. + +* In CMake the ``MSVC`` and ``WIN32`` variables will be set for both cl.exe and clang-cl.exe. + +* ``/Qspectre`` and ``/analyze`` are not supported by the clang-cl.exe front-end. Only add one of these flags for ``CMAKE_CXX_COMPILER_ID`` being set to "MSVC". + +* clang-cl.exe does not support the C++/CX language extensions (``/ZW``, ``/AI``, ``/FU``, ``/WINMD``, and ``#using``) supported by cl.exe. You can make use of [C++/WinRT language projections](/windows/uwp/cpp-and-winrt-apis/) with both MSVC and clang/LLVM for Windows with `set(CMAKE_CXX_STANDARD 17)` + +* clang-cl.exe v12 added support for ``/guard:cf``. clang-cl.exe v13 added support for ``/guard:ehcont``. From b4d170ca1fae8f277fc4101979cbbd9adbd62fa1 Mon Sep 17 00:00:00 2001 From: Chuck Walbourn Date: Sat, 29 Apr 2023 12:40:07 -0700 Subject: [PATCH 4/5] Automated code review fix --- vcpkg/users/platforms/clangcl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vcpkg/users/platforms/clangcl.md b/vcpkg/users/platforms/clangcl.md index 2d9df700..b74c8044 100644 --- a/vcpkg/users/platforms/clangcl.md +++ b/vcpkg/users/platforms/clangcl.md @@ -52,7 +52,7 @@ If you wish to select a different clang/LLVM for Windows toolset, you can instal set LLVMInstallDir="C:\Program Files\LLVM" ``` -Note that MSBuild uses the same property variable to set a custom version of clang/LLVM as well. Be sure to also set the **LLVMToolsVersion** property variable to the correct value as well. See [Microsoft Learn](/cpp/build/clang-support-msbuild?view=msvc-170#custom_llvm_location). +Note that MSBuild uses the same property variable to set a custom version of clang/LLVM as well. Be sure to also set the **LLVMToolsVersion** property variable to the correct value as well. See [Microsoft Learn](/cpp/build/clang-support-msbuild#custom_llvm_location). The vcpkg triplets will make use of the toolset pointed to by this variable if present. From 37d20f734ab45817bf8858255dbe1be9bdbc2975 Mon Sep 17 00:00:00 2001 From: Chuck Walbourn Date: Sat, 29 Apr 2023 14:13:38 -0700 Subject: [PATCH 5/5] Binary compat note --- vcpkg/users/platforms/clangcl.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/vcpkg/users/platforms/clangcl.md b/vcpkg/users/platforms/clangcl.md index b74c8044..57c6afc4 100644 --- a/vcpkg/users/platforms/clangcl.md +++ b/vcpkg/users/platforms/clangcl.md @@ -42,7 +42,7 @@ The easiest way to make use of clang/LLVM for Windows is to install it as part o ![Visual Studio 2022 Install UI](/cpp/build/media/clang-install-vs2022.png) -The vcpkg triplets will automatically make use of these tools by default. +The vcpkg clangcl triplets will automatically make use of these tools by default. ## Selecting a clang/LLVM for Windows Toolset @@ -56,6 +56,12 @@ Note that MSBuild uses the same property variable to set a custom version of cla The vcpkg triplets will make use of the toolset pointed to by this variable if present. +## C/C++ Runtime + +The clang/LLVM for Windows toolset makes use of the Microsoft Visual C/C++ Runtime, so is highly compatible with the MSVC compiler. It will use the version of the CRT that matches the Visual Studio installation. This also ensures that code built with clang/LLVM for Windows and the MSVC compiler are link-compatible. + +Keep in mind that the Microsoft Visual C/C++ Runtime is 'forward binary compatible'. This means you can build code with VS 2015 Update 3, VS 2017, VS 2019, and/or VS 2022 and link it all together. The key requirement is that the LINK must be done against the *newest* toolset in the mix. See [Microsoft Learn](/cpp/porting/binary-compat-2015-2017). + ## Known Issues * Starting with the Windows SDK (22621) or later, platform libraries will generate linker warnings if using clang/LLVM for Windows v14 or earlier. While this warning is harmless, it cannot be suppressed for older toolsets.