test(e2e),ci,docs: bare-Windows axis, spaced paths, MSVC build.mcpp

CI gains the Windows shapes it never had. windows-fresh becomes a matrix over
windows-2022 and windows-2025 — GitHub publishes no Windows CLIENT image, so
those Server builds are the closest stand-ins for the Win10 and Win11 kernel
generations; genuinely client-only behaviour (UAC, Defender, long-path policy)
still needs a self-hosted runner and is called out as uncovered.

windows-nomsvc-fresh masks Visual Studio, because no VS-free runner exists.
Masking risks a false green — miss one of msvc.cppm's three discovery
strategies and mcpp still finds MSVC, takes the old path and passes while
proving nothing — so e2e 182 opens by asserting that detection FAILS. It then
checks the fallback, that both axes persist, that the exe runs with the
toolchain off PATH, and that an explicit [toolchain] is refused rather than
swapped.

e2e 179 (spaced paths) asserts on the generated ninja file, not just on the
build succeeding: a split include flag can still compile by luck. e2e 180
fills the empty `MSVC x build.mcpp` cell, including the link-lib translation
and the module refusal.

Docs: the winlibs route moves from a footnote to the stated default, and the
three `[build] linkage` mentions are corrected — the parser only reads
`linkage` under `[target.<triple>]`, so that key was silently ignored
everywhere it was documented.

Author: Sunrisepeak

.github/workflows/ci-fresh-install.yml

@@ -374,14 +374,26 @@ jobs:
           mcpp run
 
   # ──────────────────────────────────────────────────────────────────
-  # Windows: llvm@20.1.7 + MSVC STL
+  # Windows WITH Visual Studio: llvm@20.1.7 + MSVC STL
+  #
+  # Two images, because the OS version is a real variable for a tool that
+  # touches the UCRT, the Windows SDK and long paths. GitHub publishes no
+  # Windows 10/11 CLIENT image, so these Server builds are the closest
+  # available stand-ins: windows-2022 is the Win10 21H2 kernel generation,
+  # windows-2025 the Win11 24H2 one. What they cannot cover is genuinely
+  # client-only behaviour — UAC prompts, Defender real-time scanning, the
+  # long-path policy default — which needs a self-hosted runner.
   # ──────────────────────────────────────────────────────────────────
   windows-fresh:
     needs: [wait-index]
-    name: Windows fresh install
+    name: Windows fresh install (${{ matrix.image }})
     if: ${{ github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success' }}
-    runs-on: windows-latest
+    runs-on: ${{ matrix.image }}
     timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        image: [windows-2022, windows-2025]
     env:
       # The one derived value (see the header comment): every install job names
       # the SAME version the index guard waited for, so the two cannot disagree.
@@ -437,3 +449,77 @@ jobs:
         run: |
           mcpp clean
           mcpp run
+
+  # ──────────────────────────────────────────────────────────────────
+  # Windows WITHOUT Visual Studio — the shape of an ordinary user's machine
+  #
+  # A stock Windows install ships the UCRT runtime DLLs and nothing else: the
+  # MSVC STL and the Windows SDK arrive only with Visual Studio's "Desktop
+  # development with C++" workload. mcpp's Windows default targeted the MSVC
+  # ABI, so `mcpp new && mcpp build` failed on every such box — and no CI job
+  # could see it, because every GitHub Windows image ships Visual Studio.
+  #
+  # There is no VS-free runner, so the image is masked instead. The risk with
+  # masking is a false green: miss one of msvc.cppm's three discovery
+  # strategies (vswhere, environment, well-known paths) and mcpp still finds
+  # MSVC, takes the ordinary path, and the job passes while proving nothing.
+  # e2e 182 opens by asserting `mcpp toolchain default msvc` FAILS, which
+  # turns exactly that into a hard failure.
+  # ──────────────────────────────────────────────────────────────────
+  windows-nomsvc-fresh:
+    needs: [wait-index]
+    name: Windows fresh install (no Visual Studio)
+    if: ${{ github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success' }}
+    runs-on: windows-2025
+    timeout-minutes: 30
+    env:
+      MCPP_PIN: ${{ needs.wait-index.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Mask Visual Studio
+        shell: pwsh
+        run: |
+          # All three discovery strategies at once. The runner is disposable,
+          # so renaming in place is fine and is closer to "absent" than any
+          # env-only trick would be.
+          $vswhere = "C:\Program Files (x86)\Microsoft Visual Studio\Installer\vswhere.exe"
+          if (Test-Path $vswhere) { Rename-Item $vswhere "vswhere.exe.masked" }
+
+          Get-ChildItem "C:\Program Files*\Microsoft Visual Studio" -Directory `
+              -ErrorAction SilentlyContinue | ForEach-Object {
+            $masked = "$($_.FullName).masked"
+            if (-not (Test-Path $masked)) { Rename-Item $_.FullName $masked }
+          }
+
+          foreach ($v in @('VSINSTALLDIR','VCINSTALLDIR','VCToolsInstallDir',
+                           'VS170COMNTOOLS','VS160COMNTOOLS','VS150COMNTOOLS')) {
+            "$v=" | Out-File -Append -FilePath $env:GITHUB_ENV -Encoding utf8
+          }
+
+      - name: Install xlings
+        shell: pwsh
+        env:
+          XLINGS_NON_INTERACTIVE: '1'
+        run: |
+          irm https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.ps1 | iex
+
+          $xlingsbin = "$env:USERPROFILE\.xlings\subos\current\bin"
+          $env:PATH = "$xlingsbin;$env:PATH"
+          $xlingsbin | Out-File -Append -FilePath $env:GITHUB_PATH -Encoding utf8
+
+      - name: Install mcpp and config mirror
+        shell: pwsh
+        run: |
+          xlings update
+          xlings install "mcpp@$env:MCPP_PIN" -y -g --verbose
+          mcpp --version
+          mcpp self config --mirror GLOBAL
+
+      # The self-check, the fallback, persistence, a self-contained exe, and
+      # the refusal to overrule an explicit [toolchain] — all in e2e 182, so
+      # the assertions live with the tests rather than in workflow YAML.
+      - name: "No Visual Studio: fallback to winlibs GCC (e2e 182)"
+        shell: bash
+        run: |
+          MCPP="$(command -v mcpp)" bash tests/e2e/182_windows_no_msvc_fallback.sh

.github/workflows/ci-windows.yml

@@ -292,6 +292,12 @@ jobs:
           cd "$GITHUB_WORKSPACE"
           MCPP="$MCPP_SELF" bash tests/e2e/99_msvc_native_build.sh
 
+          # build.mcpp under cl.exe. `MSVC x build.mcpp` was an empty cell in
+          # this matrix and the feature was correspondingly at zero — the ten
+          # build.mcpp e2e all run under clang, whose payload path has no
+          # spaces in it either. Both gaps closed here.
+          MCPP="$MCPP_SELF" bash tests/e2e/180_msvc_build_mcpp.sh
+
           # restore the LLVM default for the remaining steps
           "$MCPP_SELF" toolchain default llvm@20.1.7
 

README.md

@@ -294,8 +294,8 @@ the right toolchain payload is resolved and installed automatically.
 | `x86_64-linux-gnu`    | gcc *(Linux default)* or llvm | ✅ |
 | `x86_64-linux-musl`   | gcc 16, fully static | ✅ |
 | `aarch64-linux-musl`  | gcc 16, fully static — cross from x86_64 (qemu-verified) or native | ✅ |
-| `x86_64-windows-gnu`  | gcc 16 MinGW-w64 — native on Windows, cross from Linux (wine-verified) | ✅ |
-| `x86_64-windows-msvc` | `msvc@system` (detected VS/BuildTools) or llvm ¹ *(Windows default)* | ✅ |
+| `x86_64-windows-gnu`  | gcc 16 MinGW-w64 — native on Windows, cross from Linux (wine-verified) *(Windows default without Visual Studio)* | ✅ |
+| `x86_64-windows-msvc` | `msvc@system` (detected VS/BuildTools) or llvm ¹ *(Windows default with Visual Studio)* | ✅ |
 | `aarch64-macos`       | llvm *(macOS default)* | ✅ |
 | `riscv64-linux-musl`  | — | 🔄 |
 | `aarch64-linux-gnu`   | — | 🔄 |
@@ -308,10 +308,14 @@ the right toolchain payload is resolved and installed automatically.
 > `musl-gcc@…` — stay permanently accepted as aliases and normalize to the
 > canonical forms above.
 >
-> ¹ On Windows, llvm requires an existing **MSVC BuildTools or Visual Studio**
-> (UCRT, Windows SDK, MSVC STL). The MinGW route (`--target x86_64-windows-gnu`,
-> or `mcpp toolchain default gcc@16 --target x86_64-windows-gnu`) needs no
-> Visual Studio at all.
+> ¹ On Windows, llvm targets the MSVC ABI and therefore requires an existing
+> **MSVC BuildTools or Visual Studio** (UCRT, Windows SDK, MSVC STL). You do
+> not have to arrange this: on first run mcpp checks for a usable MSVC and,
+> finding none, defaults to `x86_64-windows-gnu` (winlibs MinGW-w64) — fully
+> self-contained, no Visual Studio, `import std` included. Nothing to install
+> or configure; `mcpp new && mcpp build` just works on a stock Windows box.
+> An explicit `[toolchain]` in `mcpp.toml` is always respected as written —
+> mcpp revises its own default, never yours.
 
 ## Documentation
 

README.zh-CN.md

@@ -291,8 +291,8 @@ mcpp 的身份模型是两条正交轴:**工具链** = `family@version`(family 
 | `x86_64-linux-gnu`    | gcc(*Linux 默认*)或 llvm | ✅ |
 | `x86_64-linux-musl`   | gcc 16,全静态 | ✅ |
 | `aarch64-linux-musl`  | gcc 16,全静态——x86_64 交叉(qemu 实测)或原生 | ✅ |
-| `x86_64-windows-gnu`  | gcc 16 MinGW-w64——Windows 原生,Linux 交叉(wine 实测) | ✅ |
-| `x86_64-windows-msvc` | `msvc@system`(探测 VS/BuildTools)或 llvm ¹(*Windows 默认*) | ✅ |
+| `x86_64-windows-gnu`  | gcc 16 MinGW-w64——Windows 原生,Linux 交叉(wine 实测)(*无 Visual Studio 时的 Windows 默认*) | ✅ |
+| `x86_64-windows-msvc` | `msvc@system`(探测 VS/BuildTools)或 llvm ¹(*有 Visual Studio 时的 Windows 默认*) | ✅ |
 | `aarch64-macos`       | llvm(*macOS 默认*) | ✅ |
 | `riscv64-linux-musl`  | — | 🔄 |
 | `aarch64-linux-gnu`   | — | 🔄 |
@@ -304,9 +304,12 @@ mcpp 的身份模型是两条正交轴:**工具链** = `family@version`(family 
 > 旧拼写——`x86_64-w64-mingw32`、`gcc@16.1.0-musl`、`mingw-cross@…`、`musl-gcc@…`——
 > 作为别名**永久接受**,归一到上表的 canonical 形式。
 >
-> ¹ Windows 上 llvm 依赖已安装的 **MSVC BuildTools 或 Visual Studio**(UCRT、Windows
-> SDK、MSVC STL)。MinGW 路线(`--target x86_64-windows-gnu`,或
-> `mcpp toolchain default gcc@16 --target x86_64-windows-gnu`)完全不需要 Visual Studio。
+> ¹ Windows 上 llvm 打的是 MSVC ABI,因此依赖已安装的 **MSVC BuildTools 或
+> Visual Studio**(UCRT、Windows SDK、MSVC STL)。这件事你不需要自己安排:mcpp 首跑会
+> 探测是否有可用的 MSVC,探不到就默认走 `x86_64-windows-gnu`(winlibs MinGW-w64)——
+> 完全自包含、不需要 Visual Studio、`import std` 可用。无需安装或配置,裸 Windows 上
+> `mcpp new && mcpp build` 直接可用。而 `mcpp.toml` 里显式写的 `[toolchain]` 永远按你
+> 写的执行——mcpp 只修正自己选的默认值,不改你的。
 
 ## 文档
 

docs/03-toolchains.md

@@ -110,6 +110,21 @@ and `planned` targets that are registered but not yet shipped.
 
 ## Windows PE via MinGW-w64 (`x86_64-windows-gnu`, no Visual Studio required)
 
+**This is the Windows default when no Visual Studio is present.** Windows ships
+the UCRT runtime DLLs but not the MSVC STL or the Windows SDK — those come with
+Visual Studio's "Desktop development with C++" workload. Since llvm on Windows
+targets the MSVC ABI and needs both, mcpp checks for a usable MSVC (STL **and**
+SDK — half of one is the trap) on first run and falls back here when it finds
+none, persisting the choice so later builds are silent. Nothing to install or
+configure.
+
+The same check also repairs an existing setup: if a `[toolchain] default` mcpp
+chose earlier can no longer work on this machine, it is revised in place, with
+a line saying so. An explicit `[toolchain]` in `mcpp.toml` (or a
+`[target.X].toolchain`) is never overruled — a project that needs the MSVC ABI
+to link vcpkg-built `.lib` files gets an error naming the alternative, not a
+silent ABI swap.
+
 "MinGW" in mcpp is a **target**, not a toolchain name: `x86_64-windows-gnu`
 — GCC producing Windows PE with the GNU CRT. The same identity works from
 both hosts; which self-contained payload serves it is resolved automatically
@@ -126,7 +141,14 @@ mcpp toolchain default gcc@16 --target x86_64-windows-gnu
 It uses the regular GCC module pipeline (`gcm.cache`, `import std` via
 libstdc++'s `bits/std.cc`). The target's default linkage is **static** —
 the produced `.exe` is fully self-contained (no `libstdc++-6.dll` to ship,
-runs directly under wine); `[build] linkage = "dynamic"` opts out.
+runs directly under wine). To opt out, set it on the target section —
+`linkage` is exact-triple only (§2.7 of [mcpp.toml](05-mcpp-toml.md)), and a
+`[build] linkage` key does not exist and is silently ignored:
+
+```toml
+[target.x86_64-windows-gnu]
+linkage = "dynamic"
+```
 
 In a manifest:
 
@@ -180,7 +202,9 @@ INCLUDE/LIB environment from the detected VC tools + Windows SDK (no
 `vcvarsall` involved), stages `std.ixx`/`std.compat.ixx` as `.ifc` BMIs,
 compiles `.cppm` module units via `/interface /TP /ifcOutput`, scans with
 `/scanDependencies`, and links with `link.exe`/`lib.exe` through response
-files. `[build] linkage = "static"` selects the `/MT` CRT. A missing Windows
+files. `[target.x86_64-windows-msvc] linkage = "static"` (or `mcpp build
+--static`) selects the `/MT` CRT — not `[build] linkage`, which is not a key.
+A missing Windows
 SDK fails the build with installation guidance (`mcpp self doctor` reports
 SDK status).
 

docs/07-build-mcpp.md

@@ -69,7 +69,7 @@ interface and belongs in the declarative manifest/descriptor
 ## Typed API: `import mcpp;` (recommended)
 
 Instead of printing raw strings you can write `build.mcpp` **modules-first** —
-`import mcpp;`, no `#include`, no `import std;`. The `mcpp` module is bundled in the
+`import mcpp;`, no `#include` needed. The `mcpp` module is bundled in the
 mcpp binary (so it always matches your mcpp's protocol) and is compiled on demand;
 its functions just emit the directives above:
 
@@ -98,10 +98,39 @@ int main() {
 | `mcpp::include_dir(d)` / `mcpp::include_dir_after(d)` | `mcpp:include-dir=` / `mcpp:include-dir-after=` |
 | `mcpp::rerun_if_changed(p)` / `mcpp::rerun_if_env_changed(v)` | the matching `rerun-*` directives |
 
-If your `build.mcpp` also needs to *write* a generated file, mix in a textual
-`#include <fstream>` — that's fine; only `import std;` is unnecessary. The raw
-stdout protocol above remains the low-level substrate; `import mcpp;` is the typed
-layer over it.
+The raw stdout protocol above remains the low-level substrate; `import mcpp;`
+is the typed layer over it.
+
+### `import std;` (mcpp 2026.8.2.1+)
+
+A `build.mcpp` may `import std;` (and `import std.compat;`), alone or together
+with `import mcpp;`:
+
+```cpp
+// build.mcpp
+import std;
+import mcpp;
+
+int main() {
+    for (auto const& f : std::vector<std::string>{"FOO", "BAR"})
+        mcpp::define(f.c_str());
+}
+```
+
+mcpp stages the **same** std module its own build uses, keyed on
+(toolchain × standard × dialect) — so for an ordinary build this costs
+nothing, the artifact is already there. A cross build (`--target …`) pays for
+one extra std module, because `build.mcpp` compiles and runs on the *host*
+while the project targets something else.
+
+`#include` still works and stays the right choice for a program that only
+needs `std::fopen`; there is no requirement to modularize a build script.
+
+> **Not yet under MSVC.** Named modules with `cl.exe` go through `.ifc` +
+> `/reference`, a pipeline mcpp has not wired up. A `build.mcpp` using
+> `import mcpp;` or `import std;` under a native MSVC toolchain fails with an
+> explicit message telling you to use `#include` or a GCC/Clang toolchain —
+> `#include`-based programs are fully supported there.
 
 ## Environment contract (mcpp 0.0.95+)
 

docs/zh/03-toolchains.md

@@ -115,6 +115,19 @@ Available toolchains (run `mcpp toolchain install <family> <version>`):
 
 ## Windows PE 之 MinGW-w64(`x86_64-windows-gnu`,无需 Visual Studio)
 
+**没装 Visual Studio 时,这就是 Windows 上的默认值。** Windows 自带的只有
+UCRT 运行时 DLL,MSVC STL 与 Windows SDK 都只随 Visual Studio 的
+"Desktop development with C++" 负载安装。而 llvm 在 Windows 上打的是 MSVC ABI,
+两者都需要,所以 mcpp 首跑时会探测机器上是否有可用的 MSVC(STL **与** SDK
+两件齐——只有一半才是真正的坑),探不到就落到这里,并把选择持久化,之后的
+构建不再重复提示。无需任何安装或配置。
+
+同一道检查也会修复既有配置:如果 mcpp 早先自己选定的 `[toolchain] default`
+在这台机器上已经不可用,它会被就地改写,并打印一行说明。但**用户在
+`mcpp.toml` 里显式写下的** `[toolchain]`(或 `[target.X].toolchain`)永远不会
+被推翻——一个需要 MSVC ABI 去链接 vcpkg 预编译 `.lib` 的工程,得到的是一条
+指明替代方案的错误,而不是被静默换掉 ABI。
+
 mcpp 里 "MinGW" 是一个 **target**,不是工具链名:`x86_64-windows-gnu`
 ——GCC 产出 Windows PE(GNU CRT)。两种宿主用同一个身份、同一条命令;
 由哪个自包含 payload 来承接是自动分流的(Windows 宿主 → winlibs UCRT
@@ -130,7 +143,13 @@ mcpp toolchain default gcc@16 --target x86_64-windows-gnu
 它走常规的 GCC 模块管线(`gcm.cache`、经 libstdc++ `bits/std.cc` 的
 `import std`)。该 target 默认 linkage 为 **static**——产出的 `.exe`
 完全自包含(无需随包分发 `libstdc++-6.dll`,可直接在 wine 下运行);
-`[build] linkage = "dynamic"` 可退出。
+要退出请写在 target 段上——`linkage` 只认精确 triple(见
+[mcpp.toml](05-mcpp-toml.md) §2.7),`[build] linkage` 这个键并不存在,写了会被静默忽略:
+
+```toml
+[target.x86_64-windows-gnu]
+linkage = "dynamic"
+```
 
 manifest 中:
 

docs/zh/07-build-mcpp.md

@@ -62,8 +62,8 @@ manifest/描述符里(`[build] include_dirs`),而不是构建期程序里。
 
 ## 类型化 API:`import mcpp;`(推荐)
 
-除了打印裸字符串,你还可以把 `build.mcpp` 写成**模块优先**——`import mcpp;`,无
-`#include`、无 `import std;`。`mcpp` 模块**内置在 mcpp 二进制里**(因此永远和你这版 mcpp
+除了打印裸字符串,你还可以把 `build.mcpp` 写成**模块优先**——`import mcpp;`,不需要
+`#include`。`mcpp` 模块**内置在 mcpp 二进制里**(因此永远和你这版 mcpp
 的协议匹配),按需编译;它的函数只是 emit 上面那些指令:
 
 ```cpp
@@ -91,9 +91,36 @@ int main() {
 | `mcpp::include_dir(d)` / `mcpp::include_dir_after(d)` | `mcpp:include-dir=` / `mcpp:include-dir-after=` |
 | `mcpp::rerun_if_changed(p)` / `mcpp::rerun_if_env_changed(v)` | 对应的 `rerun-*` 指令 |
 
-如果 `build.mcpp` 还需要*写*生成文件,混入一个文本 `#include <fstream>` 即可——这没问题,
-只有 `import std;` 是不必要的。上面的裸 stdout 协议仍是底层基底;`import mcpp;` 是其上的
-类型化层。
+上面的裸 stdout 协议仍是底层基底;`import mcpp;` 是其上的类型化层。
+
+### `import std;`(mcpp 2026.8.2.1+)
+
+`build.mcpp` 可以 `import std;`(以及 `import std.compat;`),单用或与
+`import mcpp;` 并用皆可:
+
+```cpp
+// build.mcpp
+import std;
+import mcpp;
+
+int main() {
+    for (auto const& f : std::vector<std::string>{"FOO", "BAR"})
+        mcpp::define(f.c_str());
+}
+```
+
+mcpp 会把它自己构建时用的**同一份** std 模块暂存过来,缓存键是
+(工具链 × 标准 × 方言)——所以普通构建下这是零成本,产物本来就在。只有交叉构建
+(`--target …`)才会多编一份:`build.mcpp` 在**宿主**上编译并运行,而工程的目标
+是别的平台。
+
+`#include` 依然有效,对只需要 `std::fopen` 的程序也依然是更合适的选择——构建脚本
+没有必须模块化的要求。
+
+> **MSVC 下尚不支持。** `cl.exe` 的具名模块走 `.ifc` + `/reference`,这条管线 mcpp
+> 还没接。在原生 MSVC 工具链下使用 `import mcpp;` 或 `import std;` 的 `build.mcpp`
+> 会得到一条明确的报错,告诉你改用 `#include` 或换 GCC/Clang 工具链——基于
+> `#include` 的程序在那里是完全支持的。
 
 ## 环境契约(mcpp 0.0.95+)
 

src/build/prepare.cppm

@@ -1508,7 +1508,8 @@ prepare_build(bool print_fingerprint,
     // dynamic-musl binaries depend on a system /lib/ld-musl-x86_64.so.1
     // that most distros don't ship. Default linkage to "static" when
     // the resolved toolchain is musl, unless the user has already opted
-    // out via [build].linkage / [target.<triple>].linkage.
+    // out via `--static` or [target.<triple>].linkage. (There is no
+    // [build].linkage — the parser only reads it under a target section.)
     if (isMuslTc && m->buildConfig.linkage.empty()) {
         m->buildConfig.linkage = "static";
     }