Skip to content

Commit ce0aeb7

Browse files
emit xpkg: a one-leg package is described for the system its program runs on; a carrier package records its carrier
Review of #859: the rule refused every one-leg ok-image package, and a package that carries its image in the carrier (--no-universal --mode self-contained or static) is a program of the carrier's system: on Linux, a static Linux program of the image's architecture. It was described under linux before, and refusing it was a regression. - mcpp-package.json `systems` (and the mcpp.pack envelope's, through one function, mcpp::pack::carried_systems) records the carrier of a one-leg self-contained ok-image package as the loader it carries: `<this system>-<image arch>`, e.g. ["linux-aarch64"]. It was empty, so the system was not a fact a reader could take. - emit xpkg describes a one-leg package for the system and architecture of its program (program_host): the triple's for a Linux (not Android), macOS or Windows target, the recorded carrier's for an ok image. It refuses only packages whose program is no program of a system: wasm, Android and iOS applications, bare metal, and an ok image without its carrier (route: the universal package, or a package that carries it). - SPEC-014 §4.5 and §8, criterion 9; docs/10 and docs/50 with docs/zh; CHANGELOG; the design record's rev 2. - Unit XpkgDescriptorDescribesProgramsOfASystem: a one-leg x86_64-openkal carrier package packed on Linux is described under linux with arch x86_64, an aarch64 one packed on macOS under macosx, a carrier-less one is refused. e2e 961 C: the package's systems, its entry under this system for the image's architecture, and the refusal of the vendored image package. Co-authored-by: speak-agent <248744407+speak-agent@users.noreply.github.com>
1 parent 40fcdc6 commit ce0aeb7

12 files changed

Lines changed: 163 additions & 51 deletions

‎.agents/docs/2026-10-29-openkal-run-test-pack-design.md‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,10 @@ status: active
1010

1111
**修订记录**
1212

13-
- rev 1(本稿):七项的实测与定案;一个发布 PR。
13+
- rev 1:七项的实测与定案;一个发布 PR(#859)。
14+
- rev 2(本稿,评审):§2.6 的 `emit xpkg` 规则改为按**程序**运行的系统描述。带载体的单腿 ok 映像包(M3)是载体所属系统的
15+
程序,rev 1 把它一并拒绝,对在 Linux 上打出、此前可用的条目是回归;包现在在 `systems` 中记录其载体的 `<os>-<arch>`,条目
16+
读这一事实,只拒绝不带载体的 ok 映像包。
1417

1518
## 0. 摘要
1619

@@ -83,9 +86,10 @@ F5 的对照:把运行器手工改为 `cmd = ["qemu-aarch64", "<aarch64 的 ok
8386
包(`xpm.<system>` 安装该系统的程序,`archs` 为机器架构)。`wasm32-emscripten` 的包两者都不是:它没有启动器,`bin/<name>.js` 由
8487
JavaScript 引擎或浏览器执行,`wasm32` 不是任何系统的机器架构,xvm 注册的 `bin/<name>` 不存在。把它描述成系统无关的条目需要为 wasm
8588
生成启动器并在条目中写运行器前缀,即一个新形状,而 Web 的分发路径是 `dist-web` 产出的页面,不是 xlings。规则按模型写成一般形式:
86-
单腿包按其腿的三元组的系统描述,三元组不是 Linux(非 Android)、macOS 或 Windows 程序时拒绝。同一条规则也拒绝其他不属于这三个系统
87-
的单腿包(Android、iOS、裸机,以及 `--no-universal` 的 ok 映像包——xlings 经通用包安装 ok 映像);此前它们都被写成 `linux`
88-
或 `macosx`。
89+
单腿包按其**程序**运行的系统与架构描述。腿为 Linux(非 Android)、macOS 或 Windows 的三元组时取三元组的;腿为 ok 映像而包携带
90+
载体(`self-contained`、`static`)时,程序是载体,为本机系统、映像架构的程序,包在 `systems` 中记录它(`<os>-<arch>`,与通用包
91+
记录 `libexec/` 中加载器的字段相同),条目读这一记录而不推测。程序不是任何系统的程序时拒绝:WebAssembly、Android、iOS、裸机,
92+
以及不带载体的 ok 映像包(一个 `.oke` 需要运行器,出路为通用包);此前它们都被写成 `linux` 或 `macosx`。
8993

9094
**`--pkg-format single-file`:拒绝。** 单文件是一个系统执行的可执行文件(原生启动器或载体);WebAssembly 模块不是。拒绝在
9195
`refused_combination` 中,任何构建之前,写出两个选择与出路(`tar`、`zip`、`dir` 或提供者的格式,页面为 `dist-web`)。
@@ -105,7 +109,7 @@ ok 映像是 x86_64 与 aarch64 上位置无关的 ELF,只导入 `kal_*`,需
105109
| F5 | `PlatformRun.TheRunnerReachesTheArtifactsArchitecture`(`runner_reach` 的表) | 960 D:记录 argv 的执行宿主收到的运行器程序是另一架构的 ELF;本机有该架构的 qemu 时真实运行 `run` 与 `test` |
106110
| F6 | — | 960 C:人类输出给出拒绝;JSON 的 `runner.refusal`、`runner.arch`;给出执行宿主时为另一架构 |
107111
| F2、F3 | — | 961:载体为映像架构的 ELF(有 qemu 时运行它);`--target <t>-openkal --list-formats` 含 `okb`,本机目标不含 |
108-
| F7a | `XpkgDescriptorDescribesProgramsOfASystem` | 962 A:合成的 wasm32-emscripten 包被拒绝,消息写出三元组与出路 |
112+
| F7a | `XpkgDescriptorDescribesProgramsOfASystem`(含 Linux 与 macOS 上打出的带载体包、不带载体的包) | 962 A:合成的 wasm32-emscripten 包被拒绝,消息写出三元组与出路;961 C:带载体的包的 `systems` 与条目,不带载体的包被拒绝 |
109113
| F7b | — | 962 B:有 emsdk 载荷时 `--pkg-format single-file --target wasm32-emscripten` 在编译前被拒绝 |
110114

111115
## 4. 文档

‎CHANGELOG.md‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -59,11 +59,16 @@
5959
Every triple that was not Windows or macOS was written `linux`: a
6060
`wasm32-emscripten` package became a Linux entry with `archs = {"wasm32"}`.
6161
An entry's `xpm.<system>` installs a program of that system for machine
62-
architectures, and a WebAssembly package has no launcher, no system and no
63-
machine architecture, so a package of one leg that is no Linux (other than
64-
Android), macOS or Windows program is refused, naming the route that
65-
distributes it: a page through `dist-web`, or for an ok image its
66-
platform's universal package (SPEC-014 §8; e2e 962).
62+
architectures. A package of one leg is now described for the system and
63+
architecture of its program: the triple's for a Linux (other than Android),
64+
macOS or Windows target, and for an ok image packed with its carrier
65+
(`--no-universal --mode self-contained` or `static`) the carrier's, which
66+
the package now records in `mcpp-package.json` `systems` (and the `mcpp.pack`
67+
envelope's), e.g. `["linux-aarch64"]`. A package whose program is no program
68+
of a system -- a WebAssembly module, an Android or iOS application, a
69+
bare-metal image, an ok image without its carrier -- is refused, naming the
70+
route that distributes it: a page through `dist-web`, or the platform's
71+
universal package (SPEC-014 §4.5, §8; e2e 961, 962).
6772
- **`--pkg-format single-file` is refused on a WebAssembly target.** A single
6873
file is an executable of one system; the pack tried a `wasm32-linux-musl`
6974
launcher. The refusal comes before anything compiles and names `tar`,

‎docs/10-pack-and-release.md‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -895,11 +895,15 @@ sha256 per architecture. The install moves the archive's top directory into
895895
place and registers the program with xvm (the `.cmd` launcher on Windows),
896896
from each system's own directory when the packages place the program apart
897897
(a Windows program at the root, a POSIX one under `bin/`). Each archive is its
898-
own `--package`. A package of one leg is described for the system of its triple
899-
(Linux, macOS or Windows); one of another target is refused, naming the route
900-
that distributes it (2026.10.29.1+): a `wasm32-emscripten` package is published
901-
as a page (`dist-web`), an ok image as its platform's universal package, and an
902-
Android, iOS or bare-metal package has no entry.
898+
own `--package`. A package of one leg is described for the system and
899+
architecture its program runs on (2026.10.29.1+): the triple's for a Linux,
900+
macOS or Windows target, and for an ok image packed with its carrier
901+
(`--no-universal --mode self-contained`) the carrier's, which the package
902+
records in `systems` (`"systems": ["linux-aarch64"]` for an aarch64 image packed
903+
on Linux). A package whose program is no program of a system is refused, naming
904+
the route that distributes it: a `wasm32-emscripten` package is published as a
905+
page (`dist-web`), an ok image without its carrier as its platform's universal
906+
package, and an Android, iOS or bare-metal package has no entry.
903907

904908
### Compression and signing
905909

‎docs/50-machine-output.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -730,7 +730,7 @@ to stderr, including what the build programs and tools the pack starts print.
730730
| `artifacts` | one record per produced artifact: `path` (absolute), `type` (`file` or `directory`), `format` (the container: the `--pkg-format` value; when none is given, `zip` for a Windows program and `tar` otherwise), `targets` (the canonical triple of each leg that went into it) and `sha256` (a file's digest; `null` for a directory; 2026.10.27.1+). A dispatched format reports the terminal outputs of the actions the request introduced; a several-`--target` Android pack reports one artifact whose `targets` lists every leg |
731731
| `stage` | the tree the artifact was made from: `dir`, `manifest` (the stage manifest below) and `closure` (`walked` or `not-walked`); `null` for a library package, when no tree was staged, and for a pack of several members |
732732
| `linkage`, `mode`, `pkgFormat` *(2026.10.27.1+)* | the three choices of the pack ([10](10-pack-and-release.md)): `linkage` is `static`, `shared` or `declared`; `pkgFormat` is the `format` of the artifacts (`tar`, `zip`, `dir`, `single-file`, or a provided format) |
733-
| `legs`, `systems` *(2026.10.27.1+)* | the canonical triple of each leg (a universal package lists every target of its platform), and the `<os>-<arch>` of each runner a self-contained universal package carries |
733+
| `legs`, `systems` *(2026.10.27.1+)* | the canonical triple of each leg (a universal package lists every target of its platform), and the `<os>-<arch>` of each runner a self-contained universal package carries, or of the carrier that is the program of a self-contained package of one ok image (2026.10.29.1+) |
734734
| `stages` *(2026.10.1.1+)* | present only for a pack of several members (`--workspace`, or `-p` repeated): one record per member in `[workspace] members` order, with `member` (the qualified package name) and the `dir`, `manifest` and `closure` of `stage` |
735735

736736
For a pack of several members `artifacts` lists every member's artifacts, in the

‎docs/specs/packaging.md‎

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -215,7 +215,7 @@ WebAssembly 的同名文件族,ok 映像的 `bin/`),规定见 docs/10。
215215
| `linkage` | `static`、`shared`,或 `declared`(每个库按自己的声明) |
216216
| `mode` | §1.2 的模式:`system`、`vendored`、`self-contained`;`--mode static` 的原生包为 `static`,映像为 `self-contained` |
217217
| `legs` | 腿的规范三元组 |
218-
| `systems` | `libexec/<runner>/` 中加载器的 `<os>-<arch>`;无加载器时为空 |
218+
| `systems` | 包携带的加载器的 `<os>-<arch>`:通用包为 `libexec/<runner>/` 中的;单腿 `self-contained` 的 ok 映像包为其载体,即程序所属的系统与映像的架构(2026.10.29.1);无加载器时为空 |
219219
| `launch` | 通用包为 `runner`(平台的 argv)与每个架构的 `entry`;单腿原生包为 `program`(程序的相对路径) |
220220
| `files` | 树中每个文件(符号链接除外):`path`(相对于树根,`/` 分隔)、`role`、`leg`(所属的腿,共用文件为 `null`)、`sha256` |
221221

@@ -317,11 +317,13 @@ openkal 目标的单文件:载体携带映像本身(映像不引用其他映像
317317
中同名的包;openkal 为 `okrun`)。依赖带命名空间:不带命名空间的名字在家目录列出的第二个索引也有同名包时有歧义,
318318
xim-pkgindex 拒绝它。
319319
- 各系统各架构一个的包:每个系统一项,一个以 `${arch}` 代替架构的 URL 与每个架构的 sha256;文件名除架构外不同时
320-
拒绝。单腿包的系统由其腿的三元组决定:Linux(Android 除外)为 `linux`,macOS 为 `macosx`,Windows 为 `windows`。
321-
腿不是这三个系统之一的程序时(WebAssembly 包、Android 与 iOS 应用、裸机映像、单腿的 ok 映像包),条目**必须**被拒绝,
322-
消息写出包、三元组与出路:WebAssembly 包以 `dist-web` 发布为页面,ok 映像以平台的通用包(不带 `--no-universal` 的
323-
打包)描述。原因:条目的 `xpm.<系统>` 安装该系统的程序,`archs` 为机器架构;WebAssembly 包没有启动器,其程序由
324-
JavaScript 引擎运行,`wasm32` 不是任何系统的机器架构(2026.10.29.1)。
320+
拒绝。单腿包按其**程序**运行的系统与架构描述:腿为 Linux(Android 除外)、macOS 或 Windows 的三元组时,为该三元组的
321+
系统(`linux`、`macosx`、`windows`)与架构;腿为 ok 映像而包携带其载体(`self-contained`,含 `--mode static`)时,
322+
程序是载体,为包在 `systems` 中记录的唯一 `<os>-<arch>`(§4.5)。程序不是任何系统的程序时(WebAssembly 包、Android
323+
与 iOS 应用、裸机映像、不带载体的 ok 映像包),条目**必须**被拒绝,消息写出包、三元组与出路:WebAssembly 包以
324+
`dist-web` 发布为页面,不带载体的 ok 映像以平台的通用包(不带 `--no-universal` 的打包)或带载体的包描述。原因:条目的
325+
`xpm.<系统>` 安装该系统的程序,`archs` 为机器架构;WebAssembly 包没有启动器,其程序由 JavaScript 引擎运行,
326+
`wasm32` 不是任何系统的机器架构;一个 `.oke` 需要运行器(2026.10.29.1)。
325327
- 安装把归档的唯一顶层目录移到安装目录。该目录以归档命名(`mcpp pack` 的写法),安装取下载文件的名字去掉扩展名,
326328
对每个系统、架构与索引日后追加的版本都成立;打包后改名的归档与 xim 不解开的文件(非 `.tar.gz`、`.tar.zst`、
327329
`.tar.xz`、`.tar`、`.zip`)在写出条目时被拒绝;配置以 xvm 注册程序(通用包为 `bin/<name>`,Windows 上为
@@ -354,7 +356,8 @@ openkal 目标的单文件:载体携带映像本身(映像不引用其他映像
354356
7. 通用包的 `mcpp emit xpkg` 条目在三个系统上为同一资产,并以运行器为依赖(e2e 957)。
355357
8. `mcpp emit xpkg` 拒绝 `wasm32-emscripten` 的包,写出包、三元组与 `dist-web`;`--pkg-format single-file` 在 WebAssembly
356358
目标上于任何编译之前被拒绝(e2e 962)。
357-
9. 单腿的 `self-contained` ok 映像包的程序是映像架构的;`mcpp pack --target <t> --list-formats` 列出该目标的平台提供的格式
359+
9. 单腿的 `self-contained` ok 映像包的程序是映像架构的,`systems` 记录其载体的 `<os>-<arch>`,`mcpp emit xpkg` 以该系统
360+
与架构描述它,不带载体的单腿 ok 映像包被拒绝;`mcpp pack --target <t> --list-formats` 列出该目标的平台提供的格式
358361
(`okb`),本机目标的列表不含它(e2e 961)。
359362

360363
## 变更记录
@@ -364,4 +367,4 @@ openkal 目标的单文件:载体携带映像本身(映像不引用其他映像
364367
| 1.0 | 2026-10-28 | 首版(mcpp#847):三个维度与构建腿、组合的合法性、选项的全局用法与 `--pkg-format`、`[pack]` 的新键、管线、单腿与通用包的布局、启动器、`--systems`、`mcpp-package.json`、`--merge`、压缩、单文件、包格式提供者与平台插件、签名、分发描述、`mcpp.pack` 的新字段。 |
365368
| 1.1 | 2026-10-28 | 与实现对齐:zip 的条目以 DEFLATE 压缩;`[pack] universal`;压缩的拒绝与项目缺省值的搁置;`--systems` 也用于映像的单文件;启动器的根与退出状态;单文件的载荷格式、校验与执行;映像单文件的载体内容;`mcpp-package.json` 的 `linkage` 取值与角色判定;`--merge` 的输入、选项写法与容器;签名的范围;`mcpp emit xpkg --package`;判据对应 e2e 954–957。 |
366369
| 1.2 | 2026-10-28 | 包名的模式后缀;单文件启动器自身失败的退出状态 127;`--merge` 取 `[pack] format`,合并后的目录以输出命名;`--linkage static` 改为 musl 的行;`mcpp emit xpkg --package` 的每系统程序目录、带命名空间的运行器依赖、以归档名定位的顶层目录与多余词的拒绝。 |
367-
| 1.3 | 2026-10-29 | mcpp 2026.10.29.1:§0 ok 映像与 Web;§1.2 单腿 `self-contained` 包的载体为映像架构的程序;§1.5、§5.2 WebAssembly 目标上的单文件被拒绝;§6 `--list-formats` 规划所选目标;§8 单腿包的系统由三元组决定,不属于 Linux、macOS、Windows 的腿被拒绝;判据 8、9(e2e 961、962)。 |
370+
| 1.3 | 2026-10-29 | mcpp 2026.10.29.1:§0 ok 映像与 Web;§1.2 单腿 `self-contained` 包的载体为映像架构的程序;§1.5、§5.2 WebAssembly 目标上的单文件被拒绝;§4.5 单腿 `self-contained` ok 映像包的 `systems` 记录其载体;§6 `--list-formats` 规划所选目标;§8 单腿包按其程序运行的系统与架构描述(系统的三元组,或 ok 映像的载体),程序不是任何系统的程序的被拒绝;判据 8、9(e2e 961、962)。 |

‎docs/zh/10-pack-and-release.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -757,8 +757,10 @@ WebAssembly 目标没有单文件:`--pkg-format single-file` 与 `--target was
757757
包不携带运行器时以运行器为依赖(`deps = { "xim:okrun" }`);各系统各架构一个的包,每个系统一项,一个带 `${arch}` 的
758758
URL 与每个架构的 sha256。安装把归档的顶层目录移到位,并向 xvm 注册程序(Windows 上为 `.cmd` 启动器);各系统的包
759759
把程序放在不同目录时(Windows 的程序在包根,POSIX 的程序在 `bin/`),按系统注册各自的目录。每个归档各以一个
760-
`--package` 给出。单腿包按其三元组的系统(Linux、macOS 或 Windows)描述;其他目标的包被拒绝,并写出分发它的
761-
途径(2026.10.29.1+):`wasm32-emscripten` 的包发布为页面(`dist-web`),ok 映像以平台的通用包发布,Android、iOS
760+
`--package` 给出。单腿包按其程序运行的系统与架构描述(2026.10.29.1+):Linux、macOS 或 Windows 目标为三元组的
761+
系统与架构;带载体打包的 ok 映像(`--no-universal --mode self-contained`)为载体的系统与架构,包把它记录在 `systems`
762+
中(在 Linux 上打包的 aarch64 映像为 `"systems": ["linux-aarch64"]`)。程序不是任何系统的程序的包被拒绝,并写出
763+
分发它的途径:`wasm32-emscripten` 的包发布为页面(`dist-web`),不带载体的 ok 映像以平台的通用包发布,Android、iOS
762764
与裸机的包没有条目。
763765

764766
### 压缩与签名

‎docs/zh/50-machine-output.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -651,7 +651,7 @@ mcpp pack [target] [--pkg-format <f>] [--target <triple>...] --message-format js
651651
| `artifacts` | 每个产出的产物一条记录:`path`(绝对路径)、`type`(`file` 或 `directory`)、`format`(容器:`--pkg-format` 的取值;未给出时 Windows 程序为 `zip`,其余为 `tar`)、`targets`(进入该产物的每条腿的规范三元组),以及 `sha256`(文件的摘要;目录为 `null`;2026.10.27.1+)。被分派的格式报告本次请求引入的那些 action 的终端输出;一个多 `--target` 的 Android 打包报告一个产物,其 `targets` 列出每一条腿 |
652652
| `stage` | 该产物所来自的那棵树:`dir`、`manifest`(即下文的暂存清单)与 `closure`(`walked` 或 `not-walked`);库包、没有暂存任何树的情形,以及对多个成员的打包,此字段为 `null` |
653653
| `linkage`、`mode`、`pkgFormat` *(2026.10.27.1+)* | 本次打包的三个选择([10](10-pack-and-release.md)):`linkage` 为 `static`、`shared` 或 `declared`;`pkgFormat` 为产物的 `format`(`tar`、`zip`、`dir`、`single-file` 或提供者的格式) |
654-
| `legs`、`systems` *(2026.10.27.1+)* | 每条腿的规范三元组(通用包列出其平台的每个目标),以及自带加载器的通用包所携带的每个运行器的 `<os>-<arch>` |
654+
| `legs`、`systems` *(2026.10.27.1+)* | 每条腿的规范三元组(通用包列出其平台的每个目标),以及自带加载器的通用包所携带的每个运行器的 `<os>-<arch>`,或单个 ok 映像的 self-contained 包中作为程序的载体的 `<os>-<arch>`(2026.10.29.1+) |
655655
| `stages` *(2026.10.1.1+)* | 只在对多个成员的打包(`--workspace`,或重复的 `-p`)中出现:每个成员一条记录,按 `[workspace] members` 的顺序,带 `member`(限定的包名),以及与 `stage` 相同的 `dir`、`manifest`、`closure` |
656656

657657
对多个成员的打包,`artifacts` 按同样的成员顺序列出每个成员的产物,每条记录多出

0 commit comments

Comments
 (0)