Skip to content

Commit 29d0759

Browse files
committed
docs(build): 更新构建系统文档,调整标题格式并简化内容
1 parent 7bd7189 commit 29d0759

File tree

1 file changed

+7
-9
lines changed

1 file changed

+7
-9
lines changed

docs/design/build.md

Lines changed: 7 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,12 @@
22
sidebar_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

5250
1. 设置默认 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

7674
1) 进入仓库根目录:
7775

@@ -104,12 +102,12 @@ cargo xtask qemu --vmconfigs configs/vms/arceos-aarch64-qemu-smp1.toml
104102
cargo 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

Comments
 (0)