Update dev guide with cross checking guides

.cargo/config.windows-cross.example.toml

@@ -0,0 +1,19 @@
+# Windows cross-checking for #[cfg(windows)] code on UNIX clippy config
+# NOTE: requires a working cross-compiler.
+# see https://rust-lang.github.io/rustup/dev-guide/linting.html#checking-windows-specific-code-on-unix
+
+[build]
+target = "x86_64-pc-windows-gnu"
+
+# For clang only: uncomment and append the clang sysroot option per your distro
+# NOTE: may need explicit sysroot config
+# see Sysroot Matrix on https://rust-lang.github.io/rustup/dev-guide/linting.html#lint-1
+# [env]
+# without explicit sysroot
+# CC_x86_64_pc_windows_gnu = { value = "clang", force = true }
+
+# with explicit sysroot
+# CC_x86_64_pc_windows_gnu = { value = "clang --sysroot=<sysroot>", force = true }
+
+# [target.x86_64-pc-windows-gnu]
+# linker = "clang"

.gitignore

@@ -4,6 +4,7 @@
 /.settings
 /.idea/
 /.vscode/
+rust-analyzer.toml
 *~
 /**/target
 /home

doc/dev-guide/src/coding-standards.md

@@ -400,10 +400,17 @@ which can build up over time.
 
 ## Writing platform-specific code
 
-For developers using BSD/Linux/Mac OS, there are Windows VMs suitable for such
-development tasks for use with virtualbox and other hypervisors are downloadable
-from
-[Microsoft](https://developer.microsoft.com/en-us/windows/downloads/virtual-machines/).
-Similarly, there are many Linux and Unix operating systems images available for
-developers whose usual operating system is Windows. Currently Rustup has no Mac
-OS specific code, so there should be no need to worry about Mac VM images.
+If you are on Unix and would like to develop Windows-specific code
+(`#[cfg(windows)]`), you can [check and lint your code
+locally](linting.md#checking-windows-specific-code-on-unix) before pushing the
+code and leaving the rest to our CI as long as the relevant test cases are in
+place.
+
+In the rare case where you would like to test Windows-specific behavior
+yourself, you can use one of [Microsoft's developer VM
+images](https://developer.microsoft.com/en-us/windows/downloads/virtual-machines/).
+
+For developing Unix-specific code (`#[cfg(unix)]`) on Windows, it is
+recommended to use
+[WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) for a full Linux
+environment.

doc/dev-guide/src/linting.md

@@ -28,36 +28,130 @@ activating only the `test` feature by replacing `--all-features` with `--feature
 
 ## Rust-Analyzer
 
-When checking the codebase using `rust-analyzer`, the first thing to do remains unchanged:
-enabling the features.
+To work with the codebase using `rust-analyzer`, you may want to configure it
+upfront. To do so, you can find an example configuration file in
+`rust-analyzer.example.toml` in the root of the repository. Then, you can copy
+it to `rust-analyzer.toml` and adjust the settings as needed.
 
-This is done by setting the `rust-analyzer.cargo.features` property to `"all"`.
+You might also want to refer to the
+[`rust-analyzer` manual](https://rust-analyzer.github.io/manual.html#configuration)
+for more details on properly setting up `rust-analyzer` in your IDE of choice.
+
+If you are using `rust-analyzer` within VSCode, you may also add the
+corresponding configuration items to your project's
+`.vscode/settings.json`[^vscode-global-cfg]. For example:
+
+```toml
+[cargo]
+features = "all"
+```
 
-For example, if you are using `rust-analyzer` within VSCode, you would want to
-add the following to your project's `.vscode/settings.json`[^vscode-global-cfg]:
+... will become:
 
 ```jsonc
 "rust-analyzer.cargo.features": "all",
 ```
 
 [^vscode-global-cfg]:
-    Alternatively, if you want to apply the configuration to all your Rust projects,
-    you can add it to your global configuration at `~/.config/Code/User/settings.json` instead.
+    Alternatively, if you want to apply the configuration to all your Rust
+    projects, you can add them to your global configuration at
+    `~/.config/Code/User/settings.json` instead.
 
-Alternatively, if you want to enable the `test` feature only, you should set the
-following instead:
+## Checking Windows-specific code on Unix
 
-```jsonc
-"rust-analyzer.cargo.features": ["test"]
+You can lint Windows-specific code (`#[cfg(windows)]`) without a Windows VM
+with `cargo clippy` targeting `x86_64-pc-windows-gnu`.
+
+> **Note**: This is for linting and diagnosis only. For building
+> distributable Windows binaries, prefer relying on our CI.
+
+### Prerequisites
+
+You need to install the corresponding cross-compilation target first:
+
+```console
+$ rustup target add x86_64-pc-windows-gnu
 ```
 
-Next, as `rust-analyzer` depends on `cargo check` by default, it is also recommended to
-enable the `cargo clippy` integration by adding the following:
+### Recommended method: mingw-w64 gcc
 
-```jsonc
-"rust-analyzer.check.command": "clippy",
+This is the most reliable approach across all platforms. The full gcc
+cross-toolchain includes its own sysroot, so no manual `--sysroot` tuning
+is needed.
+
+#### Install the dependencies
+
+| Platform      | Install Command                         |
+| ------------- | --------------------------------------- |
+| Debian/Ubuntu | `sudo apt install gcc-mingw-w64-x86-64` |
+| Fedora        | `sudo dnf install mingw64-gcc`          |
+| Arch Linux    | `sudo pacman -S mingw-w64-gcc`          |
+| macOS         | `brew install mingw-w64`                |
+
+#### Lint
+
+In most cases with mingw-w64-gcc, cargo auto-detects the cross-compiler:
+
+```console
+$ cargo clippy --target x86_64-pc-windows-gnu
 ```
 
-You might also want to refer to the
-[`rust-analyzer` manual](https://rust-analyzer.github.io/manual.html#configuration)
-for more details on properly setting up `rust-analyzer` in your IDE of choice.
+Or modify `.cargo/config.windows-cross.example.toml` based on sysroot matrix, then copy it as `.cargo/config.windows-cross.toml`.
+
+```console
+$ cargo clippy --config .cargo/config.windows-cross.toml
+```
+
+If your distro does not auto-detect, set the compiler explicitly:
+
+```console
+$ CC_x86_64_pc_windows_gnu=x86_64-w64-mingw32-gcc \
+  CARGO_TARGET_X86_64_PC_WINDOWS_GNU_LINKER=x86_64-w64-mingw32-gcc \
+  cargo clippy --target x86_64-pc-windows-gnu
+```
+
+### Alternate method: clang + mingw-w64 headers
+
+This uses a lighter install (clang + headers only instead of full gcc
+toolchain), but requires per-distro sysroot tuning because clang does not
+always auto-detect the correct MinGW header paths.
+
+#### Install the dependencies
+
+| Platform      | Install Command                                                |
+| ------------- | -------------------------------------------------------------- |
+| Debian/Ubuntu | `sudo apt install clang mingw-w64-x86-64-dev`                  |
+| Fedora        | `sudo dnf install clang mingw64-headers mingw64-winpthreads`   |
+| Arch Linux    | `sudo pacman -S clang mingw-w64-headers mingw-w64-winpthreads` |
+
+#### Lint
+
+When running `clippy`, you may need to inform the Rust toolchain of your sysroot, which requires passing a `cargo` config either via a file or with environment variables.
+
+_Sysroot Matrix_
+
+| Platform      | Need explicit sysroot | Sysroot                                |
+| ------------- | --------------------- | -------------------------------------- |
+| Debian/Ubuntu | Yes                   | /usr/x86_64-w64-mingw32                |
+| Fedora        | No                    | /usr/x86_64-w64-mingw32/sys-root/mingw |
+| Arch Linux    | No                    | /usr/x86_64-w64-mingw32                |
+
+Modify `.cargo/config.windows-cross.example.toml` based on sysroot matrix, then copy it as `.cargo/config.windows-cross.toml`.
+
+```console
+$ cargo clippy --config .cargo/config.windows-cross.toml
+```
+
+Or, you can pass them as environment variables directly, e.g.:
+
+```console
+$ CC_x86_64_pc_windows_gnu="clang --sysroot=/usr/x86_64-w64-mingw32" \
+  CARGO_TARGET_X86_64_PC_WINDOWS_GNU_LINKER=clang \
+  cargo clippy --target x86_64-pc-windows-gnu
+```
+
+### Rust-Analyzer
+
+It is also possible for the above setup to work with `rust-analyzer`. See the
+relevant sections in the [example configuration](#rust-analyzer) for more
+information.

rust-analyzer.example.toml

@@ -0,0 +1,29 @@
+# Example rust-analyzer config for rustup development.
+# Copy and rename to rust-analyzer.toml for recommended linting and diagnostics.
+
+[check]
+# Use clippy for checking
+command = "clippy"
+
+[cargo]
+# Enable the "test" feature for test-specific code
+features = ["test"]
+
+# Alternatively, enable all features if needed
+# features = "all"
+
+# Uncomment the section below to enable Windows cross-checking for #[cfg(windows)] code on UNIX.
+# NOTE: requires a working cross-compiler.
+# see https://rust-lang.github.io/rustup/dev-guide/linting.html#checking-windows-specific-code-on-unix
+# target = "x86_64-pc-windows-gnu"
+
+# For clang only: uncomment and append the clang sysroot option per your distro
+# NOTE: may need explicit sysroot config.
+# see https://rust-lang.github.io/rustup/dev-guide/linting.html#lint-1
+# [cargo.extraEnv]
+# CC_x86_64_pc_windows_gnu = "clang"
+# CARGO_TARGET_X86_64_PC_WINDOWS_GNU_LINKER = "clang"
+
+[diagnostics]
+# Disable all dimming of inactive code due to current `cfg`
+disabled = ["inactive-code"]