#31507 build: Use clang-cl to build on Windows natively
https://github.com/bitcoin/bitcoin/pull/31507 · · +131/-94 in 10 files, 6 commits · labels: Windows, Build system
Goal
- Eliminate recurring MSVC compiler crashes and custom workarounds on native Windows builds
- Produce faster Windows binaries and cut CI compilation times
This pull request migrates native Windows builds and CI from MSVC (cl.exe) to clang-cl and drops support for building with MSVC. It adjusts CMake compiler configuration and diagnostic flags, links against the clang_rt builtins library on Windows, and updates build presets and documentation.
Problem: MSVC has caused persistent maintenance friction due to internal compiler errors (such as #31456) and lacks support for inline assembly on x64 and ARM64. It also produces slower binaries and incurs significantly longer CI compile times than Clang.
Category: Build and CI (#5 of 55)
P2 · platform fix
- P2 because it resolves recurring MSVC compiler crashes and toolchain maintenance overhead
- Significantly boosts Windows execution performance and cuts CI build times from ~20 to ~12 minutes
P2 because replacing MSVC with clang-cl eliminates a persistent maintenance headache of MSVC internal compiler errors (e.g. #31456) and reduces Windows CI duration from 20m to 12m. Additionally, benchmarks show substantial improvements in block connection throughput on Windows (from ~7.4 to ~11.5 blocks/sec).
Membership: Changes CMake build configuration, compiler toolchain, and CI scripts for Windows native builds.
Factors: security/stability 1, bug 1, performance 2, user value 1, leverage 2
Reviewability: Ready
- Ready for review, with CI passing and Concept ACKs on the current head commit
The core toolchain switch is complete and CI passes. Remaining open questions concern minor doc renames and warning flag policy in CI that will not invalidate code review.
Author status: silent since 2026-08-12; previously actively addressing rebase and review requests
Open concerns:
- maflcko asked on 2026-08-18 whether suppressing -Wno-return-type in CI hides potential standard violations or undefined behavior, suggesting it should be fixed or reported upstream.
- hodlinator noted a few polish items on 2026-08-18 (renaming build-windows-msvc.md, removing a dead MSVC byteswap #elif branch, and winget flags).
Resolved concerns:
- fanquake was skeptical of maintaining multiple Windows toolchains; resolved when the author updated the PR to completely drop MSVC support instead of supporting both.
- Undefined symbol errors on Qt and 128-bit integers were resolved by linking shlwapi and clang_rt builtins.
Agreement: Mild
- Strong support for switching native Windows builds to clang-cl and dropping MSVC (fanquake, hodlinator, maflcko)
- Concept approval on the condition that MSVC support is dropped entirely (fanquake)
- Supported merging early for the 32.0 release window (maflcko)
Concept supported by fanquake and hodlinator; maflcko has an open nonblocking concern about CI warning suppression.
The transition from MSVC to clang-cl has strong maintainer concept support, particularly after MSVC support was dropped rather than maintained in parallel. One minor nonblocking concern about CI warning flags remains unanswered by the author.
- fanquake (2026-02-06): 'I think I'd be more concept-ACK here, if it included removing support for MSVC, at the same time.'
- hodlinator (2026-08-20): 'Concept ACK ec347d1108d57d682bdc239558b8ca2660be6a3a'
- maflcko (2026-08-18): 'Is this a violation of the C++26 standard? ... If not, it should not be hidden'
Objections:
| Reviewer | Kind | Harm | Status | Blocking | Author replied | Quote |
|---|---|---|---|---|---|---|
| maflcko | correctness | Suppressing -Wno-return-type in CI may hide C++ standard violations or potential undefined behavior. | open | no | no | 2026-08-18: 'Is this a violation of the C++26 standard? ... If not, it should not be hidden, to be able to confirm it.' |
| fanquake | maintenance | increases CI and maintenance burden by adding another compiler for Windows without improving shipped binaries or replacing MSVC | resolved | yes | yes | 2025-05-21: 'Reading the description, I\'m still not really clear on the goals here. It seems like this is just adding even more ways to compile for Windows, which we have to add more CI / and more work arounds for, but doesn\'t actually improve the Windows binaries we are shipping to end users in any way.' Settled: 2026-02-19: 'The support for MSVC has been removed.' |
Support:
- fanquake: Favors dropping MSVC completely in favor of clang-cl to avoid maintaining multiple Windows toolchains.
- hodlinator: Tested native Windows build successfully and gave Concept ACK.
- maflcko: increases build compatibility, enables evaluating codegen differences, and can help detect compiler bugs
Participants: maflcko (objection), fanquake (objection), theuni (question), hodlinator (support)
State derived from the lists: nonblocking objection open (maflcko)
Review verdicts (DrahtBot): 0
- Concept ACK: fanquake, hodlinator
Dependencies
Enables:
- Unblocks dropping MSVC-specific workarounds and enabling inline assembly optimizations on Windows (e.g. secp256k1)
Files
0 lines under test/bench/ci.
- CMakeLists.txt +70/-58
- doc/build-windows-msvc.md +13/-10
- .github/ci-windows.py +14/-2
- doc/release-notes-31507.md +15/-0
- CMakePresets.json +6/-8
- cmake/leveldb.cmake +6/-7
- src/compat/byteswap.h +3/-5
- .github/workflows/ci.yml +2/-2
- cmake/module/TryAppendCXXFlags.cmake +1/-1
- src/qt/CMakeLists.txt +1/-1
Card
This PR switches native Windows builds and CI from MSVC (cl.exe) to clang-cl, dropping MSVC support entirely. It resolves recurring MSVC-specific internal compiler errors (#31456), reduces Windows CI runtime from ~20 to ~12 minutes, and demonstrates notable benchmark speedups in block connection. Reviewers support the change following the decision to drop MSVC rather than support both toolchains simultaneously. Review is ready, with minor open comments on CI warning flags and documentation wording.