feat(build.mcpp): typed import mcpp; build module bundled in the binary (v0.0.81)

[Sunrisepeak]

What

build.mcpp can now be written modules-first — import mcpp; (no #include, no import std;) — calling a typed API that emits the same mcpp: wire protocol the engine parses:

import mcpp;
int main() {
    mcpp::cxxflag("-DHAVE_X=1");
    mcpp::link_lib("m");
    mcpp::define("HAVE_FEATURE");      // cfg= → -DHAVE_FEATURE
    mcpp::generated("src/gen.cpp");
    mcpp::rerun_if_changed("config.h");
}

Completes the L3 follow-up (task #20).

Architecture (design doc included)

The helper speaks this mcpp's protocol → it's part of the engine's ABI, not a third-party library. So it ships with the engine (Zig std.Build model), not as a versioned registry package (Cargo build-dep model) — eliminating version skew. And we embed the source (constexpr std::string_view), not a prebuilt BMI: BMIs are compiler-version-locked (a matrix nightmare), whereas one source string compiles against whatever host toolchain resolved. Compiled on demand into target/.build-mcpp/ (GCC -fmodules gcm.cache; Clang --precompile .pcm); I/O is C-level so the module needs no import std;.

Gated on use — mcpp only builds/links the module when build.mcpp contains import mcpp; a #include-based program compiles byte-identically to before (zero blast radius). Uses the 0.0.79 capture_exec cwd so GCC finds gcm.cache/.

See .agents/docs/2026-06-30-build-mcpp-module-library-design.md for the full five-axis (简洁/覆盖/优化/稳定/适配) comparison of the four options considered.

Files

• src/build/build_program.cppm — kMcppModuleSource + build_mcpp_module (GCC/Clang) + use-gating.
• tests/e2e/92_build_mcpp_import.sh — GCC path (typed directives + generated source reach the build).
• docs/07-build-mcpp.md (+zh) — new typed-API section.
• design doc; version → 0.0.81.

Verified locally (0.0.81)

92 passes; 89/90/91 regress clean (the #include path is unchanged). The Clang path is covered by the mcpp-index build-mcpp member's workspace job on macOS/Windows (a follow-up PR converts it to import mcpp;).

🤖 Generated with Claude Code