Windows
How xclang's MinGW and MSVC Windows targets, the Windows host toolchains, and xclang sdk fetch windows are built and configured. How to compile for Windows targets is in cross-compiling.
Why MinGW and MSVC
xclang provides two pairs of Windows targets because they serve different ABIs:
- MinGW targets (
x86_64-w64-mingw32andaarch64-w64-mingw32): use the Itanium C++ ABI with MinGW-w64 14.0.0 configured on UCRT (--with-default-msvcrt=ucrt,--with-default-win32-winnt=0x0A00). Because MinGW-w64's headers and import libraries are redistributable, their sysroots,libc++,libc++abi,libunwind,winpthreads(libpthread.a) andcompiler-rtship in every toolchain archive and link statically withld.lldout of the box (hermeticity). - MSVC targets (
x86_64-pc-windows-msvcandaarch64-pc-windows-msvc): use the Microsoft C++ ABI and link withlld-linkagainst Microsoft's CRT and the Windows SDK, fetched once withxclang sdk fetch windowsor taken from an installed Visual Studio on Windows. Use the MSVC targets when linking libraries compiled with MSVC, COM-heavy code or Windows vendor SDKs.
The Windows host toolchains (x86_64-w64-mingw32 and aarch64-w64-mingw32) are themselves MinGW programs cross-compiled on Linux x64 with PGO and ThinLTO (PGO).
The SDK without Visual Studio
xclang sdk fetch windows downloads the MSVC CRT and STL from Visual Studio's .vsix packages (listed in Visual Studio's channel manifest) and the Windows SDK from NuGet's Microsoft.Windows.SDK.CPP packages, pinned in xclang/sdk-versions.json. Whereas Visual Studio's installer and tools such as xwin unpack MSI and CAB files (and xwin has no macOS or Windows-on-Arm binaries), both .vsix and .nupkg packages are zip archives that xclang unpacks with its own code on every host.
The unpacked directory (<toolchain>/sdk/windows-msvc<ver>-sdk<ver>) is laid out as a /winsysroot tree matching a Visual Studio installation: the CRT and STL headers, the STL's std.ixx and std.compat.ixx module sources, the per-architecture static and DLL runtime libraries, the .pdb files of the static runtime (which debug links look for and warn with LNK4099 if absent), and the Windows SDK headers and import libraries (um, ucrt, shared, winrt, cppwinrt; the xclang command).
Config Files and Object Directives
A clang config file has no conditionals and fails to load if an included @file does not exist. The MSVC target config files therefore include bin/<triple>-sdk.cfg (and <triple>-clang-cl-sdk.cfg), which is empty in the release archive and rewritten by xclang sdk fetch, use and remove to include the per-architecture config file inside sdk/windows (toolchain structure).
The MSVC target config files also record linker directives in every compiled object file:
--dependent-lib=clang_rt.builtins-<arch>.lib: neitherclangnorclang-cllinkscompiler-rtbuiltins automatically on MSVC targets, and without them__int128division fails to link.--linker-option=/nodefaultlib:libucrt.liband--dependent-lib=ucrt.lib: the hybrid CRT, named inside each object solld-linkhonours it even when a build system invokeslld-linkdirectly. Becauselld-linkreads an object's directives in order and the objects nameucrt.libfirst, switching to/MTdor static UCRT passes/nodefaultlib:ucrt.libon the link command line (/MDusesucrt.libalready).-D_STATIC_INLINE_UCRT_FUNCTIONS=0: UCRT declares functions such asctime,localtimeanddifftimeasstatic inlineunless_STATIC_INLINE_UCRT_FUNCTIONSis0(MSVC 19.50 makes1the default). A C++ module cannot export a function with internal linkage, so the config files define_STATIC_INLINE_UCRT_FUNCTIONS=0to allowimport stdto build.
In CMake and Bazel, xclang compiles and links the MSVC targets with the GNU-style clang++ driver rather than clang-cl. Linking through clang++ reads the target config file on every link, whereas CMake with clang-cl invokes lld-link directly (which reads no config file) and requires mt.exe for manifests (which xclang omits because llvm-mt depends on libxml2).
The Hybrid CRT
By default on MSVC targets, a binary links libc++ (or Microsoft's STL) and the VC runtime (libvcruntime.lib and libcmt.lib) statically, and links UCRT dynamically against Windows' ucrtbase.dll (api-ms-win-crt-*). Microsoft calls this the hybrid CRT: the binary needs no vcruntime140.dll or msvcp140.dll redistributable (hermeticity), while sharing one heap, errno and stdio with every DLL in the process. The flags for selecting another C runtime are in cross-compiling.
libc++ on vcruntime
xclang builds libc++ and compiler-rt for both MSVC architectures with clang-cl against the windows-2022 SDK (MSVC 14.44), since newer MSVC toolsets link libraries built against older ones:
- Built on
vcruntime:libc++uses Microsoft'svcruntimeas its ABI library rather thanlibc++abiandlibunwind;vcruntimehandles exceptions, RTTI andoperator new, while UCRT is the C library. Patch 0016 giveslibc++its ownstd::set_new_handlerwithout Microsoft's STL library and drops its duplicatestd::nothrowdefinition. - One library for every CRT:
libc++is compiled with/MT /Zlso it embeds no default C runtime directive; its calls to UCRT andvcruntimeresolve against either the static libraries or the DLL import libraries. It is also built with_CRT_STDIO_ARBITRARY_WIDE_SPECIFIERSrather than_CRT_STDIO_ISO_WIDE_SPECIFIERS, avoiding/failifmismatcherrors when linked with objects that use Microsoft's default wideprintfspecifiers. The singlelib/clang/<major>/lib/windows/libc++-<arch>.libtherefore links with the hybrid CRT,/MT,/MDand the debug CRTs alike. - Auto-linked by
#pragma comment(lib, ...):libc++-<arch>.liblives next tocompiler-rtinlib/clang/<major>/lib/windows/, the directorylld-linksearches on its own, and the target's__config_sitenames it with#pragma comment(lib, ...). Every translation unit that includes alibc++header linkslibc++-<arch>.libautomatically (even when CMake or MSBuild invokeslld-linkdirectly), while C objects and-stdlib=platformobjects do not. -stdlib++-isystemandimport std:clang's MSVC toolchain ignores-stdlib=, so the default config files supplylibc++'s headers via-stdlib++-isystem(/clang:-stdlib++-isysteminclang-cl, silenced on C compiles by patch 0011). Passing-stdlib=platformswitches to<triple>-system.cfg(patch 0018), which omits-stdlib++-isystemsoclangfinds the SDK's STL headers. Forimport std, the CMake package takeslibc++'s module manifest from<target>/lib/libc++.modules.jsonand<target>/share/libc++/v1(sinceclang -print-library-module-manifest-pathlooks only forlibc++.a), and with-stdlib=platformcompiles the STL'sstd.ixxandstd.compat.ixx(including<malloc.h>before the module onarm64so_allocais not declared twice).
The Launchers
Windows toolchain archives contain no symbolic links because creating symbolic links on Windows requires Developer Mode or Administrator privileges, and conda packages for Windows cannot carry them. Instead, each tool executable in bin/ (clang.exe, clang++.exe, ld.lld.exe, ...) is a small launcher compiled from toolchain/launcher/alias.c that spawns llvm.exe <name> <arguments>:
- Subcommand name: the multicall
llvmbinary selects its tool from the invocation name, and on Windows LLVM replacesargv[0]with the file name of its own module (llvm.exe) before inspecting it. Passing<name>as the first argument preserves the tool identity (clang++vsclang,ld.lldvs genericlld). - Kill-on-close job object: the launcher creates
llvm.exedirectly inside a kill-on-close Windows job object (PROC_THREAD_ATTRIBUTE_JOB_LIST), so when a build system times out or kills the launcher, the compiler process is terminated with it without leaving suspended processes holding handles or working directories. - Process creation cost: each compile starts two processes instead of one. That overhead is visible on tiny C files that compile in milliseconds and negligible on C++ translation units (PGO). Build tools that want to avoid the extra process start can invoke
llvm.exe clang++ ...directly.
gc-sections and Static Initializers
On MinGW targets, ld.lld --gc-sections discards COMDAT sections whose symbols nothing references, including the static initializers that register inline or templated test cases. On ELF targets .init_array is a garbage-collection root so those initializers are kept; on MinGW [[gnu::used]] does not emit a linker /include directive. In clice, enabling --gc-sections for MinGW silently reduced the Windows unit test count from 1,619 to 1,551 as two test suites stopped registering, while leaving it off increased the stripped test binary from 64 MB to 82 MB.
The Bazel module therefore enables gc_sections in optimized builds for Linux targets and leaves it off for Windows targets (--features=gc_sections opts in when a target does not rely on unreferenced COMDAT initializers).
Case-Sensitive Headers
Windows file systems are case-insensitive, so Windows code often writes #include <Windows.h>, <BaseTsd.h> or <WinSock2.h>, whereas MinGW-w64's header files are lowercase (windows.h, basetsd.h, winsock2.h). xclang does not add mixed-case links to the MinGW sysroots; MinGW code must use lowercase header names on case-sensitive Linux file systems.
Microsoft's own CRT, STL and Windows SDK headers and import libraries use mixed spellings internally. When xclang sdk fetch windows unpacks the Windows SDK on a case-sensitive file system, it creates around 3,600 links (windows.h, winbase.h for WinBase.h, libcmt.lib for LIBCMT.lib, BaseTsd.h, Mstcpip.h, Kernel32.lib, Iphlpapi.lib, and others) so Windows code builds without changes.
Visual Studio and compiler-rt
- Finding Visual Studio from a MinGW-built
clang: upstream LLVM builds the Visual Studio Setup API lookup only when compiled with MSVC; a MinGW-builtclangfell back to registry keys for Visual Studio 2010 and older. Patch 0004 (llvm/llvm-project#226794) enables the Setup API lookup on MinGW soclangandlibclang-based tools such as clice find Visual Studio 2017 and later on Windows hosts. compiler-rtbefore Visual Studio's: on a Windows host without a fetched SDK, upstreamclangpassed Visual Studio's library directory tolld-linkbefore xclang'scompiler-rtdirectory, so Visual Studio's ownclang_rt.*.libshadowed xclang's and broke__int128division, UBSan and libFuzzer on Visual Studio 18 (MSVC 14.51). Patch 0012 places xclang'scompiler-rtdirectory first.
The Same Bytes from Every Link
xclang omits PE/COFF timestamps (patch 0014) so repeated compiles and links produce identical binaries. In large PGO and ThinLTO links (such as clice's 600 MB clice.exe), lld-link previously indexed call-graph profile ordering by function name, causing static functions with the same name in different objects to overwrite one another's profile weight depending on hash-table memory addresses; patch 0017 keeps the first entry so every link produces the same bytes.
ASan's DLL
compiler-rt builds only a dynamic AddressSanitizer runtime on Windows, for MinGW and MSVC targets alike: libclang_rt.asan_dynamic.dll and clang_rt.asan_dynamic-x86_64.dll. Every ASan-instrumented binary loads that DLL at startup from its own directory or PATH, as a test-only exception to hermeticity (sanitizers):
- MinGW's ASan DLL links
libc++andlibunwindstatically: unlikellvm-mingw's ASan DLL, which loadslibc++.dll, xclang's MinGW DLL depends only on Windows system DLLs and UCRT, while the program links the ASan-instrumentedlibc++. MSVC's ASan DLL (clang_rt.asan_dynamic-x86_64.dll) is linked bycompiler-rtagainst the dynamic VC runtime (vcruntime140.dll). - Included in
bin/on thex86_64Windows host: thex86_64Windows toolchain archive places copies of both the MinGW and MSVC ASan DLLs inbin/, so ASan binaries find their runtime whenever the toolchain is onPATH. When copying an ASan binary to another machine, copy the DLL beside it. - Copied beside binaries in Bazel: a Bazel build with
--features=asanreceives the DLL from@bazel_tools//tools/cpp:cc_runtimes_toolchain_type, and thecopy_dynamic_libraries_to_binaryfeature copies it next to the binary inbazel-binand in its runfiles forbazel runandbazel test. - Not supported under Windows on Arm's
x86_64emulator: anx86_64ASan binary cannot intercept UCRT functions when running underarm64Windows' emulation ofx86_64.
