组件开发方案 #372

ZCShou · 2026-03-02T09:11:31Z

ZCShou
Mar 2, 2026
Maintainer

组件开发方案

本文档是组件开发及管理规范的配套操作指南，专注于组件开发的具体执行方案。关于开发规范、分支规划、版本号规范等，请参考组件开发及管理规范。

一、方案概述

1.1 背景与目的

ArceOS 采用组件化架构设计，组件是功能相对独立且可独立测试的实体。为了规范组件的开发、管理和发布流程，特制定本协同开发方案。

1.2 仓库架构

我们的组件实际分布在各个独立的子仓库中，每个组件都是一个独立的 Git 仓库。同时，我们提供了 axcrates 仓库作为统一的管理入口，通过 Git Submodule 关联所有组件。因此，有两种开发方式可选，来处理组件的开发过程：

方式	适用场景	特点
独立子仓库开发	单组件修改	直接克隆子仓库，轻量快捷
axcrates 统一仓库开发	跨组件协作	通过主仓库统一管理所有组件

1.3 架构关系图

┌─────────────────────────────────────────────────────────────────────────┐
│                         组件分布与协作架构                              │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│      独立子仓库                               axcrates（统一管理仓库）     │
│   ┌──────────────┐                         ┌──────────────────────┐    │
│   │ arm_vcpu     │◄───────────────────────►│  .gitmodules         │    │
│   │ arm_vgic     │◄───────────────────────►│  scripts/            │    │
│   │ axaddrspace  │◄───────────────────────►│  ├── check.sh        │    │
│   │ axdevice     │◄───────────────────────►│  ├── version.sh      │    │
│   │ axdevice_base│◄───────────────────────►│  └── publish.sh      │    │
│   │ axhvc        │◄───────────────────────►│                      │    │
│   │ axvcpu       │◄───────────────────────►│  arm_vcpu/           │    │
│   │ axvm         │◄───────────────────────►│  arm_vgic/           │    │
│   │ axvmconfig   │◄───────────────────────►│  axaddrspace/        │    │
│   │ axvisor_api  │◄───────────────────────►│  ... (submodule)     │    │
│   │ riscv_vcpu   │◄───────────────────────►│                      │    │
│   │ riscv-h      │◄───────────────────────►│                      │    │
│   │ x86_vcpu     │◄───────────────────────►│                      │    │
│   │ x86_vlapic   │◄───────────────────────►│                      │    │
│   └──────────────┘                         └──────────────────────┘    │
│        ▲                                          ▲                    │
│        │         Git Submodule 关联               │                    │
│        └──────────────────────────────────────────┘                    │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

独立子仓库：每个组件（如 arm_vcpu、axvcpu）都有自己的独立 Git 仓库，可以独立开发、测试、发布
axcrates 主仓库：通过 Git Submodule 引用所有组件，提供统一的版本管理和协同脚本

1.4 核心开发原则

基于组件开发及管理规范，我们遵循以下核心原则：

原则	说明	实践方式
版本统一	所有组件使用相同版本号，便于管理和追踪	axcrates 仓库中 `version.sh` 批量管理所有组件版本号
分支隔离	main 分支保护（需 PR），dev 分支开放（可直接推送）	PR 流程 vs 直接推送
依赖锁定	主仓库记录子模块具体 commit，确保可复现构建	`.gitmodules` + submodule
独立演进	子仓库可独立开发测试，不受主仓库影响	直接克隆子仓库开发
代码质量	所有组件必须通过 CI 检查（fmt、clippy、doc、test）	`scripts/check.sh` 本地检查
文档完整	公开发布的组件必须具备完整的 rustdoc 文档	`cargo doc` 生成文档

1.5 分支与版本对应关系

在组件开发及管理规范中我们规定了组件仓库分支与版本必须强制对应，以便统一管理！

┌─────────────────────────────────────────────────────────────────────┐
│                         版本发布策略                                │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  dev 分支 (开放，可直接推送)                                        │
│     │                                                               │
│     ├── 日常开发 ──► 功能完成 ──► 测试通过                          │
│     │                               │                               │
│     │                               ▼                               │
│     │                       版本升级: 0.2.0-preview.1               │
│     │                               │                               │
│     │                               ▼                               │
│     │                       推送 dev 分支                           │
│     │                               │                               │
│     │                               ▼                               │
│     │                       发布到 crates.io (可选)                 │
│     │                                                               │
│     └──► 功能稳定 ──► PR ──► main 分支 (保护，需 PR)                │
│                                   │                                 │
│                                   ▼                                 │
│                           版本升级: 0.2.0 (稳定版)                  │
│                                   │                                 │
│                                   ▼                                 │
│                           打标签: v0.2.0                            │
│                                   │                                 │
│                                   ▼                                 │
│                           发布到 crates.io                          │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

二、开发环境准备

2.1 配置 Git 环境

# 配置全局用户名和邮箱（如未配置）
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# 配置 SSH 密钥（用于访问 GitHub）
# 如已有密钥可跳过
ssh-keygen -t ed25519 -C "your.email@example.com"
cat ~/.ssh/id_ed25519.pub
# 将公钥添加到 GitHub: Settings -> SSH and GPG keys -> New SSH key

2.2 安装 Rust 工具链

# 安装 Rust（如已安装可跳过）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# 安装所需目标架构
rustup target add aarch64-unknown-none-softfloat
rustup target add x86_64-unknown-none
rustup target add riscv64gc-unknown-none-elf

# 安装必要组件
rustup component add rust-src llvm-tools rustfmt clippy

三、开发工作流详解

3.1 工作流选择决策树

开始开发
    │
    ├──► 只修改单个组件？
    │       │
    │       ├──► 是 ──► 选择 3.2 独立子组件开发
    │       │
    │       └──► 否 ──► 需要修改多个组件？
    │               │
    │               ├──► 是 ──► 选择 3.3 多组件协同开发
    │               │
    │               └──► 否 ──► 只需要测试？ ──► 选择 3.2 独立子组件开发 或  3.3 多组件协同开发 均可以
    │
    └──► 发布版本？ ──► 选择 3.3 多组件协同开发
            │
            ├──► 预览版 ──► 使用 version.sh + commit.sh + tag.sh
            │
            └──► 稳定版 ──► 使用 version.sh + commit.sh + tag.sh + PR

3.2 独立子组件开发

对于每个独立的组件，我们已经在其对应的仓库中配备了完整的 CI/CD 以及本地测试脚本文件。当需要修改只修改单个组件，不涉及其他组件的 API 变更时，可以直接在独立子组件仓库中开发及测试。

新建组件时，务必参考已有组件通过引用 https://github.com/arceos-hypervisor/axci 仓库中的 CI/CD 脚本以及本地测试脚本来实现统一验证

3.2.1 克隆子仓库

# 以 axvcpu 为例
git clone git@github.com:arceos-hypervisor/axvcpu.git
cd axvcpu

# 查看当前分支
git branch -a

3.2.2 创建功能分支

所有子仓库的 main 或 master 分支受保护，无法直接推送代码。所有开发必须在功能分支上进行，通过 Pull Request 合并。

# 获取最新代码
git checkout dev
git pull origin dev

# 基于 dev 创建功能分支
git checkout -b feature/add-new-api

# 分支命名规范：
# - feature/xxx  - 新功能
# - fix/xxx      - Bug 修复
# - refactor/xxx - 代码重构
# - docs/xxx     - 文档更新

3.2.3 修改代码

# 编辑代码...
# vim src/lib.rs

# 本地构建验证
cargo build

3.2.4 代码检查

使用 scripts/check.sh 检查代码规范：

# 通过脚本
bash scripts/check.sh

# 或手动执行检查
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings

检查项目：

代码格式（cargo fmt）
构建检查（cargo build）
Clippy 检查（cargo clippy）
文档构建（cargo doc）

3.2.5 本地测试

单元测试（可选）：

# 运行单元测试
cargo test --all-features

# 运行指定测试
cargo test test_name

**集成测试（必须，具体测试内容参见：https://github.com/orgs/arceos-hypervisor/discussions/217）**：

# 使用 test.sh 执行集成测试
bash scripts/test.sh

3.2.6 提交变更

# 查看变更
git status
git diff

# 添加变更
git add .

# 提交（使用约定式提交格式）
git commit -m "feat: add new virtualization API

This commit adds support for new vCPU features:
- Add vCPU state save/restore API
- Support for new interrupt handling

Closes #123"

# 推送到远程
git push origin feature/add-new-api

3.2.7 创建 Pull Request

在当前组件仓库页面点击 "Compare & pull request" 创建 PR：

推送到 dev 分支（预览版迭代）：

GitHub 操作：
1. 打开 https://github.com/arceos-hypervisor/axvcpu
2. 点击 "Compare & pull request"
3. base: dev ← compare: feature/add-new-api
4. 填写 PR 标题和描述
5. 请求 review（可选，dev 分支可快速合并）
6. 合并 PR

推送到 main 分支（稳定版）：

GitHub 操作：
1. 打开 https://github.com/arceos-hypervisor/axvcpu
2. 点击 "Compare & pull request"
3. base: main ← compare: feature/add-new-api
4. 填写详细的 PR 描述
5. 确保 CI 检查通过
6. 请求至少 1 人 review
7. 合并 PR（需 maintainer 权限）

3.2.8 通知主仓库更新

# PR 合并后，通知主仓库维护者更新 submodule
# 提供以下信息：
# - 组件名称：axvcpu
# - 更新的分支：dev 或 main
# - 变更简述：添加了新的 vCPU API

3.3 多组件协同开发

多组件协同开发适用于需要同时修改多个组件，或者跨组件 API 变更等情况。为此，我们创建了 https://github.com/arceos-hypervisor/axcrates 统一仓库，通过 SUBMODULE 来管理所有组件，并同时提供了一系列协同开发脚本，可以统一管理所有组件，无需进入每个组件目录执行 git 命令。

脚本	功能	示例
`checkout.sh`	批量切换分支	`bash scripts/checkout.sh all dev`
`check.sh`	批量代码检查	`bash scripts/check.sh all`
`commit.sh`	批量提交组件	`bash scripts/commit.sh axvcpu "feat: xxx"`
`push.sh`	批量推送组件	`bash scripts/push.sh all`
`sync.sh`	批量同步子模块	`bash scripts/sync.sh all dev`
`version.sh`	批量更新版本	`bash scripts/version.sh all 0.2.0`
`tag.sh`	批量创建标签	`bash scripts/tag.sh all v0.2.0`

新建组件时，向 https://github.com/arceos-hypervisor/axcrates 提交 PR，以便统一管理所有组件

3.3.1 获取 axcrates 仓库

# 克隆主仓库（包含所有子模块）
git clone --recurse-submodules git@github.com:arceos-hypervisor/axcrates.git
cd axcrates

# 切换到 dev 分支
git checkout dev

3.3.2 批量切换组件分支

使用 scripts/checkout.sh 批量管理组件分支：

# 切换所有组件到 dev 分支
bash scripts/checkout.sh all dev

# 切换所有组件到 main 分支
bash scripts/checkout.sh all main

# 切换单个组件到 feature 分支
bash scripts/checkout.sh axvcpu feature/new-api

脚本功能：

自动检测当前分支，如在目标分支则跳过
自动从远程获取并创建跟踪分支
检测未提交变更并提示
汇总显示切换结果

3.3.3 确定修改范围

# 分析依赖关系，确定需要修改的组件
# 示例：修改 axvcpu API，影响 arm_vcpu 和 x86_vcpu

# 查看组件依赖树
cd axvcpu && cargo tree
cd ../arm_vcpu && cargo tree | grep axvcpu
cd ../x86_vcpu && cargo tree | grep axvcpu

3.3.4 修改组件代码

开发阶段进入各组件目录修改代码。此时所有组件已在3.3.2 批量切换组件分支切换了分支，开发流程与 3.2 独立子组件开发类似，但是可使不用在组件中直接提交代码，而是在编辑多个组件之后，统一使用 check.sh、commit.sh 等脚本批量处理多个组件。

# 场景：修改了 axvcpu API，需要适配 arm_vcpu 和 x86_vcpu

# 1. 在 axvcpu 开发并提交
cd axvcpu
# ... 编辑代码 ...
# ... 测试 ...
# ... CHECK ...
# ... 提交 ...
bash scripts/commit.sh axvcpu "refactor: update vCPU API"

# 2. 在 arm_vcpu 适配并提交
cd ../arm_vcpu
# ... 编辑代码 ...
# ... 测试 ...
# ... CHECK ...
# ... 提交 ...
bash scripts/commit.sh arm_vcpu "refactor: adapt to new axvcpu API"

# 3. 批量提交所有组件修改（在根目录执行）
cd ..
bash scripts/commit.sh axvcpu,arm_vcpu,x86_vcpu "refactor: update vCPU API and adaptations"

3.3.5 批量代码检查

开发过程中或完成后，使用 scripts/check.sh 批量检查代码质量：

# 检查所有组件（ fmt、clippy、doc ）
bash scripts/check.sh all

# 检查指定组件
bash scripts/check.sh axvcpu

# 检查指定组件指定目标
bash scripts/check.sh axvcpu x86_64-unknown-none

# 在开发循环中频繁检查
# 编辑代码 → check.sh → 修复问题 → commit.sh

检查项目：

代码格式（cargo fmt）
构建检查（cargo build）
Clippy 检查（cargo clippy）
文档构建（cargo doc）

3.3.6 批量推送组件变更

开发完成后，使用 scripts/push.sh 批量推送各组件的变更到远程：

# 推送单个组件
bash scripts/push.sh axvcpu

# 推送多个组件
bash scripts/push.sh arm_vcpu,axvcpu

# 推送所有有未推送提交的组件
bash scripts/push.sh all

# 推送到指定分支（默认当前分支）
bash scripts/push.sh all dev

脚本功能：

自动检测未推送的提交
自动跳过无变更的组件
汇总显示推送结果

3.3.7 更新 submodule 引用

使用 scripts/sync.sh 批量同步组件到远程最新，并更新主仓库引用：

# 同步单个组件到 dev 分支最新
bash scripts/sync.sh axvcpu

# 同步多个组件
bash scripts/sync.sh arm_vcpu,axvcpu

# 同步所有组件到 dev 分支最新
bash scripts/sync.sh all

# 同步所有组件到 main 分支最新
bash scripts/sync.sh all main

脚本功能：

自动初始化未初始化的子模块
自动切换到目标分支
检测本地修改并提示
显示同步前后的 commit 变化
汇总显示同步结果

四、版本发布流程

版本发布必须通过 axcrates 仓库统一处理，以确保所有组件版本号保持一致。所有组件使用相同版本号，便于管理和追踪，确保组件间的依赖关系正确，并且所有组件同时发布，避免版本混乱。

类型	版本格式	分支	发布方式	使用场景
预览版	`0.2.0-preview.1`	dev	直接推送	快速验证、内部测试
稳定版	`0.2.0`	main	PR 合并	正式发布、生产使用

4.1 发布流程概述

基于三、开发工作流详解，版本发布使用以下脚本协同完成：

┌─────────────────────────────────────────────────────────────────┐
│                      版本发布流程                                │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. version.sh    统一升级所有组件版本号                         │
│        │                                                        │
│        ▼                                                        │
│  2. commit.sh     提交版本变更到各组件                           │
│        │                                                        │
│        ▼                                                        │
│  3. push.sh       推送变更到远程仓库                             │
│        │                                                        │
│        ▼                                                        │
│  4. tag.sh        创建并推送版本标签                             │
│        │                                                        │
│        ▼                                                        │
│  5. publish.sh    发布到 crates.io                               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

4.2 预览版发布流程

根据组件开发及管理规范的要求，预览版只允许在 dev 上进行发布，因此，我们需要将所有修改合并到 dev 分支后，然后按照如下流程发布预览版！

4.2.1 统一升级版本号

在修改确保无误后，就可以通过 scripts/version.sh 统一升级组件的版本号了。

# 使用 version.sh 统一升级所有组件版本号
bash scripts/version.sh all 0.2.0-preview.1

# 验证版本号已更新
grep "^version" */Cargo.toml | head -5

4.2.2 提交并推送版本变更

# 使用 commit.sh 批量提交所有组件的版本变更
bash scripts/commit.sh all "chore: release v0.2.0-preview.1"

# 脚本会自动：
# - 检测有版本变更的组件
# - 提交变更
# - 推送到 dev 分支

4.2.3 创建标签

# 预览版可以选择不打标签，或打预览标签
bash scripts/tag.sh all v0.2.0-preview.1

4.2.4 推送标签

# 预览版可以选择不打标签，或打预览标签
bash scripts/tag.sh all v0.2.0-preview.1

4.2.5 发布到 crates.io

# 登录 crates.io
cargo login

# 使用 publish.sh 按依赖顺序发布所有组件
bash scripts/publish.sh

4.3 稳定版发布流程

根据组件开发及管理规范的要求，稳定版只允许在 mian（部分组件仓库使用 master 分支）上进行发布，因此，我们需要将所有修改合并到 master 分支后，然后按照如下流程发布预览版！

4.3.1 升级到稳定版版本号

在修改确保无误后，就可以通过 scripts/version.sh 统一升级组件的版本号了。

# 使用 version.sh 统一升级到稳定版版本号
bash scripts/version.sh all 0.2.0

# 验证版本号
grep "^version" */Cargo.toml | head -5

4.3.2 提交到 main 分支

# 提交版本变更
bash scripts/commit.sh all "chore: release v0.2.0"

4.3.3 创建 PR

在组件仓库中创建从自己使用的分支到主分支的 PR：target: main ← release-v0.2.0

4.3.4 合并 PR 后打标签

等待所有 PR 合并后：

# 切换到 main 分支并更新
git checkout main
git pull --recurse-submodules

# 同步子模块到 main 最新
bash scripts/sync.sh all main

# 验证版本号统一
grep "^version = " axvcpu/Cargo.toml

# 使用 tag.sh 统一创建并推送标签
bash scripts/tag.sh all v0.2.0

# 该脚本会：
# - 检查当前分支是 main
# - 在各子模块创建标签 v0.2.0
# - 在主仓库创建标签 v0.2.0
# - 推送所有标签到远程

4.3.5 发布到 crates.io

# 登录 crates.io
cargo login

# 使用 publish.sh 发布所有组件
bash scripts/publish.sh

# 发布顺序（自动处理）：
# Layer 0: axaddrspace, axvmconfig, axhvc, riscv-h
# Layer 1: axdevice_base, axvisor_api, axvcpu
# Layer 2: arm_vgic, x86_vlapic
# Layer 3: arm_vcpu, x86_vcpu, riscv_vcpu
# Layer 4: axdevice
# Layer 5: axvm
# Layer 6: axcrates

本文档由 ArceOS Hypervisor 团队维护

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

arceos-hypervisor

组件开发方案 #372

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

arceos-hypervisor

组件开发方案 #372

Uh oh!

Uh oh!

ZCShou Mar 2, 2026 Maintainer

组件开发方案

一、方案概述

1.1 背景与目的

1.2 仓库架构

1.3 架构关系图

1.4 核心开发原则

1.5 分支与版本对应关系

二、开发环境准备

2.1 配置 Git 环境

2.2 安装 Rust 工具链

三、开发工作流详解

3.1 工作流选择决策树

3.2 独立子组件开发

3.2.1 克隆子仓库

3.2.2 创建功能分支

3.2.3 修改代码

3.2.4 代码检查

3.2.5 本地测试

3.2.6 提交变更

3.2.7 创建 Pull Request

3.2.8 通知主仓库更新

3.3 多组件协同开发

3.3.1 获取 axcrates 仓库

3.3.2 批量切换组件分支

3.3.3 确定修改范围

3.3.4 修改组件代码

3.3.5 批量代码检查

3.3.6 批量推送组件变更

3.3.7 更新 submodule 引用

四、版本发布流程

4.1 发布流程概述

4.2 预览版发布流程

4.2.1 统一升级版本号

4.2.2 提交并推送版本变更

4.2.3 创建标签

4.2.4 推送标签

4.2.5 发布到 crates.io

4.3 稳定版发布流程

4.3.1 升级到稳定版版本号

4.3.2 提交到 main 分支

4.3.3 创建 PR

4.3.4 合并 PR 后打标签

4.3.5 发布到 crates.io

Replies: 0 comments

ZCShou
Mar 2, 2026
Maintainer