Skip to content

Commit 21537b6

Browse files
mcpp why platform and reading-time checks replace mcpp check; a patch is written with git diff; a test run is kept in the mtest store
- `mcpp check` and `mcpp patch` are removed. A platform's statement is checked as its manifest is read (a built-in row redefined or a row defined twice is an error; a provider serving no row and a priority tie are warnings), and `mcpp why platform` lists the rows it defines and the identities it serves. One list of a statement's providers (mcpp.manifest.platform_providers) serves the registration, the check and the report. - `mcpp why deps` and resolution.json state each package's root (`manifest_dir`), from which `git diff` writes a patch (docs/05). - `mcpp test` keeps each run in the mtest store's form under target/mtest (`[test] store`); the schedule of each process is recorded. - A test that keeps what it reaches reads the protocol marker from the objects it was linked from when the link dropped it (mtest before 0.5.1). - A platform that links with ld.lld keeps its own link line for tests. - The tier check reads data/builtin.toml; docs/21 lists the three rows it lacked. Co-authored-by: speak-agent <248744407+speak-agent@users.noreply.github.com>
1 parent 1fa0939 commit 21537b6

45 files changed

Lines changed: 746 additions & 705 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/docs/2026-11-09-target-model-design.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -118,7 +118,7 @@ Emscripten SDK。openkal-platform 的 hosted 部分为提供者,服务 `*-linu
118118
|---|---|
119119
| G6 描述符 | 源码制品一份、与目标无关;预编译 payload 按身份的轴匹配,含 `any` 与回落;`linux`、`macosx`、`windows`、`openkal`、`none` 块作为轴组合的别名读取,已有索引条目不变;`descriptor_keys` 照旧可读,不再必需 |
120120
| G7 能力槽 | SPEC-002 的层机制推广到普通包:`requires` 加按系统的默认提供者;解析顺序为依赖图 > 平台 > 默认值。openkal-run 的清单随之改写 |
121-
| G8 补丁根 | 包根(解析后的清单所在目录)或显式 `patch_root`;`mcpp patch edit/save` |
121+
| G8 补丁根 | 包根(解析后的清单所在目录)或显式 `patch_root`;`mcpp why deps` 报告包根,补丁由 `git diff` 写出 |
122122
| G9 按产物的编译变体 | `[targets.X.build] defines/cflags/cxxflags` 作用于该产物链接的本包翻译单元,在 `obj/_variant/<X>/` 编译变体;`[targets.X] defines/flags` 维持只作用于入口;模块接口每包一个,不做变体 |
123123
| G10 载体与打包 | 任何已解析平台能构建的行,按平台声明作载体或打包的系统 |
124124
| G11 执行宿主 | 运行器协议:传输、运行、输出流、退出码,由 runner 包实现(VM、ssh、设备);无运行器的异系统产物为「已构建,未运行」 |
@@ -200,7 +200,7 @@ Emscripten SDK。openkal-platform 的 hosted 部分为提供者,服务 `*-linu
200200
| 应用开发者 | 不必学新概念 | 「行」「提供者」「优先级」是实现与平台作者的概念 | R3:用户文档只用「请求的 target」「构建的 target」「提供者」三个词;「行」「priority」只出现在 SPEC-016 与平台作者文档 |
201201
| 应用开发者、平台开发者 | 指定用谁 | 「选一个提供者」现在有 `platform`、`toolchain`、`--platform none` 三种写法,语义交叠 | R4:内置提供者有名字(如 `builtin:msvc`、`builtin:mingw`、`builtin:glibc`);`platform` 选择一个提供者,名字或包引用皆可;`--platform none` 表示不用平台包、只用内置提供者,含义不变;`toolchain` 只选编译器族与版本,与提供者按 `pairs` 配对。不新增键或标志 |
202202
| 库开发者 | 条件依赖与预编译 payload 按 target 匹配 | Q5 使依赖图供给 C 库的项目身份改变,以 `cfg(env = "gnu")` 写的条件可能不再成立 | R5:CHANGELOG 与 docs/22 写出迁移:按 C 库写的条件应以实际 C 库为准;`mcpp why target` 显示 `cfg` 求值所用的身份 |
203-
| 平台开发者 | 用最少的键写出一个平台 | `[platform]` 与 `[platform.hosted]` 是两个特例的提供者,第三个提供者没有写法 | R6:一般形式 `[[platform.provider]]`(`serves`、`priority`、`toolchain`、`layers`、`link`、`hosted`、`execution`、`pairs`);`[platform]` 与 `[platform.hosted]` 为其两种简写,照旧可读。`mcpp new --template platform` 生成一个最小平台;`mcpp check platform` 校验 schema、行与提供者的一致、`priority` 冲突,并列出它服务的身份 |
203+
| 平台开发者 | 用最少的键写出一个平台 | `[platform]` 与 `[platform.hosted]` 是两个特例的提供者,第三个提供者没有写法 | R6:一般形式 `[[platform.provider]]`(`serves`、`priority`、`toolchain`、`layers`、`link`、`hosted`、`execution`、`pairs`);`[platform]` 与 `[platform.hosted]` 为其两种简写,照旧可读。`mcpp new --template platform` 生成一个最小平台;读取平台清单时校验行与提供者的一致与 `priority` 冲突;`mcpp why platform` 列出它服务的身份 |
204204
| 构建插件开发者 | 构建程序读到的 target 与引擎一致 | `mcpp::target_os()` 等访问器的文档以封闭集合描述取值;新系统的 os 值须照样流过 | R7:访问器返回身份的轴(字符串,取值由行定义);新增 `mcpp::target_provider()`(`MCPP_TARGET_PROVIDER`);docs/30 的取值表改为「由行定义,内置行为……」 |
205205
| agent | 可脚本化、确定、可解释 | 构建的机器输出只有身份,没有请求与提供者;拒绝没有稳定的代码 | R8:机器输出的 target 记录为 `{request, identity, provider, priority, fallback}`;选择的拒绝有稳定代码(`target-unserved`、`target-ambiguous` 等,进 SPEC-016 的拒绝码表);文档建议自动化写完整身份 |
206206
| mcpp 开发者 | 迁移不引入回归,代码不再散落 | 原生约定由代码移为数据是一次大改 | 第 9 节的等价性快照为合入条件;选择逻辑集中于一个模块,旧的代理条件(目标表 pin、`toolchain_decision` 的拒绝、三元组补全中的推断)随迁移删除,不保留双轨 |
@@ -370,7 +370,7 @@ mcpp 的单元测试(`tests/unit/` 166 个文件,以及各成员的 `modules
370370
| A1 | mcpp | 行与内置提供者为数据(build.mcpp 编入静态表)、等价性快照 | — (已完成) |
371371
| A2 | mcpp | 选择:行的登记、开放的 os 与 env、`select`、prepare 接入(pin、平台、可服务判断、报告) | A1(进行中) |
372372
| A3 | mcpp | 身份取实际 C 库(重新准备)、显式身份与图冲突的拒绝 | A2 |
373-
| A4 | mcpp | `[[platform.define]]`、`[[platform.provider]]` 的读取与登记;`[platform]`、`[platform.hosted]` 为简写;`mcpp check platform`、`mcpp new --template platform` | A2 |
373+
| A4 | mcpp | `[[platform.define]]`、`[[platform.provider]]` 的读取与登记;`[platform]`、`[platform.hosted]` 为简写;清单读取时的语句校验、`mcpp why platform`、`mcpp new --template platform` | A2 |
374374
| A5 | mcpp | llvm 配 mingw 载荷 | A2 |
375375
| A6 | mcpp | #911 G2–G11、B1–B3 | A4 |
376376
| A7 | mcpp | 统一的包引用(`git+`、缺省分支、`builtin:`);SPEC-001 修订 | — |
@@ -399,5 +399,6 @@ mcpp 的单元测试(`tests/unit/` 166 个文件,以及各成员的 `modules
399399
| 拒绝码 | 沿用 `host-cannot-serve`、`unknown-target`、`tier-planned` | 不新增与既有码同义的 `target-unserved` 等 |
400400
| B2 | 只约束构建程序的 `artifact-name` | 项目与本机对产物名的陈述是显式选择,照常生效 |
401401
| G9 | 新表 `[targets.X.build]` | 现有键的作用范围不变,升级无感 |
402-
| G8 `mcpp patch edit/save` | 保留 | 补丁是核心功能,编辑流程与之同属(同 pnpm 的 `patch`/`patch-commit`) |
402+
| G8 `mcpp patch edit/save` | 不采纳 | 核心保留的是补丁契约(`patches`、包根、`patch_root`);编辑与生成是通用工具的事:`mcpp why deps` 报告包根,`git diff` 写出补丁,无功能缺口 |
403+
| `mcpp check platform` | 不采纳,并入清单读取与 `mcpp why platform` | 一级子命令须有独立的场景;平台语句的校验在读取清单时进行,作者与使用者在构建中即得到;所服务的身份属来源解释,与 `why target`、`why flags` 同族 |
403404
| 测试程序 | 按目录组成为可选(`[test] programs`);`[test] split` 按文件分进程为缺省;测试只保留可达部分(`--gc-sections`) | 缺省不改变既有工程的程序划分与命名;按文件分进程同时保留隔离与并行 |

‎.github/tools/check_target_tiers.py‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
#!/usr/bin/env python3
22
"""Every documented tier agrees with the target table.
33
4-
WHY THIS EXISTS. `kKnownTargets` in modules/toolchain-model/src/triple.cppm is
5-
the single source for a row's tier, and four documents restate it: both
4+
WHY THIS EXISTS. The built-in rows, modules/toolchain-model/data/builtin.toml
5+
(SPEC-016 §2.2), are the single source for a row's tier, and four documents restate it: both
66
READMEs, both copies of docs/21. When `wasm32-emscripten` became `verified` and
77
the Android rows gained tiers, docs/21 was updated and the READMEs were not --
88
so the front page told a reader that three targets were `planned` while the
@@ -16,17 +16,19 @@
1616
"""
1717
import re
1818
import sys
19+
import tomllib
1920
from pathlib import Path
2021

2122
ROOT = Path(__file__).resolve().parents[2]
22-
TABLE = ROOT / "modules/toolchain-model/src/triple.cppm"
23+
TABLE = ROOT / "modules/toolchain-model/data/builtin.toml"
2324
TIERS = ("verified", "preview", "planned")
2425

2526
# The engine's answer.
2627
rows = {}
27-
for m in re.finditer(r'^\s*\{\s*"([a-z0-9_.+-]+)",\s*"(verified|preview|planned)"',
28-
TABLE.read_text(), re.M):
29-
rows[m.group(1)] = m.group(2)
28+
with TABLE.open("rb") as f:
29+
for row in tomllib.load(f).get("platform", {}).get("define", []):
30+
if row.get("tier") in TIERS:
31+
rows[row["triple"]] = row["tier"]
3032
if len(rows) < 20:
3133
sys.exit(f"ERROR: only {len(rows)} rows parsed from {TABLE.name}; "
3234
"the pattern no longer matches the table")

‎CHANGELOG.md‎

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -39,9 +39,9 @@
3939
provider of a capability it requires, taken when neither the graph nor the
4040
platform provides it (G7).
4141
- A patch names files from the package's root; `patch_root` names another
42-
directory. `mcpp patch edit <dependency>` and `mcpp patch save <dependency>`
43-
edit a dependency's sources and save the change as the edge's next patch
44-
(G8).
42+
directory, and a patch written from the archive's top applies as before.
43+
`mcpp why deps` reports each dependency's root, from which `git diff` writes
44+
a patch (G8).
4545
- `[targets.<name>.build]` compiles the shared sources an artifact links with
4646
its own defines and flags, as the artifact's variant (G9).
4747
- A row a platform defines is packed and carries as a built-in row does;
@@ -53,11 +53,18 @@
5353
its cases (`[test] split = "file" | "case" | "none"`), and a test keeps what
5454
it reaches: units are compiled with one section per function and per object
5555
and tests link with `--gc-sections` (`[test] link = "objects"` keeps every
56-
object whole). mcpp's own unit tests are one program per directory: 166
56+
object whole); a protocol marker nothing references is read from the objects
57+
the test was linked from. A run is kept in the mtest store's form under
58+
`target/mtest` (`[test] store`), which `mtest report`, `analyze` and `graph`
59+
read. mcpp's own unit tests are one program per directory: 166
5760
programs of 32 MB became one of 37 MB, run as 166 processes.
5861
- clang pairs with the MinGW-w64 payload for `x86_64-windows-gnu`: the payload
5962
is clang's sysroot and libstdc++ its C++ library, `import std` included.
60-
- `mcpp new --template platform` and `mcpp check platform`.
63+
- `mcpp new --template platform`. Reading a platform's manifest refuses a
64+
definition of a built-in row and a row defined twice, and warns of a provider
65+
that serves no row and of two providers at one priority for one identity;
66+
`mcpp why platform` lists the rows a platform defines and the identities it
67+
serves, with their providers and priorities.
6168
- `mcpp pack --all-programs` ships every program of a package.
6269
- A git reference that names no tag, rev or branch follows the remote's
6370
default branch; `--platform git+<url>[#tag=|rev=|branch=]`.
@@ -71,8 +78,9 @@
7178
identities; `aarch64-linux` on an x86_64 host is `aarch64-linux-musl`. An
7279
identity written whole is not replaced.
7380
- The identity follows the C library: a project whose graph supplies musl
74-
builds `x86_64-linux` as `x86_64-linux-musl`; an explicit identity that
75-
disagrees with the graph's C library is refused (`target-cabi-conflict`).
81+
builds `x86_64-linux` as `x86_64-linux-musl`; an explicit identity is the
82+
project's spelling and is kept, and a disagreement with the graph's C library
83+
is reported.
7684
- A git dependency names at most one of rev, tag and branch.
7785
- `mcpp pack` with several programs packs the one named after the package and
7886
names the others, and refuses when none is so named.

‎docs/04-mcpp-toml.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2156,6 +2156,9 @@ discover = ["tests/**/*.cpp"] # the default
21562156
| `main` | `{ from = "<dependency>/<entry>" }` | the entry target every test program begins in; each test file is then an ordinary translation unit of its program and defines no `main` (§2.2, `kind = "entry"`) *(2026.10.26.2+)* |
21572157
| `start` | symbol | the symbol every test image is entered at, on a freestanding target (§2.2, `start`) *(2026.10.26.2+)* |
21582158
| `programs` | `"file"` or `"directory"` | `"file"` (the default): every discovered file is a program; `"directory"`: the files of one directory below a glob's fixed directory are one program, named by the directory, beginning at the file that defines `main` when one does *(2026.11.8.1+)* |
2159+
| `split` | `"file"`, `"case"` or `"none"` | how a program that speaks the test protocol is run: a process per file of its cases (the default), per case, or once *(2026.11.9.1+)* |
2160+
| `link` | `"used"` or `"objects"` | `"used"` (the default): a test links what it reaches (`--gc-sections`, `-dead_strip`); `"objects"`: every object whole *(2026.11.9.1+)* |
2161+
| `store` | directory or `"none"` | where a run is kept in the mtest store's form, relative to the project; the default is `target/mtest`; `"none"` keeps nothing *(2026.11.9.1+)* |
21592162

21602163
The globs use the vocabulary of `[build] sources`. A test's name is its path
21612164
relative to the fixed directory of the first glob that matched it, without the

‎docs/05-dependencies.md‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -680,10 +680,19 @@ verified source.
680680
names another directory, relative to the package's root and inside its
681681
source. A patch written from the archive's top, as before 2026.11.9, applies
682682
as written, and the build says so.
683-
- `mcpp patch edit <dependency>` copies the package's root, as the build reads
684-
it (its patches applied), to `target/patch/<dependency>/`; `mcpp patch save
685-
<dependency>` writes the change as the edge's next patch,
686-
`patches/<name>-<NNNN>.patch`, and adds it to the edge's `patches`.
683+
- `mcpp why deps` reports each dependency's root as the build reads it (its
684+
patches applied). A patch is the difference git writes from a copy of that
685+
tree:
686+
687+
```sh
688+
cp -R <root> /tmp/zlib && cd /tmp/zlib
689+
git init -q && git add -A && git commit -qm base
690+
# edit, then
691+
git diff > <project>/patches/0001-fix.patch
692+
```
693+
694+
and the edge lists it in `patches`. A further patch is written the same way
695+
from the root the patched build reports, and is listed after the first.
687696
- Version and git dependencies may carry patches; a `path` dependency is a tree
688697
its consumer owns and is refused with them.
689698
- `mcpp.lock` names the variant and each patch by its path and SHA-256;

‎docs/08-testing.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,14 @@ every function (mcpp's own unit tests: 32 MB each to 14 MB). Static
7979
constructors are the collection's roots. `[test] link = "objects"` keeps every
8080
object whole.
8181

82+
A run is kept in the form of the mtest store (2026.11.9.1+): `target/mtest/`
83+
holds `runs/<id>/run.json`, a line per process in `programs.ndjson` (its
84+
status, duration, start, worker and selected cases) and a line per case in
85+
`cases.ndjson`, and `index.ndjson` lists the runs. `mtest report`, `analyze`
86+
and `graph --store target/mtest` read them as mtest's own runs: the report, the
87+
slowest cases and the run's schedule. `[test] store = "<dir>"` names another
88+
directory, relative to the project; `"none"` keeps nothing.
89+
8290
A suite compiled from several sources of its own is also a package: a workspace
8391
member whose `[build] sources` carries the suite and whose one test program
8492
drives it, selected with `mcpp test -p <member>`.
@@ -321,7 +329,9 @@ test-protocol = 1
321329
```
322330

323331
or when its file carries the marker `mtest-protocol=1`, as a program built
324-
with mtest's libraries does. A program that carries the marker and writes no
332+
with mtest's libraries does; of a test that keeps what it reaches, an object it
333+
was linked from carrying the marker counts as well, so a marker nothing
334+
references (mtest before 0.5.1) is not lost at the link. A program that carries the marker and writes no
325335
`program` event spoke no protocol: a file of plain `main` linked beside a
326336
framework's library is one case, judged by its exit status, run and listed. mcpp then gives the program the protocol's
327337
variables (`MTEST_PROTOCOL`, `MTEST_MODE`, `MTEST_REPORT`, `MTEST_TMPDIR`, and

‎docs/09-commands-by-scenario.md‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -216,9 +216,11 @@ dependency graph:
216216
requested by huxdemo.comp@0.1.0 as 'fw' in [dependencies]
217217
linked static (default)
218218
instances: target
219+
root: /work/fw
219220
```
220221

221-
`instances` states whether the package is compiled for the target, for the
222+
`root` is the package's root as the build reads it, a patched dependency's
223+
being its variant's (2026.11.9.1+; docs/05). `instances` states whether the package is compiled for the target, for the
222224
build programs, or for both (2026.10.11.1+). `mcpp why build-programs` lists the
223225
build programs' graphs: each program, the libraries it uses, the identity it
224226
was compiled from and its binary. `mcpp why compat` lists every use of a
@@ -227,8 +229,14 @@ deprecated reading with the release that removes it (51 — Supported Versions).
227229
The same graph is recorded under `graph` in
228230
`target/<triple>/<fp>/resolution.json`, one entry per package with the root
229231
first: `package` (canonical identity, namespace, name, version, source),
230-
`root`, `requested_by` (`requester`, `key`, `table`), and, for a library,
231-
`link` (`form`, `reason`).
232+
`root`, `requested_by` (`requester`, `key`, `table`), `manifest_dir` (the
233+
package's root), and, for a library, `link` (`form`, `reason`).
234+
235+
`mcpp why target` lists a request's candidates in order (docs/21), `mcpp why
236+
flags [<unit>]` each word of a unit's command line with the layer that gave it,
237+
and `mcpp why platform` the rows a platform defines and the identities it
238+
serves (docs/35); the last two are not part of the report without a topic
239+
(2026.11.9.1+).
232240

233241
The topic is `toolchain`, `runtime`, `deps` or `runners`, and all four report
234242
when none is named. `--target` and `--toolchain` turn the report into a query
@@ -765,7 +773,7 @@ mcpp is involved and its documentation will not help.
765773
## Current limitations
766774

767775
- `mcpp why --format json` is defined for the `toolchain`, `sources`, `tool`,
768-
`payload`, `build-programs` and `compat` topics. The other topics report
776+
`payload`, `build-programs`, `compat`, `target`, `flags` and `platform` topics. The other topics report
769777
`'<topic>' has no machine-readable shape yet` and exit non-zero.
770778
- `mcpp search` matches a substring; there is no field selector, and no way to
771779
restrict a search to one namespace.

‎docs/21-the-target-triple.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -528,10 +528,13 @@ other's rows.
528528
| `x86_64-windows-msvc` | verified | — | — | — | — | system |
529529
| `aarch64-macos` | verified | — | — | — | SDK | — |
530530
| `x86_64-macos` | planned | — | planned | planned | planned | planned |
531+
| `aarch64-macos-musl` | preview | `llvm@23.1.3` | graph | graph | graph | graph |
532+
| `x86_64-macos-musl` | preview | `llvm@23.1.3` | graph | graph | graph | graph |
531533
| `riscv64-none-elf` | verified | `llvm@23.1.3` | payload | payload | payload | payload |
532534
| `riscv32-none-elf` | verified | `llvm@23.1.3` | payload | payload | payload | payload |
533535
| `aarch64-none-elf` | preview | `llvm@23.1.3` | payload | payload | payload | payload |
534536
| `x86_64-none-elf` | preview | `llvm@23.1.3` | payload | payload | payload | payload |
537+
| `i686-none-elf` | preview | `llvm@23.1.3` | payload | payload | payload | payload |
535538
| `thumbv6m-none-eabi` | verified | `llvm@23.1.3` | payload | payload | payload | payload |
536539
| `thumbv7m-none-eabi` | verified | `llvm@23.1.3` | payload | payload | payload | payload |
537540
| `thumbv7em-none-eabi` | preview | `llvm@23.1.3` | payload | payload | payload | payload |

‎docs/35-platforms.md‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -312,9 +312,14 @@ built-in row is another row. `[platform]` and `[platform.hosted]` remain the two
312312
shorthands of a provider.
313313

314314
`mcpp new <name> --template platform` writes a platform package defining
315-
`<arch>-<name>`; `mcpp check platform [dir]` reads one as the engine does --
316-
its rows, its providers and the identities it serves with their priorities --
317-
and refuses a row that redefines a built-in one.
315+
`<arch>-<name>`. Reading a platform's manifest checks its statement against the
316+
rows: a definition of a built-in row, or a row defined twice, is an error
317+
wherever the platform is read; a provider that serves no row, and two providers
318+
that serve one identity at one priority, are warnings of the platform's own
319+
build. `mcpp why platform` lists the rows the platform defines and the
320+
identities it serves, each with its provider and priority: in the platform's
321+
directory its own, in a project the one its target selects (`--target`;
322+
`--format json`).
318323

319324
## Inspecting a configuration
320325

0 commit comments

Comments
 (0)