feat(build): MCPP_TARGET_OS/ARCH/ENV contract env splits

Cargo CARGO_CFG_TARGET_* parity (design §3.1 item 3): contract_env now
parses the resolved target ONCE through the canonical triple parser
(mcpp.toolchain.triple — already imported for MCPP_HOST) and injects

  MCPP_TARGET_OS    linux|macos|windows
  MCPP_TARGET_ARCH  GNU spelling (x86_64, aarch64, ...)
  MCPP_TARGET_ENV   gnu|musl|msvc, "" when the triple has no env segment

so every build.mcpp (ffmpeg/opencv per-OS selection) stops hand-splitting
MCPP_TARGET. All three are always SET; an escape-hatch triple outside the
canonical vocabulary yields "" for all three (parse failure is not an error
here — MCPP_TARGET still carries the verbatim spelling).

Re-run key: verified — contract_hash hashes the WHOLE (name,value) env
vector, and the new vars ride that same vector, so they fold into ctxHash
with no extra plumbing (a target change already re-ran the program via
MCPP_TARGET; the splits add no new invalidation axis).

Typed lib: mcpp::target_os()/target_arch()/target_env() readers.

e2e 110 extended: asserts the three vars are set, OS/ARCH agree with the
full MCPP_TARGET triple's leading segments, and ENV is set (content may be
empty on macOS). Docs env tables updated (en/zh).

Verified: unit 35/35; e2e 110/143/144/111/125 green.

Author: Sunrisepeak

docs/07-build-mcpp.md

@@ -111,6 +111,9 @@ The running program receives the build context as `MCPP_*` variables
 | Variable | Typed reader | Value |
 |---|---|---|
 | `MCPP_TARGET` | `mcpp::target()` | resolved canonical triple (the `--target` triple under cross; the host triple natively) |
+| `MCPP_TARGET_OS` | `mcpp::target_os()` | the target's OS segment (`linux`/`macos`/`windows`) — no need to hand-split `MCPP_TARGET` |
+| `MCPP_TARGET_ARCH` | `mcpp::target_arch()` | the target's arch segment (GNU spelling: `x86_64`, `aarch64`, …) |
+| `MCPP_TARGET_ENV` | `mcpp::target_env()` | the target's env segment (`gnu`/`musl`/`msvc`); empty string when the triple has none (macOS) |
 | `MCPP_HOST` | `mcpp::host()` | the host triple |
 | `MCPP_PROFILE` | `mcpp::profile()` | effective profile name (`dev`/`release`/…) |
 | `MCPP_OUT_DIR` | `mcpp::out_dir()` | a writable scratch/output dir owned by mcpp |

docs/zh/07-build-mcpp.md

@@ -103,6 +103,9 @@ int main() {
 | 变量 | 类型化读取 | 值 |
 |---|---|---|
 | `MCPP_TARGET` | `mcpp::target()` | 解析后的 canonical 三元组(交叉构建下是 `--target` 三元组,原生构建是宿主) |
+| `MCPP_TARGET_OS` | `mcpp::target_os()` | 目标的 OS 段(`linux`/`macos`/`windows`)——不必再手撕 `MCPP_TARGET` |
+| `MCPP_TARGET_ARCH` | `mcpp::target_arch()` | 目标的 arch 段(GNU 拼写:`x86_64`、`aarch64`…) |
+| `MCPP_TARGET_ENV` | `mcpp::target_env()` | 目标的 env 段(`gnu`/`musl`/`msvc`);三元组无 env 段(macOS)时为空串 |
 | `MCPP_HOST` | `mcpp::host()` | 宿主三元组 |
 | `MCPP_PROFILE` | `mcpp::profile()` | 生效 profile 名(`dev`/`release`/…) |
 | `MCPP_OUT_DIR` | `mcpp::out_dir()` | mcpp 提供的可写输出/暂存目录 |

src/build/build_program.cppm

@@ -263,6 +263,9 @@ inline void rerun_if_env_changed(const char* var) { std::printf("mcpp:rerun-if-e
 // ── environment contract (read side; values injected by the engine) ─────
 inline const char* env_or(const char* n)          { const char* v = std::getenv(n); return v ? v : ""; }
 inline const char* target()                       { return env_or("MCPP_TARGET"); }
+inline const char* target_os()                    { return env_or("MCPP_TARGET_OS"); }
+inline const char* target_arch()                  { return env_or("MCPP_TARGET_ARCH"); }
+inline const char* target_env()                   { return env_or("MCPP_TARGET_ENV"); }
 inline const char* host()                         { return env_or("MCPP_HOST"); }
 inline const char* profile()                      { return env_or("MCPP_PROFILE"); }
 inline const char* out_dir()                      { return env_or("MCPP_OUT_DIR"); }
@@ -383,6 +386,20 @@ contract_env(const fs::path& root, const fs::path& outDir, const BuildProgramEnv
     std::vector<std::pair<std::string, std::string>> e;
     auto hostT = mcpp::toolchain::triple::host_triple().str();
     e.emplace_back("MCPP_TARGET", env.targetTriple.empty() ? hostT : env.targetTriple);
+    // Convenience splits of the resolved target (Cargo CARGO_CFG_TARGET_*
+    // parity): parsed ONCE here through the canonical triple parser so every
+    // build.mcpp stops hand-splitting MCPP_TARGET. MCPP_TARGET_ENV is "" when
+    // the triple has no env segment (macOS); all three are "" for an
+    // escape-hatch triple outside the canonical vocabulary. They ride the
+    // same env vector, so contract_hash folds them into the re-run key.
+    {
+        mcpp::toolchain::triple::Triple t{};
+        if (env.targetTriple.empty()) t = mcpp::toolchain::triple::host_triple();
+        else if (auto p = mcpp::toolchain::triple::parse(env.targetTriple)) t = *p;
+        e.emplace_back("MCPP_TARGET_OS", t.os);
+        e.emplace_back("MCPP_TARGET_ARCH", t.arch);
+        e.emplace_back("MCPP_TARGET_ENV", t.env);
+    }
     e.emplace_back("MCPP_HOST", hostT);
     e.emplace_back("MCPP_PROFILE", env.profile);
     e.emplace_back("MCPP_OUT_DIR", outDir.string());

tests/e2e/110_build_mcpp_env_contract.sh

@@ -24,6 +24,11 @@ int main() {
     f << "extern \"C\" const char* bp_target()   { return \"" << env_or("MCPP_TARGET") << "\"; }\n";
     f << "extern \"C\" const char* bp_host()     { return \"" << env_or("MCPP_HOST") << "\"; }\n";
     f << "extern \"C\" const char* bp_profile()  { return \"" << env_or("MCPP_PROFILE") << "\"; }\n";
+    f << "extern \"C\" const char* bp_tos()      { return \"" << env_or("MCPP_TARGET_OS") << "\"; }\n";
+    f << "extern \"C\" const char* bp_tarch()    { return \"" << env_or("MCPP_TARGET_ARCH") << "\"; }\n";
+    // ENV may legitimately be empty (macOS) — assert set-ness, not content.
+    f << "extern \"C\" int bp_tenv_set() { return "
+      << (std::getenv("MCPP_TARGET_ENV") ? 1 : 0) << "; }\n";
     f << "extern \"C\" const char* bp_features() { return \"" << env_or("MCPP_FEATURES") << "\"; }\n";
     f << "extern \"C\" int bp_has_extra() { return "
       << (std::getenv("MCPP_FEATURE_EXTRA") ? 1 : 0) << "; }\n";
@@ -45,9 +50,13 @@ extern "C" const char* bp_host();
 extern "C" const char* bp_profile();
 extern "C" const char* bp_features();
 extern "C" int bp_has_extra();
+extern "C" const char* bp_tos();
+extern "C" const char* bp_tarch();
+extern "C" int bp_tenv_set();
 int main() {
-    std::println("target={} host={} profile={} features=[{}] extra={}",
-                 bp_target(), bp_host(), bp_profile(), bp_features(), bp_has_extra());
+    std::println("target={} host={} profile={} features=[{}] extra={} tos={} tarch={} tenvset={}",
+                 bp_target(), bp_host(), bp_profile(), bp_features(), bp_has_extra(),
+                 bp_tos(), bp_tarch(), bp_tenv_set());
     return 0;
 }
 EOF
@@ -67,6 +76,14 @@ out="$("$MCPP" run 2>&1 | tail -1)"
 host_triple_re='[a-z0-9_]+-(linux|macos|windows)(-[a-z]+)?'
 [[ "$out" =~ target=$host_triple_re\ host=$host_triple_re\ profile=dev\ features=\[\]\ extra=0 ]] || {
     echo "unexpected contract values: $out"; exit 1; }
+# MCPP_TARGET_OS/ARCH/ENV splits: OS is one of the canonical spellings, ARCH is
+# non-empty, ENV is always SET (may be "" — no env segment on macOS) and must
+# agree with the full triple's segments.
+[[ "$out" =~ tos=(linux|macos|windows)\ tarch=([a-z0-9_]+)\ tenvset=1 ]] || {
+    echo "target split vars missing/odd: $out"; exit 1; }
+tos="${BASH_REMATCH[1]}"; tarch="${BASH_REMATCH[2]}"
+[[ "$out" == *"target=${tarch}-${tos}"* ]] || {
+    echo "target split disagrees with MCPP_TARGET: $out"; exit 1; }
 
 # Identical build → no re-run (either the whole-build fast path short-circuits
 # before build.mcpp, or the build.mcpp cache hits — both are fine; a "running"