跳到主要内容

axbuild

路径：scripts/axbuild 类型：库 crate 分层：工具层 / 宿主侧构建与测试基础库 版本：0.3.0-preview.3 文档依据：Cargo.toml、src/lib.rs、src/arceos/mod.rs、src/arceos/build.rs、src/arceos/ostool.rs、src/arceos/config.rs、src/arceos/features.rs、src/axvisor/image/mod.rs、src/axvisor/xtest/mod.rs

axbuild 是当前工作区里承上启下的宿主侧构建基础库。它不属于目标镜像，也不参与内核热路径；它负责把“应用配置、axplat-dyn target/linker 装配、feature 装配、QEMU 参数、产物路径”这些宿主机侧信息整理成可执行的构建/运行计划，并复用 ostool 构建桥接能力。

架构设计​

设计定位​

axbuild 的最上层接口很简洁：

  • lib.rs 只暴露两个子域：arceos 和 axvisor
  • arceos::AxBuild 提供 build()、run_qemu()、test() 这组高层宿主侧动作
  • axvisor 子模块提供镜像管理、QEMU 测试、开发空间与 VM 配置相关工具

这说明 axbuild 不是“一个 CLI”，而是“多个 CLI 共享的构建库”。当前根工作区 tg-xtask、以及 os/axvisor 的宿主侧命令，都是建立在它之上的。

1.2 ArceOS 构建链路​

arceos::build.rs 展现了当前最关键的构建流程：

其中几个实现细节非常关键：

  • prepare_artifacts() 会先解析架构、SMP、内存、feature 等信息。
  • 旧平台配置生成路径已经移除；axplat-dyn 是当前唯一维护的构建路径。
  • PlatformResolver 负责决定动态平台 target、链接参数和构建时环境。
  • is_c_app() 会读取应用 Cargo.toml，通过是否出现 ax-libc 判断这是 C 应用还是 Rust 应用。

因此，axbuild 是把 BuildInfo 配置、feature 链和实际构建链连接起来的中枢。

1.3 feature 装配的真实策略​

axbuild 并不是简单把用户输入的 feature 原样透传给 Cargo，而是做了分层解析：

  • 旧别名和已移除的平台选择项会先被归一化或过滤。
  • 普通能力 feature，例如 fs、net、multitask，会根据应用实际依赖选择 ax-std/、ax-feat/ 或 ax-libc/ 前缀。
  • max_cpu_num > 1 时才注入对应前缀的 smp。

detect_ax_feature_prefix_family() 甚至会通过 cargo metadata 检查应用是否直接依赖 ax-std 或 ax-feat。这一步体现了 axbuild 对真实调用关系的感知，而不是纯字符串拼接。

1.4 宿主环境与目标环境的边界​

src/arceos/ostool.rs 显式构造了目标构建所需的宿主环境变量：

  • AX_ARCH
  • AX_LOG
  • AX_IP
  • AX_GW

同时还会根据 target 选择动态平台 target JSON 和链接脚本参数。由此可以看到：

  • axbuild 本身始终运行在宿主机
  • 它只负责告诉 Cargo 和下游工具“该怎样构建目标”
  • 它并不进入最终镜像，也不会在目标机上运行

1.5 Axvisor 工具子系统​

axbuild::axvisor 不是简单附带模块，而是一套较完整的宿主侧工具集：

  • image：镜像列表、下载、校验、解压、删除、同步
  • xtest：根据架构和 VM 配置自动准备镜像并跑 QEMU 测试
  • 其他模块：构建目录、VM 配置、命令分发、开发空间管理等

这使得 axbuild 同时服务 ArceOS/StarryOS 的统一构建和 Axvisor 的专用宿主工具链。

核心功能​

功能概览​

  • 解析和合并 ArceOS 构建配置。
  • 生成必要的 .qemu.toml 等宿主侧中间产物。
  • 计算模块 feature 与库 feature 的正确装配方式。
  • 调用 ostool 完成 cargo build 或 QEMU 运行。
  • 为 Axvisor 提供镜像管理和 QEMU 测试辅助。

2.2 高层 API​

在 ArceOS 侧，最核心的高层接口是：

  • AxBuild::from_overrides(...)
  • AxBuild::build()
  • AxBuild::run_qemu()
  • AxBuild::test()

这些接口都不直接执行复杂逻辑，而是进一步委托给：

  • Builder
  • QemuRunner
  • FeatureResolver
  • PlatformResolver
  • ostool 桥接模块

2.3 与 tg-xtask 的关系​

tg-xtask 负责用户交互和命令分派，axbuild 负责真正的构建编排。也就是说：

  • tg-xtask 是前台 CLI
  • axbuild 是后台构建库

两者经常一起出现，但职责边界非常明确。

依赖关系​

直接依赖​

  • ostool：真正执行 cargo 构建和 QEMU 运行的底层桥接。
  • cargo_metadata：用于解析工作区和依赖关系。
  • toml、serde、serde_json、schemars：配置读写和结构化数据处理。
  • axvmconfig：Axvisor VM 配置相关工具链依赖。
  • reqwest、flate2、tar、sha2：Axvisor 镜像下载、解压和校验能力。

主要消费者​

  • 根工作区 tg-xtask
  • os/axvisor 宿主侧命令

3.3 间接消费者​

  • ArceOS Rust 应用和 C 应用的构建流程
  • StarryOS 构建/运行流程（通过根 tg-xtask 和 ArceOS 构建能力复用）
  • Axvisor 的镜像测试流程

开发指南​

4.1 适合在这里修改的内容​

  • 宿主侧配置格式与覆写规则
  • feature 计算与平台解析
  • 中间产物生成逻辑
  • QEMU 配置拼装
  • Axvisor 宿主侧镜像与测试工具

注意事项​

  1. 不要把目标机运行时代码放进 axbuild，它必须保持宿主侧纯工具属性。
  2. 改 feature 逻辑时，要同时检查 FeatureResolver 与 ostool::build_features()。
  3. 改平台解析逻辑时，要一起检查 Cargo metadata 查找路径和链接脚本参数生成。
  4. C 应用与 Rust 应用的分流依赖 is_c_app()，相关逻辑改动要谨慎。

4.3 推荐验证路径​

  • 先跑单元测试，确认 feature、QEMU 参数和配置推导逻辑不回归。
  • 再做一次最小 ArceOS 构建，确认动态平台 target、链接参数和运行时平台路径能正确装配。
  • 涉及 QEMU 行为时，再做一次宿主侧运行验证。
  • 改 Axvisor 相关模块时，还应验证镜像下载或 xtest 流程。

测试​

测试覆盖​

axbuild 已有较多宿主侧单元测试，主要分布在：

  • src/arceos/build.rs
  • src/arceos/features.rs
  • src/arceos/ostool.rs
  • src/axvisor/image/spec.rs

5.2 已覆盖的重点​

  • feature 解析与合并
  • SMP、默认 target 和动态平台构建配置推导
  • QEMU 默认参数构造
  • .qemu.toml 生成条件
  • Axvisor 镜像规格解析

5.3 建议继续加强的点​

  • 旧平台选择请求被拒绝时的错误路径
  • 动态平台链接参数探测失败时的诊断信息
  • is_c_app() 对不同应用布局的识别
  • Axvisor 镜像下载和解压的更细粒度测试

5.4 高风险改动​

  • feature 前缀探测逻辑
  • 平台配置路径探测
  • 构建环境变量与链接参数生成
  • QEMU 测试自动化链路

跨项目定位​

ArceOS​

对 ArceOS 来说，axbuild 是宿主侧构建总控：它把配置文件、axplat-dyn 构建装配、feature 装配、产物输出和 QEMU 运行串成一条一致的工具链。

StarryOS​

StarryOS 通过根工作区的命令系统复用 axbuild 的 ArceOS 构建能力，因此它在 StarryOS 中承担的是“共享构建后端”角色，而不是 StarryOS 私有逻辑。

Axvisor​

对 Axvisor 来说，axbuild 不只是通用构建库，还包含镜像下载和 xtest 等专用宿主工具模块。因此它在 Axvisor 侧既是公共基础设施，也是专用开发工具库，但始终停留在宿主机边界之外。