组件仓库模板

[ZCShou]

组件模板说明文档

概述

本文档描述组件的完整目录结构、源码文件职责及标准模板规范，可作为其他 OS 组件的参考模板。

目录结构

arm_vcpu/
├── Cargo.toml                  # Crate 元数据和依赖配置
├── rust-toolchain.toml         # Rust 工具链配置
├── LICENSE                     # 许可证文件
├── CHANGELOG.md                # 版本变更日志（可选）
├── README.md                   # 项目简介（英文）
├── README_CN.md                # README 中文版
├── .cargo/
│   └── config.toml             # Cargo 配置（默认 target、编译选项等）
├── .github/
│   ├── workflows/
│   │  ├── check.yml            # 代码检查工作流
│   │  ├── test.yml             # 测试工作流
│   │  ├── deploy.yml           # 文档部署工作流
│   │  ├── push.yml             # 同步到父仓库
│   │  └── release.yml          # 发布工作流
│   └── config.json             # 项目配置文件
├── scripts/                    # 实用脚本
│   ├── check.sh                # 代码检查（调用 axci/check.sh）
│   └── test.sh                 # 测试（调用 axci/tests.sh）
├── tests/                      # 集成测试文件
└── src/                        # 组件源码目录
    ├── lib.rs                  # 库入口，导出公共 API
    ├── context_frame.rs        # ARMv8 上下文帧实现
    ├── exception.rs            # 异常处理相关
    ├── exception.S              # 异常处理汇编代码
    ├── exception_utils.rs       # 异常处理工具宏
    ├── pcpu.rs                 # Per-CPU 数据结构
    ├── smc.rs                  # SMC 调用处理
    └── vcpu.rs                 # vCPU 核心实现

配置文件

.github/config.json

组件配置文件，用于 CI/CD 流程读取组件信息：

{
  "targets": [
    "aarch64-unknown-none-softfloat"
  ],
  "rust_components": [
    "rust-src",
    "clippy",
    "rustfmt"
  ]
}

字段	说明
targets	编译目标平台列表
rust_components	需要安装的 Rust 组件

Cargo.toml

[package]
name = "组件名"
version = "0.1.0"
edition = "2024"
authors = ["作者"]
description = "组件描述"
license = "Apache-2.0"
repository = "https://github.com/org/repo"
keywords = ["hypervisor", "aarch64", "vcpu"]
categories = ["embedded", "no-std"]

[dependencies]
# 依赖列表

.cargo/config.toml

[target.aarch64-unknown-linux-gnu]
linker = "aarch64-linux-gnu-gcc"
runner = ["qemu-aarch64", "-L", "/usr/aarch64-linux-gnu"]

rust-toolchain.toml

[toolchain]
profile = "minimal"
channel = "nightly-2025-05-20"
components = ["rust-src", "llvm-tools", "rustfmt", "clippy"]
targets = ["aarch64-unknown-none-softfloat"]

测试与代码检查

组件通过 scripts/ 下的脚本调用 axci 统一测试框架。首次运行时自动下载 axci 到 scripts/.axci/ 目录。

test.sh — 测试

# 运行全部测试（单元测试 + 集成测试）
./scripts/test.sh

# 仅运行单元测试
./scripts/test.sh unit

# 仅运行集成测试
./scripts/test.sh integration

# 列出所有可用的测试套件
./scripts/test.sh list

# 指定编译目标
./scripts/test.sh --targets aarch64-unknown-none-softfloat

# 指定测试套件（支持前缀匹配）
./scripts/test.sh integration --suite axvisor-qemu

# 仅显示将要执行的命令
./scripts/test.sh --dry-run -v

# 使用文件系统模式，不修改配置文件
./scripts/test.sh integration --suite axvisor-qemu-aarch64-arceos --fs

# 打印 U-Boot 和串口输出到终端
./scripts/test.sh integration --suite axvisor-qemu-aarch64-arceos --fs --print

支持的测试类型：

类型	说明	示例
单元测试	cargo test 在宿主机运行	./scripts/test.sh unit
QEMU 集成测试	在 QEMU 中启动 axvisor 运行客户机镜像	--suite axvisor-qemu-aarch64-arceos
开发板集成测试	通过 U-Boot 在物理开发板上运行	--suite axvisor-board-phytiumpi-arceos
Starry 测试	构建并运行 StarryOS	--suite starry-aarch64

check.sh — 代码检查

# 运行全部检查（格式 + clippy + 构建 + 文档）
./scripts/check.sh

# 仅运行指定阶段
./scripts/check.sh --only fmt
./scripts/check.sh --only clippy
./scripts/check.sh --only build

# 指定编译目标
./scripts/check.sh --targets aarch64-unknown-none-softfloat

GitHub Workflows

所有 CI 工作流通过调用 axci 的共享工作流实现（push.yml 除外）。

check.yml — 代码检查

触发条件：push 到任意分支（tag 除外）、PR、手动触发

功能：格式检查 (rustfmt)、静态分析 (clippy)、编译检查、文档生成检查

jobs:
  check:
    uses: arceos-hypervisor/axci/.github/workflows/check.yml@main

test.yml — 集成测试

触发条件：push 到任意分支（tag 除外）、PR、手动触发

功能：运行单元测试、QEMU / 开发板集成测试

release.yml — 发布

触发条件：push 版本 tag（v*.*.* 或 v*.*.*-preview.*）

流程：check + test 通过后执行 verify-tag → GitHub Release → crates.io publish

deploy.yml — 文档部署

触发条件：push 稳定版 tag（v*.*.*，不含 -preview.*）

功能：生成 API 文档 (rustdoc) 并部署到 GitHub Pages

push.yml — 同步到父仓库

触发条件：push 到 main 分支（此工作流为独立实现，直接复制自 axci，不使用 uses:）

功能：从父仓库 scripts/repo/repos.csv 定位组件 subtree 路径，执行 git subtree pull，创建或更新 PR

CI 触发规则总览

事件	check	test	release	deploy	push
push 分支 / PR	触发	触发	-	-	-
push 稳定版 tag v1.0.0	由 release 调用	由 release 调用	触发	触发	-
push 预发布 tag v1.0.0-preview.1	由 release 调用	由 release 调用	触发	-	-
push main 分支	触发	触发	-	-	触发

文档规范

API 文档 (rustdoc) — 必需

源码中使用 /// 注释生成面向组件使用者的 API 文档：

cargo doc --no-deps --open

• 公开 API：使用 /// 注释，说明用法、参数、返回值、错误条件
• 模块级文档：每个文件顶部使用 //! 说明模块职责
• 提供可运行的 doctests 代码示例

示例：

/// 创建一个新的虚拟 CPU。
///
/// # 参数
/// - `vm_id`: 虚拟机标识符
/// - `vcpu_id`: vCPU 在 VM 内的索引
/// - `config`: 创建配置
fn new(vm_id: usize, vcpu_id: usize, config: CreateConfig) -> AxResult<Self>;

设计文档 (mdBook) — 可选

可在 docs/ 目录使用 mdBook 构建设计文档：

cargo install mdbook
cd docs && mdbook serve --open

README

默认 README.md 为英文版本，同时提供 README_CN.md 中文版。基本模板：

<h1 align="center">组件名字</h1>

<p align="center">组件的简介</p>

<div align="center">
[![Crates.io](https://img.shields.io/crates/v/组件名.svg)](https://crates.io/crates/组件名)
[![Docs.rs](https://docs.rs/组件名/badge.svg)](https://docs.rs/组件名)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/org/repo/blob/main/LICENSE)
</div>

English | [中文](README_CN.md)

# 简介

组件功能简介。

## 快速开始

### 环境要求

- 平台要求
- Rust nightly 工具链

### 使用方法

使用示例代码。

## 验证

```bash
./scripts/check.sh
./scripts/test.sh

API 文档

cargo doc --no-deps --open

贡献

1. ./scripts/check.sh
2. ./scripts/test.sh
3. 提交 PR 并通过 CI

协议

Licensed under the Apache License, Version 2.0.