Skip to content

Commit 1fa0939

Browse files
SPEC-016; specs and docs of the round; CI findings fixed
- SPEC-016 (targets and providers); SPEC-001 §5.5 (git references), SPEC-002 §3.4/§3.6/§3.7, SPEC-013 §1/§9.2/§11; docs 05, 08, 20, 21, 22, 35, 41, 90. - A written C library over a graph's other one is reported, not refused (SPEC-002 §3.4); the unused refusal codes are removed. - A build program's artifact-name alone yields to a platform's format; the project's and the machine's statements stand. - A test linked by a platform's ld.lld keeps its own link line; a capability default's line is an int (clang's narrowing). - e2e 299 and 746 state the selection; 1044 installs llvm itself. Co-authored-by: speak-agent <248744407+speak-agent@users.noreply.github.com>
1 parent 1b60252 commit 1fa0939

29 files changed

Lines changed: 432 additions & 109 deletions

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

Lines changed: 19 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
subject: target-model
3-
status: accepted
3+
status: active
44
---
55

66
# 目标与提供者:统一的目标模型(结合 mcpp#911)
@@ -65,7 +65,7 @@ SPEC-013 §0 规定引擎不持有任何平台的知识,§14 又规定宿主
6565
| `hosted` | C 环境是否 hosted;sysroot 或 c-abi 提供者亦可声明 `hosted-standard-library` | G3 |
6666
| `[platform.link] driver` | 在每一行生效;`"compiler"` 交由编译器驱动加入启动文件与库 | G4 |
6767
| `execution` | 产物的执行环境(系统、加载器) | G5、G11 |
68-
| 默认参数 | 带来源的数据;更具体的声明方以显式 `replace` 替换,否则追加 | G2 |
68+
| 默认参数 | 行的机器描述不可替换;机器不同的目标是另一行(G1、G12);每个参数的来源由 `mcpp why flags` 写出 | G2 |
6969
| `pairs` | 可与之配对的编译器族(如 mingw 提供者:gcc、llvm) | 第 7 节 |
7070

7171
**内置提供者。** 原生约定改写为随引擎发布的提供者:glibc payload(`*-linux-gnu`,native)、musl-gcc(`*-linux-musl`,
@@ -119,13 +119,13 @@ Emscripten SDK。openkal-platform 的 hosted 部分为提供者,服务 `*-linu
119119
| G6 描述符 | 源码制品一份、与目标无关;预编译 payload 按身份的轴匹配,含 `any` 与回落;`linux`、`macosx`、`windows`、`openkal`、`none` 块作为轴组合的别名读取,已有索引条目不变;`descriptor_keys` 照旧可读,不再必需 |
120120
| G7 能力槽 | SPEC-002 的层机制推广到普通包:`requires` 加按系统的默认提供者;解析顺序为依赖图 > 平台 > 默认值。openkal-run 的清单随之改写 |
121121
| G8 补丁根 | 包根(解析后的清单所在目录)或显式 `patch_root`;`mcpp patch edit/save` |
122-
| G9 按产物的编译变体 | `[targets.X] defines/flags` 作用于该产物的共享源码,按参数键编译变体,只在参数不同处 |
122+
| G9 按产物的编译变体 | `[targets.X.build] defines/cflags/cxxflags` 作用于该产物链接的本包翻译单元,在 `obj/_variant/<X>/` 编译变体;`[targets.X] defines/flags` 维持只作用于入口;模块接口每包一个,不做变体 |
123123
| G10 载体与打包 | 任何已解析平台能构建的行,按平台声明作载体或打包的系统 |
124124
| G11 执行宿主 | 运行器协议:传输、运行、输出流、退出码,由 runner 包实现(VM、ssh、设备);无运行器的异系统产物为「已构建,未运行」 |
125125
| B1 | 生成的清单以 TOML 引号书写含 `.` 的目标名 |
126126
| B2 | 平台规定的产物后缀不被宿主后缀规则覆盖;冲突在规划期报告 |
127127
| B3 | 多个程序可打包时拒绝并说明,提供打包一个包的全部程序的写法 |
128-
| 构建插件(SPEC-007) | SPEC-013 §1.2 的分工不变:行、提供者、层只能声明(解析工具链与依赖图时尚无程序可运行);`build`、`link`、`runner` 可由插件陈述,`replace` 在陈述层,来源记录 |
128+
| 构建插件(SPEC-007) | SPEC-013 §1.2 的分工不变:行、提供者、层只能声明(解析工具链与依赖图时尚无程序可运行);`build`、`link`、`runner` 可由插件陈述,来源记录;构建程序的 `artifact-name` 不改变平台的产物格式 |
129129

130130
## 9. 多视角自审
131131

@@ -141,7 +141,7 @@ Emscripten SDK。openkal-platform 的 hosted 部分为提供者,服务 `*-linu
141141
| 缓存与 ABI | `-linux-musl` 可由 musl-gcc 或 openkal-musl 提供;二者的预编译产物是否互换 | 缓存键已含工具链与平台的指纹,二者不共享缓存;索引中按身份匹配的预编译 payload 要求 C 层 ABI 兼容,openkal-musl 与 musl-gcc 的 musl 版本差异列为验证项 |
142142
| 跨平台 | 从 macOS 构建 `-linux-gnu` 需要 glibc payload 能装在 macOS 宿主上 | glibc payload 是目标数据,属 G6 的按身份匹配;在其可得之前,该身份在 macOS 宿主上不可服务,请求 `x86_64-linux` 回落到 `-musl` |
143143
| 跨平台 | macOS 无 SDK 的链接(dyld、libSystem 的存根) | 列为验证项(第 11 节);验证前 `aarch64-macos-musl` 在非 macOS 宿主上标为 preview |
144-
| 安全 | 平台包可以定义行与替换默认参数 | 平台包本就能注入参数;`replace` 只作用于带来源的默认参数,`mcpp explain flags` 写出每个参数的来源层 |
144+
| 安全 | 平台包可以定义行 | 平台包本就能注入参数;定义的行不能覆盖内置行;`mcpp why flags` 写出每个参数的来源层 |
145145
| 性能 | 选择不得拉长构建的准备阶段 | 内置行与提供者由构建程序编为引擎中的静态表,运行时不解析任何文件;平台包只在被选中或已解析时读取(与现在相同);候选按优先级依次检查可得性(本地 store 的存在性),取到第一个即停;结果在一次构建内缓存;`--timings` 报告选择所用时间,e2e 断言其上界 |
146146
| 用户体验 | 新增提示可能冗余 | 只在发生回落时附一句原因;其余沿用现有的「写法 → 身份」与层来源行 |
147147
| 诊断 | 拒绝时用户不知道下一步 | 第 6 节第 6 条:所需、各候选的原因、可执行的命令 |
@@ -387,3 +387,17 @@ mcpp 的单元测试(`tests/unit/` 166 个文件,以及各成员的 `modules
387387
| G1 | 全部 | CI 全绿、生态级自审、合入与发布、xim-pkgindex、clean-room 验证、关闭 issue | 以上全部 |
388388

389389
可以并行的部分:B1、C1 的 CI 运行期间推进 A2–A8;mcpp 的 CI 运行期间推进 D1、E1。发布顺序为 os → mtest → mcpp → openkal-platform 与 openkal-image → mcppls。
390+
391+
392+
## 19. 实现中的取舍(2026-11-09,按“通用、必要、符合规范”评估)
393+
394+
| 项 | 结论 | 理由 |
395+
|---|---|---|
396+
| G2 `replace` | 撤回 | 有了 G1 与 G12,机器不同的目标即另一行;追加参数时编译器取后者。替换机制是多余的核心复杂度 |
397+
| G2 解释 | `mcpp why flags`,不新增 `explain flags` | `why` 是来源解释的既有命令族;`explain` 只解释错误码 |
398+
| 显式身份与图冲突 | 报告,不拒绝(SPEC-002 §3.4 规则四) | 拒绝曾实测打破把宿主身份写作 `x86_64-linux-gnu` 的配置;只有未写 env 的请求随 C 库 |
399+
| 拒绝码 | 沿用 `host-cannot-serve`、`unknown-target`、`tier-planned` | 不新增与既有码同义的 `target-unserved` 等 |
400+
| B2 | 只约束构建程序的 `artifact-name` | 项目与本机对产物名的陈述是显式选择,照常生效 |
401+
| G9 | 新表 `[targets.X.build]` | 现有键的作用范围不变,升级无感 |
402+
| G8 `mcpp patch edit/save` | 保留 | 补丁是核心功能,编辑流程与之同属(同 pnpm 的 `patch`/`patch-commit`) |
403+
| 测试程序 | 按目录组成为可选(`[test] programs`);`[test] split` 按文件分进程为缺省;测试只保留可达部分(`--gc-sections`) | 缺省不改变既有工程的程序划分与命名;按文件分进程同时保留隔离与并行 |

‎.agents/docs/README.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ superseded_by: 2026-09-07-....md # when status is superseded
1818
---
1919
```
2020

21-
355 records.
21+
356 records.
2222

2323
## By subject
2424

@@ -138,6 +138,10 @@ Records that declare one. Everything else is listed by date below.
138138
- [#674 设计方案评审:`-include unistd.h` 在 Windows + `presents = "posix"` 上的可行性](2026-09-20-issue-674-design-review.md) — active
139139
- [`__cxa_thread_atexit` 在 openkal-Windows 上:两层都已定位并修复](2026-09-20-cxa-thread-atexit-finding.md) — landed
140140

141+
### target-model
142+
143+
- [目标与提供者:统一的目标模型(结合 mcpp#911)](2026-11-09-target-model-design.md) — active
144+
141145
### targets
142146

143147
- [A verified Web run that asked the host for node](2026-09-12-a-verified-web-run-that-asked-the-host-for-node.md) — landed
@@ -179,6 +183,7 @@ Records that declare one. Everything else is listed by date below.
179183

180184
### 2026-11
181185

186+
- [目标与提供者:统一的目标模型(结合 mcpp#911)](2026-11-09-target-model-design.md) — active
182187
- [生态顶层方案:#885 收尾之后的工作流、原则与依赖](2026-11-08-ecosystem-top-level-design.md) — active
183188
- [#885 收尾补充方案:目标角色、平台事实、系统接口与版本书写](2026-11-08-ecosystem-885-supplement-design.md) — active
184189
- [生态 #885 收尾设计:核心、插件、openkal、语言服务与编辑器的一轮闭合](2026-11-07-ecosystem-885-closeout-design.md) — active

‎docs/05-dependencies.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -78,10 +78,11 @@ mylib = { path = "../mylib" }
7878
```
7979

8080
```toml
81-
# Git dependency — pick exactly one of tag / branch / rev
81+
# Git dependency — at most one of tag / branch / rev; none follows the default branch
8282
[dependencies]
8383
mylib = { git = "https://github.com/user/mylib.git", tag = "v1.0.0" }
8484
applib = { git = "https://github.com/user/applib.git", branch = "develop" }
85+
tiplib = { git = "https://github.com/user/tiplib.git" } # the remote's default branch
8586
```
8687

8788
```toml
@@ -103,6 +104,12 @@ records the same resolution (2026.10.21.1+). LF and CRLF line endings are accept
103104
without rewriting an otherwise identical file. This does not skip dependency
104105
resolution or change which dependencies the lock pins.
105106

107+
A git dependency that names none of `tag`, `branch` and `rev` follows the remote's
108+
default branch, whose name the remote announces (`main`, `master`, `trunk`, ...;
109+
2026.11.9.1+); it is a `branch` from then on, locked by commit. The same string
110+
forms reach a platform or a tool on the command line:
111+
`--platform git+https://example.org/acme/acme-platform.git#tag=v1`.
112+
106113
**Git dependencies and `mcpp.lock`**: a `tag` or `rev` already names a fixed point
107114
in history, but a `branch` moves. The first build resolves the branch to a commit
108115
and records it in `mcpp.lock`, and every later build rebuilds **that** commit — the

‎docs/20-toolchains.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -307,6 +307,15 @@ Before 2026.8.3.3 a mingw build on a Windows host emitted `foo.lib` — a GNU
307307
archive wearing an MSVC name, which MSVC cannot consume. A script
308308
that globs `*.lib` out of a `windows-gnu` build, it needs to glob `*.a` now.
309309

310+
### clang with the MinGW-w64 payload (2026.11.9.1+)
311+
312+
The MinGW-w64 provider pairs with gcc and with llvm. With llvm declared
313+
(`--toolchain llvm@<v>`, or `[target.x86_64-windows-gnu] toolchain`), the
314+
payload is installed as for gcc and becomes clang's sysroot: its C library,
315+
libstdc++ (whose `bits/std.cc` is the std module, so `import std` works) and
316+
the GCC runtime, linked by lld. The build reports `Pairs clang ... with the
317+
gcc@<v> payload`.
318+
310319
## Linux ELF from Windows (`x86_64-linux-musl`, no WSL required)
311320

312321
The mirror of the section above: a Windows machine producing a **fully static

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

Lines changed: 29 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -146,40 +146,43 @@ A `.js` file carries no shebang, so an emsdk payload installed before its
146146
descriptor gained a `runner` field needs the index refresh
147147
[chapter 20](20-toolchains.md) describes before `mcpp run` finds one.
148148

149-
## Declining The Third Segment
149+
## Declining The Third Segment: A Request Names A System (2026.11.9.1+)
150150

151-
`<arch>-<os>` is a complete target on every platform:
151+
A target written whole is an **identity**: the output directory, the cache key
152+
and the subject of a `cfg()` predicate. A target that names only `<arch>-<os>`
153+
is a **request**: it reaches every identity of that system, and the build takes
154+
the first one whose **provider** -- the toolchain and the target side that
155+
serve it -- is available on this machine (SPEC-016 §4).
152156

153157
```bash
154-
mcpp build --target x86_64-linux # = x86_64-linux-gnu
155-
mcpp build --target x86_64-windows # = x86_64-windows-gnu
158+
mcpp build --target x86_64-linux # x86_64-linux-gnu on Linux; -musl where no glibc payload is
159+
mcpp build --target x86_64-windows # -msvc with MSVC installed, else -musl (openkal-platform)
160+
mcpp build --target aarch64-macos # the Apple identity on macOS, else aarch64-macos-musl
156161
mcpp build --target riscv64-none # = riscv64-none-elf
157-
mcpp build --target aarch64-linux # = aarch64-linux-gnu
158-
mcpp build --target aarch64-macos # macOS has no segment to decline
159162
```
160163

161-
Declining it changes no identity. The output directory, the cache key and the
162-
subject of a `cfg()` predicate are all the canonical form, so the two spellings
163-
share one fingerprint and the second build is a cache hit rather than a second
164-
full build.
164+
The candidates are ordered by the providers' priorities (data the engine ships:
165+
a system's own toolchain and C library first, openkal-platform next, other
166+
conventions after), then by the rows' order. The report says which identity
167+
was taken, and why when the first candidate is not available here:
165168

166-
What differs is the record of what was asked for. A triple serves as an
167-
identity, which must be total, and as a request, which must be able to say
168-
nothing; mcpp keeps both, filling the segment for the identity while recording
169-
that the fill was a fill.
170-
171-
### The completion is chosen from the vocabulary, not from a fixed word
172-
173-
A request with an omitted environment segment is completed against the
174-
known-target table. A supported lexical default takes precedence; otherwise,
175-
a unique supported sibling is selected. If none is supported, the lexical
176-
form is retained and the diagnostic names the registered siblings. An
177-
ambiguous request lists the supported candidates.
178-
179-
`aarch64-linux` selects `aarch64-linux-gnu`. The native Linux ARM64 payload
180-
uses LLVM 23.1.3 and glibc. `aarch64-linux-musl` remains the explicit spelling
181-
for a static musl artifact. A written environment segment is retained.
169+
```text
170+
Target x86_64-windows → x86_64-windows-musl
171+
msvc is not available on linux-x86_64
172+
```
182173

174+
`mcpp why target [--target <t>]` lists the candidates in order with their
175+
priorities and availability (`--format json` for scripts). A project changes
176+
the order with `[target.<selector>.priority] <provider> = <n>`, or chooses a
177+
built-in provider by name with `platform = "builtin:<name>"`. A written
178+
identity is never replaced: `--target x86_64-linux-gnu` builds that identity or
179+
is refused naming what is missing. `mcpp.lock` records the identity each
180+
request was given, and `--locked` refuses a build that selects another.
181+
182+
When the dependency graph supplies the C library (`mcpp:c-abi`) and the request
183+
names none, the identity is the C library's: `x86_64-linux` over a graph's musl
184+
builds `x86_64-linux-musl`. A written segment the graph contradicts is reported
185+
and kept.
183186

184187
### The Spelling To Use
185188

‎docs/22-target-side.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -297,6 +297,27 @@ The check runs before compilation begins. The combination it rejects otherwise
297297
fails inside the runtime's own headers, in a message naming a file the reader
298298
has never opened and no decision mcpp made.
299299

300+
### Default providers (2026.11.9.1+)
301+
302+
A package that requires a capability states the providers it takes when nothing
303+
else provides it, per target (SPEC-002 §3.6):
304+
305+
```toml
306+
[package]
307+
requires = ["mcpp:kernel-abi=openkal"]
308+
309+
[defaults."mcpp:kernel-abi=openkal"]
310+
linux = "openkal-linux@^0.25"
311+
macos = "openkal-macos@^0.25"
312+
"*" = "openkal-posix@^0.25"
313+
```
314+
315+
A provider in the graph -- the consumer's dependency, or the package the
316+
platform adds for its layer -- is used instead; otherwise the default whose
317+
selector matches the target joins the graph as the package's dependency, and
318+
the build reports it (`Default ... for ... of ...`). A selector that names the
319+
target wins over `*`.
320+
300321
The same statement is the recipe for a package whose install hook compiles a
301322
static library from source. The library is compiled against one C++ standard
302323
library and cannot be linked into a program that uses another, and the store

‎docs/35-platforms.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -284,6 +284,38 @@ platform package, with no `--target`, builds its tests for each of its
284284
architecture and those an execution host is named for (2026.10.29.1+), and
285285
reports the others as built and not run.
286286

287+
## Defining targets and providers (2026.11.9.1+)
288+
289+
A platform may serve a system no built-in row names. `[[platform.define]]`
290+
states the row, `[[platform.provider]]` the provider that serves it:
291+
292+
```toml
293+
[[platform.define]]
294+
triple = "x86_64-freebsd"
295+
clang-triple = "x86_64-unknown-freebsd14.1"
296+
object-format = "elf"
297+
family = "unix"
298+
execution = "freebsd" # the system its programs run on
299+
300+
[[platform.provider]]
301+
serves = ["x86_64-freebsd"] # patterns: `*` is any one segment
302+
priority = 100
303+
hosted = true # the C environment has `main`
304+
```
305+
306+
With the platform selected (`[target.x86_64-freebsd] platform = {...}` or
307+
`--platform`), `--target x86_64-freebsd` builds into `target/x86_64-freebsd/`,
308+
`cfg(os = "freebsd")` holds, and a program whose system is not this machine's
309+
is built, not run, until a runner states how it runs (docs/41). The row's
310+
machine description is the platform's: a target whose machine differs from a
311+
built-in row is another row. `[platform]` and `[platform.hosted]` remain the two
312+
shorthands of a provider.
313+
314+
`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.
318+
287319
## Inspecting a configuration
288320

289321
```sh

‎docs/90-build-from-source.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,7 @@ src/
8181
└── scaffold/ `mcpp new` and templates
8282
8383
tests/
84-
├── unit/ 166 mtest programs, discovered by `mcpp test`
84+
├── unit/ 166 files of mtest cases, one test program (`[test] programs = "directory"`)
8585
└── e2e/ 711 shell scripts against a real binary
8686
```
8787

@@ -94,9 +94,10 @@ are C++ programs `mcpp test` discovers. They exercise a module's contract with n
9494
binary and no filesystem state. Each is a file of [mtest](https://github.com/mcpp-community/mtest)
9595
cases: an object `UTest name{"Suite/Case", [] { ... }};` is one case, with no `main`
9696
(`mcpp test --guide`). `mcpp test --case 'TargetSelect/*'` runs the cases a pattern
97-
names; `mcpp test -p <member>` runs a member's.
97+
names; `mcpp test -p <member>` runs a member's. The files are one program, linked once and run as
98+
one process per file.
9899

99-
**End-to-end tests** (`tests/e2e/NN_<name>.sh`, 711 files) run a real `mcpp`
100+
**End-to-end tests** (`tests/e2e/NN_<name>.sh`, 721 files) run a real `mcpp`
100101
binary against a real project. `run_all.sh` is the CI entry point. `mcpp test`
101102
does **not** run them.
102103

‎docs/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -178,3 +178,4 @@ downstream tooling.
178178
- [SPEC-013 — Platforms: the configuration of a class of targets, its selection, merge, graph completion, link, seal, runner and carrier](specs/platforms.md)
179179
- [SPEC-014 — Packaging and distribution: link, closure and container, legs, the staged tree, the platform's tree, run coverage and single-file packages](specs/packaging.md)
180180
- [SPEC-015 — Target sets and legs: spelling and expansion, commands over several legs, test archives](specs/target-sets.md)
181+
- [SPEC-016 — Targets and providers: rows, providers, the selection, platform-defined rows, reports and the lock](specs/targets-and-providers.md)

‎docs/specs/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@
4545
| [SPEC-013](platforms.md) | 平台:`[platform]` 的七组键、版本组与 `hosted`,三种写法与层次,目标图与宿主图的选择,`cfg(platform)`,依赖图的补全,链接、命名与封装,运行器与载体,平台阶段与协议 17 | 评审中 v1.5 | 2026-11-07 | mcpp >= 2026.10.27.1;§10 的执行宿主与 §11 的载体架构 mcpp >= 2026.10.29.1;§7.5 版本组参与解析与 §14 平台系列 mcpp >= 2026.11.7.1;§14 内置平台为确切版本 mcpp >= 2026.11.7.2 |
4646
| [SPEC-014](packaging.md) | 打包与分发:链接、闭包、容器三个维度与构建腿,腿的合并,暂存树与 `mcpp-package.json`,平台的树、运行覆盖、单文件、polyglot、容器列表、签名、压缩、合并与分发描述 | 评审中 v2.1 | 2026-10-31 | mcpp >= 2026.10.31.1;逐条标注 |
4747
| [SPEC-015](target-sets.md) | 目标集合与腿:集合的写法与展开,命令对多条腿的语义,串行规划与一起构建,测试归档,机器输出 | 评审中 v1.0 | 2026-10-30 | mcpp >= 2026.10.30.1 |
48+
| [SPEC-016](targets-and-providers.md) | 目标与提供者:行、提供者、选择规则、平台定义的行、C 环境与执行、报告、机器输出与锁 | 评审中 v1.0 | 2026-11-09 | mcpp >= 2026.11.9.1 |
4849

4950
## 文档约定
5051

0 commit comments

Comments
 (0)