Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 71 additions & 0 deletions .devcontainer/Dockerfile
Original file line number Diff line number Diff line change
@@ -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 \
Comment on lines +7 to +8
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/*
22 changes: 11 additions & 11 deletions .devcontainer/devcontainer.json
Original file line number Diff line number Diff line change
@@ -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"
]
Expand Down
28 changes: 16 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 的设计理念

Expand Down Expand Up @@ -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
```
Comment on lines 214 to 227

> 也支持 **GitHub Codespaces**:点击仓库页面的 Code → Codespaces → Create codespace on main
>
> 详细说明见 [Dev Container 文档](./docs/docker.md)

**方式二:本地环境**

参考 [工具链文档](./docs/0_工具链.md) 配置本地开发环境。
Expand Down Expand Up @@ -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)

## 🤝 贡献指南
Expand Down
28 changes: 16 additions & 12 deletions README_ENG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
```
Comment on lines 215 to 228

> 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.
Expand Down Expand Up @@ -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
Expand Down
22 changes: 12 additions & 10 deletions docs/0_工具链.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

### 项目配置工具
Expand Down Expand Up @@ -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)
Loading
Loading