mcpp-community
diff --git a/‎CHANGELOG.md‎
Lines changed: 32 additions & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 32 additions & 0 deletions
diff --git a/‎docs/05-mcpp-toml.md‎
Lines changed: 85 additions & 1 deletion b/‎docs/05-mcpp-toml.md‎
Lines changed: 85 additions & 1 deletion
diff --git a/‎docs/07-build-mcpp.md‎
Lines changed: 89 additions & 0 deletions b/‎docs/07-build-mcpp.md‎
Lines changed: 89 additions & 0 deletions
@@ -30,8 +30,40 @@
 
   **编译**这一步刻意不设上限——与 `mcpp test` 同一条不对称纪律(run 有限 / build 无限):编译跑得久通常是正当的(首次构建 `std` 模块就是分钟级),杀掉它只会产生莫名其妙的失败;构建**程序**跑得久通常是卡住了。`capture_exec_deadline` 顺带补上了 `cwd` 形参——没有它,加超时会**静默改变**构建程序相对写入的落点。
 
+### 新增
+
+- **依赖产出的 host 工具:`tools = ["protoc"]`(#355)。** 一个包能构建出消费者在**构建期**需要的二进制(protoc、grpc_cpp_plugin、flatc、moc、转译器),但消费者此前完全拿不到它 —— `mcpp::dep_dir()` 给的是**源码树**,而依赖的 `kind = "bin"` target **从不被构建**(`plan.cppm` 只遍历 root 的 targets;唯一的例外 `kind = "shared"` 是按 `--target` 构建的,当 host 工具用不了)。
+
+  **为什么它不能是主图里的一个节点**:时序。`build.mcpp` 跑在 prepare 内,那时 BuildPlan 还不存在、build.ninja 更在其后 —— 主图产出的东西对需要它的程序来说**永远来得太晚**。再叠上交叉编译,它连架构都不对。所以工具由**嵌套的、面向 host 的子构建**产出,落进全局 store。这正是 Cargo `[build-dependencies]` / Bazel exec configuration / vcpkg `"host": true` / Conan `tool_requires` 的形状。
+
+  **为什么它便宜**:工具是**可执行文件**,与主构建零 ABI 接触。子构建因此可以用工具包自己的 `[toolchain]`、自己的 profile、自己的依赖解析,不必与消费者一致 —— 对照 `kind = "lib"` 依赖,这几条**必须**一致。
+
+  **单一版本轴**:工具的版本就是依赖的版本,所以「protoc 与 protobuf 运行时错配」这类**运行期**才炸的问题结构上不可表达。默认关闭(成本由消费者付),成本门复用已有的 `[features]` + `required_features`。全局 store 按 包版本 × host 工具链 × feature × 自身依赖闭包 缓存。
+
+  **逃生舱** `[tools.overrides]` / `MCPP_TOOL_<PKG>_<TOOL>`:直接指一个现成二进制,**完全跳过构建**。每个同类系统都提供这一条(vcpkg `VCPKG_HOST_TRIPLET`、CMake `LLVM_NATIVE_TOOL_DIR`、Qt `QT_HOST_PATH`),理由一样 —— 源码在本机构建不出来的工具不能是死路。它**刻意不进 cache key**:逃生舱不是可复现输入。
+
+- **`mcpp:action=`:声明构建图节点,而不是在 build.mcpp 里干活。** 在程序里直接写生成逻辑,是每次 prepare 跑一遍、全量、串行,失败报「build.mcpp exited 1」。**声明**成节点后它是图里的一条边 —— 增量、并行、失败可归因到具体那条边。
+
+  **一个原语,三种接线**(`role` 只决定输出接到哪,不是三套机制):`source` 进编译集(protoc、转译器)、`check` 产出 stamp 且**默认与编译并行**(clang-tidy、格式/ABI 检查;`blocking` 可改成前置)、`artifact` 的**输入**是链接产物(签名、打包、size budget)。顺序完全由 ninja 的文件依赖决定,不需要任何 phase 机制 —— 这也是为什么 `artifact` 不会像朴素的「post 钩子」那样把自己重复施加一遍。
+
+  **必须写出输出文件名**:mcpp 在 prepare 期就定死源码集、fingerprint 与模块图,名字未知的产物无法进图。内容可以晚到,名字不行。畸形 action 是**硬错误**而非静默跳过。生成**模块接口**时用 `.provides()/.imports()` 声明,mcpp 会按该声明播下占位文件让 prepare 期的扫描与生成器将要产出的内容一致 —— 与 `[modules].scan_overrides` 同一条「声明+验证」的取舍,build 期由编译器自己的 P1689 复核。
+
+  命令是 **argv 而非 shell 字符串**(不假设存在 shell),插值只有封闭的四个:`${mcpp.out_dir}` / `${mcpp.bin_dir}` / `${mcpp.compile_db}` / `${mcpp.target_file:<name>}`。
+
+- **`host-module = true`:可复用的构建规则以普通包分发。** 「跑 protoc」这类规则应该写一次,而不是每个消费者的 build.mcpp 复制一遍。把它做成普通 mcpp 库包,消费者 `import mcpp.rules.protobuf;` 即可。规则因此**有版本、能测试、能发布**,走的是已有的包管理机制,而且是用 **C++** 写的 —— 不引入第二门语言(xmake 用 Lua rule、Bazel 用 Starlark),这正是 build.mcpp 存在的理由。
+
+  实现上的关键:规则模块与 build.mcpp **在同一条命令里、用同一套 flag** 编译。这不是优化 —— BMI 只对「在 standard / dialect / 编译器身份上与它一致」的编译可用,分成两次独立解析的构建则毫无理由一致,而不一致的表现是 `module X CRC mismatch` 而不是一条清楚的错误。
+
+- **工作目录可外置(`BuildOverrides::work_dir`)。** 一次 `mcpp build` 会往工程根写 5 处(`target/`、`mcpp.lock`、`compile_commands.json`、`.mcpp/`、`target/.build-mcpp`),而「注册表包根是共享的、可能只读、绝不写入」是 `build_program.cppm` 自 G2 起的明文不变量 —— 在此之前没有任何东西能对 build.mcpp 的临时目录之外兑现它。把「源码在哪」与「往哪写」拆开,是 host 工具子构建**能够存在**的前提。五处一起搬:只搬一部分比一处都不搬更糟,那等于照样写进共享目录、只是更不显眼。
+
+### 改进
+
 - **内带 xlings 升级到 `2026.8.5.1`**(自 `2026.8.4.1`)。13 个 pin 点由 `check_version_pins.sh` 机器校验并全部更新。
 
+### 修复
+
+- **自举 pin 指向了索引已不再提供的版本。** `ci-aarch64-fresh-install` 自 2026-08-03 起在 main 上就是红的:`version '2026.8.3.2' not found for 'mcpp'`。`.xlings.json` 的自举 pin 是**自举起点**、故意滞后、不随发布走(docs/09 §4),平时不该动 —— 但它有一条硬约束是**必须命名一个可安装的版本**,这条被打破时正是该 bump 的场合(而不是「发版顺手 bump」那种误用)。改到 `2026.8.4.1`。
+
 ## [2026.8.4.1] — 2026-08-04
 
 ### 修复
 
@@ -123,7 +123,7 @@ required_features = ["gui"]                   # only built when feature `gui` is
 |---|---|
 | `defines` | Preprocessor macros (`name` or `name=value`); desugar to `-D<x>` on both the C and C++ entry compile. |
 | `cxxflags` / `cflags` | Extra compile flags for this target. Do **not** put `-std=...` here — use `[package].standard`. |
-| `required_features` | The target is emitted only when **every** listed feature is active in the build; otherwise it is silently skipped. A gate only — it does not activate features (use `--features` / `[features].default`). |
+| `required_features` | The target is emitted only when **every** listed feature is active in the build; otherwise it is silently skipped. A gate only — it does not activate features (use `--features` / `[features].default`). **One exception, and it is not a second rule:** when this target is requested as a host tool (`tools = [...]`, §2.14), the target is what was *asked for*, so its `required_features` become the sub-build's *inputs*. Same field, one meaning — the resolution just runs in the opposite direction. |
 
 > **Scope (important):** `defines` / `cxxflags` / `cflags` on a target apply **only to that
 > target's exclusive entry source** (its `main`) — never to shared module/impl objects, which
@@ -964,6 +964,90 @@ build needs (`make`/`cmake`/`protoc`/…), pin tool versions per project, or set
 build-time env vars — without hand-editing `.xlings.json`. `[toolchain]` (§2.7) remains
 the ergonomic shorthand for the compiler; `[xlings.workspace]` is the general form.
 
+### 2.14 Host tools from a dependency (mcpp 2026.8.5.1+)
+
+A package can build a binary its consumers need *at build time* — `protoc`, a
+`grpc_cpp_plugin`, `flatc`, `moc`, a transpiler. Ask for it on the dependency:
+
+```toml
+[dependencies]
+protobuf = { version = "35.1",   tools = ["protoc"] }
+grpc     = { version = "1.83.0", tools = ["grpc_cpp_plugin"] }
+```
+
+Each name must be a `kind = "bin"` target of that package. mcpp builds it **for
+the build machine** and hands `build.mcpp` its absolute path as
+`MCPP_DEP_<PKG>_BIN_<TOOL>` — read it with `mcpp::dep_bin("protobuf", "protoc")`
+(see [07 — build.mcpp](07-build-mcpp.md)).
+
+Four properties worth knowing:
+
+- **Always a host binary.** Under `mcpp build --target <triple>` the tool is
+  still built for *this* machine, because a code generator has to run here. It
+  is a separate, host-targeted sub-build — the tool package's own `[toolchain]`
+  and its own dependency resolution apply, and none of it has to agree with
+  your build. That is safe precisely because an executable has no ABI contact
+  with your code.
+- **One version axis.** The tool's version *is* the dependency's version, so
+  a `protoc` that does not match its runtime is not expressible. (This is the
+  problem with packaging the tool separately, and it is the failure mode that
+  bites at run time rather than compile time.)
+- **Default off.** Nothing is built unless someone asks; the cost is the
+  consumer's to pay. A package gates the expensive part with
+  `[features]` + `required_features` (protobuf's `protoc` needs libprotoc's
+  ~157 extra TUs, which the runtime's users must not compile).
+- **Cached globally**, keyed on package version × host toolchain × features ×
+  its own dependency closure — built once per machine, not once per project.
+
+#### `[tools.overrides]` — use a binary you already have
+
+```toml
+[tools.overrides]
+"compat.protobuf:protoc" = "/usr/bin/protoc"
+```
+
+or, without editing the manifest (CI, distro packaging):
+
+```bash
+MCPP_TOOL_PROTOBUF_PROTOC=/usr/bin/protoc mcpp build
+```
+
+An override **skips the build entirely**. Every comparable system provides this
+escape hatch (vcpkg's `VCPKG_HOST_TRIPLET`, CMake's `LLVM_NATIVE_TOOL_DIR`,
+Qt's `QT_HOST_PATH`), and for the same reason: a tool that cannot be built from
+source on this machine must not be a dead end. It is deliberately **not** part
+of the cache key — an override is an escape hatch, not a reproducible input.
+
+#### `host-module = true` — reusable build rules as packages
+
+A rule (say "run protoc over these `.proto` files") should be written once, not
+copy-pasted into every consumer's `build.mcpp`. Ship it as an ordinary mcpp
+library package and import it:
+
+```toml
+[dependencies]
+"mcpp.rules.protobuf" = { version = "0.1.0", host-module = true }
+```
+
+```cpp
+// build.mcpp
+import mcpp;
+import mcpp.rules.protobuf;
+int main() { mcpp::rules::protobuf::generate(/* … */); }
+```
+
+mcpp compiles that package's lib-root module **for the host, in the same
+command as `build.mcpp`** — which is what makes the BMI usable at all, since a
+module interface is only importable by a compile that agrees with it on
+standard, dialect and compiler identity.
+
+Rules are therefore versioned, testable and distributable through the package
+manager you already have, written in **C++** — no second language, which is the
+whole point of `build.mcpp` existing.
+
+*Limit:* the rule interface is compiled alone, so it may import `std` and the
+bundled `mcpp` module, but not a third package. A rule package is a leaf.
+
 ## Appendix A. Schema Ownership Principle (admission criteria for new fields)
 
 > **Closed syntax, open vocabulary**: whoever owns the parsing semantics defines the keys; whoever owns the domain knowledge defines the values.
 
@@ -97,6 +97,95 @@ int main() {
 | `mcpp::source(p)` | `mcpp:source=` |
 | `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 |
+| `mcpp::dep_bin(pkg, tool)` *(2026.8.5.1+)* | reads `MCPP_DEP_<PKG>_BIN_<TOOL>` — the absolute path of a **host tool** built by a dependency (see below) |
+| `mcpp::action{…}.submit()` *(2026.8.5.1+)* | `mcpp:action=` — declares a **build-graph node** instead of doing the work here (see below) |
+
+### Host tools from a dependency (2026.8.5.1+)
+
+Declare the need in `mcpp.toml`, then call it:
+
+```toml
+[dependencies]
+protobuf = { version = "35.1", tools = ["protoc"] }
+```
+
+```cpp
+// build.mcpp
+import mcpp;
+int main() {
+    const char* protoc = mcpp::dep_bin("protobuf", "protoc");
+    // … invoke it, then declare what it produced …
+}
+```
+
+mcpp builds that `kind = "bin"` target **for the build machine** (even under
+`--target`), caches it globally, and hands you the path. The request lives in
+`mcpp.toml` rather than here for the same reason a dependency does: asking the
+graph for an extra artifact is a graph-level request, and the graph stays
+statically analysable. See [05 §2.14](05-mcpp-toml.md) for the full contract,
+including `[tools.overrides]`.
+
+### Declaring work instead of doing it: `mcpp::action` (2026.8.5.1+)
+
+Generating a source by writing it *here* is the easy path and the wrong one
+past a certain size: it happens once per prepare, for the whole set, serially,
+and a failure is reported as "build.mcpp exited 1". **Declare** the work and it
+becomes an edge in the build graph — incremental, parallel, and attributable to
+the edge that failed.
+
+```cpp
+import mcpp;
+int main() {
+    const std::string out = std::string(mcpp::out_dir()) + "/foo.pb.cc";
+    mcpp::action a;
+    a.id = "protoc:foo";
+    a.role = "source";                       // "source" | "check" | "artifact"
+    a.arg(mcpp::dep_bin("protobuf", "protoc"))
+     .arg("--cpp_out=...").arg("proto/foo.proto")
+     .input("proto/foo.proto")
+     .output(out.c_str())
+     .submit();
+}
+```
+
+Three roles, one primitive — `role` only decides where the edge's outputs
+attach:
+
+| `role` | Outputs | Ordering | Typical |
+|---|---|---|---|
+| `source` | join the compile set | the compile edge consumes them | protoc, a transpiler |
+| `check` | a stamp file | runs **alongside** compilation (set `blocking = true` to gate it) | clang-tidy, a format or ABI check |
+| `artifact` | a new file | its *inputs* are link outputs, so it runs after the link | codesign, packaging, size budgets |
+
+No phase machinery is involved: ninja's own file dependencies do the
+sequencing, which is also why an `artifact` action cannot double-apply itself
+the way a naive "post-build hook" would.
+
+**You must name the output files.** mcpp fixes the source set, the fingerprint
+and the module graph during prepare, so an output whose *name* is unknown
+cannot be built. Content may arrive later; names may not. A malformed action is
+a hard error, never a silent skip.
+
+For a generated **module interface**, declare its interface too:
+
+```cpp
+a.output(gen.c_str()).provides("my.generated").imports("std").submit();
+```
+
+mcpp seeds a placeholder carrying exactly that declaration so the prepare-time
+scan agrees with what your generator will emit — the same assertion-plus-
+verification trade `[modules].scan_overrides` makes, and the compiler's own
+P1689 output checks it at build time.
+
+Commands are an **argv, not a shell string** (no shell is assumed — Windows has
+none to rely on), and the only interpolations are a closed set:
+
+| Variable | Value |
+|---|---|
+| `${mcpp.out_dir}` | the build output directory |
+| `${mcpp.bin_dir}` | where produced binaries land |
+| `${mcpp.compile_db}` | path to `compile_commands.json` (what clang-tidy's `-p` wants) |
+| `${mcpp.target_file:<name>}` | the built file of target `<name>` |
 
 The raw stdout protocol above remains the low-level substrate; `import mcpp;`
 is the typed layer over it.