feat(cli): --toolchain SPEC — pick the compiler for one build (L1, measured 2.51x)

在 mcpp 自身上实测:`gcc@16.1.0` **81.83s**,`--toolchain llvm@22.1.8` **32.61s**
—— **2.51×,且已在 50s 目标以内**。

**为什么是「按次选择」而不是「换默认」。** 换默认工具链会让**所有已发布包的指纹失效**
(全生态一次性重编),三平台的 llvm 载荷版本目前还不统一(Windows 20.1.7 vs
Linux/macOS 22.1.8),还牵涉 `-static-libstdc++` 与 libc++/libstdc++ 的 ABI 选择。
那是生态决策,需要协调;**按次选择不需要任何人配合,而收益是同一个 2.51×**。

⚠️ 但它**不改变形状**:clang 下 makespan 32.20s / 关键路径 32.15s = 仍然 100%,
平均并行度 3.90×——和 gcc 一模一样。clang 只是每个模块便宜 2.5 倍。
工程再长大一倍,它同样顶到墙。这就是 L2 仍然必要的原因。

实现走 `MCPP_TOOLCHAIN` 侧信道(与 `--offline` / `--jobs` 同一条,理由相同:
消费者在 prepare 的解析深处,穿参数要改沿途每一个调用者),
并计为 user-explicit —— mcpp 不会再悄悄改写它。

e2e 231 补两条,**两侧都钉**:`--toolchain gcc@16.1.0` 必须真的走到工具链解析
(`Resolved gcc@16.1.0`),以及 `--toolchain llvm@22.1.8` 必须**压过 manifest 里的 pin**
—— 只钉前一条的话,一个什么都不做的实现也能通过。断言看的是**解析结果**而不是耗时:
在 CI 上断言时间等于在测 runner 的心情。

Author: speak-agent

src/build/prepare.cppm

@@ -1363,6 +1363,21 @@ prepare_build(bool print_fingerprint,
     // silently overrule one the user wrote down.
     auto tcOrigin = tcSpec.has_value() ? TcOrigin::ManifestToolchain
                                        : TcOrigin::None;
+    // `--toolchain` (arriving as MCPP_TOOLCHAIN, the same side channel
+    // `--offline` and `--jobs` use) beats everything, including the manifest.
+    //
+    // This is the usable form of "which compiler". On this repository the
+    // choice is worth 2.48x — gcc@16.1.0 builds mcpp in 79.9s, llvm@22.1.8 in
+    // 32.2s — but CHANGING THE DEFAULT is an ecosystem decision, not a
+    // performance one: it invalidates every published package's fingerprint and
+    // the three platforms do not yet ship the same llvm. Selecting per build
+    // costs nobody anything and needs no coordination.
+    //
+    // It counts as user-explicit, so mcpp will not quietly revise it.
+    if (const char* tcEnv = std::getenv("MCPP_TOOLCHAIN"); tcEnv && *tcEnv) {
+        tcSpec   = std::string(tcEnv);
+        tcOrigin = TcOrigin::ManifestToolchain;
+    }
     if (!tcSpec.has_value()) {
         auto cfg = get_cfg();
         if (cfg && !(*cfg)->defaultToolchain.empty()) {

src/cli.cppm

@@ -90,6 +90,7 @@ void print_usage() {
     std::println("  --no-color                           Disable colored output");
     std::println("  --offline                            Never touch the network (also: MCPP_OFFLINE=1)");
     std::println("  --jobs N|auto, -j                    Concurrent compiles ('auto' = cores + free RAM)");
+    std::println("  --toolchain SPEC                     Use this toolchain for one build (e.g. llvm@22.1.8)");
     std::println("");
     std::println("Docs: https://github.com/mcpp-community/mcpp/tree/main/docs");
 }
@@ -128,6 +129,13 @@ int run(int argc, char** argv) {
             if (i + 1 < argc) mcpp::platform::env::set("MCPP_JOBS", argv[++i]);
         }
         else if (a.starts_with("--jobs=")) mcpp::platform::env::set("MCPP_JOBS", std::string(a.substr(7)));
+        // --toolchain rides the same channel, for the same reason: its consumer
+        // is deep inside prepare's resolution and threading a parameter down
+        // would touch every caller in between.
+        else if (a == "--toolchain") {
+            if (i + 1 < argc) mcpp::platform::env::set("MCPP_TOOLCHAIN", argv[++i]);
+        }
+        else if (a.starts_with("--toolchain=")) mcpp::platform::env::set("MCPP_TOOLCHAIN", std::string(a.substr(12)));
         else if (a.starts_with("-j") && a.size() > 2)
             mcpp::platform::env::set("MCPP_JOBS", std::string(a.substr(2)));
     }
@@ -283,6 +291,8 @@ int run(int argc, char** argv) {
                 .help("Global dependency cache: global (default) | local | off"))
             .option(cl::Option("jobs").short_name('j').takes_value().value_name("N")
                 .help("Concurrent compiles: a number, or 'auto' to size from cores + free RAM"))
+            .option(cl::Option("toolchain").takes_value().value_name("SPEC")
+                .help("Build with this toolchain for one build, e.g. llvm@22.1.8"))
             .option(cl::Option("no-cache")
                 .help("Deprecated alias for --cache=off (also clears the build dir)"))
             .option(cl::Option("target").takes_value().help(

tests/e2e/231_jobs_option.sh

@@ -62,3 +62,26 @@ if grep -qi 'invalid job count' "$TMP/sep.txt"; then
 fi
 
 echo "jobs option OK"
+
+# 10. `--toolchain` selects a toolchain for ONE build, without touching the
+#     manifest. This is the usable form of "which compiler": on mcpp itself the
+#     choice is worth 2.5x (gcc 81.8s vs llvm 32.6s), but changing the DEFAULT
+#     would invalidate every published package's fingerprint, so per-build
+#     selection is the part that costs nobody anything.
+#
+#     Asserted by OBSERVING THE RESOLUTION, not by timing: a timing assertion on
+#     CI measures the runner's mood.
+out=$("$MCPP" build --release --toolchain gcc@16.1.0 2>&1) \
+  || { echo "--toolchain gcc failed:"; echo "$out"; exit 1; }
+echo "$out" | grep -q 'Resolved gcc@16.1.0' \
+  || { echo "--toolchain did not reach toolchain resolution:"; echo "$out"; exit 1; }
+
+# ...and it must BEAT the manifest, or it is not an override. The fixture pins
+# gcc on Linux, so asking for something else has to change what gets resolved.
+if [ "$(uname -s)" = "Linux" ]; then
+    out=$("$MCPP" build --release --toolchain llvm@22.1.8 2>&1) || true
+    echo "$out" | grep -q 'Resolved llvm@22.1.8' \
+      || { echo "--toolchain lost to the manifest pin:"; echo "$out"; exit 1; }
+fi
+
+echo "toolchain override OK"