Skip to content

Commit d4def7e

Browse files
authored
docs(devcontainer): migrate from Docker to Dev Container workflow (#195)
- Add .devcontainer/Dockerfile with GCC 14 cross-compilation toolchains - Update devcontainer.json to build from local Dockerfile with VS Code settings - Rewrite docs/docker.md as Dev Container guide (VS Code, Codespaces, CLI) - Update README.md, README_ENG.md, docs/0_工具链.md: Docker → Dev Container Signed-off-by: Niu Zhihong <zhihong@nzhnb.com>
1 parent 7067923 commit d4def7e

File tree

6 files changed

+160
-278
lines changed

6 files changed

+160
-278
lines changed

.devcontainer/Dockerfile

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Copyright The SimpleKernel Contributors
2+
3+
FROM ubuntu:latest
4+
5+
ENV DEBIAN_FRONTEND=noninteractive
6+
7+
RUN apt-get update && apt-get upgrade -y && \
8+
apt-get install --no-install-recommends --fix-missing -y \
9+
ca-certificates \
10+
git \
11+
build-essential \
12+
binutils \
13+
cmake \
14+
pkg-config \
15+
flex \
16+
bison \
17+
gawk \
18+
bc \
19+
cpio \
20+
device-tree-compiler \
21+
u-boot-tools \
22+
grub-common \
23+
xorriso \
24+
mtools \
25+
dosfstools \
26+
python3-dev \
27+
python3-cryptography \
28+
python3-pyelftools \
29+
python3-setuptools \
30+
uuid-dev \
31+
libgnutls28-dev \
32+
swig \
33+
libgtest-dev \
34+
doxygen \
35+
graphviz \
36+
lcov \
37+
qemu-system-x86 \
38+
qemu-system-arm \
39+
qemu-system-misc \
40+
gdb-multiarch \
41+
gcc-14 g++-14 \
42+
gcc-14-riscv64-linux-gnu g++-14-riscv64-linux-gnu \
43+
gcc-14-aarch64-linux-gnu g++-14-aarch64-linux-gnu \
44+
gcc-14-arm-linux-gnueabihf g++-14-arm-linux-gnueabihf \
45+
gcc-14-x86-64-linux-gnu g++-14-x86-64-linux-gnu && \
46+
update-alternatives \
47+
--install /usr/bin/gcc gcc /usr/bin/gcc-14 100 \
48+
--slave /usr/bin/g++ g++ /usr/bin/g++-14 \
49+
--slave /usr/bin/gcov gcov /usr/bin/gcov-14 && \
50+
update-alternatives \
51+
--install /usr/bin/riscv64-linux-gnu-gcc riscv64-linux-gnu-gcc \
52+
/usr/bin/riscv64-linux-gnu-gcc-14 100 \
53+
--slave /usr/bin/riscv64-linux-gnu-g++ riscv64-linux-gnu-g++ \
54+
/usr/bin/riscv64-linux-gnu-g++-14 && \
55+
update-alternatives \
56+
--install /usr/bin/aarch64-linux-gnu-gcc aarch64-linux-gnu-gcc \
57+
/usr/bin/aarch64-linux-gnu-gcc-14 100 \
58+
--slave /usr/bin/aarch64-linux-gnu-g++ aarch64-linux-gnu-g++ \
59+
/usr/bin/aarch64-linux-gnu-g++-14 && \
60+
update-alternatives \
61+
--install /usr/bin/arm-linux-gnueabihf-gcc arm-linux-gnueabihf-gcc \
62+
/usr/bin/arm-linux-gnueabihf-gcc-14 100 \
63+
--slave /usr/bin/arm-linux-gnueabihf-g++ arm-linux-gnueabihf-g++ \
64+
/usr/bin/arm-linux-gnueabihf-g++-14 && \
65+
update-alternatives \
66+
--install /usr/bin/x86_64-linux-gnu-gcc x86_64-linux-gnu-gcc \
67+
/usr/bin/x86_64-linux-gnu-gcc-14 100 \
68+
--slave /usr/bin/x86_64-linux-gnu-g++ x86_64-linux-gnu-g++ \
69+
/usr/bin/x86_64-linux-gnu-g++-14 && \
70+
apt-get autoremove -y && apt-get clean -y && \
71+
rm -rf /var/lib/apt/lists/*

.devcontainer/devcontainer.json

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,23 @@
11
{
2-
"name": "SimpleKernel DevContainer",
3-
"image": "ptrnull233/simple_kernel:latest",
4-
"postCreateCommand": "git submodule update --init --recursive",
2+
"name": "SimpleKernel",
3+
"build": {
4+
"dockerfile": "Dockerfile"
5+
},
6+
"postCreateCommand": "git config --global --add safe.directory ${containerWorkspaceFolder} && git submodule update --init --recursive",
57
"customizations": {
68
"vscode": {
9+
"settings": {
10+
"cmake.configureOnOpen": true,
11+
"C_Cpp.default.cppStandard": "c++23",
12+
"C_Cpp.default.cStandard": "c23"
13+
},
714
"extensions": [
815
"ms-vscode.cpptools",
9-
"ms-vscode.cpptools-extension-pack",
1016
"ms-vscode.cmake-tools",
11-
"jebbs.plantuml",
12-
"yzhang.markdown-all-in-one",
13-
"eamodio.gitlens",
14-
"github.copilot-chat",
15-
"github.copilot",
1617
"ms-vscode.hexeditor",
17-
"xaver.clang-format",
1818
"plorefice.devicetree",
19-
"dan-c-underwood.arm",
2019
"zixuanwang.linkerscript",
20+
"dan-c-underwood.arm",
2121
"zhwu95.riscv",
2222
"13xforever.language-x86-64-assembly"
2323
]

README.md

Lines changed: 16 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ SimpleKernel 是一个**面向 AI 辅助学习的现代化操作系统内核项
4747
| 🌐 **三架构支持** | x86_64、RISC-V 64、AArch64,同一套接口适配不同硬件 |
4848
| 🧪 **测试驱动验证** | GoogleTest 测试套件验证 AI 生成的实现是否符合接口契约 |
4949
| 📖 **完整 Doxygen 文档** | 每个接口都有职责描述、前置条件、后置条件、使用示例 |
50-
| 🏗️ **工程化基础设施** | CMake 构建、Docker 环境、CI/CD、clang-format/clang-tidy |
50+
| 🏗️ **工程化基础设施** | CMake 构建、Dev Container 环境、CI/CD、clang-format/clang-tidy |
5151

5252
## 🤖 面向 AI 的设计理念
5353

@@ -203,29 +203,33 @@ SimpleKernel 的接口按功能分为以下层次:
203203
### 📋 系统要求
204204

205205
- **操作系统**: Linux (推荐 Ubuntu 24.04) 或 macOS
206-
- **容器引擎**: Docker 20.10+
207-
- **工具链**: 已包含在 Docker 镜像中(GCC 交叉编译器、CMake、QEMU 等)
206+
- **容器引擎**: Docker 或兼容的容器运行时
207+
- **工具链**: 已包含在 Dev Container 中(GCC 14 交叉编译器、CMake、QEMU 等)
208208
- **AI 工具(推荐)**: GitHub Copilot / ChatGPT / Claude
209209

210210
### 🛠️ 环境搭建
211211

212-
**方式一:使用 Docker(推荐)**
212+
**方式一:使用 Dev Container(推荐)**
213213

214214
```shell
215215
# 1. 克隆项目
216216
git clone https://github.com/simple-xx/SimpleKernel.git
217217
cd SimpleKernel
218-
git submodule update --init --recursive
219218

220-
# 2. 启动开发环境
221-
docker pull ptrnull233/simple_kernel:latest
222-
docker run --name SimpleKernel-dev -itd -p 233:22 \
223-
-v $(pwd):/root/SimpleKernel ptrnull233/simple_kernel:latest
219+
# 2. 使用 VS Code 打开并在容器中重新打开
220+
# 安装 Dev Containers 扩展后,点击左下角 >< 图标
221+
# 选择 "Reopen in Container"
224222

225-
# 3. 进入开发容器
226-
docker exec -it SimpleKernel-dev /bin/zsh
223+
# 或使用 CLI
224+
npm install -g @devcontainers/cli
225+
devcontainer up --workspace-folder .
226+
devcontainer exec --workspace-folder . bash
227227
```
228228

229+
> 也支持 **GitHub Codespaces**:点击仓库页面的 Code → Codespaces → Create codespace on main
230+
>
231+
> 详细说明见 [Dev Container 文档](./docs/docker.md)
232+
229233
**方式二:本地环境**
230234

231235
参考 [工具链文档](./docs/0_工具链.md) 配置本地开发环境。
@@ -410,7 +414,7 @@ subject: 不超过50字符,不加句号
410414
- **系统启动**: [docs/1_系统启动.md](./docs/1_系统启动.md)
411415
- **调试输出**: [docs/2_调试输出.md](./docs/2_调试输出.md)
412416
- **中断**: [docs/3_中断.md](./docs/3_中断.md)
413-
- **Docker**: [docs/docker.md](./docs/docker.md)
417+
- **Dev Container**: [docs/docker.md](./docs/docker.md)
414418
- **接口重构计划**: [docs/TODO_interface_refactor.md](./docs/TODO_interface_refactor.md)
415419

416420
## 🤝 贡献指南

README_ENG.md

Lines changed: 16 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ Unlike traditional OS teaching projects, SimpleKernel adopts an **Interface-Driv
4646
| 🌐 **Three-Architecture Support** | x86_64, RISC-V 64, AArch64 — one set of interfaces adapting to different hardware |
4747
| 🧪 **Test-Driven Verification** | GoogleTest test suites verify whether AI-generated implementations conform to interface contracts |
4848
| 📖 **Complete Doxygen Documentation** | Every interface has responsibility descriptions, preconditions, postconditions, and usage examples |
49-
| 🏗️ **Engineering Infrastructure** | CMake build, Docker environment, CI/CD, clang-format/clang-tidy |
49+
| 🏗️ **Engineering Infrastructure** | CMake build, Dev Container environment, CI/CD, clang-format/clang-tidy |
5050

5151
## 🤖 AI-Oriented Design Philosophy
5252

@@ -204,29 +204,33 @@ SimpleKernel's interfaces are organized into the following layers:
204204
### 📋 System Requirements
205205

206206
- **Operating System**: Linux (Ubuntu 24.04 recommended) or macOS
207-
- **Container Engine**: Docker 20.10+
208-
- **Toolchain**: Included in Docker image (GCC cross-compilers, CMake, QEMU, etc.)
207+
- **Container Engine**: Docker or compatible container runtime
208+
- **Toolchain**: Included in Dev Container (GCC 14 cross-compilers, CMake, QEMU, etc.)
209209
- **AI Tools (recommended)**: GitHub Copilot / ChatGPT / Claude
210210

211211
### 🛠️ Environment Setup
212212

213-
**Option 1: Using Docker (Recommended)**
213+
**Option 1: Using Dev Container (Recommended)**
214214

215215
```shell
216216
# 1. Clone the project
217217
git clone https://github.com/simple-xx/SimpleKernel.git
218218
cd SimpleKernel
219-
git submodule update --init --recursive
220219

221-
# 2. Start development environment
222-
docker pull ptrnull233/simple_kernel:latest
223-
docker run --name SimpleKernel-dev -itd -p 233:22 \
224-
-v $(pwd):/root/SimpleKernel ptrnull233/simple_kernel:latest
220+
# 2. Open in VS Code and reopen in container
221+
# Install Dev Containers extension, click the >< icon at bottom-left
222+
# Select "Reopen in Container"
225223

226-
# 3. Enter development container
227-
docker exec -it SimpleKernel-dev /bin/zsh
224+
# Or use CLI
225+
npm install -g @devcontainers/cli
226+
devcontainer up --workspace-folder .
227+
devcontainer exec --workspace-folder . bash
228228
```
229229

230+
> Also supports **GitHub Codespaces**: Click Code → Codespaces → Create codespace on main
231+
>
232+
> See [Dev Container documentation](./docs/docker.md) for details.
233+
230234
**Option 2: Local Environment**
231235

232236
Refer to [Toolchain Documentation](./docs/0_工具链.md) for local development environment setup.
@@ -411,7 +415,7 @@ subject: max 50 chars, no period
411415
- **System Boot**: [docs/1_系统启动.md](./docs/1_系统启动.md)
412416
- **Debug Output**: [docs/2_调试输出.md](./docs/2_调试输出.md)
413417
- **Interrupts**: [docs/3_中断.md](./docs/3_中断.md)
414-
- **Docker**: [docs/docker.md](./docs/docker.md)
418+
- **Dev Container**: [docs/docker.md](./docs/docker.md)
415419
- **Interface Refactoring Plan**: [docs/TODO_interface_refactor.md](./docs/TODO_interface_refactor.md)
416420

417421
## 🤝 Contributing

docs/0_工具链.md

Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -160,20 +160,22 @@ gdb bin/kernel.elf
160160

161161
## 辅助工具
162162

163-
### Docker 容器化构建
163+
### Dev Container 开发环境
164164

165-
项目提供 Docker 支持,确保构建环境的一致性
165+
项目提供 [Dev Container](https://containers.dev/) 支持,确保开发环境的一致性
166166

167-
- **Dockerfile**: 定义了包含所有必要工具链的构建镜像
168-
- 支持所有目标架构的交叉编译
169-
- 详细使用方法见 [doc/docker.md](./doc/docker.md)
167+
- 基于 Ubuntu,包含 GCC 14 交叉编译工具链(x86_64 / riscv64 / aarch64)
168+
- 预装 QEMU、CMake、GDB 等全部构建和调试依赖
169+
- 支持 VS Code Dev Containers、GitHub Codespaces 和 devcontainer CLI
170+
- 详细使用方法见 [Dev Container 文档](./docker.md)
170171

171172
```bash
172-
# 使用预构建的 Docker 镜像
173-
docker run -it simplekernel/dev
173+
# VS Code: 安装 Dev Containers 扩展后,选择 "Reopen in Container"
174174

175-
# 或从源码构建镜像
176-
docker build -t simplekernel-dev .
175+
# CLI 方式
176+
npm install -g @devcontainers/cli
177+
devcontainer up --workspace-folder .
178+
devcontainer exec --workspace-folder . bash
177179
```
178180

179181
### 项目配置工具
@@ -217,4 +219,4 @@ RISC-V 工具链:https://github.com/riscv/riscv-gnu-toolchain
217219

218220
构建系统详细文档:[doc/build_system.md](./build_system.md)
219221

220-
Docker 使用说明:[doc/docker.md](./docker.md)
222+
Dev Container 使用说明:[docs/docker.md](./docker.md)

0 commit comments

Comments
 (0)