读者: 解析 mcpp 输出的工具、编辑器扩展或 CI 任务的作者。
本章回答的那一个问题: 一个程序可以依赖什么,输出如何被版本化,以及协议 如何被识别。
不在这里: 面向人的输出,它不携带任何兼容性承诺;以及退出码契约,那是 SPEC-003。
mcpp 面向两类读者写作。本章是对第二类读者 —— 程序 —— 的契约。编辑器扩展、 CI 脚本,以及任何解析 mcpp 输出的程序,都可以依赖本章陈述的内容。
靠解析 stdout 来识别协议,不靠退出码,也不靠「命令没有失败」这一点。
读取 stdout,尝试按 JSON 解析,并要求 schemaVersion 与 kind 二者都在。
只要缺一个,就说明这个 mcpp 不支持调用方所请求的协议。
这不是风格上的偏好。mcpp --protocol-version 看起来理应是入口,在支持它的
版本上确实是个有用的捷径。但在它存在之前发布的每一个 mcpp 上,这条命令
本身就是一个未知选项 —— 而未知选项过去的行为是把人类可读的文本打印到
stdout、退出码为 1、stderr 为空。成功与失败走的是同一个通道。把它拼成
--json 也不会改变什么,两者最终走的是同一条路径。
所以「正向识别」是唯一在各版本上都成立的规则,下面的一切设计都围绕它展开。
schemaVersion 与 kindVersion 被特意分开:如果只有一个全局版本号,给
mcpp.env 增加一个字段就会推高客户端为 mcpp.xpkg 读到的版本号,而客户端
无从判断真正变化的是哪一个。
effects 永远存在。空数组表示「什么都没做」;字段缺失会表示「未知」,那是
另一个断言。
命令产出了它自己的文档时,data 才存在。命令在拿到文档之前就失败时,省略
data 而不是给出一个空对象,原因写在 diagnostics 里;mcpp.build-database
就是这样的 kind(见 §8)。
{
"code": "MCPP_MANIFEST_UNKNOWN_KEY",
"severity": "error" | "warning" | "note",
"source": "mcpp",
"message": "unknown key 'standrad'",
"path": "mcpp.toml", // omitted when there is none
"range": { "start": {"line": 3, "column": 1},
"end": {"line": 3, "column": 9} } // omitted when there is none
}位置从 1 开始计数。column 数的是 UTF-8 字节,因此索引的正是 mcpp 实际
读到的那份文件。
一条没有位置的诊断会省略 path 与 range,而不是填 0 —— line: 0 会把
读者指向一个不存在的位置。
消息以源码位置开头的诊断 —— <path>:<line>:<col>: 、<path>:<line>: 或
<path>: error: ,即 mcpp 写出的每一条带位置的消息的形式 —— 把这个位置作为
path 与 range 携带(2026.10.26.1+)。清单的拒绝定位到它点名的键或表:
[build].sources must be … 指向 sources 所在的那一行。已经在 path 中写明文件
的命令保留自己的写法,并补上 range。
code 永远存在。解析 code,永远不要解析 message。
mcpp <command> --format json
目前只支持 json。ndjson 为将来真正需要流式的场景保留,现在不被接受
—— 请求它是一个错误,而不是静默地回落到别的格式。
构建类命令改用 --message-format json 来请求机器输出,mcpp test 就是这样做的:
build、test、run 与 pack。mcpp pack 与 mcpp run 的包格式是 --pkg-format
(tar、zip、dir、single-file、msi;2026.10.27.1+;在这两个命令上 --format 是旧写法,会给出警告),所以打包的
报告方式是 mcpp pack --message-format json(2026.9.16.1+)。具体形状随 kind 而定:
mcpp test 的测试是随时间陆续完成的,所以它按测试逐条输出流式记录;一次
mcpp pack 只有一个结果,所以它输出一个信封。mcpp build --message-format json
(2026.10.26.1+)在构建过程中输出事件流,以一个信封结束(§9)。
两者都写往 stderr,退出码为 2,并且不向 stdout 写任何东西:
$ mcpp self env --format yaml
error: unsupported --format 'yaml'; expected: json # stderr
$ echo $?
2
一个还不知道自己会得到什么格式的请求,不应该往协议独占的那个通道里写东西。 结合 §1,客户端的规则就是完整的了:stdout 上没有 JSON,就意味着不支持, 无论原因是什么。
带信封命令的退出码 —— 即 --protocol-version 所声明的那几个 kind。这张
表刻意只覆盖它们:别的命令返回的退出码不在其中,把它写进来等于记录一件这些
命令给不出的事实。跨越 mcpp 全部命令的完整映射见
退出码契约。
| 退出码 | 含义 |
|---|---|
| 0 | 成功 |
| 1 | 命令运行了并且失败 —— 见 stderr;当 stdout 携带信封时见 diagnostics |
| 2 | 用法错误 —— 未知选项、不支持的取值 |
| 5 | 运行在调用方拒绝的副作用之前停下(§10;2026.10.26.1+) |
| 70 | 内部错误(未捕获的异常) |
| 127 | 未知命令 |
1 可以与 stdout 上的信封同时出现。 mcpp xpkg parse 会把一份违反命名
形态的描述符以 JSON 形式报出并且退出 1:这份文档就是答案,退出码说明这个
答案是一次拒绝。§1 依然成立 —— 解析 stdout,不要按退出码分支 —— 但一个把任何
非零退出都当成「没有输出」的客户端,会丢掉它已经拿到手的文档。
每条命令都写两个流,划分方式对所有命令相同。2026.9.30.2 及更早的版本把叙述写到标准输出,所以原先在那里读取叙述的使用方,现在应当读标准错误。
| 流 | 携带的内容 |
|---|---|
| 标准输出 | 命令的结果:mcpp run 下程序打印的内容;文档(信封、mcpp emit、mcpp run --list-runners、--version、--help);列表(mcpp toolchain list、mcpp cache list、mcpp search、mcpp test --list);以及 mcpp test 的报告:每个测试的结论、失败测试的输出、test result 行,以及工作区运行的 workspace result 行 |
| 标准错误 | 叙述:状态行(Resolving、Compiling、Finished、Running、Packing、Packed、Downloading、Updating 及其他以动词开头的行)、终端上的进度条与状态行、Running 之后的空行、warning:、error:、note:、tip: 行、编译器诊断,以及 --verbose 增加的内容 |
判断一行属于哪个流,依据它的用途。说明命令正在做什么或已经做了什么的行是叙述;命令被要求产生的东西是结果。Cargo 把 libtest 的报告写到标准输出,mcpp test 同理。
- 管道只收到结果。
mcpp run -q 2>/dev/null写出的恰好是程序的标准输出;mcpp build >/dev/null仍然显示各步骤。在终端上两个流都到达屏幕,状态行画在标准错误上,所以mcpp build 2>/dev/null不显示状态行。 --quiet抑制叙述,包括Running之后的空行,保留警告、错误和诊断。- 机器可读模式(
--format json、--message-format json)仍把标准输出留给自己的文档。它们在标准错误上叙述什么没有变化:mcpp test --message-format json不叙述;mcpp pack --message-format json与mcpp emit build-database在规划与构建期间在标准错误上叙述。 - 两个流在同一条管道上保持写入顺序。
mcpp build 2>&1 | tee log记录各步骤,这是原先写mcpp build | tee log的脚本应改成的写法(同时捕获两个流的 CI 日志不受影响)。
一个带有 untrusted-workspace 门禁的 IDE,必须在运行之前就做出决定。等 信封送达时,它所描述的事情已经发生了。所以同一份信息也以静态方式提供:
mcpp --protocol-version
{
"schemaVersion": 1,
"kind": "mcpp.protocol",
"envelope": { "min": 1, "max": 1 },
"kinds": { "mcpp.env": 1, "mcpp.xpkg": 1, "mcpp.cache": 1 },
"commands": {
"self env": { "effects": [] },
"xpkg parse": { "effects": [] },
"cache list": { "effects": [] }
},
"features": ["target-sets", "pkg-format-list"]
}effects 采用具名的方式而不是一个 destructive: true|false,因为布尔值分不
清「无害的动作」与「门禁真正要拦的那件事」:
| effect | 含义 |
|---|---|
init-mcpp-home |
首次使用时可能创建 $MCPP_HOME。位于项目目录之外。 |
read-project |
读取 manifest 与源码 |
write-project |
写入项目树(target/、compile DB) |
write-global-cache |
写入共享构建缓存 |
network |
可能发起网络请求 |
exec-build-script |
执行工作区里的代码(build.mcpp) |
多数门禁只关心 exec-build-script 与 write-project,可以忽略
init-mcpp-home —— mcpp 给自己做初始化,不算工作区在动作。
上表列出的是命令可能做的事。信封里的 effects 是这次运行实际做了的
事,其中 network 按实际观测记录,而不是按声明:只要本次运行启动过索引
刷新、安装,或者一次 git 远程操作,就会被列出,包括失败了的或被期限终止的
那一次;在 --offline 下运行时永远不会列出。
kinds 说明输出遵循哪些 schema,commands 说明有哪些命令以及它们做什么;features 是已有命令中的语义能力,
客户端据以开关某项功能。客户端按特性判断,而不是比较版本号。一个名字在有客户端依据它开关功能时才加入,
永不改名、永不删除。早于该列表的 mcpp 没有 features;客户端为此之前的已发布版本保留一张对照表,之后的版本不再需要。
同一列表也在每个信封的 mcpp 字段中(§2):客户端为一个项目执行一次 self env,即同时得知版本与特性;任何 job 的信封
都说明两者是否已变。
| 特性 | 起始 | 含义 | 使用方 |
|---|---|---|---|
target-sets |
2026.10.31.1(语义自 2026.10.30.1) | --target openkal 等集合展开为其腿(SPEC-015 §1) |
IDE 的 target 选择 |
pkg-format-list |
2026.10.31.1(语义自 2026.10.30.1) | --pkg-format tar,okb 写出一棵树的各个容器(SPEC-014 §5.4) |
IDE 的打包界面 |
test-launch |
2026.10.31.2 | mcpp test <name> --print-launch 打印一个测试的 mcpp.launch(见下) |
调试测试的 IDE |
launch-stream |
2026.11.7.2 | mcpp run --print-launch --message-format json 先流式输出构建事件,再输出 mcpp.launch 信封(见下) |
IDE 的运行,边构建边显示 |
test-protocol |
2026.11.8.1 | 实现测试协议的测试程序,其用例在 mcpp test --message-format json 的记录中被列出(--cases)、选择(--case)并报告(§8) |
IDE 的测试树、从编辑器运行一个用例 |
test-parts |
2026.11.10.1 | 在 test-protocol 之上:以多个进程运行的程序([test] split)在 --cases 下写出其各部分(parts),各部分的记录写出 part_of(§8) |
IDE 的测试树 |
test-case-stream |
2026.11.10.1 | 在 test-protocol 之上:每个用例开始与结束时各有一条 case 记录,先于其程序的记录(§8) |
IDE 的实时结果 |
test-metrics |
2026.11.10.1 | 在 test-protocol 之上:用例的 kind、tags、metrics、bounds 与程序的 usage,出现在记录与 mcpp test 保存的运行中(mtest 规范 P6、P10.2、P12;§8) |
IDE 的指标、界限与趋势 |
test-launch-records |
2026.11.10.1 | 在 test-protocol 之上:构建而未运行(--no-run)的程序记录带 launch:argv、env、cwd、via(SPEC-017 B5) |
自行启动程序的测试会话 |
test-frameworks |
2026.11.10.1 | mcpp test --guide 写出每个框架的 capabilities 与 session(SPEC-017 B6) |
在会话与进程之间选择的 IDE |
test-checks |
2026.11.10.1 | 在 test-protocol 之上:失败的 source 与 fatal,用例的 checks(held、failed),按程序的报告(SPEC-017 O3) |
IDE 的检查点列表 |
test-output |
2026.11.10.1 | 在 test-case-stream 之上:用例自己的输出 output:程序的 output 事件,或只运行该用例的程序的全部输出;出现在程序的 cases 中,来自事件时也出现在其 end 记录中(SPEC-017 O8) |
IDE 中单个用例的输出 |
为某个项目运行 mcpp 的工具(IDE 后端、语言服务器、CI 脚本)在项目根目录中运行它,程序名为 PATH 上的
mcpp(版本管理器的 shim)或用户设置的路径,并从环境中去掉 XLINGS_PROJECT_DIR。这样应答的就是该项目使用的
mcpp:锁定了版本的项目由其目录选定版本,任何工具都不读取锁定文件。mcpp self env --format json 报告该 mcpp
的 mcppVersion 与 program(正在运行的文件)。
有两条命令在本协议存在之前就已经发布了 --json:
mcpp xpkg parse <file> --json -> {"namespace": …, "name": …, …}
mcpp cache list --json -> {"root": …, "entries": [ … ]}
那些 payload 是裸的——没有信封——而且已经有消费方在读取它们。所以:
--json永久保留它的 payload。带信封的是--format json。
--json 没有被弃用,使用它也不会打印任何警告:客户端正在解析这份输出,一条
警告会落在它中间。
两种拼法出自同一个数据来源,因此永远描述同一件事:一个答案,两种形状。
mcpp run 报告的是程序自身的退出状态。整个取值空间分四段,只有第一段属于
程序:
| 区间 | 含义 |
|---|---|
0–124 |
程序运行过了;这是它自己的状态,原样透传。例外是 101,见下一行 |
101 |
mcpp run 无法构建程序:规划或构建失败,没有启动任何东西。这是 cargo run 构建失败时 Cargo 给出的状态 |
125–127 |
尝试过启动但被拒绝 —— 127 是找不到,126 是找到了但不可执行,125 是其他原因;对 mcpp run --pkg-format <f> 而言,一个是目录、且没有任何 runner 能到达的分发物同样得到 126,它在启动之前就被拒绝,含义相同(2026.9.14.2+) |
2 |
mcpp 在构建任何东西之前拒绝了请求,或在构建之后、启动任何东西之前拒绝了请求:用法错误、--pkg-format 与 --no-runner 同用、项目没有声明的程序或 runner、未启用的 runner(消息带 [runner-not-enabled];2026.11.16.1+) |
在 2026.9.30.2 之前,构建失败退出 1,规划失败退出 2,脚本因此无法区分
一次编译错误和一个返回 1 的程序。现在构建失败是 101;mcpp build、
mcpp test、mcpp pack 保持各自的状态。
在 2026.9.4.3 之前,所有非零状态都被折叠成 1,目的是让 2 能表示「起不来」
以区别于「跑了但失败」。这个区分值得保留,但代价不值得:main 返回 3 的
程序会让 mcpp run 退出 1,qemu 报出 3 的裸机镜像同样到达为 1 ——
本项目让人使用的这条命令因此无法用于分支判断。
中间那一段,是 env、timeout、nice 早已在用、并且被 shell 文档化的取
值,因此 126 与 127 到达时带着它们惯常的含义,而不是本项目自行分配的
编号。101 同理,它是 Cargo 的取值。
程序自身也可以以 101 或 125–127 退出,mcpp 不试图靠数字去区分两者。
区分它们的是:构建或启动失败一定会向 stderr 写出原因,而程序自身的退出状态从
不这样做。需要确定结果的客户端应当读 stderr,或者使用 --format json —— 那里
退出状态是一个字段,不是一条通道。
使用 runner(--runner、[target.<triple>].runner)时,透传的是 runner 的状态;
自己返回 101 的 runner 读起来与构建失败相同。这一点被接受,Cargo 也是如此。
mcpp test 保持不变,仍然是 0 或 1:它聚合了多个程序的结果,没有单一的
状态可以透传。每个测试各自的退出码在 JSON 流的 exit_code 字段里(见
§8)。
对每一个 kind,在同一个 kindVersion 之内:
- 字段只会被新增,从不删除
- 一个字段的含义永远不变
- 破坏性变更会抬升版本号;在需要过渡窗口时,
protocol.min/max会重叠, 使两个版本都可读
这个承诺只有被强制执行才有价值,因此每个 kind 都配有一个测试:字段名一改就
变红。没有人能弄坏的 schema 不是 schema —— xlings interface --list
声明了 20 个 capability,它们的 outputSchema 全部只有
{"exitCode": integer},而一个客户端看到版本号就会以为背后有一份契约。
mcpp self env --format json
{
"initialized": false, // is there a config.toml yet?
"mcppHome": "/home/u/.mcpp",
"originalHome":"/home/u/.mcpp",
"homeSource": "user",
"homeLocator": "",
"registry": "/home/u/.mcpp/registry",
"xlingsHome": "/home/u/.mcpp/registry",
"xlingsBinary":"/home/u/.mcpp/registry/bin/xlings",
"config": "/home/u/.mcpp/config.toml",
"buildCache": "/home/u/.mcpp/build-cache/v1",
"mcppVersion": "2026.8.8.3",
"program": "/home/u/.mcpp/registry/data/xpkgs/xim-x-mcpp/2026.10.31.1/bin/mcpp", // 2026.10.31.1+
"defaultToolchain": "gcc@16.1.0", // 2026.9.28.2+
"engineModules": "/home/u/.mcpp/engine/2026.10.11.1/modules" // 2026.10.11.1+
}人类和机器使用的 self env 查询均为只读(2026.10.19.1+)。
冷 home 下返回将使用的路径和 initialized: false。
originalHome 是 locator 所在目录,mcppHome 是实际数据目录;
homeSource 表示实际目录的选择来源(重定向时为 locator,否则为
environment、portable、user 或 system),未重定向时 homeLocator 为空。
这些新增字段不会创建文件。
这也是这个 kind 存在的理由:没有它,客户端就得自己重新实现一遍 mcpp 的 home
解析逻辑 —— 包括「PATH 上的 mcpp 可能是一个 xlings shim 而不是真正的
二进制」这一部分。
一个配置 (2026.10.27.1+)。带 --target <triple>(宿主图用 --host)时,self env
准备该配置而不构建,并报告它;在工程中是该工程的配置,工程之外是 home 缓存中一个空程序的配置。
--platform 与 --host-platform 的选择与构建相同(35)。
{
"triple": "x86_64-openkal",
"graph": "target", // or "host"
"toolchain": {"compiler": "/…/xim-x-llvm/23.1.3/bin/clang++", "origin": "platform"},
"platform": {"name": "mcpplibs.openkal-platform", "version": "0.18.0", "source": "built-in",
"hosted": false, "fields": {"runner": {"value": ["okrun", "{}"], "source": "platform"}}},
"tools": {"okld": "/…/okld", "okrun": "/…/okrun"},
"runner": {"argv": ["okrun", "{}"], "host": "same-arch", "exclusive": false,
"program": "/…/okrun", "arch": "x86_64", "built": true, "refusal": null,
"source": "platform"},
"runUnder": [],
"runUnderProgram": null
}未选择平台时 platform 为 null;其形状与 plan 事件的相同(§9)。运行器指名平台自己的工具时
runner.program 为该工具,否则为本机找到的程序。对目标图(2026.10.29.1+),该程序就是 mcpp run 与
mcpp test 会启动的程序:runner.arch 为其架构;产物属于另一架构、运行器为 same-arch 且给出了执行宿主时,
它是平台为该架构准备的运行器,报告第一次运行构建它的位置(此前 built: false;self env 不构建任何东西)。
runUnderProgram 为执行宿主的程序,runner.refusal 为本机拒绝运行的原因(不拒绝时为 null;未启用的 runner 亦是,带 [runner-not-enabled])。--host 时,工程的构建程序已在宿主平台下构建过,才报告宿主平台
的 runner 与 tools。工程源码会被拒绝的原因
(图中没有 C++ 运行时而 import std)是一条代码为 MCPP_CONFIGURATION_SOURCES_REFUSED 的
warning 诊断,配置照常报告。无法准备的配置带 MCPP_CONFIGURATION_FAILED,没有 data。
defaultToolchain 是在这台宿主上、什么都没有配置时一次构建所解析的工具链:首次运行
安装的正是它,各 CI 宿主也以它核对 docs/01 与 docs/20 的表格。在 Windows 上,它取决于
是否存在可用的 MSVC(来自 Visual Studio 或受管的工具集)。
mcpp xpkg parse <file.lua> --format json
data 就是 --json 裸打印出来的那份文档。
mcpp 字段是内联表的描述符,产出的是完整文档:namespace、name、
versions、standard、import_std、sources、include_dirs、
generated_files、generated_contents、targets、unknown_keys。没有
内联表的描述符,会用 "form": "A" 代替构建信息。两种形态都携带
versions —— 描述符各平台 xpm 表的版本键。
mcpp cache list --format json
data 是 {root, entries[]},与 --json 裸打印出来的一致。
mcpp why sources|tool <name>|payload <ns:name> --format json
它解析并报告,不构建。data 为:
| 字段 | |
|---|---|
topic |
sources、tool 或 payload |
subject |
问题收窄到的名字,sources 下为空 |
status |
ok 或 refused |
reason |
一个拒绝 token,或 none |
sources[] |
每个主体一条 |
每条为 {subject, value, class, origin, decidedFor, considered[]}:
subject是toolchain.build、toolchain.bootstrap、payload:<ns>:<name>或tool:<module>:<name>;class是managed、pinned、custom、program或host—— 前两者属于生态, 其余属于某个人或某台机器;origin是{kind, file, line, key},其中kind为default、manifest、env、config、build-program或graph;decidedFor点名它所回应的那个包的声明;considered列出查过什么以及各自答了什么。
"sources": [ { "subject": "payload:xim:cmake", "value": "/usr/bin/cmake",
"class": "custom",
"origin": { "kind": "manifest", "file": "mcpp.toml", "line": 22,
"key": "[xlings.overrides]" },
"decidedFor": "mcpp:plugins",
"considered": ["payload xim:cmake@>=3.31 (not installed: overridden)"] } ]每次构建把同一份记录写入
target/<triple>/<fingerprint>/resolution.json 的 sources。主体 sysroot 记录目标基座的
陈述,run_under 记录执行宿主的包装前缀。mcpp why sysroot --format json 等同于
mcpp why sources sysroot(2026.10.24.1+)。
resolution.json 还在每次构建中携带描述目标基座与执行宿主的两个对象(2026.10.24.1+):
"base": { "form": "path", "statement": "path:/work/app/third_party/sysroot",
"address": "gnu-sysroot", "runtime": "binding",
"root": "/work/app/third_party/sysroot",
"c_abi": { "impl": "glibc", "version": "2.31" }, "multiarch": "",
"loader": "/work/app/third_party/sysroot/lib64/ld-linux-x86-64.so.2",
"runtime_dirs": ["/work/app/third_party/sysroot/lib64"],
"identity": "3d9bbfa57f6acda6" },
"execution": { "run_under": ["remote-run", "team-mac", "--"], "origin": "mcpp.toml:15" }生态缺省基座的 form 为 default,其余字段描述引擎缺省解析出的结果。
mcpp why build-programs --format json
mcpp why compat --format json
两者都像 mcpp why 一样准备构建并报告它记录的内容;data 带 status(ok 或 refused),以及:
| kind | 字段 | 内容 |
|---|---|---|
mcpp.why.build-programs |
graphs[] |
每张构建程序图一项:workspace(其目录)与 programs[],每个程序为 {member, package, source, libraries[], identity, binary} |
mcpp.why.compat |
uses[] |
每次使用弃用读法一项:{id, where, detail, warned, since, floor, canonical, docs};在构建不编辑的清单中 warned 为 false |
mcpp why target [--target <t>] --format json
mcpp why flags [<unit>] [--target <t>] --format json
mcpp why platform [--target <t>] --format json
data 带 status,以及:
| kind | 字段 | 内容 |
|---|---|---|
mcpp.why.target |
target |
{request, identity, provider, priority, fallback, why, candidates[]},每个候选 {identity, provider, priority, available, why}(SPEC-016 §7) |
mcpp.why.flags |
flags |
{identity, units[], link[]}:每个单元 {file, package, words[]},每个参数 {word, layer, detail},层为 compiler、row、platform、toolchain、package、engine 之一 |
mcpp.why.platform |
platform |
{package, version, defines[], serves[], warnings[]},每个所服务的身份 {identity, provider, priority};构建不用平台包时为 null |
mcpp.env 的 engineModules 是本版本 mcpp 的引擎接口包的目录,构建程序图依赖它(30 ——
build.mcpp);第一次编译构建程序之后它才存在。
mcpp toolchain list --format json
data 是 {host, toolchains[], targets[]}。一个工具链的形状是
{family, version, default};一份 Visual Studio 安装另有
source: "system" —— 它是在机器上被定位到的,不是由 mcpp 安装的。一行目标
的形状是 {target, note, toolchain, pin, status, default},status 取
installed / available / via dependency graph / planned 之一。
目标行另有 platform(2026.10.27.1+):目标表为该目标选择的平台包
(2026.11.15.1 起为 mcpplibs.openkal-platform@0.28.0,2026.11.12.1 为 @0.27.1,2026.11.10.2 为 @0.26.0,2026.11.10.1 为 @0.25.0,2026.11.8.1 起为 @0.24.4,2026.11.7.2 为 @0.24.3;2026.11.7.1 为系列 ^0.24),或 null。
toolchain 与 pin 不是把同一个字段写了两遍。 toolchain 表示这一行
关联到什么 —— 已装的行是装好的载荷,词表行是它自己的约定。pin 只承载目标
表自己的约定,没有约定的行留空。x86_64-linux-gnu 装了 gcc,却根本没有约定,
所以要挑出「约定是 gcc」的那些行,必须读 pin。
mcpp why toolchain [--target <triple>] [--toolchain <spec>] --format json
它只解析并报告,不执行构建。data:
| 字段 | |
|---|---|
requested |
{target, toolchain} —— 请求的内容 |
status |
ok 或 refused |
reason |
拒绝的记号,或 none |
compiler |
{family, version, driver, chosenBy} —— 真正会运行的驱动器,以及选中它的原因 |
triple |
{requested, toolchain, llvm} |
cLibrary |
{mode, path, origin, suppliesTarget} —— mode 取 sysroot / payload-first / none,origin 取 payload / subos / host / none |
layers[] |
目标侧的五个层:{layer, interface, impl, origin, subset} |
compiler.chosenBy 回答「为什么是它」。 {origin, requiredBy, replaced} —— origin 与构建的状态行使用的是同一句话
([toolchain] in mcpp.toml、your default、target default、
required by the dependency graph、first-run default)。当一条
requires = ["mcpp:compiler=…"] 做出了这个决定时,requiredBy 点名那个
包,replaced 点名被顶掉的那个 spec;两者在没有发生时都为空。
"compiler": { "family": "clang", "version": "22.1.8", "driver": "…/clang++",
"chosenBy": { "origin": "required by the dependency graph",
"requiredBy": "openkal-llvm-runtime@0.1.3",
"replaced": "gcc@16.1.0" } }没有它,一个要问「为什么」的消费方就只能去解析状态行 —— 而消除这种字符串 匹配,正是这份文档存在的理由。
cLibrary 与 layers[].c-abi 回答的是两个不同的问题,suppliesTarget
说明该信哪一个。 cLibrary 描述的是载荷自己的链接模型 —— 一份由载荷
供给的 C 库会使用的搜索路径。layers[].c-abi 描述的是这次构建本身。当
某个依赖供给了 C 库时,两者会出现分歧,而在 suppliesTarget 出现之前,
同一份文档会同时报出两者,却没有任何字段说明二者该信哪一个:
"cLibrary": { "origin": "payload", "path": "…/xim-x-glibc/2.44/lib64",
"suppliesTarget": false }, // ← added; the payload is not in the artifact
"layers": [ { "layer": "c-abi", "interface": "musl",
"impl": "openkal-musl@0.3.5", "origin": "graph" } ]这里新增的是一个字段,而不是给 cLibrary 改名或者给 mode 加一个取值,
因为 §7 承诺字段只增不减,且一个字段的含义永远不变。
2026.9.1.1 起,一份由载荷供给的 glibc 使 layers[].interface 的取值发生了
变化 —— 从 gnu 变为 glibc,在 Windows 上从 gnu 变为 ucrt。字段的
含义没有变(它依然表示「是哪一个实现」),因此 §7 仍然成立;变化的是它不再
报告三元组的 env 段 —— 那是一次请求,而不是一个实现,也不是任何 C 库的名字。
现在的取值正是 22 —— 目标侧 一直列出的那些,包也可以在
cfg(c-abi = …) 谓词里与它们比较。按字面量 gnu 取值判断的客户端需要更新;
musl、picolibc、libSystem 不受影响。
reason 是一个记号,不是一句话。 拒绝的消息仍然是写给人看的,仍然点名
目标、规则与出路 —— 但一个要给结果分类的程序读的是 reason:
reason |
|
|---|---|
unknown-target |
该拼写不对应任何一行,(arch, os) 也没有对应的组 |
ambiguous-request |
该 (arch, os) 有多行受支持,且没有一行是默认值 |
compiler-requirement-conflict |
图所要求的编译器在这里不可用 |
tier-planned |
词表里存在这一行,但还没有任何东西接线 |
host-cannot-serve |
本机没有载荷,也没有依赖供给这个系统 |
capability-pin |
这一行的工具链是一项能力陈述,不是一个偏好 |
managed-only |
--managed-only 遇到了不属于生态的来源:消息逐条点名它与陈述它的位置 (2026.10.1.3+) |
payload-override |
一条 [xlings.overrides] 点名的路径不存在、版本被某条要求拒绝,或它由依赖写出 (2026.10.1.3+) |
payload-request |
构建程序请求了本次构建中没有任何清单声明 provision = "on-request" 的载荷,或连续三次运行都在请求 (2026.10.1.3+) |
lto-export-discovery |
导出需要被发现的 PE 共享库会被 cl.exe 编译成没有符号表的 /GL 对象:在 lto = true 下陈述了 windows_auto_export = true,或在它所链接的包的 flag 中写了 /GL (2026.10.5.2+) |
local-toolchain |
由路径命名的工具链,或构建程序工具链阶段陈述的工具链无法使用:没有驱动、族与驱动矛盾、缺少某个工具,或 spec 与只属于路径工具链的键一同陈述 (2026.10.1.3+) |
target-base |
目标基座(sysroot)无法服务本次构建:该行不接受的写法、不存在的路径、不供给 C 库的目录、低于编译器运行库要求的 C 库、缺少 loader 的本机基座,或依赖图中的第二个 C 库供给者 (2026.10.24.1+) |
convention-unreplaced |
约定被推翻了,而没有任何东西接替它 |
os-mismatch |
请求的三元组与解析出的三元组命名不同的系统 |
layer-requirement |
某个包要求的层,解析结果没有提供 |
layer-ordering |
五个层无法叠加 |
layer-cycle |
供给各层的包相互需要成环(写在 C 库之上的 kernel-abi 位于写在 kernel-abi 之上的 C 库之下);消息写出每个包、它供给的层与它需要的层,并以方括号带出该记号 (2026.11.10.1+) |
exclusive-capability |
一项能力有多个提供者,其中至少一个声明了独占 |
version-floor-unmet |
某个包对机器的要求,高于机器被声明拥有的水平 |
accel-mismatch |
一条 [build] sources 条目被约束到本次构建未覆盖的设备集合 |
accel-backend-undeclared |
一条 [build] sources 条目命名的后端,未出现在该包自己的 [package] accelerators 中 |
device-source-unconsumed |
一个设备类源文件没有到达任何 action,因此没有任何东西编译它 |
host-module-missing |
build.mcpp 导入的模块,没有任何依赖以 host module 的形式提供 |
tool-version-conflict |
两处声明把同一个 xlings 包定在不能同时成立的两个版本上 |
shared-library-cxx-runtime |
图所在的构建中,C++ 运行时是一个包,而某个依赖的 C++ 共享库没有声明私有副本 |
offline-download-required |
本次运行离线,而规划需要下载某样东西:工具链、包、git 修订,或包索引 (2026.9.16.1+) |
package-cycle |
依赖图中存在一个包的环;消息列出环上的边 (2026.9.16.1+) |
program-cxx-runtime-split |
一个声明了自含 C++ 运行时的程序或测试,加载了本次构建中耦合到共享运行时的 C++ 共享库 (2026.9.16.1+) |
static-package-in-two-images |
一个静态包被本次构建的多个映像到达,而在该目标上一个映像不能使用另一个映像里的副本 (2026.9.16.1+) |
c-env-unrealisable |
解析出的 C 库的 [c-abi] 声明在这个目标上没有已知的实现方式,或者解析出的编译器做不到这一点 (2026.9.18.1+) |
c-env-verification-mismatch |
用已实现出的 [c-abi] 配置编译出的探针,其结果与声明不符 (2026.9.18.1+) |
platform-dependency |
[build] platform-dependencies = "refuse",而图里有某个包带来了平台 SDK (2026.9.18.1+) |
interface-not-provided |
某个包的 [kernel-abi] requires-interfaces 点名了一个解析出的实现并不提供的接口 (2026.9.20.1+) |
apple-sdk-absent |
目标需要本机没有的一个 Apple SDK;它是被定位而不是被安装的,因为它不可再分发 |
lld-required-absent |
目标直接通过 lld 链接,而解析出的工具链载荷不带 lld |
host-tool-toolchain |
一个交叉 --target 下的 build.mcpp 需要一个可解析的宿主工具链,而一个都没有配置 |
std-module-precompile |
标准库的模块在这个配置下无法被预编译 |
msvc-redist-unavailable |
在 MSVC ABI 的行上显式写了 cxx_runtime = "toolchain-coupled",而该行的工具集没有可放置的 redistributable 目录 (2026.9.28.1+) |
crt-declared-under-host-coupled |
程序的契约是 host-coupled(由系统的运行时服务、不放置任何副本),而程序旁声明了 MSVC C++ 运行时的文件 (2026.9.28.2+) |
platform-not-a-platform |
被选为该目标平台的包没有 [platform] 段 (2026.10.27.1+) |
platform-target-unserved |
所选平台不服务该目标:三元组不在其 targets 中,宿主三元组也不在其 [platform.hosted] targets 中 (2026.10.27.1+) |
platform-tool-absent |
平台的链接或封装要运行的程序(ok 映像的 okld)既不由图构建,也不在本机 (2026.10.27.1+;2026.10.26.2 中为 image-tool-absent) |
platform-version-group |
平台版本组中的一个包以另一个版本出现在图中 (2026.10.27.1+) |
platform-phase-directive |
平台插件陈述了其阶段不接受的指令 (2026.10.27.1+) |
other |
一个尚未被赋予记号的拒绝分支 |
其中一个记号也由 mcpp build 自己打印。 interface-not-provided 会
出现在拒绝消息本身里,用方括号括着,与 E0006 是同一个约定。一个只有人能
认出来的拒绝,会逼迫每一个机器消费方去匹配一段散文 —— 而这段散文,一个包
自己的编译错误恰好也可能包含;mcpp-index 的兼容性测量正是靠这个记号,把
「这个图没有供给这个成员所要求的」与「这个成员没能构建」区分开,而这个区分
决定了一个成员算不算进兼容率。
只要问题被回答了就退出 0,包括答案是「拒绝」这种情况。 「这次构建能不能 成立,不能的话为什么」被「不能,因为这一行的 pin 是一项能力陈述」完整地 回答了。非零退出的含义是这次查询本身没能运行起来。
它声明的 effects 故意偏宽。 --protocol-version 为这条命令列出了
network、write-global-cache 与 exec-build-script:答案来自与一次构建
相同的解析过程,而那个过程可能拉取包、安装载荷,并运行某个依赖的构建程序。
客户端是在运行之前读这张表来决定是否放行的,漏报任何一项都等于给出一句
不成立的安全承诺。
mcpp emit build-database [--spec s1|compile-commands] --format json
它按 mcpp build --configure-only 的方式、用相同的选择器规划,不写入项目
目录。data 为:
| 字段 | |
|---|---|
spec |
{"name": "s1", "version": "0.3.0"}(2026.9.28.1 之前为 0.2.0);使用 --spec compile-commands 时为 {"name": "compile-commands"} |
database |
该规范对应的文档:一份 S1 构建数据库,或者 mcpp build --configure-only 写入 compile_commands.json 的那些条目 |
watch |
一旦发生变化就可能改变这份文档的输入:相对工作区根目录的路径与 glob,或绝对路径 |
inputs-fingerprint |
fnv1a:<16 位十六进制>,对上述输入、mcpp 版本与选择器求出的摘要 |
不带 --format 时,命令只输出这份文档;-o <file> 会把原本要输出的内容
写入 <file>。文档的内容、不写入项目目录这条保证,以及 watch 的规则,见
SPEC-005。
自 2026.9.28.1 起,S1 的集合还在 ide.generated 中列出其包的构建程序生成的文件
(S1 0.3.0 §7.2)。命令不运行任何 action,所以这样的文件在文档所指的目录中尚不存在。
每一项给出同一组选择下 mcpp build 写入的路径(build-path)以及写出它的步骤,
编辑器因此可以说明“这是生成的文件,构建一次即可”,而不是报告缺少头文件。
emit 独立规划每一个被选中的成员(#699 第 1 项):一个成员的规划失败不会
连累它的兄弟成员。不在项目中,或者被选中的成员全部规划失败时,信封省略
data 并以 1 退出,每个失败的成员各带一条诊断:不在项目中是
MCPP_BUILD_DATABASE_NO_PROJECT;离线规划(--offline、MCPP_OFFLINE、
MCPP_NO_AUTO_INSTALL)需要下载某样东西(工具链、包、git 修订,或包索引,
消息会指出第一个)时是 MCPP_OFFLINE_DOWNLOAD_REQUIRED;因其他原因规划失败
时是 MCPP_BUILD_DATABASE_PLAN_FAILED。离线这一种不是项目的缺陷:不带
--offline 再运行一次即可消除它。每个成员的诊断都带 path,即该成员的
mcpp.toml,相对工作区根目录。
只要有一个被选中的成员规划成功,data 就会出现,并描述每一个规划成功的
成员:规划失败的成员不贡献任何集合,只贡献上面那样一条 error 诊断,它的
mcpp.toml 与存在时的 build.mcpp 一并加入 watch。只要诊断里有一条是
error,退出码依然是 1——因此消费方靠结构就能读出三种结果:没有 data;
data 伴随若干 error 诊断,描述了诊断所指之外的一切;data 且没有
error,不需要解析消息文本。
构建程序失败的包(#699 第 2 项)会被描述为不含该程序产生的指令:清单自身
的那部分配置、工具链、模块图与标准库单元仍照常描述,另附一条 error 诊断
MCPP_BUILD_DATABASE_PROGRAM_FAILED 点名它,path 为它的 build.mcpp。若
后续失败是由缺失的指令引起的,则按上面的规则使整个成员失败。这条命令
不构建宿主工具(mcpp 2026.9.27.1+):全局工具库中已有的被请求工具照常使用,
库中没有的被推迟,以说明 MCPP_BUILD_DATABASE_HOST_TOOL_DEFERRED 报告,点名
工具与所属包。请求它的构建程序收到该工具将被发布到的路径,并像工具已构建时
一样完成配置。mcpp build 不受影响:它构建该工具,构建程序或宿主工具在其中
失败仍然会使构建失败。
| 诊断码 | 严重级别 | |
|---|---|---|
MCPP_LOCK_WOULD_CHANGE |
警告 | 解析结果与项目的 mcpp.lock 不一致,命令不写这个文件 |
MCPP_GENERATED_FILE_NOT_MATERIALIZED |
警告 | 根包 [build] generated_files 中的某个文件缺失或内容已过期,命令不写这个文件 |
MCPP_BUILD_DATABASE_STD_UNIT_UNDESCRIBED |
警告 | 没有任何标准库构建命令点名它的模块源文件,该单元因此不被列出 |
MCPP_BUILD_DATABASE_HOST_TOOL_DEFERRED |
说明 | 被请求的宿主工具不在工具库中,命令不构建它;计划给出它将被发布到的路径(2026.9.27.1+;取代 2026.9.26.2 的警告 MCPP_BUILD_DATABASE_HOST_TOOL_UNBUILT) |
MCPP_BUILD_DATABASE_PAYLOAD_DEFERRED |
说明 | 构建程序请求了一个声明 provision = "on-request" 的载荷;规划不安装任何东西,点名该程序与这些包,并在没有它们的情况下描述计划(2026.10.1.3+) |
MCPP_BUILD_DATABASE_PROGRAM_FAILED |
错误 | 构建程序失败;它所属的包被描述为不含它产生的指令 |
MCPP_INDEX_REQUIRES_NEWER_MCPP |
说明 | 本次运行刷新的某个索引要求更新的 mcpp;先前的副本被保留或恢复,或者没有可用的副本(2026.9.28.1+;终端运行以结尾的 tip: 行打印同一条说明) |
--protocol-version 为这条命令声明 init-mcpp-home、read-project、
network、write-global-cache 与 exec-build-script,从不声明
write-project。
mcpp pack [target] [--pkg-format <f>] [--target <triple>...] --message-format json
信封在命令结束后输出一次;所有给人看的行都改走 stderr,包括打包过程启动的
构建程序与工具输出的内容。data 为:
| 字段 | |
|---|---|
artifacts |
每个产出的产物一条记录:path(绝对路径)、type(file 或 directory)、format(容器:--pkg-format 的取值;未给出时 Windows 程序为 zip,其余为 tar)、targets(进入该产物的每条腿的规范三元组),以及 sha256(文件的摘要;目录为 null;2026.10.27.1+)。被分派的格式报告本次请求引入的那些 action 的终端输出;一个多 --target 的 Android 打包报告一个产物,其 targets 列出每一条腿;每腿一个包的打包(2026.10.30.1+)报告每个包及其自己的腿 |
stage |
该产物所来自的那棵树:dir、manifest(即下文的暂存清单)与 closure(walked 或 not-walked);库包、没有暂存任何树的情形,以及对多个成员的打包,此字段为 null |
linkage、mode、pkgFormat (2026.10.27.1+) |
本次打包的三个选择(10):linkage 为 static、shared 或 declared;pkgFormat 为产物的 format(tar、zip、dir、single-file 或提供者的格式) |
legs、systems (2026.10.27.1+) |
命令命名的每条腿的规范三元组(目标集合已展开;2026.10.30.1+),以及自带运行器的映像树所携带的每个运行器的 <os>-<arch> |
pkgFormats (2026.10.30.1+) |
写出的全部容器,按 --pkg-format 命名的顺序;pkgFormat 为第一个 |
runsOn (2026.10.30.1+) |
包在哪里运行,同其 mcpp-package.json 的 runs_on:{"self": ["linux-x86_64", …], "with": {"okrun": […]}};单文件为各文件的组合 |
stages (2026.10.1.1+) |
只在对多个成员的打包(--workspace,或重复的 -p)中出现:每个成员一条记录,按 [workspace] members 的顺序,带 member(限定的包名),以及与 stage 相同的 dir、manifest、closure |
对多个成员的打包,artifacts 按同样的成员顺序列出每个成员的产物,每条记录多出
member,即它所属成员的限定包名。对一个成员的打包既没有 stages 也没有 member:
信封与以往完全一样。
失败时省略 data,以命令自身的退出码退出,并携带诊断码
MCPP_PACK_FAILED;原因写在 stderr 上。对多个成员的打包若有成员失败,则对每个这样的成员
再多带一条点名它的 MCPP_PACK_FAILED 诊断,同样省略 data:已经打包的成员在磁盘上,
并在 stderr 上点名。每次运行的 effects 是
read-project、write-project 与 write-global-cache,若运行了某个构建
程序则再加上 exec-build-script。--protocol-version 为 pack 声明
init-mcpp-home、read-project、write-project、network、
write-global-cache 与 exec-build-script。
mcpp test [pattern] [--workspace] --message-format json
这条流早于 §2 的信封,也不被它包裹:它是 NDJSON,每个测试结束时一条记录(--no-run 与 --cases
时每个测试构建完成时一条,2026.11.8.1 起),随后
每个成员一条汇总记录。--workspace 运行以一条 workspace_summary 记录
结束。对多个成员的测试会在每个组的第一条测试记录之前增加一条 group_build 记录。
§7 的保证对它同样成立 —— 字段只增不减,字段含义永不改变 —— 下表是
2026.9.2.1 时点的契约,各行注明其后的新增。
每个测试:
| 字段 | |
|---|---|
member |
所属的 workspace 成员;在 workspace 之外为 "" |
test |
按路径命名的测试名(tests/00-a/0.cpp → 00-a/0) |
status |
pass、compile_fail、run_fail、not_run 或 built |
exit_code |
该测试的退出状态;not_run 与 built 时为 0 |
signal |
状态编码了信号时为信号编号,否则为 null |
duration_ms |
决定该测试状态的那一步的墙钟时间:运行过的测试是运行,compile_fail 是构建 |
build_ms |
本次调用中该测试自身二进制的构建耗时,即它的链接边与主单元编译边在 .ninja_log 里的耗时之和;两者都未重新构建时为 0 (2026.10.1.1+) |
timed_out |
被 --timeout 杀掉时为 true(run_fail) |
compile_output、run_output |
捕获到的诊断输出 |
reason |
仅 not_run 时:一句话说明原因;其余情况为 "" |
protocol |
程序实现的测试协议版本,或 null (2026.11.8.1+,08) |
cases |
实现协议并运行过的程序:每个用例的 id、status(pass、fail、skip、xfail、xpass、invalid)、duration_ms、有原因时的 reason,以及 failures(file、line、message,陈述时还有 expected 与 actual) (2026.11.8.1+) |
missing |
选择中命名而程序没有对应用例的标识 (2026.11.8.1+) |
listed |
--cases 时:每个用例的 id、name、file、line,陈述时还有 kind、tags、expect (2026.11.8.1+) |
guide |
测试所用框架陈述了指南时,该指南文件 (2026.11.8.1+) |
program、sources |
构建而未运行的测试(--no-run、--cases):程序,以及它由之编译的文件(它自己的与它链接的库的),供按改动选择测试的运行器使用 (2026.11.8.1+) |
parts |
--cases 时,运行会分成多个进程的程序([test] split = "file",用例分布在其多个文件中):每部分的 name(<test>/<文件主名>,与运行的记录同名)与 file (2026.11.10.1+,test-parts) |
part_of |
一个部分的记录:它所属的程序 (2026.11.10.1+,test-parts) |
usage |
程序报告的机器使用(P10.2):user_ms、sys_ms,陈述时还有 peak_bytes、read_bytes、written_bytes (2026.11.10.1+,test-metrics) |
程序陈述时,cases 中的用例还有 kind、tags、metrics(name、value、unit,陈述时还有 samples、
better、precision)与 bounds(metric、max、min);listed 的条目有 bounds
(2026.11.10.1+,test-metrics)。
用例的实时记录 (2026.11.10.1+,test-case-stream)。程序运行时即读取其报告,每个用例的开始与结束
各成一条记录,先于程序的记录;程序的记录仍带全部用例:
{"case":{"member":"","test":"unit/a","id":"alpha","event":"begin","t_ms":12}}
{"case":{"member":"","test":"unit/a","id":"alpha","event":"end","status":"pass","duration_ms":3.1}}t_ms 从运行开始计,与存储中的 started_ms 相同。end 记录带 cases 中用例的各字段。程序结束时没有某用例的
end,该用例停留在已开始;其程序的记录写明它失败(协议 P5.4)。
汇总记录,{"summary": {...}}:
| 字段 | |
|---|---|
member、passed、failed |
计数 |
not_run |
已构建但没有执行的测试数 |
not_run_reason |
它们共同的原因,或 "" |
built |
在 --no-run 下构建、本就不打算执行的测试数 |
elapsed_ms、build_ms、run_ms |
墙钟时间,分段给出 |
build_group |
(2026.10.1.1+) 成员与其他成员一起规划时出现:它的测试所等待的那次构建所属的 group_build 记录的 group |
build_ms 是该成员的测试等待它们的构建所用的墙钟时间。单独规划的成员,它就是自己
的构建;与其他成员一起规划的成员,它是整个组的构建时间,同一组的每个成员数字相同,
对 build_ms 按成员求和的消费方按 build_group 去重;不求和的消费方不受影响。
elapsed_ms 是整个成员的墙钟时间,包含规划与组的构建。
对多个成员的 mcpp test 把同一配置的成员放在一起规划、只构建一次,因此构建的时间
属于组,只说一次。每个组一条记录,位于该组第一条测试记录之前:
{"group_build":{"group":0,"members":["libs/a","libs/b"],"build_ms":8210}}| 字段 | |
|---|---|
group |
组的编号,从 0 起,按构建顺序 |
members |
该组规划的成员,按 [workspace] members 的写法 |
build_ms |
该组构建的墙钟时间:它的包与每个测试二进制 |
组内某个成员的包构建失败时,报告
{"error":"package","member":"…","compile_output":"…"},该组中包能构建的成员照常
运行。用 -p 或命令所在目录指定的单个成员的测试,既没有这条记录,也没有 build_group;
全体选择(--workspace,或虚拟根下不带 -p)即使只含一个成员,也按分组形式报告。
built 与 not_run 是两个不同的答案,分开计数。 两者描述的都是一个
编译过、没有执行的测试,相似之处到此为止:not_run 意味着 mcpp 试过而做不
到,问题因此仍然悬而未决,退出码是 2;built 意味着 --no-run 要求不要
执行,构建就是问题的全部,退出码是 0。把两者相加的消费方,会把一次它从未要求
过的运行,报告成一次没能完成的运行。
not_run 既不是 pass 也不是 run_fail,退出码也说明了这一点
(2026.9.2.1)。 当本机无法加载测试产物时(比如交叉目标未声明 runner 时的
Exec format error),或者声明的 [target.<triple>].runner 找不到、启动不
了时,该测试被标记为 not_run。这是关于整次调用的事实:它被确立一次之后,
其余测试直接报告为 not_run 而不再启动,进程以 2 退出。退出码 1 的含义
不变 —— 有测试运行过并且失败了;0 表示每个测试都运行过并且通过了。只按退出
码判断 pass/fail 的客户端必须处理 2 这个值;由 failed == 0 推断「全部通过」
的客户端也必须读取 not_run。
workspace_summary 增加了 tests_not_run(各成员之和)、tests_built
(--no-run 下构建的测试数之和)与 unrunnable_members(所有测试都是
not_run 的那些成员),与既有的 not_run 列表并列;后者仍然指
--workspace-timeout 到期时尚未开始的那些成员。tests_built 与
tests_not_run 分开计数,理由与逐成员的那两个字段相同:一个是被悬置的问题,
另一个是压根没被问过的问题。
mcpp pack 在它暂存的树旁边写出 <staged tree>.stage-manifest,一个点名
${mcpp.stage_dir} 的 artifact action 依赖这个文件(见
30)。它是
一个按行组织的文本文件,而不是一个 JSON 信封,各行按下列顺序构成三块:
| 行 | 内容 |
|---|---|
closure = walked 或 closure = not-walked |
第一行:树所需要的每一个库是否都已解析 |
reason = <text> |
只在 closure = not-walked 时出现;一行 |
needs<TAB><name><TAB><where> (mcpp 2026.9.14.2+) |
闭包读到的每一个库名各占一行,已排序;<where> 是暂存库相对于树的路径、目标机提供的库记为 platform,或 unresolved |
<size> <path> 或 link <path> |
每一个暂存文件或符号链接各占一行,已排序 |
<name> 按需要它的对象自己的拼写给出:一条 DT_NEEDED 条目、一个 PE 导入
名,或一个 Mach-O install name。needs 行的各字段以 TAB 分隔,因为名字与
路径都可能包含空格。一棵由不打包任何东西的 mode(system、static)暂存
出的树不带 needs 行,由更早版本的 mcpp 暂存出的树同样不带;自行放置库的
读者应当读取这些行,而不是从 lib/ 下的文件推断闭包。
mcpp test --guide --message-format json (2026.11.8.1+) 输出一个对象 {"guide": {...}}:frameworks
(每项 package、version、entry、protocol 或 null、guide 或 null、repo)、commands(list、
one、records、debug)、docs,以及包没有框架时的 suggest(mtest 的 dev-dependency 写法与仓库)。
构建一个工程的每条调用链 —— 终端里的人、只有 shell 的 agent、IDE、CI 任务 —— 都终止于一次 mcpp 运行,因此一条链需要了解另一条链的构建时,由 mcpp 以同一种 形式写到磁盘上。
mcpp build [target] [-p <member>] [--release] --message-format json
标准输出是 NDJSON。除最后一行外,每一行是一个事件:
{"schemaVersion":1,"kind":"mcpp.event","event":"plan","configuration":{"triple":"x86_64-linux-gnu","profile":"dev","fingerprint":"c0641c458b2bde43","outputDir":"/…/target/x86_64-linux-gnu/c0641c458b2bde43"}}
{"schemaVersion":1,"kind":"mcpp.event","event":"progress","finished":12,"total":34}
{"schemaVersion":1,"kind":"mcpp.event","event":"artifact","artifact":{"name":"app","kind":"bin","path":"/…/bin/app","launch":{…}}}| 事件 | 携带 |
|---|---|
plan |
configuration:构建已进入其构建目录的那个配置;platform 与 hostPlatform(2026.10.27.1+)是目标图与宿主图的平台,或 null |
waiting |
holder(pid、command、client、startedAt)与 waitedMs:另一次构建持有这个构建目录,本次在等待(§11) |
progress |
finished、total:ninja 的步骤计数;一次构建可以运行不止一轮 ninja,每轮重新计数 |
diagnostic |
diagnostic:失败步骤输出中的一条编译器诊断,形状同下文记录的 diagnostics[] |
artifact |
artifact:一个产物,形状同下文记录的 artifacts[] |
最后一行是 mcpp.build 信封,占一行。它的 data 是本次运行写下的结果记录(见
下文);在进入构建目录之前就失败的运行省略 data。重放未变化的树已记录的构建(快速路径,
包的或工作区成员的)时,重述该构建的产物,既作为事件也在 data 中(工作区的,2026.11.13.1+)。
它的 diagnostics 是 mcpp
自己的错误,每条按其消息定位(§2),代码为 MCPP_BUILD_FAILED;在被拒绝的副作
用之前停下的运行为 MCPP_EFFECT_DENIED。叙述写到标准错误,与每一种机器可读模式
相同。
构建在开始写构建目录时写下 <outputDir>/result.json(kind mcpp.result),其中
"status": "running",结束时再写一次。target/.last-result.json(kind
mcpp.last-result)指向工程最近一次构建写下的记录。两者都原子替换。因此终端里的
一次构建对读取记录的 IDE 可见,反之亦然。
data 的字段 |
|
|---|---|
command |
本次运行的命令行 |
client |
调用方设置的 MCPP_CLIENT(§12),没有时为 "" |
pid |
写下记录的进程 |
startedAt、finishedAt |
自纪元起的毫秒数;running 期间与 cancelled 之后 finishedAt 为 null |
status |
running、ok、failed 或 cancelled |
configuration |
triple、profile、fingerprint、outputDir、platform、hostPlatform(2026.10.27.1+) |
compileDatabase |
该配置的 compile_commands.json,或 null |
artifacts |
name、kind(bin、test、shared、static)、path;可运行的产物另有 launch;陈述了程序起点或入口符号时另有 entry |
diagnostics |
失败构建的编译器诊断:severity、message、path、range |
launch 是 mcpp run 启动该产物的方式:argv、cwd、env 与 via。env 只含
mcpp 为程序设置或改写的变量(加载器的搜索路径、运行时载荷需要的变量),从不包含
调用方的其余变量,因此记录中不含调用方的机密。via 为 null、"runner"(由
[target.<triple>].runner 包装)或 "run_under"(由执行宿主包装)。调试器、IDE 或
CI 按 launch 启动程序,与 mcpp run 的启动一致。
entry 说明程序从哪里开始、镜像从哪里进入(docs/04,kind = "entry" 与 start):
from 是 main = { from } 指名的 "<依赖>/<入口>",start 是陈述的入口符号,
start_from 是指名它的陈述。各键只在有陈述时出现。
被 SIGINT、SIGTERM 或 SIGHUP 结束的运行在两个文件中都留下 cancelled
(退出码 §3.7)。status 仍为 running、而 pid 已不存在
的记录属于一次被强制结束的运行。
.last-result.json:
{"schemaVersion":1,"kind":"mcpp.last-result","kindVersion":1,
"data":{"result":"/…/target/x86_64-linux-gnu/c0641c458b2bde43/result.json","status":"ok","finishedAt":1792964065954}}多条腿 (2026.10.30.1+)。对目标集合或多个 --target 的命令每个目标构建一条腿
(SPEC-015),每条腿写自己的 result.json。mcpp.build 信封的 data
为第一条腿的记录,status 汇总全部腿,legs 含每条腿的记录;每个 artifact 与 diagnostic
事件带其腿的 triple。.last-result.json 指向第一条腿的记录,并增加 legs,每条腿一项
{triple, result, status}。只有一条腿时信封、事件与两个文件与此前相同。self env --target <集合>
在 mcpp.env 中增加 legs,每条腿一份报告,顶层字段取第一条腿。
mcpp run [target] --print-launch
按 mcpp run 的方式构建程序,然后打印信封而不启动它。data 为 program、
argv、cwd、env 与 via,同上文的 launch。--print-launch 不接受
--format:在 mcpp run 上,--pkg-format 表示可分发物的格式。
带 --message-format json(2026.11.7.2+,特性 launch-stream)时,标准输出为 NDJSON:先是与
mcpp build --message-format json 相同的构建事件(plan、waiting、progress、artifact),
最后一行是 mcpp.launch 信封。不带 --print-launch 的 mcpp run --message-format json 被拒绝
(退出码 2)。
没有改动时,启动描述与 mcpp run 一样走快速路径(2026.11.7.2+):完整路径把它组合出的启动
记录在该配置的目录中;快速路径自己组合出的启动与记录逐项相同时,输出这份记录,并附上本次的
程序参数。其他启动(runner、执行宿主、runner 携带的文件)由完整路径描述。
data.configuration(2026.11.7.1+)包含所选程序的 triple、profile 与解析后的
platform,字段与构建记录的 configuration 相同。目标集合中,它描述本次启动所选的
目标。configuration.runners 列出可用的具名运行器,包括 platform 为 null 时
项目声明的运行器。旧引擎不提供 configuration;消费者检查该字段是否存在。
mcpp test <name> --print-launch [-- <参数>]
对一个测试作同样的描述(特性 test-launch,2026.10.31.2):<name> 指定的测试按 mcpp test
的方式构建,并按 mcpp test 启动它的方式描述——它的运行器、运行所加的环境、-- 之后的参数——data
另以 test 给出测试名,以 protocol 给出程序实现的测试协议或 null(2026.11.8.1+)。多个测试名包含该模式时取名字完全相同的那个;仍指向多个测试时拒绝,--list、
--no-run、--archive、--message-format json、多条腿与多个成员同样拒绝。调试器启动信封描述的程序。
mcpp --deny network,exec-build-script build
MCPP_DENY_EFFECTS=write-project mcpp build
--deny 接受 §4 中以逗号分隔的副作用;MCPP_DENY_EFFECTS 接受同样的列表,一次
运行拒绝两者的并集。read-project 不可拒绝;未知的名字是用法错误(退出 2)。
--offline 拒绝 network,作为它的写法保留。
运行在它将要执行、且被调用方拒绝的第一个副作用之前停下,在标准错误上写明副作用
及其用途(effect denied: write-project -- the build writes …;被拒绝的 network
所需的下载照旧报告为离线拒绝),以 note: stopped before a denied effect (…); exit status 5 结束,退出 5。被拒绝的 write-global-cache 不会让构建停下:构建
改用工程自己的缓存。运行不需要的副作用即使被拒绝也不构成阻碍 —— 记录的计划有效
的构建不运行构建程序,因此在 --deny exec-build-script 下也能成功。信封的
effects 继续报告运行实际做了什么。
一个配置的构建目录同一时刻只由一次运行写入。同一配置的第二次构建等待第一次,在
标准错误上报告持有者(Waiting for the build directory, held by pid 1234 (mcpp build, from vscode, 8s)),并发出 waiting 事件,之后几乎无事可做。不同配置的
构建、查询(emit build-database、cache list、读取记录),以及 mcpp run 与
mcpp test 启动的程序从不等待。链接产物整体替换,因此在链接期间启动的程序不会
执行半个文件。mcpp.lock 以乐观方式写入:本次解析期间被另一次运行写入的锁文件
不会被覆盖,运行以 [lockfile-concurrent] 停下。契约见
docs/specs/concurrency.md。
MCPP_CLIENT=<name>在构建目录锁的持有者与结果记录中写明调用方(IDE 的后端、 agent 的宿主),不改变其他任何行为。- 颜色:
MCPP_NO_COLOR=1或非空的NO_COLOR关闭颜色;否则CLICOLOR_FORCE非空且 不为0、或FORCE_COLOR非空且不为0、false时,管道也有颜色;否则终端有颜色,管道没有。 mcpp --home <dir> <command>以<dir>作为一条命令的 mcpp home 运行,与MCPP_HOME=<dir>相同(SPEC-010)。
mcpp search [keyword] --format json
data 为 keyword(未给出时为 "",此时列出全部包)与 packages:每个包一条
记录,含 id(namespace:name)、namespace、name、index、description、
licenses、repo 与 versions(最新在前)。每个索引只读一次;命令不需要工程。
mcpp index list --format json
data 为 registries(name、url、default)与 indices(在工程中运行时,
工程的 [indices] 条目)。包的目录由 mcpp search 回答。
mcpp pack --list-formats
data.formats 列出引擎自己的格式(tar、zip、dir、single-file;builtin: true)以及已解析依赖
图中某个包提供的每种格式(builtin: false,带 providers)。依赖图在 mcpp home 的
一个目录中规划,因此不向工程写入任何东西。带 --target <triple> 时(2026.10.29.1+;多次给出时取最后一个),
规划的是该目标的依赖图,并列出其平台的格式:mcpp pack --target x86_64-openkal --list-formats 列出
okb,由 mcpplibs.openkal-platform 提供。
- 退出码表的作用域仅限于它点名的那些命令。 别的命令返回的退出码不在表 里,把它加进来等于记录一件这些命令承诺不了的事。
- 一条没有位置的诊断会省略
path与range,而不是发送 0:line: 0会指向 一个不存在的位置。 - stdout 上没有 JSON,就意味着「不支持」,无论原因是什么 —— 一个较旧的引擎、 一个未知选项,或者一条根本没有机器格式的命令。客户端仅凭这一条流本身,分辨 不出这三种情况。
{ "schemaVersion": 1, // the ENVELOPE's version "kind": "mcpp.env", // which document this is "kindVersion": 1, // this kind's own data version "effects": [], // what running the command did — see §4 "mcpp": { "version": "2026.8.8.3", "protocol": { "min": 1, "max": 1 }, "features": ["target-sets", "pkg-format-list"] // 自 2026.10.31.1 起 —— 见 §4 }, "data": { /* specific to `kind` */ }, "diagnostics": [] }