一、 开发环境搭建（Windows/WSL2/Docker）

1.1 基础环境

  • 宿主机：Windows 11（建议内存 16GB 以上）。
  • WSL2：安装 Ubuntu 发行版（如 Ubuntu-D），代码一定要放在 WSL 文件系统内（如 /home/user/asterinas），不要放在 C:\ 盘，否则性能极差。
  • Docker Desktop：安装并启用 WSL2 集成。在 Settings -> Resources -> WSL Integration 中，务必打开你使用的发行版（如 Ubuntu-D）的开关。
  • 网络配置：在 Windows 用户目录创建 .wslconfig，配置 networkingMode=mirrored 和 autoProxy=true，解决 NAT 模式下代理不通的问题。代理软件需开启“允许局域网连接”。

1.2 启动 Dev Container

  • 在 WSL 终端克隆代码：git clone https://github.com/asterinas/asterinas
  • 使用 VS Code 打开该文件夹，按 F1 选择 Dev Containers: Reopen in Container。
  • 首次启动会自动拉取 asterinas/dev 镜像并安装 VS Code Server。若卡在下载，请确保容器网络畅通。
  • 持久化配置：建议在 .devcontainer/devcontainer.json 的 mounts 中挂载 ~/.vscode-server 目录，避免每次重建容器重复下载。
  • 插件安装：在 customizations.vscode.extensions 中添加你需要的插件（如 rust-lang.rust-analyzer, vadimcn.vscode-lldb, eamodio.gitlens），重建容器后会自动安装。

1.3 AI 辅助工具（超级外挂）

Dev Container 已预装 claude 和 codex CLI。

  • Claude Code / Codex CLI：在项目根目录运行，会自动读取 AGENTS.md 和 CLAUDE.md，理解 Asterinas 的编译规范和代码风格。
  • 账号订阅建议：推荐购买 ChatGPT Plus（含 Codex 额度），或使用 API Key 按量付费。不要买共享号，容易封号。

二、 编译、运行与调试

2.1 核心 Makefile 命令

Asterinas 的构建、运行、测试全部通过根目录的 Makefile 管理。

  • make kernel：编译内核，并生成 initramfs（初始内存文件系统，包含基础用户态程序）。
  • make run_kernel：编译并在 QEMU 中启动内核。成功后会进入 Asterinas 内部的 ~ # 终端。
  • make run_kernel LOG_LEVEL=debug：打开详细日志运行，便于排查问题。

2.2 验证流程（极其重要）

修改代码后，必须按以下顺序验证：

  1. 格式与静态检查：make check（检查空格、rustfmt、clippy、拼写等）。报错就运行 make format 自动修复。
  2. 单元测试：make test（用户态）、make ktest（内核态）。
  3. 回归测试：make run_kernel AUTO_TEST=regression。如果末尾输出 All regression tests passed.，说明没有破坏现有功能。
  4. 手动验证：进入 Asterinas 终端，手动运行相关命令验证修改是否生效。

三、 开源贡献标准流程（SOP）

3.1 寻找任务

  • 筛选标签：在 GitHub Issues 页面筛选 C-good-first-issue（新手任务）、help wanted（急需帮助）、C-bug（修复 Bug）、C-documentation（文档）、C-test（测试）。
  • 避坑指南：不要碰 C-feature（新功能）、C-architecture（架构重构）以及带有 RFC 或 discussion 标签的哲学辩论帖。

3.2 认领任务（防撞车）

  • 必须认领：在 Issue 下方评论 @boterinas claim，机器人会自动把你设为 Assignee。
  • 有人讨论但无人认领：先礼貌留言询问是否有人正在做，等待 24-48 小时无人反对后，再 claim。
  • 绝对不要抢：如果有人已经留言“我正在做”或已发起 PR，不要抢别人的任务。

3.3 开发与提交

  • 建立分支：git checkout -b fix-issue-xxxx。
  • 原子提交：一个提交只做一件事，提交信息使用祈使语气（如 Fix u32 underflow in ...），首行不超过 72 字符。
  • 同步主分支：使用 git rebase origin/main 把你的提交“搬”到最新代码上，保持历史线性。
  • 整理提交：使用 git rebase -i HEAD~N 合并多余的 fix 提交。修改后需 git push -f 强制推送。
  • 发起 PR：在 PR 描述中用 Fixes #Issue编号 关联任务。若涉及用户可见 API，必须同步更新 Linux Compatibility 文档。

3.4 遇到困难与放弃（非常重要）

  • 求助：在 Issue 中描述你卡住的具体技术点和已尝试的方案，维护者通常会指引方向。
  • 体面放弃：如果确实做不出来，不要“占坑不干活”。在 Issue 中诚恳说明情况，分享你的排查记录，然后评论 @boterinas unclaim 释放任务。维护者会认为你非常专业。

四、 附录（杂项与冷知识）

  • C- 前缀的含义：C 代表 Category（分类）或 Component（组件），与 C 语言毫无关系。例如 C-bug、C-documentation。
  • C-documentation 改什么：修补代码注释（Rust ///）、更新官方书籍（book/）、修正拼写与死链、更新 Linux 兼容性表格。
  • C-test 改什么：补充边界单元测试、添加回归测试脚本（test/initramfs/src/regression/）、解除被屏蔽的测试用例。
  • initramfs 是什么：全称 initial RAM filesystem，是内核启动早期加载到内存中的临时根文件系统（cpio 归档）。Asterinas 用它作为最小用户环境来运行测试。
  • Docker 镜像与容器：镜像是只读模板（大），容器是可写实例（小）。删除容器不会删除镜像，重建容器会丢失容器内临时安装的软件，但挂载的代码和配置不会丢。
  • Docker 磁盘空间回收：删除镜像后，Windows 磁盘空间不会立刻变小。需用 diskpart 或 Optimize-VHD 压缩 ext4.vhdx 虚拟硬盘。
  • git rebase vs git merge：大项目偏爱 rebase，是为了保持线性历史，方便 git bisect 二分查找排错，并避免无意义的合并提交污染主分支历史。
  • VS Code 插件持久化：手动在容器内安装的插件，重建容器后会丢失；写进 devcontainer.json 的 extensions 数组中才会自动重装。