fix(axbuild): improve qemu and rootfs robustness on macOS

[pengzechen]

在 macOS 本地执行 ArceOS/Starry 流程时，存在多处环境相关失败：首次缺失 ArceOS build 配置会直接报错；未显式传入 qemu 配置时无法提前生成 runtime disk；部分主机缺少 rust-objcopy、mkfs.fat、debugfs 导致流程中断。

变更：

ArceOS build 模式加载前自动确保 build 配置存在，避免首次运行读取失败。
ArceOS qemu 流程增强 runtime disk 处理：
支持展开 ${workspace} 路径占位符。
未显式传入 qemu 配置时，回退读取包目录默认 qemu-.toml。
缺少 truncate 时使用文件长度方式创建镜像；缺少 mkfs.fat 时降级为 raw 文件并告警。 QEMU 运行前补齐 rust-objcopy 可发现路径：
若 PATH 中缺失 rust-objcopy，自动尝试注入当前 Rust toolchain rustlib bin 目录。 Starry rootfs 注入流程增强：
当系统无 debugfs 时跳过注入并输出 warning，不再中断 rootfs 准备。

[ZR233]

本次审查覆盖了 PR 元数据、当前 head、既有 review 线程、CI 状态、隔离 worktree diff、base 分支实现和相关 open PR 搜索。PR 主要改动 axbuild 的 ArceOS 默认 QEMU 配置读取、runtime disk 准备、rust-objcopy PATH 补齐，以及 Starry rootfs 在缺少 debugfs 时的降级路径。

阻塞问题：ArceOS QEMU 的新增默认 qemu-.toml 回退只把 QemuConfig 读出来，没有让同一个配置文件里的 runner-side 附属字段继续参与后续流程。start_qemu_host_http_server(&request) 仍然只看显式传入的 request.qemu_config，所以默认配置中的 [host_http_server] 会被跳过。apps/arceos/httpclient/qemu-x86_64.toml 就包含该字段；我在当前 head 上运行 cargo xtask arceos qemu -p arceos-httpclient --arch x86_64 时没有启动 host http server，随后 guest 连接 10.0.2.2:18080 失败并触发 panic。显式传入 --qemu-config apps/arceos/httpclient/qemu-x86_64.toml 时会打印 host http server: 127.0.0.1:18080，说明差异来自默认配置路径没有被同等用于附属配置处理。请让默认解析出的 qemu 配置路径也被 host_http_server 等额外配置消费，或把 load_qemu_config 的返回结构调整为同时携带配置内容和来源路径，并补充覆盖该默认路径的回归测试。

本地验证：cargo fmt --check 通过；cargo xtask clippy --package axbuild 通过；cargo xtask arceos qemu -p arceos-httpclient --arch x86_64 复现上述默认路径问题。CI 当前 head 60c4bd3d24e29e0ae91e57e73e0e52b0203a2dd7 上主要 run_host/run_container 检查多项通过，Test starry x86_64 qemu / run_container 查询时仍为 pending，旧的取消 run 不作为当前结论依据。

重复/重叠分析：base 分支已有显式 qemu config 的 host_http_server 处理，但没有本 PR 新增的默认 qemu-.toml 回退；搜索 open PR 的 axbuild/qemu/rootfs/macOS/rust-objcopy/mkfs.fat/debugfs/host_http_server/default qemu config 相关关键词，没有发现重复或可替代实现。既有 review 线程为空，未处理合并冲突，当前 PR 为 UNSTABLE 且 maintainerCanModify=false。

[mai-team-app]

本次审查覆盖了 PR 元数据、变更文件、CI 状态、既有 review 线程、本地验证和重复/重叠分析。

审查概述

PR 主要改动 axbuild 的四个文件，目标是增强 macOS 上的 QEMU 和 rootfs 鲁棒性：

1. arceos/build.rs：自动确保 build 配置存在
2. arceos/mod.rs：默认 qemu-.toml 回退、runtime disk 降级处理、${workspace} 路径展开
3. context/mod.rs：rust-objcopy PATH 自动补齐
4. starry/rootfs.rs：debugfs 缺失时跳过注入并告警

阻塞问题

默认 qemu 配置的 host_http_server 不生效

load_qemu_config 中新增的默认 qemu-<arch>.toml 回退逻辑正确读取了 QemuConfig，但该默认配置路径并未回写至 request.qemu_config。后续 start_qemu_host_http_server（第 158-169 行）仍然只读取 request.qemu_config，当用户未显式传入 --qemu-config 时该字段为 None，导致默认配置中的 [host_http_server] 段被完全跳过。

以 apps/arceos/httpclient/qemu-x86_64.toml 为例：该文件包含 [host_http_server] 配置，运行 cargo xtask arceos qemu -p arceos-httpclient --arch x86_64 时 guest 会因 HTTP server 未启动而失败；显式传入 --qemu-config apps/arceos/httpclient/qemu-x86_64.toml 则正常。

修复方向：让默认解析出的 qemu 配置路径也被 start_qemu_host_http_server 消费。可以考虑：(a) 在 load_qemu_config 内部将默认解析路径回填到 request（需要传递可变引用），或 (b) 将 load_qemu_config 的返回结构调整为同时携带配置内容和来源路径，或 (c) 在 run_qemu_request_with_cargo 中额外记录默认配置路径并传递给 host_http_server 启动逻辑。同时建议添加覆盖默认路径 host_http_server 行为的回归测试。

此问题与 ZR233 在先前的 review 中指出的问题一致，当前 PR head 尚未修复。

代码质量观察

• arceos/mod.rs 中的 command_exists 与 context/mod.rs 中的 is_command_in_path 具有完全相同的实现，建议提取为 crate 内的公共工具函数以减少重复。

本地验证结果

检查项	结果
cargo fmt --check	✅ 通过
cargo clippy --manifest-path scripts/axbuild/Cargo.toml --all-features -- -D warnings	✅ 通过
cargo test --manifest-path scripts/axbuild/Cargo.toml --all-features	630 passed, 1 failed (预存问题)

失败的测试 build::tests::checked_in_build_configs_do_not_declare_default_dynamic_builds 在 base 分支（dev）上同样失败，属于 PR 变更范围外的预存问题，不阻塞合入。

CI 状态

当前 head 60c4bd3d 的 CI 检查中：

• success: Detect changed paths, Run clippy / run_host, Test with std / run_host, Test arceos loongarch64 qemu / run_host, Test starry self-hosted board licheerv-nano-sg2002 / run_host
• skipped: 多项 matrix/path-filter 跳过的检查，属于预期行为

无 PR 相关的 CI 失败。

重复/重叠分析

• 在 base 分支搜索了 axbuild/qemu/rootfs/rust-objcopy/mkfs.fat/debugfs/default qemu config 相关实现，未发现已有等效功能。
• 审查了当前 open PR 列表（#984, #1223 等），未发现与本 PR 重叠或冲突的改动。
• 结论：PR 是独立的新功能增强，不与其他 PR 重复。

Powered by deepseek-v4-pro

[mai-team-app]

审查概述

PR 共两次提交，修改 scripts/axbuild/src/ 下 6 个文件（+270/-32），目标增强 macOS 上 ArceOS/Starry 构建工具的鲁棒性。

变更内容

1. ArceOS build 配置自动创建（arceos/build.rs）：加载 build mode 前调用 ensure_build_info，避免首次运行时缺失配置文件直接报错。

2. 默认 QEMU 配置回退（arceos/mod.rs）：未显式传入 --qemu-config 时，自动查找包目录下的 qemu-<arch>.toml 作为默认配置。LoadedQemuConfig 结构同时携带 config 和 config_path，调用链中所有 QEMU 启动路径均已接入。

3. ${workspace} 路径占位符展开（arceos/mod.rs）：expand_workspace_path 支持 QEMU 磁盘路径中的 ${workspace} 占位符，便于跨环境复用配置。

4. Runtime disk 降级处理（arceos/mod.rs）：

   • 无 truncate 时使用 File::set_len 创建镜像
   • 无 mkfs.fat 时降级为 raw 文件并告警
   • parse_size_to_bytes 支持 B/K/M/G 等常见大小后缀

5. rust-objcopy PATH 自动补齐（context/mod.rs）：scoped_qemu_path 中新增 configure_rust_objcopy_path，通过 rustc --print sysroot 推导 Rust toolchain 的 rustlib/<host>/bin 目录并注入 PATH。

6. Starry rootfs debugfs 降级（starry/rootfs.rs）：ensure_apk_region_in_rootfs 在无 debugfs 时跳过注入并打印 warning，不再中断 rootfs 准备流程。

前一 review 阻塞问题的修复验证

ZR233 和 mai-team-app 在 commit 60c4bd3 上指出的阻塞问题（默认 qemu 配置的 [host_http_server] 不生效）已在 commit bd1aa27 中修复：

• 新增 LoadedQemuConfig { config, config_path } 结构，load_qemu_config 返回时保留默认配置的来源路径。
• start_qemu_host_http_server 新增 qemu_config_path 参数，通过 request.qemu_config.as_deref().or(qemu_config_path) 同时消费显式和默认配置路径。
• 所有调用方（run_qemu_request_with_cargo、run_c_app_qemu_request_with_cargo、qemu_with_explicit_rootfs、prepare_rust_qemu_cases）均传递 loaded_qemu.config_path.as_deref()。
• 新增测试 qemu_request_starts_host_http_server_from_fallback_qemu_config_path 覆盖默认路径 host_http_server 场景。
• 2 个相关 review thread 已在当前 head 上确认修复后完成 resolve。

本地验证

检查项	结果
cargo fmt --check	✅ 通过
cargo clippy --manifest-path scripts/axbuild/Cargo.toml --all-features -- -D warnings	✅ 通过
cargo test --manifest-path scripts/axbuild/Cargo.toml --all-features	631 passed, 1 failed（预存问题）

build::tests::checked_in_build_configs_do_not_declare_default_dynamic_builds 在本 PR 和 base dev 分支上均失败，属于 PR 变更范围外的预存问题，不阻塞合入。

CI 状态

当前 head bd1aa27 的 CI workflow（run #27356742691）结论为 success：

• success: Check formatting / run_host, Run sync-lint / run_container, Test with std / run_host, Test arceos x86_64 qemu / run_host, Test arceos aarch64 qemu / run_host, Test arceos loongarch64 qemu / run_host, Test starry x86_64 qemu / run_container, Test starry loongarch64 qemu / run_container, Test starry aarch64 qemu / run_container, Test axvisor riscv64 qemu / run_host, Test axvisor aarch64 qemu / run_host, Test axvisor self-hosted x86_64 / run_host, Test axvisor x86_64 svm hosted / run_host, Test axvisor self-hosted board orangepi-5-plus-linux / run_host, Test axvisor self-hosted board roc-rk3568-pc-linux / run_host, Test starry self-hosted board orangepi-5-plus / run_host, Test starry self-hosted board licheerv-nano-sg2002 / run_host, Test axvisor self-hosted x86_64 UEFI / run_host
• skipped: 多项 matrix/path-filter 跳过的检查（run_host 与 run_container 互斥、branch-restricted publish、path-filter 跳过的架构），属于预期行为
• failure: 无

无 PR 相关的 CI 失败。

代码质量观察（非阻塞）

• arceos/mod.rs 中的 command_exists 与 context/mod.rs 中的 is_command_in_path 实现完全相同，建议后续提取为 crate 内公共工具函数以减少代码重复。

重复/重叠分析

• 在 base dev 分支搜索 parse_size_to_bytes、command_exists、expand_workspace_path、debugfs_available、configure_rust_objcopy_path 等函数，未发现已有等效实现。
• 搜索 open PR 中 axbuild/qemu/rootfs/macOS/rust-objcopy/mkfs.fat/debugfs/default qemu config 相关关键词，未发现与本 PR 重叠或冲突的改动（#984 为 macOS HVF self-build 文档，#1232 为 kmod 支持，均不冲突）。
• 未发现 [patch.crates-io] 覆盖。

结论

本 PR 解决了 macOS 环境下 axbuild 工具链的多处鲁棒性问题，前一 review 的阻塞问题已完整修复，本地格式/clippy/测试验证通过，CI 全部相关检查通过，无 overlap 或冲突。批准合入。

Powered by deepseek-v4-pro

[ZR233]

本次审查覆盖当前 head bd1aa27e2db5fb44a785da2cea9856ba343e969b、PR diff、既有 review 线程、CI、隔离 worktree 本地验证，以及相关 open PR 重叠搜索。PR 主要修改 axbuild 的 ArceOS 默认 QEMU 配置读取、runtime disk 准备、rust-objcopy PATH 补齐，以及 Starry rootfs 在缺少 debugfs 时的降级路径。

结论：暂不建议合入，需要先处理两个阻塞问题（已留 inline 评论）。

检查清单：

• ✅ PR 范围与标题：fix(axbuild): improve qemu and rootfs robustness on macOS 与主要改动范围一致。
• ✅ 既有线程：之前默认 qemu-<arch>.toml 的 [host_http_server] 线程已在当前实现中通过 LoadedQemuConfig.config_path 修复，相关线程已 resolve。
• ✅ 合并状态：GitHub 当前显示 mergeable=MERGEABLE，未发现当前 base 上的合并冲突。
• ✅ CI：当前 run 27356742691 的格式化、clippy、ArceOS/Starry/Axvisor 相关检查均通过；旧 run 27356736120 的 Detect changed paths fail 属于 stale/canceled 轮次，不作为当前 head 失败依据。
• ✅ 本地基础验证：cargo fmt --check 通过；cargo xtask clippy --package axbuild 通过；cargo xtask arceos test qemu --list --arch x86_64 通过；正常 PATH 下 cargo xtask arceos test qemu --arch x86_64 -g rust -c fs-basic 通过。
• ❌ 阻塞：缺少 mkfs.fat 时现在只生成 unformatted raw disk，但 fs-basic 会在 guest 侧找不到文件系统后 panic；这不是可用降级。
• ❌ 阻塞：rust-objcopy PATH 补齐只发生在 scoped_qemu_path() 中，无法覆盖在 QEMU 前先调用 prepare_elf_artifact(..., qemu.to_bin) 的 C app/C test 路径；隐藏 PATH 中的 rust-objcopy 后可复现 No such file or directory (os error 2)。
• ✅ 重复/重叠分析：base 分支没有等效的 configure_rust_objcopy_path、${workspace} 展开或默认 QEMU config fallback。open PR 搜索覆盖 axbuild qemu macOS、rust-objcopy、mkfs.fat、debugfs axbuild rootfs、host_http_server default qemu、qemu config fallback；除 #1231 外，命中项主要是 Starry app/test、文档、自编译或平台接入。#1135 也碰 scripts/axbuild/src/context/mod.rs/arceos/mod.rs，但内容是 ostool invocation/API 调整和 Axvisor/NUC 接入，不是本 PR 的 macOS robustness 修复；当前 PR 仍显示可 merge。
• ✅ Reviewer：讨论 #594 中 axbuild、测试、发行版/rootfs 方向与当前已请求的 ZCShou、luodeb 匹配，未额外调整 reviewer。

[ZR233]

这里不能只 warning 后继续使用未格式化的 raw disk。当前 ArceOS runtime disk 的使用方（例如 test-suit/arceos/rust/qemu-x86_64.toml 的 fs-basic）依赖 guest 能识别到 FAT32 文件系统；在隐藏 mkfs.fat 但保留 truncate/rust-objcopy/QEMU 的环境里运行 cargo xtask arceos test qemu --arch x86_64 -g rust -c fs-basic，这里会生成全零 raw image，启动后日志显示 No supported filesystem found in partitions.，随后 fs-basic 访问 root fs 时 panic。也就是说缺少 mkfs.fat 时不是可用降级，而是把原本的早期失败推迟成 guest 侧失败。

建议这里继续返回明确错误，或者在没有 mkfs.fat 时用一个能在目标环境可用的方式实际写入 FAT32；同时补一个隐藏 mkfs.fat 的回归覆盖，避免后续误认为 unformatted raw 可以支撑 disk.img runtime asset。

[ZR233]

把 rust-objcopy 的 PATH 补齐放在 scoped_qemu_path() 里只覆盖了 qemu()/run_qemu() 这类会先进入该路径 guard 的流程，但还有 prepare_elf_artifact(..., qemu.to_bin) 在 run_prepared_qemu() 之前调用，例如 ArceOS C app 和 C test 路径（arceos/mod.rs、arceos/test.rs）。这些路径在真正进入 QEMU 前就已经需要执行 rust-objcopy，因此仍然会在 macOS/精简 PATH 场景下失败。

我用一个只暴露 rust-lld、不暴露 rust-objcopy，但 Rust sysroot 里实际存在 rust-objcopy 的 PATH 复现了这一点：cargo xtask arceos test qemu --arch riscv64 -g c -c mem 可以完成编译链接，但在 prepare_elf_artifact 执行 rust-objcopy --binary-architecture=... 时返回 No such file or directory (os error 2)。建议把这个 PATH 修复提升到所有 prepare_elf_artifact 之前都会执行的位置，或让 prepare_elf_artifact 自身做同样的工具路径解析，并补上 C/to_bin 路径的回归测试。

[ZR233]

按本轮开放 PR 维护标准关闭。

• 当前 head：bd1aa27e2db5fb44a785da2cea9856ba343e969b
• 最后一次代码提交：2026-06-11T15:07:53Z
• 当前合并状态：CONFLICTING / DIRTY
• 一个月未更新的判断截止线：2026-07-07T00:00:00Z

截至本次清理，该分支已超过一个月没有代码提交，并且当前与 dev 存在合并冲突，因此不再保留为活动 PR。此次关闭不表示该 PR 的全部改动已经由 dev 覆盖。若仍需继续，请先基于最新 dev 重新整理改动并解决冲突，再重新打开或提交范围清晰的新 PR。