From a2910ce5b494c211780d5ca296f99785082fae75 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mateusz=20Miku=C5=82a?= Date: Fri, 5 Dec 2025 20:16:15 +0100 Subject: [PATCH] Update windows-gnullvm platform support doc --- .../src/platform-support/windows-gnullvm.md | 54 +++++++++---------- 1 file changed, 26 insertions(+), 28 deletions(-) diff --git a/src/doc/rustc/src/platform-support/windows-gnullvm.md b/src/doc/rustc/src/platform-support/windows-gnullvm.md index b469af0153130..e5db656e89f7a 100644 --- a/src/doc/rustc/src/platform-support/windows-gnullvm.md +++ b/src/doc/rustc/src/platform-support/windows-gnullvm.md @@ -2,9 +2,11 @@ **Tier: 2 (with host tools)** -Windows targets similar to `*-windows-gnu` but using UCRT as the runtime and various LLVM tools/libraries instead of GCC/Binutils. +Windows targets similar to `*-windows-gnu` but using UCRT as the runtime and various LLVM tools/libraries instead of +GCC/Binutils. Target triples available so far: + - `aarch64-pc-windows-gnullvm` - `i686-pc-windows-gnullvm` - `x86_64-pc-windows-gnullvm` @@ -16,10 +18,11 @@ Target triples available so far: ## Requirements -The easiest way to obtain these targets is cross-compilation, but native build from `x86_64-pc-windows-gnu` is possible with few hacks which I don't recommend. -Std support is expected to be on par with `*-windows-gnu`. +Building those targets requires an LLVM-based C toolchain, for example, [llvm-mingw][1] or [MSYS2][2] with CLANG* +environment. -Binaries for this target should be at least on par with `*-windows-gnu` in terms of requirements and functionality. +Binaries for this target should be at least on par with `*-windows-gnu` in terms of requirements and functionality, +except for implicit self-contained mode (explained in [the section below](#building-rust-programs)). Those targets follow Windows calling convention for `extern "C"`. @@ -27,37 +30,32 @@ Like with any other Windows target, created binaries are in PE format. ## Building the target -These targets can be easily cross-compiled -using [llvm-mingw](https://github.com/mstorsjo/llvm-mingw) toolchain or [MSYS2 CLANG*](https://www.msys2.org/docs/environments/) environments. -Just fill `[target.*]` sections for both build and resulting compiler and set installation prefix in `bootstrap.toml`. -Then run `./x.py install`. -In my case I had ran `./x.py install --host x86_64-pc-windows-gnullvm --target x86_64-pc-windows-gnullvm` inside MSYS2 MINGW64 shell -so `x86_64-pc-windows-gnu` was my build toolchain. - -Native bootstrapping is doable in two ways: -- cross-compile gnullvm host toolchain and use it as build toolchain for the next build, -- copy libunwind libraries and rename them to mimic libgcc like here: https://github.com/msys2/MINGW-packages/blob/68e640756df2df6df6afa60f025e3f936e7b977c/mingw-w64-rust/PKGBUILD#L108-L109, stage0 compiler will be mostly broken but good enough to build the next stage. - -The second option might stop working anytime, so it's not recommended. +Both native and cross-compilation builds are supported and function similarly to other Rust targets. ## Building Rust programs -Rust does ship a pre-compiled std library for those targets. -That means one can easily cross-compile for those targets from other hosts if C proper toolchain is installed. +Rust ships both std and host tools for those targets. That allows using them as both the host and the target. -Alternatively full toolchain can be built as described in the previous section. +When used as the host and building pure Rust programs, no additional C toolchain is required. +The only requirements are to install `rust-mingw` component and to set `rust-lld` as the linker. +Otherwise, you will need to install the C toolchain mentioned previously. +There is no automatic fallback to `rust-lld` when the C toolchain is missing yet, but it may be added in the future. ## Testing -Created binaries work fine on Windows or Wine using native hardware. Testing AArch64 on x86_64 is problematic though and requires spending some time with QEMU. -Most of x86_64 testsuite does pass when cross-compiling, -with exception for `rustdoc` and `ui-fulldeps` that fail with and error regarding a missing library, -they do pass in native builds though. -The only failing test is std's `process::tests::test_proc_thread_attributes` for unknown reason. +Created binaries work fine on Windows and Linux with Wine using native hardware. +Testing AArch64 on x86_64 is problematic, though, and requires launching a whole AArch64 system with QEMU. + +Most of the x86_64 testsuite does pass, but because it isn't run on CI, different failures are expected over time. ## Cross-compilation toolchains and C code -Compatible C code can be built with Clang's `aarch64-pc-windows-gnu`, `i686-pc-windows-gnullvm` and `x86_64-pc-windows-gnu` targets as long as LLVM-based C toolchains are used. -Those include: -- [llvm-mingw](https://github.com/mstorsjo/llvm-mingw) -- [MSYS2 with CLANG* environment](https://www.msys2.org/docs/environments) +Compatible C code can be built with Clang's `aarch64-pc-windows-gnu`, `i686-pc-windows-gnullvm` and +`x86_64-pc-windows-gnu` targets as long as LLVM-based C toolchains are used. Those include: + +- [llvm-mingw][1] +- [MSYS2][2] with CLANG* environment + +[1]: https://github.com/mstorsjo/llvm-mingw + +[2]: https://www.msys2.org/docs/environments