组件仓库模板

[ZCShou]

组件模板说明文档

概述

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

目录结构

arm_vcpu/
├── Cargo.toml                  # Crate 元数据和依赖配置
├── rust-toolchain.toml         # Rust 工具链配置（指定版本、target、组件）
├── LICENSE                     # 许可证文件
├── CHANGELOG.md                # 版本变更日志（可选）
├── CONTRIBUTING.md             # 贡献指南（可选）
├── README.md                   # 项目简介和快速上手（默认英文）
├── README_CN.md                # README.md 对应的中文版
├── .cargo/
│   └── config.toml             # Cargo 配置（默认 target、编译选项等）
├── .github/
│   ├── workflows/
│   │  ├── check.yml            # 代码检查工作流（调用 axci/.github/workflows/check.yml）
│   │  ├── test.yml             # 测试工作流（调用 axci/.github/workflows/test.yml）
│   │  ├── deploy.yml           # 文档部署工作流（调用 axci/.github/workflows/deploy.yml）
│   │  ├── push.yml             # 通知父仓库工作流（调用 axci/.github/workflows/push.yml）
│   │  └── release.yml          # 发布工作流（调用 axci/.github/workflows/release.yml）
│   └── config.json             # 项目配置文件（组件名、编译目标、rust组件等）
├── docs/                       # 基于 mdBook 实现的设计文档
│   ├── book.toml               # mdBook 配置文件
│   ├── README.md               # 说明文档
│   └── src/                    # 文档源文件目录
│       ├── SUMMARY.md          # 文档目录结构（仅列主章节，不要锚点）
│       └── ***                 # 文档源文件
├── tests/
│   └── ****                    # 单元测试文件
├── examples/                   # 示例代码
│   ├── Cargo.toml              # 示例工作空间配置
│   ├── README.md               # 示例说明
│   └── basic.rs                # 基础使用示例
├── scripts/                    # 实用脚本
│   ├── check.sh                # 代码检查脚本（调用 axci/check.sh）
│   └── test.sh                 # 测试脚本（调用 axci/tests.sh）
└── src/                        # 组件源码目录，必须支持 rustdoc 生成 API 文档

测试与验证

组件必须独立可测试与验证。

本地测试

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

基本用法：

# 运行全部测试（单元测试 + 集成测试）
./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 --unit-targets x86_64-unknown-linux-gnu

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

# 组合使用
./scripts/test.sh all --unit-targets x86_64-unknown-linux-gnu --suite axvisor-qemu

其他选项：

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

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

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

# 从 git 仓库拉取代码（默认从 crates.io）
./scripts/test.sh integration --from-git --branch master

支持的测试类型：

类型	说明	示例
单元测试	cargo test --target <triple>	--unit-targets x86_64-unknown-linux-gnu
QEMU 集成测试	在 QEMU 中启动 axvisor 运行客户机镜像	--suite axvisor-qemu-aarch64-arceos
开发板集成测试	通过 U-Boot 在物理开发板上运行	--suite axvisor-board-phytiumpi-arceos
Starry 测试	构建并运行 StarryOS	--suite starry-aarch64

本地代码检查：

# 运行格式检查、clippy、构建、文档生成
./scripts/check.sh

CI

本地测试环境有限，组件必须配置 CI 进行全面测试。所有 CI 工作流通过调用 axci 的共享工作流实现，组件侧只需编写简单的调用文件。示例如下：

name: Check

on:
  push:
    branches: ['**']
    tags-ignore: ['**']
  pull_request:
  workflow_dispatch:

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

使用示例

必须在组件的 examples/ 目录中提供组件的使用示例代码。

示例目录结构

examples/
├── Cargo.toml              # 示例工作空间配置
├── README.md               # 示例说明文档
└── basic.rs                # 基础使用示例

示例 Cargo.toml

[package]
name = "examples"
version = "0.1.0"
edition = "2021"

[dependencies]
组件名 = { path = ".." }

示例代码规范

• 每个示例文件应包含完整的可运行代码
• 在文件顶部添加简要说明注释
• 覆盖组件的主要使用场景

配置文件

.github/config.json

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

{
  "component": {
    "name": "组件名称",
    "crate_name": "crate名称"
  },
  "targets": [
    "aarch64-unknown-none-softfloat"
  ],
  "unit_test_targets": [
    "x86_64-unknown-linux-gnu"
  ],
  "rust_components": [
    "rust-src",
    "clippy",
    "rustfmt"
  ]
}

字段	说明
component.name	组件名称
component.crate_name	Crate 名称
targets	编译目标平台列表
unit_test_targets	单元测试目标平台
rust_components	需要安装的 Rust 组件

Cargo.toml

Crate 元数据和依赖配置：

[package]
name = "组件名"
version = "0.1.0"
edition = "2021"
authors = ["作者"]
description = "组件描述"
license = "Apache-2.0"
homepage = "https://github.com/org/repo"
repository = "https://github.com/org/repo"
documentation = "https://docs.rs/组件名"
keywords = ["arceos", "arm", "aarch64"]
categories = ["embedded", "no-std", "hardware-support", "os"]

[dependencies]
# 依赖列表

文档规范

组件文档分为两个层次：设计文档（mdBook）和 API 文档（rustdoc）。

设计文档 (mdBook)

必须在组件的 docs/ 目录使用 mdBook 构建面向组件开发者、架构设计者和维护者的组件设计文档。

文件结构：

docs/
├── book.toml           # mdBook 配置文件
├── README.md           # 说明
└── src/                # 文档源文件目录
    ├── SUMMARY.md      # 目录结构（仅列主章节）
    └── ***             # 文档源文件

文档源文件：

根据需要以子目录形式区分不同文档

本地构建：

# 安装 mdbook
cargo install mdbook

# 进入 docs 目录并启动预览服务
cd docs
mdbook serve --open

# 或仅构建
mdbook build

写作要点：

• 解释"为什么"这样设计，而非"怎么做"
• 包含架构图、时序图、数据流图（使用 Mermaid 或 ASCII 图）
• 记录关键的设计决策和权衡
• 说明模块间的协作关系和边界

API 文档 (rustdoc)

在编写源代码时，必须添加必要的 /// 注释，以便可以直接通过 rustdoc 生成面向组件使用者的 API 文档。

# 本地生成文档
cargo doc --no-deps

# 生成并在浏览器打开
cargo doc --no-deps --open

文档位置：

• 公开 API：在 src/lib.rs 和各个模块的公开项上使用 /// 注释
• 模块级文档：每个文件顶部的 //! 注释说明模块职责
• 特性标注：使用 #[doc(cfg(feature = "..."))] 标记条件编译项

API 文档示例：

/// 创建一个新的虚拟 CPU。
///
/// # 参数
/// - `vm_id`: 虚拟机标识符
/// - `vcpu_id`: vCPU 在 VM 内的索引
/// - `config`: 创建配置
///
/// # 示例
/// ```
/// let config = Aarch64VCpuCreateConfig::default();
/// let vcpu = Aarch64VCpu::<MyHal>::new(0, 0, config)?;
/// ```
///
/// # 错误
/// - `AxError::InvalidInput`: 配置参数无效
pub fn new(vm_id: usize, vcpu_id: usize, config: CreateConfig) -> AxResult<Self>;

写作要点：

• 解释"怎么用"这个 API
• 说明参数、返回值、错误条件
• 提供可运行的代码示例（doctests）
• 标注 panic 条件、unsafe 前提（如有）

README

默认 README.md 为英文版本，同时提供对应的中文版本 README_CN.md，两者的基本模板如下所示：

<!-- <div align="center">

<img src="https://arceos-hypervisor.github.io/doc/assets/logo.svg" alt="axvisor-logo" width="64">

</div> -->

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

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

<div align="center">
<!-- 组件相关的 BADGE -->
[![GitHub stars](https://img.shields.io/github/stars/arceos-hypervisor/axvisor?logo=github)](https://github.com/arceos-hypervisor/axvisor/stargazers)
[![GitHub forks](https://img.shields.io/github/forks/arceos-hypervisor/axvisor?logo=github)](https://github.com/arceos-hypervisor/axvisor/network)
[![license](https://img.shields.io/github/license/arceos-hypervisor/axvisor)](https://github.com/arceos-hypervisor/axvisor/blob/master/LICENSE)

</div>

<!-- 必须中英文切换 -->
English | [中文](README_CN.md)

# 简介

## 示例

使用示例代码

## 验证

通过本地 `test.sh` 快速启动验证

# 文档

## 设计文档

## API 文档

# 贡献

1. 通过本地 `check.sh`
2. 通过本地 `test.sh`
3. 提交 PR 并通过 CI 检查

# 协议

Axvisor is licensed under the Apache License, Version 2.0. See the [LICENSE](./LICENSE) file for details.

GitHub Workflows

check.yml — 代码检查

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

功能：

• 代码格式检查 (rustfmt)
• 静态分析 (clippy)
• 编译检查
• 文档生成检查

test.yml — 集成测试

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

功能：

• 运行单元测试
• 运行 QEMU / 开发板集成测试
• 生成测试报告

release.yml — 发布

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

流程：

check ──┐
        ├──→ release（verify-tag → GitHub Release → crates.io publish）
test  ──┘

• check 和 test 必须通过后才执行 release
• verify-tag 确保 tag 在正确分支上且版本号与 Cargo.toml 一致

deploy.yml — 文档部署

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

功能：

• 生成 API 文档 (rustdoc)
• 部署到 GitHub Pages

push.yml — 通知父仓库

触发条件：push 到 main 分支

功能：

• 通知父仓库更新依赖
• 触发父仓库的 CI

CI 触发规则总览

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

脚本文件

check.sh - 本地代码检查

#!/bin/bash
# 下载并调用 axci 仓库中的检查脚本

./scripts/check.sh

执行内容：

• 下载 axci 仓库到 .axci/ 目录
• 调用 axci/check.sh 执行检查

test.sh - 本地测试

#!/bin/bash
# 下载并调用 axci 仓库中的测试脚本

./scripts/test.sh

执行内容：

• 下载 axci 仓库到 .axci/ 目录
• 调用 axci/tests.sh 执行测试

可选文件

CHANGELOG.md - 版本变更日志

记录每个版本的变更内容，遵循 Keep a Changelog 格式：

# Changelog

## [Unreleased]

## [0.1.0] - 2024-01-01
### Added
- 初始版本

### Changed
- ...

### Fixed
- ...

CONTRIBUTING.md - 贡献指南

说明如何为项目做出贡献：

• 开发环境搭建
• 代码规范
• 提交规范
• PR 流程

.cargo/config.toml - Cargo 配置

[build]
target = "aarch64-unknown-none-softfloat"

[target.aarch64-unknown-none-softfloat]
rustflags = ["-C", "link-arg=-Tlinker.ld"]

rust-toolchain.toml - Rust 工具链配置

[toolchain]
channel = "nightly"
components = ["rust-src", "clippy", "rustfmt"]
targets = ["aarch64-unknown-none-softfloat"]

组件源码

src 目录下的组件源码必须符合 Rust 标准，并支持 rustdoc 生成 API 文档。

源码结构

文件	职责
lib.rs	库入口，定义模块级文档 (//!)，导出公开 API
***.rs	各功能模块，使用 /// 注释公开项

代码规范

• 模块级文档: 每个文件顶部使用 //! 说明模块职责
• 公开 API 文档: 使用 /// 注释说明用法、参数、返回值、错误条件
• 代码示例: 提供可运行的 doctests
• 条件编译: 使用 #[doc(cfg(feature = "..."))] 标记特性门控项

示例

//! # 模块名称
//!
//! 模块功能简介

/// 函数/类型说明
///
/// # 参数
/// - `param`: 参数说明
///
/// # 示例
/// ```
/// // 可运行的代码示例
/// ```
///
/// # 错误
/// - 错误情况说明
pub fn some_function(param: Type) -> Result<Output>;

标准开发工作流

1. 编写或修改源代码

   • 遵循 Rust 代码规范
   • 添加必要的文档注释

2. 代码检查

   ./scripts/check.sh

3. 构建及测试

   # 全量测试
   ./scripts/test.sh
   
   # 快速验证：仅单元测试
   ./scripts/test.sh unit --unit-targets x86_64-unknown-linux-gnu
   
   # 指定集成测试套件
   ./scripts/test.sh integration --suite axvisor-qemu-aarch64-arceos --fs --print

4. 生成文档

   cargo doc --no-deps --open

5. 提交 PR

   • CI 自动运行 check + test
   • 代码审查通过后合并

6. 发布

   # 预发布（dev 分支）
   git tag v0.2.0-pre.1
   git push origin v0.2.0-pre.1
   
   # 正式发布（main 分支）
   git tag v0.2.0
   git push origin v0.2.0