Skip to content

Latest commit

 

History

History
1053 lines (839 loc) · 67.6 KB

50-machine-output.md

File metadata and controls

1053 lines (839 loc) · 67.6 KB

50 —— 机器可读输出

读者: 解析 mcpp 输出的工具、编辑器扩展或 CI 任务的作者。

本章回答的那一个问题: 一个程序可以依赖什么,输出如何被版本化,以及协议 如何被识别。

不在这里: 面向人的输出,它不携带任何兼容性承诺;以及退出码契约,那是 SPEC-003。

mcpp 面向两类读者写作。本章是对第二类读者 —— 程序 —— 的契约。编辑器扩展、 CI 脚本,以及任何解析 mcpp 输出的程序,都可以依赖本章陈述的内容。

1. 首要规则

靠解析 stdout 来识别协议,不靠退出码,也不靠「命令没有失败」这一点。

读取 stdout,尝试按 JSON 解析,并要求 schemaVersion 与 kind 二者都在。 只要缺一个,就说明这个 mcpp 不支持调用方所请求的协议。

这不是风格上的偏好。mcpp --protocol-version 看起来理应是入口,在支持它的 版本上确实是个有用的捷径。但在它存在之前发布的每一个 mcpp 上,这条命令 本身就是一个未知选项 —— 而未知选项过去的行为是把人类可读的文本打印到 stdout、退出码为 1、stderr 为空。成功与失败走的是同一个通道。把它拼成 --json 也不会改变什么,两者最终走的是同一条路径。

所以「正向识别」是唯一在各版本上都成立的规则,下面的一切设计都围绕它展开。

2. 信封

{
  "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": []
}

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。

3. 请求机器输出

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 日志不受影响)。

4. effects —— 命令在打印结果之前执行的动作

一个带有 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 下运行时永远不会列出。

特性(features)

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 的方式

为某个项目运行 mcpp 的工具(IDE 后端、语言服务器、CI 脚本)在项目根目录中运行它,程序名为 PATH 上的 mcpp(版本管理器的 shim)或用户设置的路径,并从环境中去掉 XLINGS_PROJECT_DIR。这样应答的就是该项目使用的 mcpp:锁定了版本的项目由其目录选定版本,任何工具都不读取锁定文件。mcpp self env --format json 报告该 mcpp 的 mcppVersion 与 program(正在运行的文件)。

5. --json 不等于 --format json

有两条命令在本协议存在之前就已经发布了 --json:

mcpp xpkg parse <file> --json     ->  {"namespace": …, "name": …, …}
mcpp cache list --json            ->  {"root": …, "entries": [ … ]}

那些 payload 是裸的——没有信封——而且已经有消费方在读取它们。所以:

--json 永久保留它的 payload。带信封的是 --format json。

--json 没有被弃用,使用它也不会打印任何警告:客户端正在解析这份输出,一条 警告会落在它中间。

两种拼法出自同一个数据来源,因此永远描述同一件事:一个答案,两种形状。

6. 退出状态

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)。

7. 稳定性承诺

对每一个 kind,在同一个 kindVersion 之内:

  • 字段只会被新增,从不删除
  • 一个字段的含义永远不变
  • 破坏性变更会抬升版本号;在需要过渡窗口时,protocol.min/max 会重叠, 使两个版本都可读

这个承诺只有被强制执行才有价值,因此每个 kind 都配有一个测试:字段名一改就 变红。没有人能弄坏的 schema 不是 schema —— xlings interface --list 声明了 20 个 capability,它们的 outputSchema 全部只有 {"exitCode": integer},而一个客户端看到版本号就会以为背后有一份契约。

8. 各个 kind

mcpp.env —— mcpp 使用的各个路径

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 —— 一份被解析的描述符

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 —— 全局构建缓存

mcpp cache list --format json

data 是 {root, entries[]},与 --json 裸打印出来的一致。

mcpp.why.sources —— 每个工具的来源 (mcpp 2026.10.1.3+)

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 与 mcpp.why.compat (mcpp 2026.10.11.1+)

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、mcpp.why.flags 与 mcpp.why.platform (mcpp 2026.11.9.1+)

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 —— 已安装的工具链,以及这台宿主能服务的目标

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, toolchain) 的解析结果

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.build-database —— 以构建数据库表达的构建计划 (mcpp 2026.9.15.1+)

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 —— 一次打包的产物 (mcpp 2026.9.16.1+)

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 --message-format json —— 测试流

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 是整个成员的墙钟时间,包含规划与组的构建。

组记录*(2026.10.1.1+)*

对多个成员的 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 写法与仓库)。

9. 构建事件流与结果记录 (mcpp 2026.10.26.1+)

构建一个工程的每条调用链 —— 终端里的人、只有 shell 的 agent、IDE、CI 任务 —— 都终止于一次 mcpp 运行,因此一条链需要了解另一条链的构建时,由 mcpp 以同一种 形式写到磁盘上。

mcpp build --message-format json —— 事件,然后是 mcpp.build

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。叙述写到标准错误,与每一种机器可读模式 相同。

结果记录:result.json 与 target/.last-result.json

构建在开始写构建目录时写下 <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.launch —— mcpp run 启动程序的方式

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、多条腿与多个成员同样拒绝。调试器启动信封描述的程序。

10. 拒绝副作用 —— --deny (mcpp 2026.10.26.1+)

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 继续报告运行实际做了什么。

11. 并发运行

一个配置的构建目录同一时刻只由一次运行写入。同一配置的第二次构建等待第一次,在 标准错误上报告持有者(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。

12. 调用方的名字、颜色与单次运行的 home (mcpp 2026.10.26.1+)

  • 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)。

13. 查询 (mcpp 2026.10.26.1+)

mcpp.search —— 索引提供的包

mcpp search [keyword] --format json

data 为 keyword(未给出时为 "",此时列出全部包)与 packages:每个包一条 记录,含 id(namespace:name)、namespace、name、index、description、 licenses、repo 与 versions(最新在前)。每个索引只读一次;命令不需要工程。

mcpp.index —— 注册表与工程的索引

mcpp index list --format json

data 为 registries(name、url、default)与 indices(在工程中运行时, 工程的 [indices] 条目)。包的目录由 mcpp search 回答。

mcpp.pack.formats —— mcpp pack --pkg-format 接受的格式

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,就意味着「不支持」,无论原因是什么 —— 一个较旧的引擎、 一个未知选项,或者一条根本没有机器格式的命令。客户端仅凭这一条流本身,分辨 不出这三种情况。