Skip to content

Commit 424385e

Browse files
authored
2026.11.17.1: deploy entries, license files in every pack, run files, the index's platform column, N48 (#944)
* design record: N43-N47 (UEFI Shell arguments, the DOS first stack, N9 and dist-web 0.20.0, a run's input files, the UEFI payload disk) and the layers of further target rows * design record: ecosystem gap supplement, part 2 -- the roles of a file, a run's inputs, the manifest's writing and part 1's remaining items (for review) * Design record: part 2 revised after a multi-angle review (v2) * Design record: part 2 v3, the decided points and a two-way review against the verification project * Design record: part 2 v4, N48, the FreeBSD runner, setup-mcpp, and the implementation plan with its review * Design record: part 2 v4, mark the settled sections * Design record: part 2 v5, the plan is settled and new repositories go through their first pull request * N48: a row's fixed executable suffix ends a templated name A row states exe-suffix-fixed = true when its executable suffix is part of loading its programs. A name template (a build program's artifact_name, link.exe) then decides what precedes the suffix, and the name ends in it once: artifact_name("exe", "{name}") gives app.js beside app.wasm on wasm32-emscripten, where it gave a bare app, and {name}.js gives app.js, not app.js.js. The built-in wasm32-emscripten row states it; a platform states it for its own rows. The key is read by the built-in table's generator and by the platform reader alike. Spec: targets-and-providers v1.4 (2.1). Test: e2e web 1101. * deploy: an entry is a path or a table; globs, name, and stale copies removed [runtime] deploy takes a string, which is { from = <string> }, or a { from, to, name } table, in mcpp.toml and in descriptors. from may be a glob of the engine's one dialect; a match lands under to at its path below the glob's fixed directory (a literal path's is its parent, so every existing entry lands where it did). name renames the one match. A glob matching nothing and a name over several files are refused, naming the package and the entry; a literal path may still be generated by the build. deploy_files globs expand by the same rule. The expansion runs when the build is planned and enters the graph; placed.list beside build.ninja remembers the destinations, and a copy the new graph no longer places is removed from beside the program. SPEC-004 §15 (v1.20); docs/04 in both languages; unit tests for the readers and expand_deploy_entry; e2e runtime/deploy 1102. * license_files: every pack stages each package's license files [package] license_files names a package's license and notice files as globs relative to its root; a descriptor writes the same key in its mcpp segment. Unset, the engine's default {LICENSE,LICENCE,COPYING, NOTICE}* applies. The build plan records each package of the graph with its patterns, and every pack, in every mode, stages them under share/licenses/<package>/ with the role metadata: static libraries are covered as shared ones are. A package for which nothing is found is named in the report; a declared glob that selects nothing is warned about. This replaces collect_licenses, which ran only in self-contained packs, under seven fixed names, and said nothing when it found none. That mode still looks for the default files beside the shared objects it bundles that no package declares, and names those without. SPEC-004 §15.6-7, SPEC-014 §4.5.1 (v2.6); docs/04 and docs/10 in both languages; unit tests for both readers; e2e pack/modes 1103. * run files: mcpp run --file, [test] files, and the run's working directory mcpp run --file FROM[=TO] (repeatable, dirun's spelling) and [test] files (the deploy entry grammar, with [target.'<sel>'.test] files) name the files a run finds in its working directory. With them, the program runs in run/<id>/ of the build tree, into which they are copied (never linked): mcpp run waits for the program and removes the directory; a test program's directory is shared by its split parts, removed when it passes, kept and named when it fails. The directory is prepared before the launch is composed, so --print-launch and a test's launch name a directory that holds the files. Without run files nothing changes. A runner receives them as run_files in MCPP_RUN_CLOSURE (schema 2) and in MCPP_RUNTIME_FILES beside the runtime files, which is now derived as the union: where the program has a file system of its own, its directory is its working directory. Both fast paths decline when run files are named. SPEC-002 §6.2 and §6.2.1 (v1.9), SPEC-017 B1.6 and B5 (2.4); docs/04, docs/08 and docs/09 in both languages; unit test for [test] files; e2e run/contract 1104 and test/selection 1105; 927 reads schema 2. * platform: a row the built-in table has no platform for takes the one the index lists A platform package's index entry lists the rows it serves (`platform_rows = { "x86_64-uefi", ... }`). Step 5 of the platform choice, the target table's platform column, consults the index when the built-in table has no answer: a row the engine does not know, a row a platform defines, or a `planned` row. The package is selected as a series (`<ns>.<name>@*`), so its release is chosen, locked and updated as any platform series is, and the report names the source `index`. - The project's own indices ([indices], .mcpp/) rank before the shared ones; within one rank two claims are named and the first is taken. - A row the table answers is unchanged, and every statement of the project, the machine, the environment and the command line still comes first. - The entries are scanned once per command, and only for such a row (about 0.05 s for the whole refusal over ~400 entries). - mcpp 2026.11.16.1 reads an entry carrying the field and ignores it (measured with openkal-platform's entry). Tests: e2e 1106 (unknown row, planned row, the project first, two claims, no column), PlatformSelect unit. SPEC-013 v1.11 (§3.1, §14, criterion 16), docs/35 en/zh; the openkal-platform example uses multi-line inline tables. * docs: multi-line inline tables are 2026.11.17.1+, and the changelog says so (#929) * Design record: part 2 v6, measurements and the decisions taken while implementing * 2026.11.17.1: the version and the changelog's section * Design record: part 2 is active; the .agents/docs index; the dirun test's cause * platform: a manifest's [[platform.system]] reaches the platform reader * tests: 1104's runner is declared for the host's own row; 1105 states its host file for Windows too and names its copy apart from the original on case-insensitive file systems; the design record states the dirun test's cause as found * platform: the index's column is scanned with no lock held, so a leg that holds the home's lock does not wait on another; the scan is cached per set of roots * skills: a pull request that needs the full CI is labelled ci:full before its push * platform: a row the table holds with no platform and no built-in provider of that row here (x86_64-freebsd) takes the index's platform rather than a sibling row; table_answers decides it in both places * Design record: the timeouts' cause is open; the fourth kind of row the index answers; illumos and OpenBSD findings * SPEC-013 §14: which rows an entry's platform_rows lists, and that a host's own row is never among them * test: a package's programs are planned with its dev-dependencies, as its tests are, so a shared module is not compiled again over itself; a failure naming no step shows ninja's last lines (#945) * test: the programs a test runs request no [test] features (#941 stands); the testing chapter says the programs are planned with the dev-dependencies * tests: 1104 takes the host's row from its build directory (mcpp has no --print-target) * Design record: the timeouts did not recur with the scan's lock released; i686-openkal is the planned row a set's legs scan for * run files: the run's directory is removed by the interrupt watcher too, so a request that ends mcpp leaves no run-<pid>-<n> behind * Bases: a version directory with a manifest is the package root; a base's C++ library leaves the link when another package supplies the C++ layer An OpenBSD sysroot holds only usr/ beside its mcpp.toml, and the payload resolution descended into usr/ as into an extracted tarball (payload_root, unit PmPayloadRoot). A NetBSD program built with libc++ from source (the provider's layers) still linked the base's libstdc++ through the base's ldflags (SPEC-002 §2.5, e2e 1108). * Design record: the OpenBSD package root, the image profile, and NetBSD's import std through libc++ from source * A cfg selector names the platform of a row only that platform defines The early selection read only tables keyed by the triple, so [target.'cfg(any(os = "netbsd", os = "openbsd"))'] platform was refused as an unknown target. Until a row defines the triple, a selector is answered by its words, <arch>-<os>[-<env>] (SPEC-013 §3.1, e2e 1040). * runner = true | false: an override's consent alone, { enabled = ... }; the refusal names it and the platform-wide selector A runner's statement (a platform's, a provider's) states its command; an override table may enable or disable it by a boolean (e2e 1092 G, H). * Revert the programs planned with the dev-dependencies (#945): a dev-dependency's objects reached the programs' link CI showed the change wrong: a dev-dependency that supplies main (gtest_main) was linked into the program (duplicate symbol main, e2e graph/78), and the programs' plan no longer matched mcpp build's, so the test fast path declined (e2e 1069). The programs are planned as mcpp build plans them, as before. The diagnostic for a failure that names no step stays. * Docs: runner = true | false, and a runner's statement and its consent as two layers (SPEC-013 §10, docs/41, docs/04) * Matrix: i686-linux-musl and i686-openkal are named a platform by the index's column (measured on all four hosts) * A test plan that configures a package otherwise than mcpp build builds in a directory of its own; a build program's unchanged output keeps its time (#945) The tests' configuration axis (#test=) enters the fingerprint when the tests ask a package for features ([test] features, or a dev-dependency entry that asks a package the manifest also depends on). One directory held both configurations, whose interfaces and objects are named by module and package, and each plan compiled over the other. A build program rerun when its cached answer was another configuration's rewrote its generated source with a new time. e2e 1107: one compile per configuration, none again.
1 parent dcc96e5 commit 424385e

68 files changed

Lines changed: 3233 additions & 246 deletions

Some content is hidden

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

‎.agents/docs/2026-11-15-ecosystem-gap-supplement-design.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,11 @@ mcpp、openkal、xlings/xim 的包、dirun 与 mcpp:plugins 是通用基础设
5757
| N34 | UEFI 程序读不到任何文件:`cd` 为 `/`,`dir` 为 File Not Found | openkal-uefi 未实现 `fs`(其 README 写明 `fs` 待 SIMPLE_FILE_SYSTEM) | 实现 · openkal-uefi |
5858
| N35 | UEFI 参数含引号时切分错误 | openkal-uefi 按空格切分 load options;由 Shell 启动时,Shell 已给出 `EFI_SHELL_PARAMETERS_PROTOCOL` 的 argv | 实现 · openkal-uefi |
5959
| N42 | UEFI 参数中的空白在启动文件中未引用 | dirun 0.4.0 以空格连接 `{args}` 写入 `startup.nsh`,Shell 按空白切分(13.9) | 实现 · dirun 0.5.0 `[payload] quote`;数据 · ovmf r3 |
60+
| N43 | UEFI 参数含连续空白时被截短(`"two words"` 到达为 `two wor`) | OVMF(edk2 9.2.4)内置 Shell 交给程序的 argv 已截短;dirun 写出的行与 openkal-uefi 的转换均已核对(13.12) | 外部 · edk2 Shell;待评审 |
61+
| N44 | DOS 行的程序在栈超过 64 KiB 后静默结束(状态 0),或挂起 | openkal-dos 的 stub 把首个栈固定为 64 KiB,栈越界不产生故障(mcpplibs/openkal-dos#3;13.13) | 实现 · openkal-dos;待评审 |
62+
| N45 | 工程自行命名的 emscripten 程序在 dist-web 0.20.0 下打包失败,报“no action claimed” | N9 使行的 `.js` 让位于工程命名,旧的 dist-web 按 `<name>.js` 查找;报告不含原因(13.14) | 插件 · mcpp.plugins;平台 · plugins 版本 |
63+
| N46 | 单次运行无法附带输入文件(脚本、数据) | 运行器协议有 `MCPP_RUNTIME_FILES`,但其条目只来自随产物发布的 `[runtime]`(13.15) | 引擎;待评审 |
64+
| N47 | UEFI 行的程序不能写文件 | ovmf 配置以只读的 `fat:{dir}` 挂载载荷目录(13.16) | 运行器 · dirun、ovmf 包;待评审 |
6065
| N15 | UEFI 上 mimalloc 警告无安全随机源 | 未接 EFI_RNG_PROTOCOL | 实现 · openkal-uefi |
6166
| N19 | okrun 打不开含 `//` 的路径 | 打开映像前未规范化 | 实现 · openkal-image |
6267
| N12 | dirun 0.3.2 携带的 okrun 落后,仍有 `../` 错误 | dirun 自带一份 okrun 副本 | 运行器 · dirun |
@@ -721,3 +726,72 @@ profile 给出一次提示。需要评审后实现,不在本轮。
721726

722727
- 在 openkal-platform 仓库中以 mcpp 2026.11.16.1 执行 `mcpp why deps --target x86_64-openkal`,内置平台 0.28.0 的 openkal-tools 0.6.3 与仓库所述的 0.6.4 合并失败(`'=0.6.4,=0.6.3' matches none`)。`mcpp test` 把仓库本身当作平台,不受影响。
723728
- 待定:在平台包自身的仓库中,`why`、`build` 等命令是否也应以该包为平台(与 `mcpp test` 一致)。本轮不改。
729+
730+
### 13.12 N43:UEFI Shell 截短含连续空白的参数(外部验证工程中定位,待评审)
731+
732+
- 现象:`mcpp run --target x86_64-uefi -- "two words" "x y z" "ab cdefg" "aaaaaaaaaaaa b"` 中,程序收到 `["two wor", "x y z", "ab cdef", "aaaaaaaaaaaa "]`。截短只出现在含三个以上连续空白、且长度在 10 以上的参数中,长度更短的参数完整到达。
733+
- 已排除:
734+
- dirun:`startup.nsh` 中的行为 `APP.EFI "two words" …`,Shell 的 `echo` 对同一写法输出完整文本。
735+
- 引用写法:`"…"`、`^ ` 转义和两者混用,结果相同。
736+
- openkal-uefi:0.11.0 逐个转换 `EFI_SHELL_PARAMETERS_PROTOCOL` 的 `Argv`,不做切分。
737+
- 结论:截短发生在 edk2 Shell 为应用程序生成 `Argv` 的过程中,属于 xim 的 ovmf 9.2.4 所带的 Shell。
738+
- 候选:
739+
1. openkal-uefi 在 Shell 启动时改读映像的 `LoadOptions`,按 Shell 的规则自行切分。前提是 `LoadOptions` 保留完整的行,尚未实测。
740+
2. 换用修复了该问题的 edk2 版本(需先确认上游状态)。
741+
3. 在 openkal-platform 的文档中写明此限制。
742+
743+
### 13.13 N44:DOS 行的首个栈(openkal-dos#3 的第二种表现,待评审)
744+
745+
- 现象:一个批处理解释器在 `i686-dos-musl` 上执行脚本,到第一个 `IF` 时以状态 0 结束,没有输出,也没有故障报告。
746+
- 定位:
747+
- 同一份源码在 Linux 上,栈限制为 96 KiB 时正常运行,64 KiB 时段错误。该程序一层嵌套命令执行持有约 80 KiB 的栈缓冲区。
748+
- openkal-dos 0.1.0 的 `stub/stub.S` 把首个栈设为 `0x10000`,且栈与可加载段位于同一块内存中,越界写入相邻内存,而不是产生故障。
749+
- #3 记录的是同一原因下的挂起。
750+
- 候选设计:
751+
1. 首个栈默认 1 MiB,与 Windows 主线程一致。
752+
2. 可执行文件可以声明栈大小(`PT_GNU_STACK` 的 `p_memsz`,即 `ld -z stack-size`),由 stub 读取。
753+
3. 栈置于内存块低端,越界时离开描述符的界限,产生 `#SS` 或 `#PF`,经现有的故障报告输出。
754+
- 发布路径:openkal-dos 0.1.1,收入索引,再由 openkal-platform 0.29.1 引用。
755+
756+
### 13.14 N45:N9 与 dist-web 0.20.0
757+
758+
- 现象:工程以 `artifact_name("exe", "{name}")` 去掉宿主追加的后缀;在 mcpp 2026.11.16.1 下,emscripten 行的启动文件从 `<name>.js` 变为 `<name>`,wasm 文件从 `<name>.wasm` 变为去掉扩展名后的 `<stem>.wasm`。dist-web 0.20.0 按原名查找,未提交任何产物,引擎报告“no action claimed --pkg-format 'web'”。
759+
- 判断:产物名的变化是 N9 的既定行为,已写入 CHANGELOG。不足有两处:
760+
1. 引擎的报告没有给出提供者未提交的原因(N30 的机制要求提供者陈述原因,dist-web 0.20.0 没有陈述)。
761+
2. openkal-platform 0.29.0 以 plugins 0.20.0 构建,一次构建只容纳一个 plugins 版本,选用该平台行的工程因此无法单独升级 dist-web。
762+
- 工程侧的处理:只在非 emscripten 行上调用 `artifact_name`。
763+
- 候选:dist-web 在找不到启动文件时以警告陈述原因;openkal-platform 的下一个补丁版本跟进 plugins 的最新版本。
764+
765+
### 13.15 N46:单次运行的输入文件(待评审)
766+
767+
- 现象:一个程序在 UEFI 与 DOS 行上运行脚本时,脚本需要放在程序旁边。现有的做法只能绕过 mcpp 直接调用 dirun,在包目录中查找 dirun、ovmf 与 qemu 的路径,并在脚本里写死它们的版本。这样做依赖存储布局,重复了平台的 runner 数据,也绕过了按需启用与运行器协议。
768+
- 现有机制:运行器协议的 `MCPP_RUNTIME_FILES` 已由 dirun(0.4.0 起,经 `[payload] place` 旁或文件盘)与 Android runner(adb)投递;但它的条目只来自 `[runtime] deploy` 与 `deploy_files`,二者随产物发布,不适合测试输入。
769+
- 候选设计:
770+
1. `mcpp run --file HOST[=DEST]`(可重复),只为本次运行向 `MCPP_RUNTIME_FILES` 追加条目,`DEST` 相对于程序所在目录。
771+
2. 测试作用域的同类声明,供 `mcpp test` 的用例使用。
772+
3. 在此之上,可由 mcpp.plugins 提供脚本测试(发现 `tests/*.<ext>` 与对应的预期输出,经目标的 runner 运行,归一化行尾与颜色转义后比对),使 `mcpp test --target <triple>` 覆盖解释器类工程。
773+
- 待定:在本机直接运行时(不经过 runner),`DEST` 的落点有三种候选:只校验、复制到临时工作目录、或要求 `HOST` 与 `DEST` 是同一路径。
774+
- 不采用插件包装 runner 的做法:运行输入属于运行期,而插件在构建期执行;包装 runner 需要复制平台 runner 的命令行,而各 runner 的命令行不同。
775+
776+
### 13.16 N47:UEFI 载荷目录只读(待评审)
777+
778+
- ovmf 配置以 `-drive …,readonly=on,file=fat:{dir}` 挂载载荷目录。QEMU 的 vvfat 写入不可靠,因此只读挂载是有意为之;代价是程序写文件失败(openkal-uefi 把 `EFI_WRITE_PROTECTED` 报为 `kal_err_permission`,这一侧正确)。
779+
- 候选:dirun 为载荷生成一个可写的 FAT 映像,运行后读回其中的改动,由配置文件选择(例如 `[payload] disk = "fat-image"`)。
780+
781+
### 13.17 更多目标行的分层(待评审)
782+
783+
- 一个新系统的支持分三层,各层都只用数据:
784+
- xim:sysroot 包,以及“磁盘映像加其 dirun 配置”的包。
785+
- 平台包(mcpp-index):行、工具链,以及 `enabled = false` 的 runner,命令形如 `dirun --profile {pkg:<image>}/dirun.toml`。
786+
- 工程:只写 `[target] <triple>.platform`。
787+
- FreeBSD 行(`x86_64-freebsd-sysroot@14.5`、`freebsd-disk-image`)是现成的模板。
788+
- 候选与可行性:
789+
790+
| 档 | 系统 | 依据 |
791+
|---|---|---|
792+
| A | OpenBSD、NetBSD | clang 支持其三元组;sysroot 取自官方安装集;可在 QEMU 中运行。待实测:lld 对 OpenBSD 版本化共享库(`libc.so.N.M`)的查找;NetBSD 下 lld 能否链接 |
793+
| A | illumos(OmniOS、OpenIndiana) | `x86_64-pc-solaris2.11`;作为 System V R4 系统的现代后代,映像可公开分发 |
794+
| B | Haiku、GNU/Hurd | clang 支持其三元组;Haiku 的官方工具链为 GCC,需要专用的 dirun 配置;Hurd 在 QEMU 中运行慢且不稳定 |
795+
| C | PureDarwin、原版 System V R4 | 没有可用的 SDK 与可启动的映像;原版 SVR4 没有对应的 LLVM 目标,头文件、库与映像有版权,只能做成“自带 sysroot 与映像”的本地平台 |
796+
797+
- OpenBSD 自 7.4 起只允许经 libc 发出系统调用(`pinsyscalls`),因此 OpenBSD 上的 okrun 须以原生行构建;openkal 镜像在 OpenBSD 上运行,以原生行为前提。

0 commit comments

Comments
 (0)