|
| 1 | +--- |
| 2 | +subject: release |
| 3 | +status: active |
| 4 | +--- |
| 5 | + |
| 6 | +# 发布的发布面与 macOS 链接的 SDK 契约(2026-11-14 补充) |
| 7 | + |
| 8 | +**日期:** 2026-11-14 |
| 9 | +**状态:** 第 1 节(B1–B4)与第 2 节的 M1 在 mcpp 2026.11.14.1 实施;M2、M3 在 openkal-macos 的补丁版实施,待负责人审阅。 |
| 10 | + |
| 11 | +本文补充 `2026-11-14-ci-and-release-time-cost-design.md`,处理 v2026.11.13.1 发布中测到的两件事:一是 `publish-ecosystem` |
| 12 | +的耗时与它对 xim-pkgindex 自动更新器的依赖;二是 canary `cxx aarch64-macos test` 揭示的 mcpp 与 openkal-macos 之间关于 |
| 13 | +macOS SDK 的契约矛盾。两件事互不依赖,各自一个 PR(mcpp 一个,openkal-macos 一个)。 |
| 14 | + |
| 15 | +## 1. 发布面:GitCode 同步默认关闭,索引 PR 直接创建 |
| 16 | + |
| 17 | +### 1.1 测量(v2026.11.13.1,运行 43594022005) |
| 18 | + |
| 19 | +| 环节 | 用时 | |
| 20 | +|---|---| |
| 21 | +| 四个构建并行,至 `create-release` | 40 分钟 | |
| 22 | +| 封存(`release-manifest`) | 约 1 分钟 | |
| 23 | +| GitHub 镜像(`xlings-res/mcpp`,8 个资源) | 64 s,每个资源 1 s | |
| 24 | +| GitCode 镜像(同 8 个资源) | 713 s;四个归档各约 604 s(10–17 MB),`.sha256` 各 4–7 s | |
| 25 | +| 索引 PR(`bump_index.sh`) | 向 xim-pkgindex 发 `repository_dispatch`,等待其更新器开出 PR,上限 1200 s | |
| 26 | + |
| 27 | +GitCode 一侧的瓶颈是 GitHub 美国 runner 到 `file.gitcode.com` 的上行(`mirror_res.sh` 的测量:0.012 MB/s;中国大陆主机为 |
| 28 | +1.84 MB/s)。同一批资源由负责人在本地以 gtc 上传、取回逐字节比对,用时以分钟计。 |
| 29 | + |
| 30 | +`bump_index.sh` 不写配方,它请求 xim-pkgindex 的更新器(`xpkgindex-update.yml`)提出 PR;该更新器要求 GLOBAL 与 CN 两处 |
| 31 | +资源都已存在才提出。因此索引 PR 被串在 GitCode 镜像之后,GitCode 慢或失败时索引 PR 也不出现。 |
| 32 | + |
| 33 | +### 1.2 方案 |
| 34 | + |
| 35 | +**B1. GitCode 镜像是一项可选择的步骤,默认不运行。** |
| 36 | + |
| 37 | +- `release.yml` 的 `workflow_dispatch` 增加布尔输入 `gitcode`(缺省 `false`)。`publish-ecosystem` 的镜像分为两步: |
| 38 | + GitHub 一步以 `MIRROR_HOSTS=gh` 调用 `mirror_res.sh`,总是运行;GitCode 一步以 `MIRROR_HOSTS=gtc` 调用,只在 |
| 39 | + `WITH_GITCODE`(`github.event_name == 'workflow_dispatch' && inputs.gitcode`)为真时运行。tag 推送没有输入, |
| 40 | + 只镜像 GitHub。`mirror_res.sh` 已支持 `MIRROR_HOSTS=both|gh|gtc`,脚本本身不改。 |
| 41 | +- 步骤的 `timeout-minutes`:GitHub 一步 10 分钟,GitCode 一步 45 分钟(脚本自身的 GitCode 期限为 2400 s)。 |
| 42 | +- 本地补齐 GitCode 的做法写入 `docs/92-release.md` §2:`MIRROR_HOSTS=gtc bash .github/tools/mirror_res.sh mcpp <version>` |
| 43 | + (需要 `GITCODE_TOKEN` 与 PATH 上的 gtc),随后逐个资源从 GitCode 取回并与 GitHub 的字节比对。检查清单中"两处镜像都提供 |
| 44 | + 四个平台"一项保留,执行者由 CI 变为负责人。 |
| 45 | + |
| 46 | +**B2. 索引 PR 由发布直接创建,不经 xim-pkgindex 的更新器。** |
| 47 | + |
| 48 | +- 新脚本 `.github/tools/index_pr.py --manifest <mcpp-release.json> --gitcode pending|absent`(替换 `bump_index.sh`, |
| 49 | + 后者删除): |
| 50 | + 1. 读本次运行封存的 `mcpp-release.json`(`release-manifest` 作业上传的 artifact `mcpp-release-manifest`),取版本与四个 |
| 51 | + 平台归档的 sha256;不重新下载、不重新计算,索引写入的摘要即封存的摘要。tag 重建时版本亦取自清单而非 `mcpp.toml`。 |
| 52 | + 2. 在 xim-pkgindex `main` 的 `pkgs/m/mcpp.lua` 中,向 `linux`、`macosx`、`windows` 三张表各追加该版本的条目(GLOBAL 为 |
| 53 | + `github.com/xlings-res/mcpp/releases/download/<v>/…`,CN 为 `gitcode.com/xlings-res/mcpp/releases/download/<v>/…`), |
| 54 | + 并把三处 `latest` 指向它。条目的形状与更新器写出的相同(见 xim-pkgindex#1149)。 |
| 55 | + 3. 以 `XIM_PKGINDEX_TOKEN`(Contents 与 Pull requests 权限;`gh auth setup-git` 供推送认证)推送分支 |
| 56 | + `auto/bump-xim-mcpp`,开 PR。PR 正文以更新器的标记 |
| 57 | + `<!-- xpkgindex-update: {"id":"xim:mcpp","candidate":"<v>"} -->` 开头:更新器按该标记识别已有提案,不再重复提出。 |
| 58 | + 同一分支上若有较早版本的打开 PR,改写其标题与正文,不另开。 |
| 59 | + 4. PR 正文写明 GitCode 一侧的状态:`pending`(本次运行随后镜像 GitCode,作业绿后合入)或 `absent`(未由本次运行镜像, |
| 60 | + 以 `MIRROR_HOSTS=gtc` 补齐后合入)。 |
| 61 | +- 已存在同一标记的 PR(打开或已合入)时脚本不做任何事;配方已含该版本时同样不做任何事。重复运行无副作用。 |
| 62 | +- 改写的是配方的版本表,不改配方逻辑。由此配方多了一个写入者(mcpp 的发布),这是有意的取舍:发布不再等待另一仓库的 |
| 63 | + 调度,代价是条目形状须与更新器一致,由 xim-pkgindex 自身的 CI(配方解析、L3/L4 安装检查)把关。更新器继续服务其余包。 |
| 64 | + |
| 65 | +**B3. 次序与时长。** `publish-ecosystem` 变为:GitHub 镜像(约 1 分钟)→ 索引 PR(秒级)→ 可选的 GitCode 镜像(放在最后, |
| 66 | +失败不影响前两步的结果,但仍使作业为红)。发布从分派到索引 PR 预计约 42 分钟。负责人在本地补齐 GitCode 之后合入索引 PR, |
| 67 | +随后 `ci-fresh-install` 与真实安装验证照旧。 |
| 68 | + |
| 69 | +**B4. 验证。** `tests/scripts/test_index_pr.py` 离线运行:以固定的 `mcpp.lua` 片段与封存清单为输入,断言追加的三处条目、 |
| 70 | +`latest` 的移动、标记行与幂等;并读 `release.yml`,断言 `gitcode` 输入缺省为假、三步的次序、只有 GitCode 一步调用 gtc |
| 71 | +且受 `WITH_GITCODE` 约束、索引一步读封存清单。另以 v2026.11.13.1 的真实清单对 #1155 之前的 `mcpp.lua` 执行 |
| 72 | +`--edit`,结果与手工合入的 xim-pkgindex#1155 逐字节相同。 |
| 73 | + |
| 74 | +## 2. macOS 链接的 SDK:mcpp 与 openkal-macos 的契约 |
| 75 | + |
| 76 | +### 2.1 现象 |
| 77 | + |
| 78 | +canary `cxx aarch64-macos test`(macOS runner,`mcpp test --target aarch64-macos`)自加入起 9 次运行全部链接失败: |
| 79 | +`ld64.lld: error: undefined symbol: strlen`(以及 `memcpy`、`pthread_create` 等)。测试程序经 mtest → mcpplibs.os 依赖 |
| 80 | +openkal-macos;同一行的 build、run 两格不依赖 openkal-macos,通过。 |
| 81 | + |
| 82 | +### 2.2 原因:两处陈述自 2026-08-25 起矛盾 |
| 83 | + |
| 84 | +| 时间 | 变化 | |
| 85 | +|---|---| |
| 86 | +| 2026-06-24(mcpp#162) | macOS 的每个链接带 `-isysroot <SDK>`,不依赖主机开发工具的状态 | |
| 87 | +| 2026-08-24(mcpp#486) | `build_program.cppm` 对构建程序陈述:Mac 上 `--target aarch64-macos` 的目标侧由图供给,mcpp 不把系统 SDK 放上链接。openkal-macos 据此在 `MCPP_TARGET_REQUESTED` 非空时把 `port/`(只列三个名字的 `libSystem.tbd`)加入链接搜索路径 | |
| 88 | +| 2026-08-25(d35c0436) | 图供给 C 库时 `-isysroot` 同样保留(`flags.cppm` "AND KEPT")。上一行的陈述自此不成立 | |
| 89 | + |
| 90 | +`-L port` 先于 SDK 被搜索,三个名字的存根遮蔽了 SDK 的完整 `libSystem`。缺陷不由 2026.11.13.1 引入,自 2026.8.25.2 起 |
| 91 | +潜伏:mcpp 自己的 macOS 作业是原生构建(不写 `--target`,openkal-macos 不加存根),canary 是第一个在 Mac 上以 `--target` |
| 92 | +构建依赖 openkal-macos 的程序的检查。 |
| 93 | + |
| 94 | +影响面:在 Mac 上以 `--target aarch64-macos`、`--target x86_64-macos`,或以含 macOS 成员的目标集合,构建任何依赖 |
| 95 | +openkal-macos 的项目(mcpplibs.os、mtest 的使用者)。 |
| 96 | + |
| 97 | +### 2.3 方案 |
| 98 | + |
| 99 | +openkal-macos 要回答的问题是"链接中有没有系统自己的 `libSystem`",而不是"是否指定了目标"。这个事实由 mcpp 决定, |
| 100 | +因此由 mcpp 陈述。 |
| 101 | + |
| 102 | +**M1(mcpp):构建程序得到链接所用的 SDK。** |
| 103 | +- 新变量 `MCPP_TARGET_SDK`:链接以 `-isysroot` 指名的 SDK 目录;链接不指名 SDK 时为空。与其余变量一样总是给出,空即不适用。 |
| 104 | +- 取值与 `flags.cppm` 的链接参数出自同一个函数:把 `flags.cppm` 中选择 `macos_sdk` 的三支(Apple 交叉行的 SDK、以 |
| 105 | + `AppleIsysroot` 陈述的基座、`apple::sdk_path()`)提为 `mcpp::toolchain::apple::link_sdk(...)`,链接参数与构建程序的环境 |
| 106 | + 各读一次,二者不会再分歧。 |
| 107 | +- `hostprogram.cppm` 增加访问器 `target_sdk()`;`build_program.cppm` 中关于"`--target` 时不放 SDK"的陈述改为现行行为。 |
| 108 | +- 变量进入构建程序的重跑键(`contract_hash`),SDK 改变时构建程序重新运行。 |
| 109 | +- 文档:`docs/30-build-mcpp.md` 的变量表(中英)。测试:单元测试断言 macOS 链接参数中的 `-isysroot` 与 `MCPP_TARGET_SDK` |
| 110 | + 相同、非 Apple 目标为空。 |
| 111 | + |
| 112 | +**M2(openkal-macos):存根只在链接中没有系统的存根时提供。** |
| 113 | +- `build.mcpp` 的条件改为:指定了目标(`MCPP_TARGET_REQUESTED` 非空),且 `MCPP_TARGET_SDK` 为空。典型情形是从 Linux 交叉 |
| 114 | + 到 macOS。原生构建、Mac 上的 `--target` 由 SDK 回答,不再加存根。 |
| 115 | +- 兼容:不认识 `MCPP_TARGET_SDK` 的旧 mcpp 不给出它(读为空),条件退化为现行条件,行为不变。新 mcpp 配旧 openkal-macos |
| 116 | + 的组合仍是现行行为。 |
| 117 | +- 文件头的说明随之改写:判断依据是链接中是否已有系统的存根,由 mcpp 陈述。 |
| 118 | +- 以补丁版发布(0.23.x 的下一个)。mcpplibs.os 的依赖范围为 `>=0.22.0, <0.24.0`,使用者解析时自动取到,不需要其余包改动。 |
| 119 | + |
| 120 | +**M3(验证)。** |
| 121 | +- openkal-macos 的 CI:macOS 上以 `--target aarch64-macos` 构建并运行其一致性测试(此前只有原生构建);Linux 上交叉到 |
| 122 | + `aarch64-macos` 的链接仍取存根并成功。 |
| 123 | +- mcpp 的 canary:`cxx aarch64-macos test` 在新的 openkal-macos 发布后通过,canary 报告该格与矩阵不符,矩阵改回 `ok`。 |
| 124 | + |
| 125 | +### 2.4 不采纳 |
| 126 | + |
| 127 | +- **mcpp 把 SDK 的库目录排在包的 `link_search` 之前。** 这改变 `-L` 的一般语义(包陈述的搜索路径先于系统),为一个包的 |
| 128 | + 问题改所有包的规则。 |
| 129 | +- **openkal-macos 以主机系统判断。** 其文件头记录了以主机判断的失败(2026-08-23):判断应依据链接的事实,而该事实只有 |
| 130 | + mcpp 知道。 |
| 131 | +- **openkal-macos 自行探测 SDK(`xcrun --show-sdk-path`)。** 它重复 mcpp 的判断,且与 mcpp 实际所用的 SDK(`SDKROOT`、 |
| 132 | + 基座陈述)可能不同。 |
| 133 | + |
| 134 | +## 3. 平台服务 `planned` 行(负责人 2026-11-15 确认) |
| 135 | + |
| 136 | +### 3.1 现象 |
| 137 | + |
| 138 | +openkal-platform 0.28.0 在 `[platform] targets` 中列出 `i686-openkal`,并以 `toolchain = "llvm@23.1.3"` 陈述其工具链。 |
| 139 | +mcpp 的内建数据仍把该行登记为 `planned`,未指定工具链的构建一律拒绝。以 `--target openkal`(平台各 target 组成的集合) |
| 140 | +构建的每个使用者因此在 `i686-openkal` 一支上被拒绝,除非逐个项目写 `[target.i686-openkal] toolchain`。 |
| 141 | + |
| 142 | +### 3.2 规则 |
| 143 | + |
| 144 | +`planned` 表示引擎自己的提供者尚未服务该行,不表示该行不可构建。已有的例外是"为构建指定的工具链" |
| 145 | +(`[target.<row>] toolchain`、`--toolchain`、使用者传给子构建的工具链)。本节增加第二个同等明确的来源: |
| 146 | +为该请求选择的平台(`--platform`、`[target.<row>] platform`、配置),其陈述以工具链服务该行——该行列在 |
| 147 | +`[platform] targets` 且有 `toolchain`,或列在指定了工具链的 `[[platform.provider]]` 中。 |
| 148 | + |
| 149 | +- 判定读平台的陈述(`mcpp.manifest.platform_providers::serves_with_toolchain`),与 `mcpp why platform`、 |
| 150 | + 语句检查共用同一份提供者列表,不按平台名或行名硬编码。 |
| 151 | +- 时机:目标层级检查时平台尚未读入,故记录待定的行(`PrepareState::plannedRow`);平台为目录或第二遍已在 |
| 152 | + P1 读入时在 `step1_select_platform` 判定;由本遍获取的包在 `step4b_apply_platform` 判定,服务则以平台已读入 |
| 153 | + 的状态重新准备一遍(既有的 platform restart),不服务则拒绝。 |
| 154 | +- 拒绝信息指名该平台及其来源,并给出两条出路(指定工具链,或选择服务该行的平台)。未选择平台时信息不变。 |
| 155 | +- 兼容:只放宽,不改变已能构建的请求;旧 mcpp 对同一平台仍按原规则拒绝,平台以 `mcpp >= 2026.11.14.1` 声明下限。 |
| 156 | + |
| 157 | +### 3.3 验证 |
| 158 | + |
| 159 | +- 单元:`PlatformManifest/APlannedRowIsServedByAStatementWithAToolchain`(有工具链则服务,未列出或无工具链则不服务)。 |
| 160 | +- 本机:`--target i686-openkal --platform path:<openkal-platform>` 与 `--target openkal` 构建成功; |
| 161 | + `--target riscv64-linux-musl --platform path:<openkal-platform>` 与 `--platform openkal-platform@0.27.1 --target i686-openkal` |
| 162 | + (索引包,本遍获取)均被拒绝并指名平台。 |
| 163 | + |
| 164 | +## 4. 测试发现不进入另一个包 |
| 165 | + |
| 166 | +mtest 的标准布局把需要构建之外输入的一类测试放成独立成员包(`tests/cts/mcpp.toml`)。默认的 |
| 167 | +`tests/**/*.cpp` 此前会把这样一个包的源文件(`tests/cts/src/main.cpp`)当作根包的测试编译。 |
| 168 | + |
| 169 | +- 规则:包根之下含有 `mcpp.toml` 的目录是另一个包;任何 `[test] discover` glob 都不发现其中的文件。 |
| 170 | + 规则以清单文件为依据,不依赖目录名,夹具工程(`tests/e2e/<data>/app/mcpp.toml`)同样适用。 |
| 171 | +- 实现:`discover_test_targets` 对每个候选文件沿父目录向上检查到包根,结果按目录缓存。 |
| 172 | +- 验证:单元 `TestTargets/APackageBelowTestsIsNotItsTests`;本机一个含 `tests/cts/mcpp.toml` 的工程, |
| 173 | + `mcpp test --list` 只列出根包的测试。 |
0 commit comments