fix(build): make the C++ runtime contract one decision (#336) (#337)

* fix(build): make the C++ runtime contract one decision (#336)

`[build] static_stdlib = false` was silently ignored for test binaries from
0.0.86 to 2026.8.2.2 while docs/05-mcpp-toml.md kept documenting the opt-out.
The cause is structural: "does this artifact carry its own C++ runtime" was
derived independently in five places — ldStdlibDefault, ldStdlibTest, the
-static-libstdc++ string, the MinGW -static branch, and the
LinkUnit::TestBinary two-way switch in the ninja emitter — and #202's new
semantics landed in some of them and not the others.

Replaced by a three-layer model in src/build/distribution.cppm:

  Role      intrinsic to the link unit (test binaries run here and are
            discarded; archives embed no runtime at all)
  Contract  what the artifact promises about the machine that runs it
  Mechanism (contract x stdlib x binary format) -> flags, as a TOTAL function

Totality is the property that matters: every cell answers, and a cell that
cannot honor what was asked returns `degraded` plus a diagnostic the backend
must print. That turns three silent downgrades into reported ones — including
Linux + clang/libc++, where `static_stdlib = true` emitted no flag at all and
shipped a toolchain-coupled artifact while the manifest, the docs and the
build output all called it self-contained. It now links libc++.a/libc++abi.a/
libunwind.a for real (NEEDED drops to libc/libm/loader).

Also fixes the crash that made the gap visible. On macOS a global object whose
constructor touches std::cout SIGSEGVs at process start under the default
contract: Mach-O runs __init_offsets in link order and has no priority-ordered
init section, so the stream initializer pulled out of libc++.a lands last, and
libc++'s <iostream> has no ios_base::Init guard of its own (libstdc++ and the
MSVC STL do, which is why only macOS breaks). Nor could package code work
around it — std::ios_base::Init is only forward-declared in libc++'s headers,
so the standard's own remedy is unavailable there. mcpp now links a generated
C object first whose constructor calls ios_base::Init::Init(); the reference is
weak, so a toolchain spelling that symbol differently links exactly as before.

New surface: [build] cxx_runtime = "self-contained" | "toolchain-coupled" |
"host-coupled", per role via { default, tests } and per triple via
[target.<triple>].cxx_runtime — beside `linkage`, which is the same axis.
static_stdlib stays a faithful alias.

Analysis: .agents/docs/2026-08-02-issue336-pr142-analysis.md
Unblocks: mcpplibs/mcpp-index#142

* fix(build): a platform limit nobody asked about is not a diagnostic

The MSVC runtime has no self-contained mechanism at all (no /MT emission),
so the default contract degraded on EVERY Windows build and printed a warning
nobody could act on. A diagnostic is for a broken promise — mcpp said the
artifact would be self-contained and it is not. Where mcpp never made the
promise, the cell now stays quiet unless the contract was written down
explicitly. Cells that DO promise something (a missing libc++.a under the
default) still report regardless.

* fix(build): the macOS ordering shim must not be able to break the link

Two Mach-O facts the first CI round found the hard way:

  * an __asm__ label is used VERBATIM — clang does not prepend Mach-O's
    global '_'. The C++ symbol _ZNSt3__18ios_base4InitC1Ev therefore has to
    be written __ZNSt3__18ios_base4InitC1Ev, and getting it wrong is not a
    silent no-op: every macOS link failed with
    'undefined symbol: ZNSt3__18ios_base4InitC1Ev'.

  * plain __attribute__((weak)) on a declaration is NOT Mach-O's
    weak-undefined form, so it did not make the bad reference optional.
    weak_import is.

Both are now correct, but neither is the safety net. The backend only
generates the shim TU when the libc++ archive actually defines the symbol —
checked by scanning the ranlib index in the archive's first member, no
subprocess — so an unexpected libc++ spelling disables the ordering aid and
says so, instead of failing the build. A check upstream of the reference
cannot break a link the way the reference itself can.

* docs: record what shipped and what the CI rounds corrected (#336)

---------

Co-authored-by: sunrisepeak <speakshen@163.com>

Author: speak-agent

.agents/docs/2026-08-02-issue336-pr142-analysis.md

@@ -3,6 +3,32 @@
 > 本文件追踪 `mcpp-community/mcpp` 公开仓的版本演进。
 > 格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)。
 
+## [2026.8.3.1] — 2026-08-03
+
+### 修复
+
+- **`[build] static_stdlib = false` 对测试二进制静默失效(#336)。** #124 在 0.0.52 明确写下这个 opt-out,`docs/05-mcpp-toml.md` 至今也还这么写;但 #202(0.0.86)把测试二进制改成与分发目标相同的静态 `-load_hidden` libc++ 时,新增的那条推导**没有带上 `staticStdlib` 门**。结果是约一年时间里 macOS 上的 `mcpp test` 没有任何办法回到动态 libc++,而文档一直在承诺它可以。
+
+- **macOS 上全局对象在静态初始化期访问 `std::cout` 必崩(#336)。** Mach-O 没有按优先级排序的初始化段(`init_priority` 只在单个 TU 内有效),归档成员的初始化器按链接顺序排在最后;而 libc++ 的 `<iostream>` 不像 libstdc++ / MSVC STL 那样自带 `ios_base::Init` 守卫,流的构造只存在于库内对象里。两件事叠起来的后果是:默认配置下,任何在构造函数里碰 `std::cout` 的全局对象都会读到 vptr 为零的流,进程启动即 SIGSEGV —— 而且**包侧无法修复**,因为 `std::ios_base::Init` 在 libc++ 的头文件里只有前向声明(`ios:70`),标准为静态初始化次序提供的官方解药在 libc++ 上用户根本写不出来。
+
+  修法是让静态链接恢复动态链接本来就有的保证:macOS + 自包含时,mcpp 生成一个极小的 C 翻译单元并把它的对象排在链接行**最前**,由它先把流顶上去。它对 `ios_base::Init::Init()` 的引用是 **weak** 的 —— 换一份不这么拼这个 ABI 符号的工具链,链接与今天完全一样,shim 退化为空操作。
+
+### 新增
+
+- **C++ 运行时分发契约 `[build] cxx_runtime`。** 三档:`self-contained`(默认)/ `toolchain-coupled` / `host-coupled`,可按角色(`{ default = ..., tests = ... }`)也可按目标三元组(`[target.<triple>] cxx_runtime`,与 `linkage` 并列 —— 它们本就是同一根轴)。`static_stdlib` 保留为忠实别名(`true`↔`self-contained`,`false`↔`host-coupled`)。
+
+  这个字段替换的旧字段名描述的是**手段**("静态链接 stdlib"),而它承载的其实是**意图**(产物能在哪些机器上跑)—— 这正是同一个 `true` 在四种配置上展开成四种不同结果的原因,其中一种是**静默空转**:Linux + clang/libc++ 工具链上 `static_stdlib = true` 一个 flag 都不发,交付的是工具链耦合的产物,而 manifest、文档和 `--version` 都说它是自包含的。
+
+- **Linux + libc++ 工具链现在真的能自包含**:显式链入 `libc++.a` / `libc++abi.a` / `libunwind.a`(缺 libunwind.a 时产物仍会拉 `libunwind.so.1`,所以它是机制的一部分而不是可选项)。实测 `NEEDED` 只剩 libc / libm / loader。
+
+- **兑现不了的契约一定会被报出来。** 工具链不带 `libc++.a`、macOS 没有 deployment floor、MSVC 运行时没有 `/MT` 机制、macOS 上没有可用的 `toolchain-coupled` 形态(LLVM 的 libc++abi/libunwind dylib 向上链 `/usr/lib/libc++`,会把第二份 libc++ 载进进程)—— 这些格子现在都会打印实际退到了哪一档。
+
+### 变更
+
+- **五处独立推导收敛成一处。** "这个产物自带 C++ 运行时吗"过去在 `flags.cppm` 的 `ldStdlibDefault` / `ldStdlibTest` / `-static-libstdc++` / MinGW `-static` 四处,加上 `ninja_backend.cppm` 里那个按 `LinkUnit::TestBinary` 的二分派,各推一遍 —— 这正是新语义只落到其中一处的成因。现在是 `src/build/distribution.cppm` 里的三层模型:角色(由链接单元内在决定)→ 契约(按角色取默认,可覆盖)→ 机制(唯一放 flag 的地方,且是**总函数**)。
+
+- 相应地,C++ 运行时相关的链接 flag 从全局 `ldflags` 移到了**每个链接单元**的 `unit_ldflags` —— 两个角色在同一次构建里可以持有不同契约,这一点全局通道表达不了。它们都是驱动级 flag,相对库的位置无意义,Linux/Windows 的链接语义不变。
+
 ## [2026.8.1.2] — 2026-08-01
 
 ### 新增

CHANGELOG.md

@@ -157,7 +157,7 @@ cflags       = ["-DFOO=1"]        # Extra C compile flags
 cxxflags     = ["-DBAR=2"]        # Extra C++ compile flags (do not put -std=... here)
 ldflags      = ["-lfoo"]          # Extra link flags
 defines      = ["BIZ=1", "QUX"]   # Preprocessor macros for every TU (desugars to -D; reaches module scans)
-static_stdlib = true               # Statically link libstdc++ (default true)
+cxx_runtime  = "self-contained"   # C++ runtime contract (§ below); static_stdlib is the old spelling
 target       = "x86_64-linux-musl" # Default build target when no --target is passed
                                    # (≙ cargo build.target; e.g. "ship fully-static")
 macos_deployment_target = "14.0"   # Minimum supported OS version for macOS artifacts (macOS only)
@@ -188,16 +188,66 @@ baseline, and 14.0 is the floor of LLVM's official static libraries themselves).
 This value enters the BMI fingerprint, so switching targets automatically rebuilds
 the module cache.
 
-**Static runtime by default (portable by default)**: when `static_stdlib = true`
-(the default), macOS linking statically links in LLVM's bundled libc++/libc++abi —
-the system libc++ would otherwise pin the actual runnable version to the build
-machine's OS (older systems lack newer symbols, e.g. the support symbols behind
-`std::print`), and only static linking can truly deliver the floor. As a result,
-the default build's artifacts work out of the box on any macOS ≥ 14. Set
-`static_stdlib = false` to fall back to the dynamic system libc++ (the artifact is
-then only guaranteed to run on the build machine's version and above). A lower
-floor (11–13) requires a self-built libc++ archive (already verified to work, a
-data-level switch, available on request).
+### The C++ runtime contract (`cxx_runtime`)
+
+`cxx_runtime` states what the produced artifact promises about the machine that
+runs it. It is a **distribution** property, not a build one — it describes the
+runtime dependency set, and the flags that deliver it differ per platform.
+
+```toml
+[build]
+cxx_runtime = "self-contained"          # applies to every target (the default)
+
+# or, per role:
+[build.cxx_runtime]
+default = "self-contained"              # binaries and shared libraries
+tests   = "host-coupled"                # test binaries never leave this machine
+
+# or, per target triple — beside `linkage`, which is the same axis:
+[target.x86_64-linux-gnu]
+cxx_runtime = "host-coupled"            # e.g. this build is for a distro package
+```
+
+| value | the artifact needs, at run time | typical use |
+|---|---|---|
+| `self-contained` (default) | no C++ runtime outside itself | shipping a binary |
+| `toolchain-coupled` | the C++ runtime of the toolchain mcpp installed | local iteration |
+| `host-coupled` | whatever the driver resolves by default (the system runtime) | distro packaging, `dlopen` plugins that must share a runtime with their host |
+
+**Self-contained by default (portable by default)**: on macOS this statically
+links LLVM's bundled libc++/libc++abi — the system libc++ would otherwise pin the
+runnable version to the build machine's OS (older systems lack newer symbols, e.g.
+the support symbols behind `std::print`), and only static linking can truly deliver
+the `macos_deployment_target` floor. On Linux/MinGW it is `-static-libstdc++` (GCC)
+or the whole-link `-static` (MinGW); on a Linux clang/libc++ toolchain it links
+libc++.a/libc++abi.a/libunwind.a explicitly. A lower macOS floor (11–13) requires a
+self-built libc++ archive (already verified to work, a data-level switch, available
+on request).
+
+`static_stdlib` is the older spelling and still works: `true` means
+`self-contained`, `false` means `host-coupled`. An explicit `cxx_runtime` wins.
+
+**A contract that cannot be honored is reported, never silently downgraded.** If a
+toolchain ships no `libc++.a`, or a contract has no mechanism on that platform
+(`self-contained` under the MSVC runtime would need `/MT`, which mcpp does not emit
+yet), the build prints what it fell back to instead of quietly producing a
+different artifact than the manifest asked for.
+
+**Scope.** The contract governs the C++ runtime only. Static **libc** is a separate
+axis (`linkage = "static"` / `--static`, e.g. a musl target), and the deployment
+floor is a third (`macos_deployment_target`). Also, `host-coupled` means mcpp adds
+nothing to embed a C++ runtime; it does not strip the toolchain rpath the link
+carries for other reasons, so on ELF such an artifact may still find the
+toolchain's libraries first.
+
+> **macOS + `self-contained` and static initialization order.** Mach-O has no
+> priority-ordered initializer section and libc++'s `<iostream>` carries no
+> `ios_base::Init` guard of its own (unlike libstdc++ and the MSVC STL), so a
+> stream initializer pulled out of `libc++.a` would otherwise run *after* the
+> program's own global constructors — a global whose constructor touches
+> `std::cout` would read an unconstructed stream and crash at process start. mcpp
+> links a tiny generated object first to force the streams up; nothing is required
+> of your code. See mcpp-community/mcpp#336.
 
 `defines` takes **bare** macro names (no `-D`) and desugars each entry to `-D<x>` on
 both the C and C++ compile channels. It reaches every TU in the package — module

docs/05-mcpp-toml.md

@@ -151,7 +151,7 @@ cflags       = ["-DFOO=1"]        # 额外 C 编译参数
 cxxflags     = ["-DBAR=2"]        # 额外 C++ 编译参数(不要放 -std=...)
 ldflags      = ["-lfoo"]          # 额外链接参数
 defines      = ["BIZ=1", "QUX"]   # 作用于每个 TU 的预处理宏(脱糖为 -D;会进入模块扫描)
-static_stdlib = true               # 静态链接 libstdc++(默认 true)
+cxx_runtime  = "self-contained"   # C++ 运行时契约(见下节);static_stdlib 是旧拼写
 macos_deployment_target = "14.0"   # macOS 产物的最低支持系统版本(仅 macOS 生效)
 cache        = "global"           # 依赖的全局构建缓存:global(默认)| local | off(见 §2.10)
 ```
@@ -174,13 +174,59 @@ cargo/rustc、cc 等同样尊重该变量)> 本字段(项目默认,类似 SwiftP
 14.0 即 LLVM 官方静态库自身的下限)。该值会进入 BMI 指纹——切换 target
 会自动重建模块缓存。
 
-**默认即静态运行时(portable by default)**:`static_stdlib = true`
-(默认)时,macOS 链接会静态链入 LLVM 自带的 libc++/libc++abi ——
-系统 libc++ 会把实际可运行版本钉死在构建机的 OS(老系统缺新符号,
-如 `std::print` 的支撑符号),静态化才能真正兑现 floor。因此默认构建的
-产物在任何 macOS ≥ 14 上开箱即用。设 `static_stdlib = false` 退回动态
-系统 libc++(产物只保证在构建机同版本及以上运行)。更低 floor(11–13)
-需自建 libc++ 归档(已验证可行,数据级切换,按需提供)。
+### C++ 运行时契约(`cxx_runtime`)
+
+`cxx_runtime` 声明的是**产物对运行它的机器做出的承诺**。它是**分发**属性而非
+构建属性 —— 它描述的是运行期依赖集,而兑现它的 flag 逐平台不同。
+
+```toml
+[build]
+cxx_runtime = "self-contained"          # 作用于所有目标(默认值)
+
+# 或者按角色分别指定:
+[build.cxx_runtime]
+default = "self-contained"              # 可执行文件与共享库
+tests   = "host-coupled"                # 测试二进制从不离开本机
+
+# 或者按目标三元组 —— 与 `linkage` 并列,因为它们是同一根轴:
+[target.x86_64-linux-gnu]
+cxx_runtime = "host-coupled"            # 例如这次构建是为发行版打包
+```
+
+| 取值 | 产物运行时需要 | 典型场景 |
+|---|---|---|
+| `self-contained`(默认) | 自身之外不需要任何 C++ 运行时 | 分发二进制 |
+| `toolchain-coupled` | mcpp 装的那份工具链的 C++ 运行时 | 本地迭代 |
+| `host-coupled` | 驱动默认解析到的那份(通常是系统运行时) | 发行版打包;必须与宿主共用同一份运行时的 `dlopen` 插件 |
+
+**默认即自包含(portable by default)**:macOS 上这会静态链入 LLVM 自带的
+libc++/libc++abi —— 系统 libc++ 会把实际可运行版本钉死在构建机的 OS(老系统
+缺新符号,如 `std::print` 的支撑符号),只有静态化才能真正兑现
+`macos_deployment_target` 的 floor。Linux/MinGW 上它是 `-static-libstdc++`
+(GCC)或整条链的 `-static`(MinGW);Linux 上的 clang/libc++ 工具链则显式链入
+libc++.a/libc++abi.a/libunwind.a。更低的 macOS floor(11–13)需自建 libc++
+归档(已验证可行,数据级切换,按需提供)。
+
+`static_stdlib` 是旧拼写,仍然有效:`true` 等价于 `self-contained`,`false`
+等价于 `host-coupled`。显式写了 `cxx_runtime` 时以后者为准。
+
+**兑现不了的契约会被报出来,绝不静默降级。** 若工具链不带 `libc++.a`,或某个
+契约在该平台上没有对应机制(MSVC 运行时的 `self-contained` 需要 `/MT`,mcpp
+目前不发射),构建会打印实际退到了哪一档,而不是悄悄交付一个与 manifest 所述
+不同的产物。
+
+**边界。** 该契约只管 C++ 运行时。静态 **libc** 是另一根轴(`linkage = "static"`
+/ `--static`,如 musl 目标),部署下限是第三根轴(`macos_deployment_target`)。
+另外,`host-coupled` 只承诺 mcpp 不做任何"把 C++ 运行时打进产物"的动作,它不会
+去掉链接因其它原因已经携带的工具链 rpath —— 所以在 ELF 上这类产物仍可能优先
+找到工具链的库。
+
+> **macOS + `self-contained` 与静态初始化次序。** Mach-O 没有按优先级排序的
+> 初始化段,而 libc++ 的 `<iostream>` 也不像 libstdc++ / MSVC STL 那样自带
+> `ios_base::Init` 守卫 —— 于是从 `libc++.a` 里拉出来的流初始化器本来会排在
+> 程序自己的全局构造函数**之后**:一个在构造函数里碰 `std::cout` 的全局对象会
+> 读到尚未构造的流,进程启动即崩。mcpp 会把一个极小的生成对象排在链接最前面
+> 把流顶上去,你的代码不需要做任何事。详见 mcpp-community/mcpp#336。
 
 `defines` 接受**裸**宏名(不带 `-D`),把每个条目脱糖为 `-D<x>`,同时作用于 C 和
 C++ 编译通道。它覆盖包内每个 TU(含模块接口单元),因此也会进入 P1689 模块扫描

docs/zh/05-mcpp-toml.md

@@ -1,6 +1,6 @@
 [package]
 name        = "mcpp"
-version     = "2026.8.2.2"
+version     = "2026.8.3.1"
 description = "Modern C++ build & package management tool"
 license     = "Apache-2.0"
 authors     = ["mcpp-community"]