命令索引

所有命令由 scripts/axbuild 实现，通过 cargo xtask 统一入口调用。本文是完整的命令参考：列出每个 cargo xtask 顶层命令及其全部子命令、参数和用法示例，并提供到详细原理文档的链接。

1. 调用方式

默认调用方式为 cargo xtask <cmd>，经 tg-xtask 包转发到 axbuild::run()：

cargo xtask <cmd>  →  cargo run -p tg-xtask -- <cmd>  →  axbuild::run()

.cargo/config.toml 中预配置了以下别名，使命令更简洁：

完整命令	别名
`cargo xtask arceos ...`	`cargo arceos ...`
`cargo xtask starry ...`	`cargo starry ...`
`cargo xtask axvisor ...`	`cargo axvisor ...`
`cargo xtask board ...`	`cargo board ...`

两种写法等价：

cargo xtask arceos qemu --package arceos-httpserver
cargo arceos qemu --package arceos-httpserver   # 同上

2. 顶层命令

cargo xtask 的顶层命令（与 tg-xtask --help 输出一致），按职能分组：

命令	说明	详细文档
代码质量检查
`cargo xtask test`	workspace std 白名单测试	Std 白名单测试
`cargo xtask ktest`	在 QEMU 或板卡运行 harness=false 内核 axtest	内核测试
`cargo xtask clippy`	workspace clippy（feature × target 矩阵）	Clippy 检查
`cargo xtask sync-lint`	可疑 `Relaxed` 原子序检查	Sync Lint
`cargo xtask lock-lint`	统一锁依赖与 runtime provider 边界检查	Lock Lint
辅助工具
`cargo xtask board`	远程板卡管理（ls/connect/config）	板卡管理
`cargo xtask backtrace`	host 端 backtrace 符号化	Backtrace 符号化
`cargo xtask image`	TGOS rootfs/guest 镜像管理	镜像管理
`cargo xtask ovmf`	获取经校验的 OVMF CODE/VARS 路径	本节
`cargo xtask axloader`	UEFI bootloader 构建与 HTTP smoke 测试	Axloader
`cargo xtask agent-review-bench`	历史 PR 快照的离线 review benchmark	Review Benchmark
OS 子系统
`cargo xtask arceos`	ArceOS 构建/运行/测试	ArceOS
`cargo xtask starry`	StarryOS 构建/运行/测试/app/perf/kmod	StarryOS
`cargo xtask axvisor`	Axvisor 构建/运行/测试（含 `test uboot`）	Axvisor

通用的参数解析、Snapshot、Build Info、feature 校验和 QEMU to_bin 契约见参数与配置；三套系统共享的 QEMU/板卡测试编排（用例发现、build wrapper、pipeline 类型、rootfs 缓存、grouped runner）见测试基础设施；CI 自动化见自动 CI 测试。

3. 质量检查

3.1 标准测试

对 scripts/test/std_crates.csv 白名单中的每个 crate 执行 cargo test -p <package>。无参数。

cargo xtask test

详见 Std 白名单测试。

3.2 内核测试

构建并运行确实依赖 QEMU/板卡的 harness = false Cargo 集成 axtest target；宿主可运行的测试应使用普通 #[test] 和 cargo xtask test。无参数时从 Cargo metadata 选择所有直接声明 workspace axtest dev-dependency 的 package；--workspace、可重复 -p/--package、--exclude、--test 与构建参数采用 Cargo 风格。--arch 会过滤到支持该架构的执行单元，每个 test bin 独立构建并启动一次 QEMU。

cargo xtask ktest qemu --workspace --arch x86_64
cargo xtask ktest qemu -p starry-kernel --test axtest_kernel --arch x86_64
cargo xtask ktest board -p arceos-axtest-sg2002-usb-msc --test axtest -b aka-00-sg2002

详见内核测试。

3.3 Clippy 检查

对 workspace 包按 feature × target 矩阵执行 clippy。三种模式互斥：--all 或无参数 = 全量；--package = 显式；--since = 增量。

参数	说明
`--all`	审计全部 workspace 包
`--package <PACKAGE>`（可重复）	仅检查指定的 workspace 包
`--since <REF>`	仅检查自 git ref 以来变更及受影响的包

cargo xtask clippy                         # 全量（CI 默认）
cargo xtask clippy --package axcpu
cargo xtask clippy --since origin/main

详见 Clippy 检查。

3.4 并发检查

用 syn 识别可疑的 Relaxed 原子序同步模式。

参数	说明
`--since <REF>`	仅检查自 git ref 以来变更的 Rust 文件（省略则全量）

cargo xtask sync-lint                     # 全量（CI 默认）
cargo xtask sync-lint --since origin/main # 增量

详见 Sync Lint。

3.5 依赖检查

守护统一锁边界，禁止已移除锁 crate、第一方直接 spin、Starry/Axvisor facade 绕过和重复 runtime provider。无参数。

cargo xtask lock-lint

详见 Lock Lint。

4. 工程工具

4.1 板卡管理

远程板卡管理，通过 ostool-server 交互。

子命令	用法	说明
`ls`	`board ls [--server <H>] [--port <P>]`	列出可用板卡类型
`connect`	`board connect -b <TYPE> [--server <H>] [--port <P>] [--session-file <REL=LOCAL>...]`	分配板卡并连接串口，可上传一次性会话文件
`config`	`board config`	编辑板卡服务器配置

详见板卡管理。

4.2 回溯符号化

从日志中提取并符号化 BACKTRACE_BEGIN/BT/BACKTRACE_END 块。

cargo xtask backtrace symbolize --elf <PATH> [--log <PATH>] [--kind <KIND>] [--adjust-ip <BOOL>] [--ip-bias <I64>]

参数	默认	说明
`--elf <PATH>`	必填	用于符号化的 ELF（必须保留 debug info）
`--log <PATH>`	stdin	输入日志路径，省略则读 stdin
`--kind <KIND>`	自动	仅符号化匹配的块 kind
`--adjust-ip <BOOL>`	`true`	符号化前 `ip -= 1`（call-site 调整）
`--ip-bias <I64>`	`0`	符号化前对 `ip` 施加有符号偏移（地址 slide）

cargo xtask backtrace symbolize --elf target/x86_64/debug/arceos-httpserver --log qemu.log

详见 Backtrace 符号化。

4.3 镜像管理

TGOS rootfs/guest 镜像管理。全局选项（所有子命令可用）：-R/--registry <URL>、-D/--download-dir <PATH>、-E/--extract-dir <PATH>。

子命令	用法	说明
`ls`	`image ls [-v] [PATTERN]`	列出注册表镜像（`-v` 详情，`PATTERN` 正则过滤）
`pull`	`image pull [<IMAGE>] [--arch <ARCH>] [--no-extract]`	拉取镜像并校验 SHA-256
`resize`	`image resize <IMAGE> --size-mib <MIB> [-o <OUT>]`	扩容 ext rootfs（不支持缩容）
`check`	`image check <IMAGE> [--sha256 <HASH>]`	输出并可选校验本地镜像 SHA-256

pull 的 <IMAGE> 可选带 :version（如 rootfs-riscv64-alpine.img:0.0.11）；省略时配合 --arch 拉取该架构默认 rootfs。

详见镜像管理。

4.4 OVMF 固件

通过 Ostool 的固定版本、镜像探测和 SHA-256 校验流程准备 OVMF，并在 stdout 输出一个仅包含 code、vars 路径的 JSON 对象：

cargo xtask ovmf --arch x86_64
TGOS_OVMF_DIR=/path/to/cache cargo xtask ovmf --arch aarch64

--arch 支持 x86_64、aarch64、riscv64、loongarch64 和 ia32。默认缓存根目录为 $TMPDIR/ostool/ovmf；TGOS_OVMF_DIR 只覆盖缓存根目录，不绕过版本选择和校验。

4.5 UEFI 引导

UEFI bootloader（axloader）构建与 HTTP smoke 测试。

子命令	用法	说明
`build`	`axloader build [--target <T>] [--release\|--debug]`	编译（默认 `x86_64-unknown-uefi`，默认 release）
`test qemu`	`axloader test qemu [--target <T>]`	host 单测 + QEMU HTTP smoke test

详见 Axloader。

4.6 Review Benchmark

离线回放 scripts/agent-review-bench/cases/*.toml 中登记的历史 PR 快照，并对 review findings 评分。该命令面向维护 benchmark，而非日常构建：

cargo xtask agent-review-bench list
cargo xtask agent-review-bench check
cargo xtask agent-review-bench run --case <id> --agent codex --min-recall 80

详见 Review Benchmark。

5. ArceOS 命令

cargo xtask arceos 的全部子命令。详细原理见 ArceOS 概述、构建、运行、测试。

通用参数（build / qemu / uboot / board）：

参数	说明
`-c/--config <CONFIG>`	显式 Build Info 路径
`-p/--package <PACKAGE>`	ArceOS app 包名（必需）
`--arch <ARCH>`	目标架构，默认 `aarch64`
`-t/--target <TARGET>`	target triple
`--smp <CPUS>`	CPU 核数
`--debug`	debug 构建

子命令	说明
`build`	编译 ArceOS app
`qemu`	编译并在 QEMU 中运行
`uboot`	编译并通过 U-Boot 运行
`board`	编译并在远程板卡运行
`test qemu`	QEMU 测试套件（Rust + C）
`test board`	板级测试套件
`defconfig <BOARD>`	生成默认板卡配置
`config ls`	列出可用板卡名称

各运行目标的额外参数：

子命令	额外参数
`qemu`	`--qemu-config <PATH>`、`--rootfs <IMAGE>`
`uboot`	`--uboot-config <PATH>`
`board`	`--board-config <PATH>`、`-b/--board-type <TYPE>`、`--server <HOST>`、`--port <PORT>`

测试子命令：

子命令	用法
`test qemu`	`[--arch \| -t/--target \| --list] [-g/--test-group <G>] [-c/--test-case <C>] [--no-symbolize] [--keep-qemu-log]`（三选一）
`test board`	`[-c/--test-case <C>] [--board <B>] [-b/--board-type <T>] [--server <H>] [--port <P>] [--list]`

ArceOS Build Config 通过 features、log、max_cpu_num 与 [env] 描述构建能力；BuildInfo::validate_features() 验证输入，构建命令输出 ELF，QEMU TOML 的 to_bin 决定运行阶段是否准备 BIN。

cargo xtask arceos build --package arceos-helloworld --arch aarch64
cargo xtask arceos qemu  --package arceos-httpserver
cargo xtask arceos test qemu --arch riscv64 -g rust -c task-yield

6. StarryOS 命令

cargo xtask starry 的全部子命令，命令面最广。详细原理见 StarryOS 概述、构建、运行、测试、应用运行、性能剖析、内核模块、rootfs 准备。

通用参数（build / qemu / uboot / board）：

参数	说明
`-c/--config <CONFIG>`	显式 Build Info 路径
`--arch <ARCH>`	目标架构，默认 `riscv64`
`-t/--target <TARGET>`	target triple
`--smp <CPUS>`	CPU 核数
`--debug`	debug 构建

子命令	说明
`build`	编译整个 StarryOS 内核
`qemu`	编译并在 QEMU 中运行（含 rootfs 准备）
`uboot`	编译并通过 U-Boot 运行
`board`	编译并在远程板卡运行
`test qemu` / `test board`	QEMU / 板级测试
`app list` / `app qemu` / `app board`	`apps/starry/` 应用运行
`perf`	qperf 性能剖析
`kmod build`	编译内核模块
`rootfs`	准备默认 managed rootfs
`defconfig <BOARD>` / `config ls`	板卡配置
`quick-start ...`	兼容便捷入口

各运行目标的额外参数：

子命令	额外参数
`qemu`	`--qemu-config <PATH>`、`--rootfs <IMAGE>`
`uboot`	`--uboot-config <PATH>`
`board`	`--board-config <PATH>`、`-b/--board-type <TYPE>`、`--server <HOST>`、`--port <PORT>`

测试子命令：

子命令	用法
`test qemu`	`[--arch \| -t/--target \| --list] [-c/--test-case <C>]`
`test board`	`[-c/--test-case <C>] [--board <B>] [-b/--board-type <T>] [--server <H>] [--port <P>] [--list]`

应用运行（app）：

子命令	用法	关键参数
`app list`	`app list [--kind qemu\|board]`	—
`app qemu`	`app qemu [--all] [-t <CASE>] [--cap <CAP>...] [--arch <A>] [--qemu-config <P>] [--debug]`	`--all` 跑全部；`--cap` 声明能力
`app board`	`app board -t <CASE> [--board-config <P>] [-b <T>] [--server <H>] [--port <P>] [--debug] [--linux-stage]`	`-t` 必需

性能剖析（perf）：

cargo xtask starry perf [options]

参数	默认	说明
`-c/--case <NAME>`	`boot`	性能测试用例名
`--arch <ARCH>`	`riscv64`	目标架构
`--freq <HZ>`	`99`	采样频率
`--format`	`all`	`folded`/`svg`/`pprof`/`all`
`--mode`	`tb`	`tb`（trace buffer）/ `insn`（指令级）
`--max-depth <N>`	`128`	最大调用栈深度
`--timeout <SEC>`	`20`	采集超时
`--output-dir <DIR>`	—	输出根目录，报告位于 `<DIR>/perf/<arch>/latest`
`--shell-init-cmd <CMD>`	—	Guest shell 就绪后发送的命令（别名 `--workload`）
`--shell-prefix <STR>`	—	发送 `--shell-init-cmd` 前匹配的提示子串
`--start-marker` / `--stop-marker`	—	采样窗口起止标记
`--workload-timeout <SEC>`	—	采样窗口超时
`--host-time` / `--no-host-time`	开	收集/禁用 QEMU 进程 host CPU 时间
`--host-perf`	—	用 host `perf stat` 采集 QEMU 进程指标
`--host-perf-events <LIST>`	默认集	host perf stat 事件（逗号分隔）
`--qperf-metrics`	—	启用 in-guest qperf 指标计数
`--flamegraph`	—	即使 `--format` 非 SVG 也生成火焰图
`--flamegraph-kind`	`svg`	`svg`/`html`/`folded`
`--full-stack`	—	保留最深栈
`--perf-callchain`（别名 `--callchain`）	—	`leaf`/`fp`/`logical`
`--perf-debuginfo`	—	添加 DWARF 调试信息
`--perf-force-frame-pointers`	—	强制帧指针
`--demangle`	—	强制 Rust demangle
`--no-truncate`	—	火焰图保留极小帧
`--include-kernel-symbols`	开	包含内核符号
`--include-user-symbols`	—	包含用户符号
`--symbol-style`	`full`	`full`/`short`/`module`
`--focus <REGEX>`	—	为匹配帧生成聚焦火焰图
`--kernel-filter`	—	仅保留内核态帧
`--qemu-arg <ARG>`（可重复）	—	追加原始 QEMU 参数
`--smp <CPUS>`	—	CPU 核数
`--debug`	—	debug 构建

详见 StarryOS 性能剖析。

内核模块（kmod build）：

cargo xtask starry kmod build [--arch <A>] [--target <T>] [--config <P>] [--smp <N>] [--debug] [-m/--module <PATH>... | --all] [--rootfs <IMAGE>]

参数	说明
`-m/--module <PATH>`（可重复）	模块 crate 路径（自动查找深度 ≤ 10）
`--all`	构建 `os/StarryOS/lkm/` 下所有模块（与 `--module` 互斥）
`--rootfs <IMAGE>`	把产物注入到此 rootfs 的 `/modules/`

其他命令：

子命令	用法
`rootfs`	`rootfs [--arch <ARCH>]`（准备默认 managed rootfs）
`defconfig`	`defconfig <BOARD>`
`config ls`	`config ls`
`quick-start`	`quick-start <platform> {build\|run}`（支持 `qemu-{aarch64,riscv64,loongarch64,x86_64}`/`orangepi-5-plus`/`licheerv-nano-sg2002`）

cargo xtask starry build
cargo xtask starry qemu
cargo xtask starry test qemu --arch riscv64
cargo xtask starry app qemu --all
cargo xtask starry perf --format Svg
cargo xtask starry kmod build --all

6.1 性能剖析

cargo xtask starry perf 构建 StarryOS 并通过 qperf 进行性能剖析，输出火焰图或 callchain 数据：

cargo xtask starry perf [options]

参数	说明
`-c/--case`	性能测试用例名（默认 `boot`）
`--arch`	目标架构
`--freq`	采样频率（Hz，默认 99）
`--format`	输出格式：`Folded`/`Svg`/`Pprof`/`All`（默认 `All`）
`--mode`	采样模式：`Tb`（trace buffer，默认）/ `Insn`（指令级）
`--max-depth`	最大调用栈深度（默认 128）
`--timeout`	采集超时（秒，默认 20）
`--output-dir`/`--out`	输出根目录，最终报告位于 `<DIR>/perf/<arch>/latest`
`--host-time`/`--no-host-time`	收集/禁用 QEMU 进程的 host wall/user/system CPU 时间
`--host-perf`	在 host 侧用 `perf stat` 采集 QEMU 进程指标
`--host-perf-events`	host perf stat 事件（逗号分隔，默认 `task-clock,cycles,...`）
`--shell-init-cmd`/`--workload`	Guest shell 出现 boot 提示后发送的命令
`--shell-prefix`	发送 `--shell-init-cmd` 前匹配的提示子串
`--start-marker`/`--stop-marker`	Guest stdout 标记，控制采样窗口起止
`--workload-timeout`	采样窗口超时（秒），超时则停止 QEMU
`--qperf-metrics`	启用 feature-gated 的 in-guest qperf 指标计数
`--flamegraph`	即使 `--format` 非 SVG 也生成火焰图
`--flamegraph-kind`	火焰图格式：`Svg`（默认）/`Html`/`Folded`
`--full-stack`	保留本构建可采集的最深栈
`--perf-callchain`（别名 `--callchain`）	qperf callchain 模式：`Leaf`（最快）/`Fp`（需帧指针）/`Logical`
`--perf-debuginfo`	添加 DWARF 调试信息并保留符号
`--perf-force-frame-pointers`	强制帧指针以支持 FP 解栈
`--demangle`	在 qperf-analyzer 中强制 Rust demangle
`--no-truncate`	火焰图中保留极小帧（min width 设为 0）
`--include-kernel-symbols`	包含内核符号（StarryOS 默认开启）
`--include-user-symbols`	包含用户符号（当前 qperf 仅解析内核 ELF）
`--symbol-style`	折叠栈符号风格：`Full`（默认）/`Short`/`Module`
`--focus`	为匹配正则的帧生成额外的聚焦折叠栈/火焰图
`--kernel-filter`	仅保留内核态帧
`--smp`	CPU 核数
`--debug`	debug 构建

6.2 内核模块

cargo xtask starry kmod build 编译 StarryOS 可加载内核模块（.ko）：

cargo xtask starry kmod build [--arch <ARCH>] [--target <TARGET>] [--config <PATH>] [--smp <N>] [--debug] \
                              [-m/--module <PATH>... | --all] [--rootfs <IMAGE>]

模块从 os/StarryOS/lkm/ 目录或 --module 显式指定的路径发现（支持目录深度 ≤ 10 的自动查找）。Rust 模块复用 StarryOS 内核构建配置的 Cargo 环境，使用独立链接脚本 os/StarryOS/scripts/kmod-linker.ld 把 rlib 部分链接为 ET_REL .ko；Linux Kbuild C 模块仅在所选架构与 host 架构相同时调用模块目录自带的 Makefile。--rootfs 指定时，所有产物会通过 debugfs 注入到镜像的 /modules/ 目录下。

--all 与 --module 互斥；两者都未提供时默认扫描 os/StarryOS/lkm/。

7. Axvisor 命令

cargo xtask axvisor 的全部子命令。详细原理见 Axvisor 概述、构建、运行、测试。

通用参数（build / qemu / uboot / board）：

参数	说明
`-c/--config <CONFIG>`	显式 Build Info 路径
`--arch <ARCH>`	目标架构，默认 `aarch64`
`-t/--target <TARGET>`	target triple
`--smp <CPUS>`	CPU 核数
`--debug`	debug 构建
`--vmconfigs <VMCONFIGS>`（可重复）	Guest VM 配置文件列表

子命令	说明
`build`	编译 Axvisor
`qemu`	编译并在 QEMU 中运行
`uboot`	编译并通过 U-Boot 运行
`board`	编译并在远程板卡运行
`test qemu`	QEMU 测试
`test uboot`	U-Boot 测试（Axvisor 独有）
`test board`	板级测试
`defconfig <BOARD>`	生成默认板卡配置
`config ls`	列出可用板卡名称

各运行目标的额外参数：

子命令	额外参数
`qemu`	`--qemu-config <PATH>`、`--rootfs <IMAGE>`
`uboot`	`--uboot-config <PATH>`
`board`	`--board-config <PATH>`、`-b/--board-type <TYPE>`、`--server <HOST>`、`--port <PORT>`

测试子命令：

子命令	用法	关键参数
`test qemu`	`[--arch \| -t/--target \| --list] [-g/--test-group <G>] [-c/--test-case <C>]`	三选一
`test uboot`	`-b/--board <BOARD> [--guest <GUEST>] [--uboot-config <P>]`	`--guest` 默认 `linux`
`test board`	`[-g/--test-group <G>] [-c/--test-case <C>] [--board <B>] [-b/--board-type <T>] [--server <H>] [--port <P>] [--list]`	—

Axvisor 的平台与 x86 虚拟化后端由 Build Config 的 feature 声明，QEMU CPU、UEFI 和设备参数由所选 TOML 定义。vmx 与 svm 分别对应 Intel 和 AMD 的虚拟化构建能力。

cargo xtask axvisor build
cargo xtask axvisor qemu --vmconfigs os/axvisor/configs/vms/qemu/aarch64/linux-smp1.toml
cargo xtask axvisor test uboot --board OrangePi-5-Plus

1. 调用方式​

2. 顶层命令​

3. 质量检查​

3.1 标准测试​

3.2 内核测试​

3.3 Clippy 检查​

3.4 并发检查​

3.5 依赖检查​

4. 工程工具​

4.1 板卡管理​

4.2 回溯符号化​

4.3 镜像管理​

4.4 OVMF 固件​

4.5 UEFI 引导​

4.6 Review Benchmark​

5. ArceOS 命令​

6. StarryOS 命令​

6.1 性能剖析​

6.2 内核模块​

7. Axvisor 命令​

1. 调用方式

2. 顶层命令

3. 质量检查

3.1 标准测试

3.2 内核测试

3.3 Clippy 检查

3.4 并发检查

3.5 依赖检查

4. 工程工具

4.1 板卡管理

4.2 回溯符号化

4.3 镜像管理

4.4 OVMF 固件

4.5 UEFI 引导

4.6 Review Benchmark

5. ArceOS 命令

6. StarryOS 命令

6.1 性能剖析

6.2 内核模块

7. Axvisor 命令