diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile new file mode 100644 index 000000000..7a6e048f2 --- /dev/null +++ b/.devcontainer/Dockerfile @@ -0,0 +1,71 @@ +# Copyright The SimpleKernel Contributors + +FROM ubuntu:latest + +ENV DEBIAN_FRONTEND=noninteractive + +RUN apt-get update && apt-get upgrade -y && \ + apt-get install --no-install-recommends --fix-missing -y \ + ca-certificates \ + git \ + build-essential \ + binutils \ + cmake \ + pkg-config \ + flex \ + bison \ + gawk \ + bc \ + cpio \ + device-tree-compiler \ + u-boot-tools \ + grub-common \ + xorriso \ + mtools \ + dosfstools \ + python3-dev \ + python3-cryptography \ + python3-pyelftools \ + python3-setuptools \ + uuid-dev \ + libgnutls28-dev \ + swig \ + libgtest-dev \ + doxygen \ + graphviz \ + lcov \ + qemu-system-x86 \ + qemu-system-arm \ + qemu-system-misc \ + gdb-multiarch \ + gcc-14 g++-14 \ + gcc-14-riscv64-linux-gnu g++-14-riscv64-linux-gnu \ + gcc-14-aarch64-linux-gnu g++-14-aarch64-linux-gnu \ + gcc-14-arm-linux-gnueabihf g++-14-arm-linux-gnueabihf \ + gcc-14-x86-64-linux-gnu g++-14-x86-64-linux-gnu && \ + update-alternatives \ + --install /usr/bin/gcc gcc /usr/bin/gcc-14 100 \ + --slave /usr/bin/g++ g++ /usr/bin/g++-14 \ + --slave /usr/bin/gcov gcov /usr/bin/gcov-14 && \ + update-alternatives \ + --install /usr/bin/riscv64-linux-gnu-gcc riscv64-linux-gnu-gcc \ + /usr/bin/riscv64-linux-gnu-gcc-14 100 \ + --slave /usr/bin/riscv64-linux-gnu-g++ riscv64-linux-gnu-g++ \ + /usr/bin/riscv64-linux-gnu-g++-14 && \ + update-alternatives \ + --install /usr/bin/aarch64-linux-gnu-gcc aarch64-linux-gnu-gcc \ + /usr/bin/aarch64-linux-gnu-gcc-14 100 \ + --slave /usr/bin/aarch64-linux-gnu-g++ aarch64-linux-gnu-g++ \ + /usr/bin/aarch64-linux-gnu-g++-14 && \ + update-alternatives \ + --install /usr/bin/arm-linux-gnueabihf-gcc arm-linux-gnueabihf-gcc \ + /usr/bin/arm-linux-gnueabihf-gcc-14 100 \ + --slave /usr/bin/arm-linux-gnueabihf-g++ arm-linux-gnueabihf-g++ \ + /usr/bin/arm-linux-gnueabihf-g++-14 && \ + update-alternatives \ + --install /usr/bin/x86_64-linux-gnu-gcc x86_64-linux-gnu-gcc \ + /usr/bin/x86_64-linux-gnu-gcc-14 100 \ + --slave /usr/bin/x86_64-linux-gnu-g++ x86_64-linux-gnu-g++ \ + /usr/bin/x86_64-linux-gnu-g++-14 && \ + apt-get autoremove -y && apt-get clean -y && \ + rm -rf /var/lib/apt/lists/* diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 114db0d43..aca834149 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -1,23 +1,23 @@ { - "name": "SimpleKernel DevContainer", - "image": "ptrnull233/simple_kernel:latest", - "postCreateCommand": "git submodule update --init --recursive", + "name": "SimpleKernel", + "build": { + "dockerfile": "Dockerfile" + }, + "postCreateCommand": "git config --global --add safe.directory ${containerWorkspaceFolder} && git submodule update --init --recursive", "customizations": { "vscode": { + "settings": { + "cmake.configureOnOpen": true, + "C_Cpp.default.cppStandard": "c++23", + "C_Cpp.default.cStandard": "c23" + }, "extensions": [ "ms-vscode.cpptools", - "ms-vscode.cpptools-extension-pack", "ms-vscode.cmake-tools", - "jebbs.plantuml", - "yzhang.markdown-all-in-one", - "eamodio.gitlens", - "github.copilot-chat", - "github.copilot", "ms-vscode.hexeditor", - "xaver.clang-format", "plorefice.devicetree", - "dan-c-underwood.arm", "zixuanwang.linkerscript", + "dan-c-underwood.arm", "zhwu95.riscv", "13xforever.language-x86-64-assembly" ] diff --git a/README.md b/README.md index 59a83bee0..fadcc20f6 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ SimpleKernel 是一个**面向 AI 辅助学习的现代化操作系统内核项 | 🌐 **三架构支持** | x86_64、RISC-V 64、AArch64,同一套接口适配不同硬件 | | 🧪 **测试驱动验证** | GoogleTest 测试套件验证 AI 生成的实现是否符合接口契约 | | 📖 **完整 Doxygen 文档** | 每个接口都有职责描述、前置条件、后置条件、使用示例 | -| 🏗️ **工程化基础设施** | CMake 构建、Docker 环境、CI/CD、clang-format/clang-tidy | +| 🏗️ **工程化基础设施** | CMake 构建、Dev Container 环境、CI/CD、clang-format/clang-tidy | ## 🤖 面向 AI 的设计理念 @@ -203,29 +203,33 @@ SimpleKernel 的接口按功能分为以下层次: ### 📋 系统要求 - **操作系统**: Linux (推荐 Ubuntu 24.04) 或 macOS -- **容器引擎**: Docker 20.10+ -- **工具链**: 已包含在 Docker 镜像中(GCC 交叉编译器、CMake、QEMU 等) +- **容器引擎**: Docker 或兼容的容器运行时 +- **工具链**: 已包含在 Dev Container 中(GCC 14 交叉编译器、CMake、QEMU 等) - **AI 工具(推荐)**: GitHub Copilot / ChatGPT / Claude ### 🛠️ 环境搭建 -**方式一:使用 Docker(推荐)** +**方式一:使用 Dev Container(推荐)** ```shell # 1. 克隆项目 git clone https://github.com/simple-xx/SimpleKernel.git cd SimpleKernel -git submodule update --init --recursive -# 2. 启动开发环境 -docker pull ptrnull233/simple_kernel:latest -docker run --name SimpleKernel-dev -itd -p 233:22 \ - -v $(pwd):/root/SimpleKernel ptrnull233/simple_kernel:latest +# 2. 使用 VS Code 打开并在容器中重新打开 +# 安装 Dev Containers 扩展后,点击左下角 >< 图标 +# 选择 "Reopen in Container" -# 3. 进入开发容器 -docker exec -it SimpleKernel-dev /bin/zsh +# 或使用 CLI +npm install -g @devcontainers/cli +devcontainer up --workspace-folder . +devcontainer exec --workspace-folder . bash ``` +> 也支持 **GitHub Codespaces**:点击仓库页面的 Code → Codespaces → Create codespace on main +> +> 详细说明见 [Dev Container 文档](./docs/docker.md) + **方式二:本地环境** 参考 [工具链文档](./docs/0_工具链.md) 配置本地开发环境。 @@ -410,7 +414,7 @@ subject: 不超过50字符,不加句号 - **系统启动**: [docs/1_系统启动.md](./docs/1_系统启动.md) - **调试输出**: [docs/2_调试输出.md](./docs/2_调试输出.md) - **中断**: [docs/3_中断.md](./docs/3_中断.md) -- **Docker**: [docs/docker.md](./docs/docker.md) +- **Dev Container**: [docs/docker.md](./docs/docker.md) - **接口重构计划**: [docs/TODO_interface_refactor.md](./docs/TODO_interface_refactor.md) ## 🤝 贡献指南 diff --git a/README_ENG.md b/README_ENG.md index ad3a5fc16..5cabeb02c 100644 --- a/README_ENG.md +++ b/README_ENG.md @@ -46,7 +46,7 @@ Unlike traditional OS teaching projects, SimpleKernel adopts an **Interface-Driv | 🌐 **Three-Architecture Support** | x86_64, RISC-V 64, AArch64 — one set of interfaces adapting to different hardware | | 🧪 **Test-Driven Verification** | GoogleTest test suites verify whether AI-generated implementations conform to interface contracts | | 📖 **Complete Doxygen Documentation** | Every interface has responsibility descriptions, preconditions, postconditions, and usage examples | -| 🏗️ **Engineering Infrastructure** | CMake build, Docker environment, CI/CD, clang-format/clang-tidy | +| 🏗️ **Engineering Infrastructure** | CMake build, Dev Container environment, CI/CD, clang-format/clang-tidy | ## 🤖 AI-Oriented Design Philosophy @@ -204,29 +204,33 @@ SimpleKernel's interfaces are organized into the following layers: ### 📋 System Requirements - **Operating System**: Linux (Ubuntu 24.04 recommended) or macOS -- **Container Engine**: Docker 20.10+ -- **Toolchain**: Included in Docker image (GCC cross-compilers, CMake, QEMU, etc.) +- **Container Engine**: Docker or compatible container runtime +- **Toolchain**: Included in Dev Container (GCC 14 cross-compilers, CMake, QEMU, etc.) - **AI Tools (recommended)**: GitHub Copilot / ChatGPT / Claude ### 🛠️ Environment Setup -**Option 1: Using Docker (Recommended)** +**Option 1: Using Dev Container (Recommended)** ```shell # 1. Clone the project git clone https://github.com/simple-xx/SimpleKernel.git cd SimpleKernel -git submodule update --init --recursive -# 2. Start development environment -docker pull ptrnull233/simple_kernel:latest -docker run --name SimpleKernel-dev -itd -p 233:22 \ - -v $(pwd):/root/SimpleKernel ptrnull233/simple_kernel:latest +# 2. Open in VS Code and reopen in container +# Install Dev Containers extension, click the >< icon at bottom-left +# Select "Reopen in Container" -# 3. Enter development container -docker exec -it SimpleKernel-dev /bin/zsh +# Or use CLI +npm install -g @devcontainers/cli +devcontainer up --workspace-folder . +devcontainer exec --workspace-folder . bash ``` +> Also supports **GitHub Codespaces**: Click Code → Codespaces → Create codespace on main +> +> See [Dev Container documentation](./docs/docker.md) for details. + **Option 2: Local Environment** Refer to [Toolchain Documentation](./docs/0_工具链.md) for local development environment setup. @@ -411,7 +415,7 @@ subject: max 50 chars, no period - **System Boot**: [docs/1_系统启动.md](./docs/1_系统启动.md) - **Debug Output**: [docs/2_调试输出.md](./docs/2_调试输出.md) - **Interrupts**: [docs/3_中断.md](./docs/3_中断.md) -- **Docker**: [docs/docker.md](./docs/docker.md) +- **Dev Container**: [docs/docker.md](./docs/docker.md) - **Interface Refactoring Plan**: [docs/TODO_interface_refactor.md](./docs/TODO_interface_refactor.md) ## 🤝 Contributing diff --git "a/docs/0_\345\267\245\345\205\267\351\223\276.md" "b/docs/0_\345\267\245\345\205\267\351\223\276.md" index a032c10fe..13ac44112 100644 --- "a/docs/0_\345\267\245\345\205\267\351\223\276.md" +++ "b/docs/0_\345\267\245\345\205\267\351\223\276.md" @@ -160,20 +160,22 @@ gdb bin/kernel.elf ## 辅助工具 -### Docker 容器化构建 +### Dev Container 开发环境 -项目提供 Docker 支持,确保构建环境的一致性: +项目提供 [Dev Container](https://containers.dev/) 支持,确保开发环境的一致性: -- **Dockerfile**: 定义了包含所有必要工具链的构建镜像 -- 支持所有目标架构的交叉编译 -- 详细使用方法见 [doc/docker.md](./doc/docker.md) +- 基于 Ubuntu,包含 GCC 14 交叉编译工具链(x86_64 / riscv64 / aarch64) +- 预装 QEMU、CMake、GDB 等全部构建和调试依赖 +- 支持 VS Code Dev Containers、GitHub Codespaces 和 devcontainer CLI +- 详细使用方法见 [Dev Container 文档](./docker.md) ```bash -# 使用预构建的 Docker 镜像 -docker run -it simplekernel/dev +# VS Code: 安装 Dev Containers 扩展后,选择 "Reopen in Container" -# 或从源码构建镜像 -docker build -t simplekernel-dev . +# CLI 方式 +npm install -g @devcontainers/cli +devcontainer up --workspace-folder . +devcontainer exec --workspace-folder . bash ``` ### 项目配置工具 @@ -217,4 +219,4 @@ RISC-V 工具链:https://github.com/riscv/riscv-gnu-toolchain 构建系统详细文档:[doc/build_system.md](./build_system.md) -Docker 使用说明:[doc/docker.md](./docker.md) +Dev Container 使用说明:[docs/docker.md](./docker.md) diff --git a/docs/docker.md b/docs/docker.md index 324ffb5bc..b98425253 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -1,257 +1,58 @@ -# Docker 开发环境配置 +# Dev Container 开发环境 -本文档介绍如何使用 Docker 搭建 SimpleKernel 的开发环境,支持两种方式:使用预构建镜像或自建镜像。 +本项目使用 [Dev Container](https://containers.dev/) 提供一致的开发环境,包含 GCC 14 交叉编译工具链、QEMU 和全部构建依赖。 -## 目录 +## 快速开始 -- [快速开始(推荐)](#快速开始推荐) -- [自建镜像](#自建镜像) -- [SSH 配置](#ssh-配置) -- [VSCode 远程开发](#vscode-远程开发) -- [常用命令](#常用命令) +### VS Code -## 快速开始(推荐) +1. 安装 [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) 扩展 +2. 打开项目目录 +3. 点击左下角 `><` 图标,选择 **Reopen in Container** +4. 等待容器构建完成(首次约 5-10 分钟) -### 1. 拉取并运行预构建镜像 +### GitHub Codespaces -```shell -# 进入项目目录 -cd SimpleKernel - -# 拉取最新镜像 -docker pull ptrnull233/simple_kernel:latest - -# 启动容器(包含完整的挂载配置) -docker run --name SimpleKernel-container -itd \ - -p 233:22 \ - -v ./:/root/SimpleKernel \ - -v ~/.ssh:/root/.ssh \ - -v ~/.gitconfig:/root/.gitconfig \ - ptrnull233/simple_kernel:latest - -# 进入容器 -docker exec -it SimpleKernel-container /bin/zsh -``` - -### 2. 验证环境 - -进入容器后,验证开发工具是否正常: - -```shell -# 检查编译器 -gcc --version -clang --version - -# 检查交叉编译工具链 -aarch64-linux-gnu-gcc --version -riscv64-linux-gnu-gcc --version - -# 检查构建工具 -cmake --version -make --version - -# 尝试构建项目 -cd /root/SimpleKernel -mkdir -p build && cd build -cmake .. -make -j$(nproc) -``` - -## 自建镜像 - -如果需要自定义镜像或预构建镜像不可用: - -### 1. 构建镜像 - -```shell -cd SimpleKernel -docker buildx build -t simple_kernel-docker-image ./tools -``` - -### 2. 启动自建镜像容器 - -```shell -docker run --name SimpleKernel-container -itd \ - -p 233:22 \ - -v ./:/root/SimpleKernel \ - -v ~/.ssh:/root/.ssh \ - -v ~/.gitconfig:/root/.gitconfig \ - simple_kernel-docker-image -``` - -### 3. 进入容器 - -```shell -docker exec -it SimpleKernel-container /bin/zsh -``` - -## SSH 配置 - -为了更好的开发体验,可以配置 SSH 远程访问: - -### 1. 生成 SSH 密钥(本地) - -```shell -# 检查是否已存在 SSH 密钥 -ls ~/.ssh/ - -# 如果不存在,生成新的 RSA 密钥 -# 将 替换为你的邮箱 -ssh-keygen -t rsa -b 4096 -C "" - -# 查看公钥内容 -cat ~/.ssh/id_rsa.pub -``` +点击仓库页面的 **Code → Codespaces → Create codespace on main**,环境自动就绪。 -### 2. 配置容器 SSH 访问 +### CLI ```shell -# 通过 SSH 连接到容器(首次需要密码) -ssh -p 233 zone@localhost -# 默认密码:zone +# 安装 devcontainer CLI +npm install -g @devcontainers/cli -# 在容器内创建 SSH 目录和授权文件 -mkdir -p /home/zone/.ssh -touch /home/zone/.ssh/authorized_keys -chmod 700 /home/zone/.ssh -chmod 600 /home/zone/.ssh/authorized_keys +# 构建并启动 +devcontainer up --workspace-folder . -# 将本地公钥内容添加到 authorized_keys -# 可以通过 docker exec 或直接编辑文件 +# 在容器内执行命令 +devcontainer exec --workspace-folder . cmake --preset=build_x86_64 ``` -### 3. 验证 SSH 免密登录 +## 验证环境 ```shell -# 现在应该可以免密登录 -ssh -p 233 zone@localhost -``` - -## VSCode 远程开发 - -### 1. 安装插件 - -在 VSCode 中安装以下插件: -- `Remote - SSH` -- `Remote - Containers` (可选) - -### 2. 配置 SSH 连接 - -1. 打开命令面板:`Ctrl+Shift+P` (Windows/Linux) 或 `Cmd+Shift+P` (macOS) -2. 输入:`Remote-SSH: Add New SSH Host...` -3. 输入 SSH 命令:`ssh -p 233 zone@localhost` -4. 选择配置文件保存位置 - -### 3. 连接并打开项目 - -1. 打开命令面板:`Ctrl+Shift+P` / `Cmd+Shift+P` -2. 输入:`Remote-SSH: Connect to Host...` -3. 选择 `zone@localhost` -4. 在新窗口中打开文件夹:`/home/zone/SimpleKernel` - -### 4. 推荐插件(远程环境) - -在远程环境中安装以下插件以获得更好的开发体验: -- C/C++ Extension Pack -- CMake Tools -- GitLens -- Clang-Format - -## 常用命令 - -### 容器管理 - -```shell -# 查看容器状态 -docker ps -a - -# 启动已停止的容器 -docker start SimpleKernel-container - -# 停止容器 -docker stop SimpleKernel-container - -# 重启容器 -docker restart SimpleKernel-container - -# 删除容器 -docker rm SimpleKernel-container - -# 查看容器日志 -docker logs SimpleKernel-container -``` - -### 镜像管理 - -```shell -# 查看本地镜像 -docker images - -# 删除镜像 -docker rmi simple_kernel-docker-image - -# 清理未使用的镜像 -docker image prune +gcc --version # GCC 14 +aarch64-linux-gnu-gcc --version # aarch64 交叉编译器 +riscv64-linux-gnu-gcc --version # riscv64 交叉编译器 +cmake --version +qemu-system-x86_64 --version ``` -### 文件传输 +## 构建与运行 ```shell -# 从容器复制文件到主机 -docker cp SimpleKernel-container:/path/to/file /host/path/ - -# 从主机复制文件到容器 -docker cp /host/path/file SimpleKernel-container:/path/to/ -``` - -## 故障排除 - -### 常见问题 - -1. **端口 233 已被占用** - ```shell - # 检查端口占用 - lsof -i :233 - # 或使用其他端口 - docker run -p 234:22 ... - ``` - -2. **容器启动失败** - ```shell - # 查看详细错误信息 - docker logs SimpleKernel-container - ``` +# 配置 + 编译(三选一) +cmake --preset=build_x86_64 && cmake --build build_x86_64 --target SimpleKernel +cmake --preset=build_riscv64 && cmake --build build_riscv64 --target SimpleKernel +cmake --preset=build_aarch64 && cmake --build build_aarch64 --target SimpleKernel -3. **挂载目录权限问题** - ```shell - # 检查目录权限 - ls -la ./ - # 确保 Docker 有权限访问挂载目录 - ``` +# 运行(在对应 build 目录下) +make run -4. **SSH 连接失败** - ```shell - # 检查容器是否在运行 - docker ps - # 检查 SSH 服务状态 - docker exec -it SimpleKernel-container systemctl status ssh - ``` - -### 重置环境 - -如果遇到无法解决的问题,可以重置整个环境: - -```shell -# 停止并删除容器 -docker stop SimpleKernel-container -docker rm SimpleKernel-container +# 调试 +make debug # GDB 连接 localhost:1234 -# 重新创建容器 -docker run --name SimpleKernel-container -itd \ - -p 233:22 \ - -v ./:/root/SimpleKernel \ - -v ~/.ssh:/root/.ssh \ - -v ~/.gitconfig:/root/.gitconfig \ - ptrnull233/simple_kernel:latest +# 单元测试 + 覆盖率(仅 host 架构) +cmake --build build_x86_64 --target unit-test coverage ```