22sidebar_position : 1
33---
44
5- # ** Cargo xtask 构建系统**
5+ # 构建系统
66
77## 简介
88
99- ** 位置** : ` xtask/ ` 是本仓库用于组织辅助构建、运行与工具命令的子命令二进制。主入口在 ` xtask/src/main.rs ` 。
1010
11- ** 概览** :
12-
1311- ** 用途** : ` cargo xtask ` 提供一个简单的、以仓库为中心的构建与运行工具集,用来封装常用的 build、qemu 启动、uboot 构建、clippy 检查等操作。
1412- ** 原理** : 使用一个单独的二进制(` xtask ` ),通过 clap 解析子命令并调用仓库内部实现(例如在 ` xtask/src/cargo.rs ` 中的 ` run_qemu ` )。这样可以避免在 CI/开发机器上写大量 shell 脚本,同时将仓库特定的逻辑用 Rust 实现并纳入版本控制。
1513
@@ -36,18 +34,18 @@ sidebar_position: 1
3634 3 . 生成一个默认 QEMU 配置文件路径(例如 ` .qemu-aarch64.toml ` )。如果该文件不存在,会从 ` scripts/ostool/qemu-aarch64.toml ` 复制过去。
3735 4 . 构造 ` CargoRunnerKind::Qemu ` 并调用 ` self.ctx.cargo_run(&build_config, &kind).await ` ,交由 ` ostool ` 执行具体的 cargo 运行 / 启动 qemu 流程。
3836
39- ### ** 影响 ** :
37+ ## 影响
4038
4139- 虽然 ` QemuArgs ` 声明了 ` --build-config ` 和 ` --qemu-config ` ,` main.rs ` 当前实现并没有把它们传递给 ` Context ` 。因此,实际 ` cargo xtask qemu ` 会依赖仓库根的 ` .build.toml ` (或使用 ` cargo xtask defconfig ` 预先设置),并自动创建 ` .qemu-<arch>.toml ` 。
4240- QEMU 的具体行为依赖 ` ostool ` 的 ` CargoRunnerKind::Qemu ` 实现以及 ` scripts/ostool/qemu-*.toml ` 模板。
4341
44- ### ** 前置条件** :
42+ ## 前置条件
4543
4644- Rust toolchain(与仓库 ` rust-toolchain.toml ` 一致)。
4745- 系统安装 QEMU(例如 ` qemu-system-aarch64 ` )以便 ` ostool ` 能够启动模拟器。
4846- 在第一次运行 ` qemu ` 之前,最好通过 ` cargo xtask defconfig <board> ` 初始化 ` .build.toml ` ,或者手工创建 ` .build.toml ` 并确保 ` target ` 字段正确(例如包含 ` aarch64- ` )。
4947
50- ## ** 快速上手** :
48+ ## 快速上手
5149
52501 . 设置默认 board(示例使用 qemu-aarch64):
5351
@@ -71,7 +69,7 @@ cargo xtask qemu --vmconfigs configs/vms/arceos-aarch64-qemu-smp1.toml
7169 - ` --vmconfigs ` 接受一个或多个 VM 名称(与仓库 ` configs/vms/ ` 下的 TOML 文件名对应,但不一定要带路径)。
7270 - 运行时,xtask 会根据 ` .build.toml ` 决定 target,自动创建 ` .qemu-<arch>.toml ` (若缺失),并通过 ` ostool ` 的 cargo runner 启动 QEMU。
7371
74- ## ** 完整示例:从 0 到启动**
72+ ## 完整示例:从 0 到启动
7573
76741 ) 进入仓库根目录:
7775
@@ -104,12 +102,12 @@ cargo xtask qemu --vmconfigs configs/vms/arceos-aarch64-qemu-smp1.toml
104102cargo xtask qemu --vmconfigs configs/vms/arceos-aarch64-qemu-smp1.toml; configs/vms/linux-aarch64-qemu-smp1.toml
105103```
106104
107- ### ** 调试与常见问题** :
105+ ## 调试与常见问题
108106
109107- 如果 ` cargo xtask qemu ` 提示找不到 ` .build.toml ` 或 target 不支持,请先运行 ` cargo xtask defconfig <board> ` 。
110108- 若 QEMU 无法启动,检查本机是否安装了相应的 QEMU 二进制(例如 ` qemu-system-aarch64 ` )并在 PATH 中可用。
111109- 想要自定义 qemu 配置文件,可在仓库根创建 ` .qemu-aarch64.toml ` (xtask 会优先使用它;若不存在则从 ` scripts/ostool/qemu-aarch64.toml ` 复制模板)。
112110
113- ### ** 注意 ** :
111+ ## 注意
114112
115113- 本仓库把与执行相关的细节抽象到 ` xtask ` (Rust 二进制)和 ` ostool ` (工具运行器)中,方便在 CI 与本地开发环境中复用。若需要不同的 CLI 行为(例如传递自定义 ` --qemu-config ` 到 ` run_qemu ` ),可以在 ` xtask/src/main.rs ` 中将参数传递到 ` Context ` 并在 ` xtask/src/cargo.rs ` 中使用这些路径(当前 ` qemu ` 分支未直接使用 ` QemuArgs.build_config ` / ` qemu_config ` )。
0 commit comments