| 项 |
值 |
| 规范编号 |
SPEC-015 |
| 标题 |
目标集合与腿:集合的写法与展开,命令对集合的语义,腿的规划与构建,测试归档,机器输出 |
| 状态 |
评审中 v1.0 |
| 版本 |
1.0 |
| 最后修改 |
2026-10-30 |
| 对应实现 |
mcpp >= 2026.10.30.1 |
| 相关设计文档 |
.agents/docs/2026-10-29-ecosystem-target-sets-packaging-and-editors-design.md(§3) |
| 相关 issue |
mcpp#847 |
| 相关规范 |
SPEC-011(锁与原子发布)、SPEC-013(平台的选择、运行器、执行宿主)、SPEC-014(打包的腿与合并) |
| 使用文档 |
21 —— 目标三元组、08 —— 测试、50 —— 机器输出 |
用语按 RFC 2119:必须 / 禁止为强制,应当为建议,可以为可选。
本规范规定 --target 的一种写法:目标集合,即一个系统(及至多一个环境)所含的、本 mcpp 构建的全部目标;以及
build、run、test、pack、self env 对一组目标(腿)的行为。腿的打包与合并属于 SPEC-014 §1.4。
- 精确目标是三元组,含义不变(docs/21)。
- 目标集合是首段属于系统词表的写法。词表:
linux、macos、windows、openkal、emscripten、ios、android、
none。识别只看首段:triple::parse 不校验首段(unknown-linux-gnu 解析为架构 unknown),所以集合不以解析失败识别。
- 集合由系统与至多一个环境组成:
openkal、linux-musl、windows-gnu、none-eabihf。多于两段的写法被拒绝。
| 写法 |
系统 |
环境 |
linux |
linux |
gnu |
linux-<env> |
linux |
<env> |
windows |
windows |
gnu(不含 msvc) |
android |
linux |
android(不接受更多的段) |
none |
— |
拒绝:裸机没有缺省环境,写出 none-elf、none-eabi、none-eabihf |
none-<env>、ios、ios-<env> |
同名 |
按写法 |
openkal、macos、emscripten |
同名 |
无;写出环境段时被拒绝 |
- 候选为内置目标表中系统与环境都相同、且等级不是
planned 的行。
- 每个候选按 SPEC-013 的规则选择平台(目标行的平台列、
[target.<sel>] platform、MCPP_<T>_PLATFORM)。全部候选
必须选到同一个平台;否则命令被拒绝,消息逐行写出每个候选及其平台。
- 没有候选时命令被拒绝;表中有
planned 的行时,消息写出这些行。
- 结果为规范三元组,按目标表的顺序。
| 写法 |
展开(mcpp 2026.10.30.1 的目标表与 openkal-platform 0.18.0) |
openkal |
x86_64-openkal、aarch64-openkal |
linux-musl |
x86_64-linux-musl、aarch64-linux-musl(planned 的行不在内) |
linux |
x86_64-linux-gnu、aarch64-linux-gnu |
- 一条命令的腿是全部
--target 的并集:集合展开为其成员,精确目标保持原写法(单独规划时的补全与报告不变)。
- 同一目标只算一次(以规范形式比较)。顺序为目标表的顺序;表中没有的目标排在其后,保持书写的顺序。
- 机器输出与摘要只写展开后的目标;集合的写法不进入记录。
[build] target 必须是精确目标;写集合时清单被拒绝。集合可以写在命令行与 [pack] targets(SPEC-014 §2.2)。
| 命令 |
一条腿 |
多条腿 |
build |
构建这条腿 |
构建全部腿,每条腿在 target/<triple>/ 下;一个 Finished |
run |
本机架构经运行器;另一架构经执行宿主(SPEC-013 §10),否则拒绝 |
选第一条能到达的腿,本机架构优先;只构建这一条;写出所选的腿;都不能到达时拒绝 |
test |
同 run 的到达规则;到达不了即拒绝 |
构建全部腿,运行能到达的腿,其余逐条报告"已构建、未运行"及原因;一个测试都没有运行时失败(退出码 1) |
pack |
一个包 |
SPEC-014 §1.4 |
self env |
不变 |
data.legs[] 每项是一份精确目标的报告;顶层取第一条腿 |
平台包中不带 --target 的 mcpp test 遍历平台的 targets,即多条腿的一个特例,行为同上表。
- 腿逐条串行规划:一次规划一条腿,
mcpp.lock 只在规划阶段写入,避免 SPEC-011 §4 的乐观写入冲突。
- 规划完成后各腿一起构建:
[build] jobs 按腿静态分摊;构建目录锁按目标名排序获取。
- 一条腿失败时,其余腿完成构建;命令的状态为第一条失败的腿的状态。
- 单腿时规划、构建、
.last-result.json 与记录的 configuration 与 2026.10.29.1 相同。多腿时 .last-result.json 记录每条腿,
根目录的编译数据库为第一条腿的。
- 写:
mcpp test [--target <t>...] --no-run --archive <file> 构建各腿的测试程序,与清单 mcpp-tests.json(每个测试的腿、
参数、工作目录)一起写为一个 tar 归档。归档是引擎的格式,与平台的容器无关。压缩方式由文件名决定
(.tar.gz/.tgz、.tar.zst、.tar.xz、.tar),读写同一规则;其他名称在构建前拒绝(退出码 2)。
- 读:
mcpp test --archive <file> 在同一项目的检出中运行归档内本机能到达的测试,不构建;工作目录为项目检出;报告与
mcpp test 相同。
- 读取时:有测试失败则退出码 1;一个测试都没有运行则退出码 1 并写明;本机到达不了的腿报告为"未运行"。
- 原生交叉同样适用:在 Linux 上构建的
x86_64-windows-gnu 测试可以在 Windows 上运行。
mcpp.build:单腿时逐字节不变。多腿时 data 的顶层字段取第一条腿,status 汇总全部腿,legs[] 每项为一份完整的结果
记录;artifact 与 diagnostic 事件带 triple。mcpp.env(self env --format json):多腿时增加 legs[]。mcpp.pack:legs、pkgFormats、runsOn(SPEC-014 §9)。- 新字段只增加,不改变已有字段的含义(docs/50)。
mcpp build --target openkal 构建两条腿,各在 target/<triple>/ 下,一个 Finished;信封的 data 为第一条腿的记录,
legs 含两条,每个 artifact 事件写出其腿(e2e 963)。mcpp run --target openkal 运行本机的腿并写出所选的腿;mcpp test --target openkal 运行本机的腿,另一条报告为
已构建、未运行,退出码 0(e2e 963)。- 各腿都到达不了时
mcpp test 不运行任何测试,退出码 1 并写明(e2e 963)。
mcpp self env --target openkal --format json 报告两条腿(e2e 963)。none(无环境)、linux-msvc(无成员)与 [build] target 中的集合被拒绝(e2e 963)。- 集合的识别、补全、展开、去重与顺序,
planned 的行不在内,候选选到不同平台被拒绝(unit TargetSet)。
- 腿的规划串行、构建一起、作业分摊与第一条失败的腿(unit
BuildLegs)。
--no-run --archive 写出的归档含两条腿与清单;在没有 target/ 的检出中 --archive 运行本机的腿、不构建;失败的
测试使退出码为 1;没有一条腿能到达的归档不运行任何测试且退出码为 1;.tar.zst 写为 zstd 帧并同样运行,不表明 tar
归档的名称在构建前以退出码 2 拒绝(e2e 964);本机系统的腿(由系统直接启动的测试程序)同样从归档运行,不需要
llvm(e2e 989);文件名与压缩方式互逆(unit PackCompress)。
| 版本 |
日期 |
变更 |
| 1.0 |
2026-10-30 |
首版(mcpp 2026.10.30.1,设计 2026-10-29 §3):集合的识别、补全与展开,一条命令的腿,build、run、test、self env 对多条腿的语义,串行规划与一起构建,测试归档,机器输出;判据 1–8(e2e 963、964,unit TargetSet、BuildLegs)。 |