diff --git a/src/doc/rustc/src/SUMMARY.md b/src/doc/rustc/src/SUMMARY.md index a3939e5a5c451..201a550307972 100644 --- a/src/doc/rustc/src/SUMMARY.md +++ b/src/doc/rustc/src/SUMMARY.md @@ -113,6 +113,7 @@ - [\*-unknown-openbsd](platform-support/openbsd.md) - [\*-unknown-redox](platform-support/redox.md) - [\*-unknown-uefi](platform-support/unknown-uefi.md) + - [\*-unknown-windows-msvc](platform-support/windows-msvc.md) - [\*-uwp-windows-msvc](platform-support/uwp-windows-msvc.md) - [\*-wrs-vxworks](platform-support/vxworks.md) - [wasm32-wasip1](platform-support/wasm32-wasip1.md) diff --git a/src/doc/rustc/src/platform-support.md b/src/doc/rustc/src/platform-support.md index 559e4867bbb10..3cab57df75a82 100644 --- a/src/doc/rustc/src/platform-support.md +++ b/src/doc/rustc/src/platform-support.md @@ -34,11 +34,11 @@ target | notes -------|------- [`aarch64-apple-darwin`](platform-support/apple-darwin.md) | ARM64 macOS (11.0+, Big Sur+) `aarch64-unknown-linux-gnu` | ARM64 Linux (kernel 4.1+, glibc 2.17+) -`i686-pc-windows-msvc` | 32-bit MSVC (Windows 10+, Windows Server 2016+, Pentium 4) [^x86_32-floats-return-ABI] [^win32-msvc-alignment] +[`i686-pc-windows-msvc`](platform-support/windows-msvc.md) | 32-bit MSVC (Windows 10+, Windows Server 2016+, Pentium 4) [^x86_32-floats-return-ABI] [^win32-msvc-alignment] `i686-unknown-linux-gnu` | 32-bit Linux (kernel 3.2+, glibc 2.17+, Pentium 4) [^x86_32-floats-return-ABI] [`x86_64-apple-darwin`](platform-support/apple-darwin.md) | 64-bit macOS (10.12+, Sierra+) [`x86_64-pc-windows-gnu`](platform-support/windows-gnu.md) | 64-bit MinGW (Windows 10+, Windows Server 2016+) -`x86_64-pc-windows-msvc` | 64-bit MSVC (Windows 10+, Windows Server 2016+) +[`x86_64-pc-windows-msvc`](platform-support/windows-msvc.md) | 64-bit MSVC (Windows 10+, Windows Server 2016+) `x86_64-unknown-linux-gnu` | 64-bit Linux (kernel 3.2+, glibc 2.17+) [^x86_32-floats-return-ABI]: Due to limitations of the C ABI, floating-point support on `i686` targets is non-compliant: floating-point return values are passed via an x87 register, so NaN payload bits can be lost. Functions with the default Rust ABI are not affected. See [issue #115567][x86-32-float-return-issue]. @@ -88,7 +88,7 @@ so Rustup may install the documentation for a similar tier 1 target instead. target | notes -------|------- -`aarch64-pc-windows-msvc` | ARM64 Windows MSVC +[`aarch64-pc-windows-msvc`](platform-support/windows-msvc.md) | ARM64 Windows MSVC `aarch64-unknown-linux-musl` | ARM64 Linux with musl 1.2.3 [`aarch64-unknown-linux-ohos`](platform-support/openharmony.md) | ARM64 OpenHarmony `arm-unknown-linux-gnueabi` | Armv6 Linux (kernel 3.2+, glibc 2.17) diff --git a/src/doc/rustc/src/platform-support/windows-msvc.md b/src/doc/rustc/src/platform-support/windows-msvc.md new file mode 100644 index 0000000000000..71dc4ddc2e65c --- /dev/null +++ b/src/doc/rustc/src/platform-support/windows-msvc.md @@ -0,0 +1,69 @@ +# `*-pc-windows-msvc` + +Windows MSVC targets. + +**Tier 1 with host tools:** + +- `i686-pc-windows-msvc`: Windows on 32-bit x86. +- `x86_64-pc-windows-msvc`: Windows on 64-bit x86. + +**Tier 2 with host tools:** + +- `aarch64-pc-windows-msvc`: Windows on ARM64. + +## Target maintainers + +[@ChrisDenton](https://github.com/ChrisDenton) +[@dpaoliello](https://github.com/dpaoliello) +[@lambdageek](https://github.com/lambdageek) +[@sivadeilra](https://github.com/sivadeilra) +[@wesleywiser](https://github.com/wesleywiser) + +## Requirements + +### OS version + +Windows 10 or higher is required for client installs, Windows Server 2016 or higher is required for server installs. + +### Host tooling + +The minimum supported Visual Studio version is 2017 but this support is not actively tested in CI. +It is **highly** recommended to use the latest version of VS (currently VS 2022). + +### Platform details + +These targets fully implement the Rust standard library. + +The `extern "C"` calling convention conforms to Microsoft's default calling convention for the given architecture: [`__cdecl`] on `i686`, [`x64`] on `x86_64` and [`ARM64`] on `aarch64`. + +The `*-windows-msvc` targets produce PE/COFF binaries with CodeView debuginfo, the native formats used on Windows. + +[`__cdecl`]: https://learn.microsoft.com/en-us/cpp/cpp/cdecl?view=msvc-170 +[`x64`]: https://learn.microsoft.com/en-us/cpp/build/x64-calling-convention?view=msvc-170 +[`ARM64`]: https://learn.microsoft.com/en-us/cpp/build/arm64-windows-abi-conventions?view=msvc-170 + +## Building Rust programs + +These targets are distributed via `rustup` and can be installed via `rustup component add [--toolchain {name}] {target}`. + +For example, adding the 32-bit x86 target to the `nightly` toolchain: + +```text +rustup component add --toolchain nightly i686-pc-windows-msvc +``` + +or adding the ARM64 target to the active toolchain: + +```text +rustup component add aarch64-pc-windows-msvc +``` + +## Testing + +There are no special requirements for testing and running this target. + +## Cross-compilation toolchains and C code + +Architectural cross-compilation from one Windows host to a different Windows platform is natively supported by the MSVC toolchain provided the appropriate components are selected when using the VS Installer. + +Cross-compilation from a non-Windows host to a `*-windows-msvc` target _may_ be possible but is not supported.