docs(starry): add macOS HVF self-build app#1325
Conversation
![mai-team-app[bot]](https://avatars.githubusercontent.com/u/34859362?s=60&v=4){kind=small}
There was a problem hiding this comment.
Review 总结：APPROVE ✅
变更范围
本 PR 只新增 apps/starry/macos-selfbuild/ 目录（16 个文件，+3549 行），不修改任何 kernel、filesystem、driver 或 platform 公共语义。全部变更在 apps/starry/ 范围内，遵循项目 app 布局约定。
CI 检查
| Check | 状态 | 说明 |
|---|---|---|
| Detect changed paths | success | 正确识别仅 apps/starry/ 变更 |
| Cancel stale CI runs | success | 正常 |
| matrix.name (×2) | skipped | 期望行为：路径过滤未触发 build/test 矩阵 |
| Publish container images (×2) | skipped | 期望行为：app-only 变更不触发 |
无 CI 失败。
代码质量
- Shell 语法：全部 10 个
.sh脚本通过bash -n；guest-selfbuild.sh通过sh -n - 无
[patch.crates-io]：✅ - 无
cntv-timer/fdt-edit引用：✅ 与原 #984 干净分离 - 无尾部空白：
git diff --check通过 - 脚本结构：错误处理完善（
set -euo pipefail），安全防护到位（rootfs 新鲜度检查、crate 数量守卫、QEMU 超时），环境变量可配置，文档详尽
重复/重叠分析
apps/starry/macos-selfbuild/在 origin/dev 上不存在，无重复- 开放 PR #1326（tmpfs dir cookie fix）和 #1327（jobserver wait stress test）均不相关，无重叠
- 分类：无重复、无冲突
验证限制
完整 self-build 需要 Apple Silicon macOS + QEMU HVF 环境，当前 Linux x86_64 Docker 容器无法运行。作者已在 RESULTS.md 中提供了完整的本地验证参考数据（8-vCPU 默认配置 331s）。由于本 PR 纯 app/文档变更且 CI 已正确跳过构建矩阵，不阻塞此限制。
结论
无阻塞问题。PR 干净、文档完善、安全防护到位、无重复，建议合入。
Powered by mimo-v2.5-pro
ZR233
left a comment
ZR233
left a comment
There was a problem hiding this comment.
检查了新增的 apps/starry/macos-selfbuild app、文档、QEMU 配置和 host/guest 脚本。这个 PR 相比仍打开的 #984 是干净的 app-only 拆分：#984 还包含大量 kernel/driver/runtime/test 变更，而本 PR 只新增 macOS HVF self-build 场景并更新 apps/starry/README.md，因此两者概念上重叠但本 PR 本身没有代码冲突；建议后续单独处理 #984 的 supersede/关闭状态。
本地验证：
- 所有 host
.sh通过bash -n guest-selfbuild.sh通过sh -ngit diff --check origin/dev...HEAD- 检查了
prebuild.sh的STARRY_OVERLAY_DIR注入路径、source metadata/tarball 生成、run_selfbuild.sh的 fresh-rootfs guard 和 QEMU marker 监控、guest-selfbuild.sh的 fast-profile guard/离线 Cargo/self-build 命令，以及qemu-aarch64-hvf*.toml的 success/fail regex
端到端 QEMU/HVF self-build 需要 Apple Silicon macOS + HVF，当前 Linux x86_64 审查环境无法实际跑完整场景；不过该限制和 RESULTS.md/README 中的复现条件一致。当前 CI 对 app-only 变更按路径过滤跳过矩阵，未见失败。未发现阻塞问题，可以合入。
4cba4d5 to
eb86a46
Compare
There was a problem hiding this comment.
Review 总结：APPROVE ✅
变更范围
本 PR 是原 #984 的 app-only 拆分版本，只新增 apps/starry/macos-selfbuild/ 目录（16 个文件，+3642 行，0 删除）并更新 apps/starry/README.md 入口说明。不修改任何 kernel、filesystem、driver 或 platform 公共语义，也不包含 cntv-timer、[patch.crates-io]、vendored fdt-edit 等原 #984 的底层改动。全部变更在 apps/starry/ 范围内，遵循项目 app 布局约定。
实现逻辑
PR 提供了完整的 macOS/HVF self-build 复现路径：
reproduce.sh：端到端编排入口（rootfs → kernel → QEMU self-build）build_rootfs.sh：macOS 原生 AArch64 Alpine rootfs 构建，含 Rust/Cargo 离线缓存注入（966 行，功能完善）build_kernel.sh：AArch64 种子内核构建，自动检测并创建 zig-backed musl-gcc 包装器run_selfbuild.sh：host 侧 QEMU 管理器，含 rootfs 新鲜度检查、crate 数量守卫、QEMU 超时、failure pattern 匹配和心跳监控guest-selfbuild.sh：guest 侧 self-build 执行器，纯sh兼容，含 kallsyms 生成、marker-based 成功/失败报告qemu-aarch64-hvf.toml/qemu-aarch64-hvf-boot.toml：QEMU 配置模板，含合理的success_regex/fail_regexcheck_rootfs.sh/prepare_rootfs.sh/fetch_rootfs.sh/extract_kernel.sh：辅助工具README.md+RESULTS.md：详细文档和参考数据
脚本设计合理：host runner 和 guest script 职责分离，错误处理完善（set -euo pipefail / set -eu），安全防护到位（rootfs 新鲜度检查、crate 数量守卫、QEMU 超时），环境变量可配置。
CI 检查
| Check | 结论 | 说明 |
|---|---|---|
| Detect changed paths | ✅ success | 正确识别仅 apps/starry/ 变更 |
| Cancel stale CI runs | ✅ success | 正常 |
| matrix.name (×2) | ⏭ skipped | 期望行为：路径过滤未触发 build/test 矩阵 |
| Publish container images (×2) | ⏭ skipped | 期望行为：app-only 变更不触发 |
CI 状态：success=2, skipped=4, failure=0。无 CI 失败。跳过项均为 app-only 变更的期望路径过滤行为。
本地验证
- 所有 10 个
.sh脚本通过bash -n✅ guest-selfbuild.sh通过sh -n✅git diff --check通过 ✅- 无
[patch.crates-io]✅ - 无
cntv-timer/fdt-edit引用 ✅ - 无尾部空白 ✅
重复/重叠分析
apps/starry/macos-selfbuild/在 origin/dev 上不存在，无重复- PR #984（原 PR）已关闭，被本 PR 的 app-only 拆分取代
- PR #1333（feat/self-build-on-HVF，1301182193）：另一作者的 macOS self-build 方案，使用
cargo xtask image resize/inject+ 通用 bootarg，与本 PR 的独立脚本方案互补而非冲突 - PR #1334（fix/platform: support AArch64 HVF timer boot，yks23）：修复 HVF 启动问题（cntv-timer/GICv3），是 self-build 完整流程的依赖，但本 PR 不依赖它即可合入
- 分类：无重复、无冲突
测试覆盖
本 PR 纯 app/文档变更，不含内核或语义修改，不需要新增 test-suit 测试。完整的 macOS/HVF self-build 验证需要 Apple Silicon macOS + QEMU HVF 环境，当前 Linux x86_64 Docker 容器无法运行端到端场景。作者已在 RESULTS.md 中提供了完整的本地验证参考数据（8-vCPU 默认配置 331s），且 PR body 记录了本地验证方法。此限制是 app 平台要求的固有限制，非 PR 缺陷。
未解决 review thread
无未解决的 review thread。
结论
无阻塞问题。PR 干净、文档完善、安全防护到位、无重复、无冲突，建议合入。
Powered by mimo-v2.5-pro
ZR233
left a comment
ZR233
left a comment
There was a problem hiding this comment.
本次复审针对最新 head eb86a46f25955ba167bb7412cb1a99b01f8832a8。变更仍然只限于 apps/starry/macos-selfbuild/** 和 apps/starry/README.md，脚本结构和 app 放置位置本身没有问题，也没有引入 [patch.crates-io]、vendored fdt-edit 或原 #984 中那些底层改动。
已跑的本地检查：git diff --check origin/dev...HEAD、cargo fmt --all --check、bash -n apps/starry/macos-selfbuild/*.sh、sh -n apps/starry/macos-selfbuild/guest-selfbuild.sh，以及 cargo xtask starry build -c apps/starry/macos-selfbuild/build-aarch64-unknown-none-softfloat.toml，均通过；最后一个命令能构建出 AArch64 StarryOS seed kernel 和 .bin。当前 GitHub checks 只有 path detection/stale-cancel 成功，矩阵构建按路径过滤 skipped。
阻塞点在可复现性和合并顺序：这个 PR 不是纯说明文档，而是新增可执行的 macOS HVF Self-Build app/runbook，主流程声称能在 Apple Silicon + QEMU/HVF 下启动 AArch64 StarryOS 并完成 guest self-build。但当前 PR head 的内核仍使用 base 中的 non-hv EL1 CNTP timer 路径，也没有 GICD SPI 跳过/初始化控制；而相关 HVF timer/GIC 支持仍在其它 open PR（例如 #1334/#1333）中，并未进入当前 origin/dev，本 PR 也没有把它们声明为前置依赖或在文档里说明需要基于哪一个平台修复版本运行。也就是说，脚本和 seed build 可以过，但 PR 描述中的核心 HVF QEMU app 目前不能作为“基于当前 dev 可复现”的工作流来合入。
另外，本地确认该分支也不是基于最新 origin/dev（merge-base --is-ancestor origin/dev HEAD 为否）。请先 rebase/merge 最新 dev，并在平台前置修复进入 base 后，更新文档/PR 描述使依赖关系和实际运行条件明确；如果仍要保持 app-only PR，也请在 README 和 PR body 中说明必须依赖哪个已合入的 AArch64 HVF timer/GIC 修复，并用当前 head 重新给出 macOS/HVF 端到端复现结果。
| "-snapshot", | ||
| "-nographic", | ||
| "-accel", | ||
| "hvf", |
There was a problem hiding this comment.
这里新增的是实际会通过 HVF 运行的 QEMU app 配置，但当前 PR head 没有包含或声明所需的 AArch64 HVF 前置支持：base 里的 non-hv EL1 仍走 CNTP timer，也没有 GICD SPI 跳过/初始化控制。请等对应平台修复进入 dev 后 rebase，并在 README/PR body 中明确该 app 依赖的已合入前置条件；否则这个 runbook 在当前 base 上不能按描述独立复现。
|
这个 PR 的目标已经被 #1333 覆盖并合入 具体原因：
后续如果还需要补充 macOS self-build 文档或脚本细节，建议基于当前 |
2 participants
问题
原 #984 把 macOS HVF self-build app 和若干底层 OS / filesystem / driver interface / platform 改动放在同一个 PR 里，review 反馈认为 app 目标本身可以接受，但底层语义变化需要独立证明和审查。
本 PR 是拆分后的 app-only 版本：只新增 Apple Silicon macOS 上的 StarryOS HVF self-build 复现场景。
修复摘要
新增
apps/starry/macos-selfbuild/，提供从 macOS host 到 StarryOS guest self-build 的完整复现路径：变更范围
本 PR 只包含：
apps/starry/macos-selfbuild/**apps/starry/README.md中的入口说明本 PR 不修改 kernel、filesystem、driver interface、platform 公共语义；也不包含 vendored
fdt-edit、workspace[patch.crates-io]、rsext4/axfs-ng/rdif/mmio/futex/eBPF 等原 #984 中的底层改动。复现方式
brew install qemu e2fsprogs zig llvm git clone https://github.com/yks23/tgoskits.git cd tgoskits git checkout app/starry-macos-selfbuild-only RUST_DIST_SERVER=https://rsproxy.cn \ STARRY_CARGO_REGISTRY_INDEX=sparse+https://rsproxy.cn/index/ \ apps/starry/macos-selfbuild/reproduce.sh成功标志：
本地验证
bash -n apps/starry/macos-selfbuild/*.shsh -n apps/starry/macos-selfbuild/guest-selfbuild.shgit diff --checkcntv-timer/[patch.crates-io]/ vendoredfdt-edit风险
完整 rootfs 构建和 guest self-build 耗时较长，且需要 Apple Silicon macOS + QEMU HVF 环境。CI 上主要覆盖脚本/格式/常规矩阵，完整 self-build 仍以本地 macOS 复现为准。