Skip to content

Commit fcadaba

Browse files
SPEC-014 2.0: a pack holds the legs it names -- sets expand, images of a platform with a runner are one tree whatever the number of legs, other programs a package per leg; runs_on in the summary and the envelope; --systems <os>, <os>-<arch>, all; --pkg-format lists of one tree's containers; single files cover legs x systems; --merge writes the launchers again; the universal spellings migrated
Co-authored-by: speak-agent <248744407+speak-agent@users.noreply.github.com>
1 parent bdd9029 commit fcadaba

37 files changed

Lines changed: 2073 additions & 703 deletions

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

Lines changed: 138 additions & 86 deletions
Large diffs are not rendered by default.

‎docs/24-openkal-cross.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -439,8 +439,8 @@ machine of another architecture `mcpp run` and `mcpp test` refuse the image and
439439
name `run_under`, the key that states the execution host. With one named, the
440440
runner runs there, and its program is the platform's runner for the image's
441441
architecture: mcpp builds the platform's carrier with nothing carried, for this
442-
system and that architecture, which is the program a self-contained universal
443-
package carries under `libexec/okrun/<os>-<arch>/`. A user-mode emulator is an
442+
system and that architecture, which is the program a self-contained package of
443+
images carries under `libexec/okrun/<os>-<arch>/`. A user-mode emulator is an
444444
execution host; on an x86_64 Linux machine with `qemu-aarch64`:
445445

446446
```toml
@@ -464,9 +464,10 @@ $ mcpp run --target aarch64-openkal
464464
for one run, and `[target.aarch64-openkal] run_under` in `~/.mcpp/config.toml`
465465
for one machine. `mcpp self env --target aarch64-openkal` reports the runner's
466466
program and its architecture and the execution host's program, or why runs
467-
are refused on this machine. A self-contained package of one image
468-
(`--no-universal --mode self-contained`) is a program of this system and the
469-
image's architecture ([10](10-pack-and-release.md)).
467+
are refused on this machine. A single file of one image
468+
(`--pkg-format single-file`) is a program of this system and the image's
469+
architecture; a self-contained package of it is the image's tree with that
470+
runner ([10](10-pack-and-release.md)).
470471

471472
### ok Images And The Web
472473

‎docs/35-platforms.md‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -71,8 +71,8 @@ for this machine and one for an ok image leave each other's entries in place.
7171
| the compile | `[platform.build]`, `[platform.build.'cfg(…)']` | flags for every unit of the target |
7272
| the link | `[platform.link]` | `driver`, `flags`, `start`, `script`, `inputs`, the names `exe` and `shared`, the `seal` steps |
7373
| the run | `runner`, `runners` | how `mcpp run` and `mcpp test` start an artifact, and named device actions |
74-
| the carrier | `carrier` | the program `mcpp pack` builds of a loaded artifact for a system: the self-contained program, a universal package's runner, a single file |
75-
| the package | `universal` | a pack of any target covers all of them, in one package ([10](10-pack-and-release.md)) |
74+
| the carrier | `carrier` | the program `mcpp pack` builds of a loaded artifact for a system: a self-contained tree's runner, a single file; a table or a list of tables, each serving the `<os>-<arch>` pairs of its `hosts` |
75+
| where the runner exists | `runner.hosts` | the `<os>-<arch>` pairs the runner's program exists for: where a package that needs it runs (`runs_on.with`, [10](10-pack-and-release.md)) |
7676
| the code | `plugin` | a build program run in the platform phase, for what depends on the graph |
7777
| the group | `[platform.versions]` | one version of each package of a family |
7878
| the host part | `[platform.hosted]` | what a host triple takes when it selects the platform |
@@ -192,7 +192,6 @@ targets = ["x86_64-openkal", "aarch64-openkal"]
192192
toolchain = "llvm@23.1.3"
193193
runner = { cmd = ["okrun", "{}"], host = "same-arch" }
194194
carrier = { package = "openkal-run@0.1.3", section = ".oke", main = "carrier/main.cpp" }
195-
universal = true
196195
plugin = "build.mcpp"
197196

198197
[platform.layers]
@@ -237,7 +236,7 @@ seal = [["okld", "note", "{}"], ["okld", "check", "{}", "--with", "{needed}"]]
237236
phase ([34](34-authoring-a-bsp.md)).
238237
- **The carrier's entry reads what it carries.** mcpp places the carried bytes
239238
between `mcpp_carried_begin` and `mcpp_carried_end` (the entry's name at
240-
`mcpp_carried_name`): nothing, when the program is a universal package's
239+
`mcpp_carried_name`): nothing, when the program is a self-contained tree's
241240
runner and runs the image its first argument names; the image itself; or a
242241
stored zip of the images (`PK\x03\x04`, each aligned to 64 KiB) for a
243242
single file of an image that names others ([SPEC-013](specs/platforms.md)

‎docs/50-machine-output.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -727,10 +727,12 @@ to stderr, including what the build programs and tools the pack starts print.
727727

728728
| field | |
729729
|---|---|
730-
| `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 |
730+
| `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; a pack of a package per leg (2026.10.30.1+) reports each package with its own 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, or of the carrier that is the program of a self-contained package of one ok image (2026.10.29.1+) |
733+
| `legs`, `systems` *(2026.10.27.1+)* | the canonical triple of each leg the command named (a target set expanded; 2026.10.30.1+), and the `<os>-<arch>` of each runner a self-contained tree of images carries |
734+
| `pkgFormats` *(2026.10.30.1+)* | every container written, in the order `--pkg-format` named them; `pkgFormat` is the first |
735+
| `runsOn` *(2026.10.30.1+)* | where the package runs, as its `mcpp-package.json` `runs_on` says: `{"self": ["linux-x86_64", …], "with": {"okrun": […]}}`; a single file's pairs are its files' |
734736
| `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` |
735737

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

‎docs/51-supported-versions.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,9 @@ the rows of this table (mcpp 2026.10.11.1+).
8080
| `abi-capability`: an `abi:` runtime capability (`abi:glibc`, `abi:libc=<c>`, `abi:cxxstdlib=<c++>`), read as a requirement on a target-side layer | 2026.10.26.1 | 2027.1 | `requires = ["mcpp:c-abi=<impl>"]` or `["mcpp:c++-abi=<impl>"]` |
8181
| `undeclared-cxx-runtime`: a C++ runtime other than the build's own, named on its link line or needed by a library the line names, that no package declares | 2026.10.26.1 | 2027.1 | `requires = [{ layer = "mcpp:c++-abi=<impl>", visibility = "private" }]` in the package that needs it |
8282
| `plugin-imports-from-build-dependencies`: a build plugin's library importing a package it lists in its own `[build-dependencies]` with `host-module = true` | 2026.10.11.1 | 2027.1 | the package in the plugin's `[dependencies]` |
83+
| `pack-universal`: `[pack] universal` -- `true` refused, `false` ignored; a pack's targets are its legs | 2026.10.30.1 | 2027.1 | `[pack] targets = ["openkal"]` (every architecture), or one `--target` |
84+
| `platform-universal`: a platform's `[platform] universal`, ignored; a pack's targets are its legs | 2026.10.30.1 | 2027.1 | nothing in the platform; the pack names its targets (`--target openkal`) |
85+
| `no-universal-flag`: `mcpp pack --no-universal`, which a pack of one target no longer needs (refused with a target set) | 2026.10.30.1 | 2027.1 | `--target <arch>-<os>` (one leg) |
8386

8487
## Reproducing a build
8588

‎docs/specs/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@
4343
| [SPEC-011](concurrency.md) | 并发运行:三段、构建目录锁、原子发布、`mcpp.lock` 的乐观写入、取消 | 评审中 v1.0 | 2026-10-26 | mcpp >= 2026.10.26.1 |
4444
| [SPEC-012](human-output.md) | 面向人的输出:两条流、两种介质、行的种类、颜色 | 评审中 v1.0 | 2026-10-26 | mcpp >= 2026.10.26.1 |
4545
| [SPEC-013](platforms.md) | 平台:`[platform]` 的七组键、版本组与 `hosted`,三种写法与层次,目标图与宿主图的选择,`cfg(platform)`,依赖图的补全,链接、命名与封装,运行器与载体,平台阶段与协议 17 | 评审中 v1.2 | 2026-10-29 | mcpp >= 2026.10.27.1;§10 的执行宿主与 §11 的载体架构 mcpp >= 2026.10.29.1 |
46-
| [SPEC-014](packaging.md) | 打包与分发:链接、闭包、容器三个维度与构建腿,暂存树与 `mcpp-package.json`,通用包、单文件、签名、压缩、合并与分发描述 | 评审中 v1.3 | 2026-10-29 | mcpp >= 2026.10.29.1;逐条标注 |
46+
| [SPEC-014](packaging.md) | 打包与分发:链接、闭包、容器三个维度与构建腿,腿的合并,暂存树与 `mcpp-package.json`,平台的树、运行覆盖、单文件、容器列表、签名、压缩、合并与分发描述 | 评审中 v2.0 | 2026-10-30 | mcpp >= 2026.10.30.1;逐条标注 |
4747

4848
## 文档约定
4949

0 commit comments

Comments
 (0)