mirror of
https://github.com/Leonmmcoset/cleonos.git
synced 2026-04-21 10:40:00 +00:00
README
This commit is contained in:
125
README.md
Normal file
125
README.md
Normal file
@@ -0,0 +1,125 @@
|
||||
# CLeonOS
|
||||
|
||||
[English](README.md) | [简体中文](README.zh-CN.md)
|
||||
|
||||
Experimental x86_64 operating system project with a C kernel, Rust-assisted runtime pieces, user-space ELF apps, and a stage-based development history.
|
||||
|
||||
## Highlights
|
||||
|
||||
- x86_64 kernel booted by Limine
|
||||
- RAM-disk VFS layout (`/system`, `/shell`, `/temp`, `/driver`)
|
||||
- Virtual TTY subsystem (multi TTY, ANSI handling, cursor, PSF font support)
|
||||
- Keyboard and mouse input stack, plus desktop mode on TTY2
|
||||
- User-space ELF app model with syscall ABI (`int 0x80`)
|
||||
- User shell with external command apps (`ls`, `cat`, `grep`, `mkdir`, `cp`, `mv`, `rm`, etc.)
|
||||
- Pipe and redirection support in user shell (`|`, `>`, `>>`)
|
||||
- Optional host-side CLeonOS-Wine runner (Python + Unicorn) in [`wine/`](wine)
|
||||
|
||||
## Repository Layout
|
||||
|
||||
```text
|
||||
.
|
||||
|- clks/ # Kernel sources (arch, drivers, scheduler, tty, syscall, ...)
|
||||
|- cleonos/ # Userland runtime, libc-like layer, user apps, Rust user library
|
||||
|- ramdisk/ # Static files copied into runtime ramdisk
|
||||
|- configs/ # Boot configuration (Limine)
|
||||
|- cmake/ # Shared CMake scripts (tool checks, logging, limine setup)
|
||||
|- docs/ # Stage documents and syscall reference
|
||||
|- wine/ # Host runner for CLeonOS user ELF (no full VM required)
|
||||
|- CMakeLists.txt # Main build definition
|
||||
|- Makefile # Developer-friendly wrapper around CMake targets
|
||||
```
|
||||
|
||||
## Build Requirements
|
||||
|
||||
Minimum required tools:
|
||||
|
||||
- `cmake` (>= 3.20)
|
||||
- `make`
|
||||
- `git`
|
||||
- `tar`
|
||||
- `xorriso`
|
||||
- `sh` (POSIX shell)
|
||||
- `rustc`
|
||||
- Kernel/user toolchain (resolved automatically with fallback):
|
||||
- kernel: `x86_64-elf-gcc`/`x86_64-elf-ld` (or fallback `gcc`/`clang` + `ld.lld`)
|
||||
- user: `cc` + `ld`
|
||||
|
||||
For building Limine from source, install extras such as `autoconf`, `automake`, `libtool`, `pkg-config`, `mtools`, and `nasm`.
|
||||
|
||||
For runtime:
|
||||
|
||||
- `qemu-system-x86_64` (for `make run` / `make debug`)
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
git clone <your-repo-url>
|
||||
cd cleonos
|
||||
git submodule update --init --recursive
|
||||
make run
|
||||
```
|
||||
|
||||
If you already have Limine artifacts and want to skip configure:
|
||||
|
||||
```bash
|
||||
make run LIMINE_SKIP_CONFIGURE=1
|
||||
```
|
||||
|
||||
## Common Targets
|
||||
|
||||
- `make setup` - check tools and prepare Limine
|
||||
- `make kernel` - build kernel ELF
|
||||
- `make userapps` - build user-space ELF apps
|
||||
- `make ramdisk` - package runtime ramdisk
|
||||
- `make iso` - build bootable ISO
|
||||
- `make run` - launch QEMU
|
||||
- `make debug` - launch QEMU with `-s -S` for GDB
|
||||
- `make clean` - clean `build/x86_64`
|
||||
- `make clean-all` - clean all build output
|
||||
|
||||
## Debugging (GDB)
|
||||
|
||||
Start debug VM:
|
||||
|
||||
```bash
|
||||
make debug
|
||||
```
|
||||
|
||||
Attach in another terminal:
|
||||
|
||||
```bash
|
||||
gdb build/x86_64/clks_kernel.elf
|
||||
(gdb) target remote :1234
|
||||
```
|
||||
|
||||
## User Shell Examples
|
||||
|
||||
```sh
|
||||
help
|
||||
ls /shell
|
||||
cat /shell/init.cmd
|
||||
grep -n exec /shell/init.cmd
|
||||
cat /shell/init.cmd | grep -n exec
|
||||
ls /shell > /temp/shell_list.txt
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
- Stage index: [`docs/README.md`](docs/README.md)
|
||||
- Syscall ABI reference: [`docs/syscall.md`](docs/syscall.md)
|
||||
|
||||
## CI
|
||||
|
||||
GitHub Actions workflow [`build-os.yml`](.github/workflows/build-os.yml) builds the OS ISO on push and pull request, and uploads the ISO as an artifact.
|
||||
|
||||
## Contributing
|
||||
|
||||
1. Fork and create a feature branch.
|
||||
2. Keep changes stage-oriented and update docs when behavior changes.
|
||||
3. Run at least `make iso` before opening a PR.
|
||||
4. Include boot log snippets or screenshots for kernel/user visible changes.
|
||||
|
||||
## License
|
||||
|
||||
Apache-2.0. See [`License`](License).
|
||||
125
README.zh-CN.md
Normal file
125
README.zh-CN.md
Normal file
@@ -0,0 +1,125 @@
|
||||
# CLeonOS
|
||||
|
||||
[English](README.md) | [简体中文](README.zh-CN.md)
|
||||
|
||||
一个实验性的 x86_64 操作系统项目，包含 C 内核、Rust 辅助运行时代码、用户态 ELF 应用，以及按 Stage 演进的开发历史。
|
||||
|
||||
## 项目特性
|
||||
|
||||
- 基于 Limine 启动的 x86_64 内核
|
||||
- RAM-disk VFS 目录布局（`/system`、`/shell`、`/temp`、`/driver`）
|
||||
- 虚拟 TTY 子系统（多 TTY、ANSI、光标、PSF 字体）
|
||||
- 键盘/鼠标输入栈，TTY2 提供桌面模式
|
||||
- 用户态 ELF 应用模型，syscall ABI 使用 `int 0x80`
|
||||
- 用户 Shell + 外部命令 ELF（`ls`、`cat`、`grep`、`mkdir`、`cp`、`mv`、`rm` 等）
|
||||
- Shell 管道与重定向（`|`、`>`、`>>`）
|
||||
- 可选主机侧 CLeonOS-Wine 运行器（Python + Unicorn），位于 [`wine/`](wine)
|
||||
|
||||
## 仓库结构
|
||||
|
||||
```text
|
||||
.
|
||||
|- clks/ # 内核源码（架构、驱动、调度、TTY、syscall 等）
|
||||
|- cleonos/ # 用户态运行时、基础库、用户应用、Rust 用户库
|
||||
|- ramdisk/ # 运行时 ramdisk 的静态文件
|
||||
|- configs/ # 启动配置（Limine）
|
||||
|- cmake/ # CMake 公共脚本（工具检查、日志、limine 初始化）
|
||||
|- docs/ # Stage 文档与 syscall 文档
|
||||
|- wine/ # 主机侧用户 ELF 运行器（无需完整虚拟机）
|
||||
|- CMakeLists.txt # 主构建定义
|
||||
|- Makefile # 面向开发者的 CMake 包装入口
|
||||
```
|
||||
|
||||
## 构建依赖
|
||||
|
||||
最低需要：
|
||||
|
||||
- `cmake`（>= 3.20）
|
||||
- `make`
|
||||
- `git`
|
||||
- `tar`
|
||||
- `xorriso`
|
||||
- `sh`（POSIX shell）
|
||||
- `rustc`
|
||||
- 内核/用户工具链（会自动回退查找）：
|
||||
- 内核：`x86_64-elf-gcc` / `x86_64-elf-ld`（可回退到 `gcc`/`clang` + `ld.lld`）
|
||||
- 用户态：`cc` + `ld`
|
||||
|
||||
如需从源码构建 Limine，请安装额外依赖：`autoconf`、`automake`、`libtool`、`pkg-config`、`mtools`、`nasm`。
|
||||
|
||||
运行时还需要：
|
||||
|
||||
- `qemu-system-x86_64`（用于 `make run` / `make debug`）
|
||||
|
||||
## 快速开始
|
||||
|
||||
```bash
|
||||
git clone <your-repo-url>
|
||||
cd cleonos
|
||||
git submodule update --init --recursive
|
||||
make run
|
||||
```
|
||||
|
||||
如果你已经准备好 Limine 产物，可跳过 configure：
|
||||
|
||||
```bash
|
||||
make run LIMINE_SKIP_CONFIGURE=1
|
||||
```
|
||||
|
||||
## 常用目标
|
||||
|
||||
- `make setup` - 检查工具并准备 Limine
|
||||
- `make kernel` - 构建内核 ELF
|
||||
- `make userapps` - 构建用户态 ELF 应用
|
||||
- `make ramdisk` - 打包运行时 ramdisk
|
||||
- `make iso` - 生成可启动 ISO
|
||||
- `make run` - 启动 QEMU
|
||||
- `make debug` - 以 `-s -S` 启动 QEMU 供 GDB 附加
|
||||
- `make clean` - 清理 `build/x86_64`
|
||||
- `make clean-all` - 清理全部构建产物
|
||||
|
||||
## 调试（GDB）
|
||||
|
||||
先启动调试 VM：
|
||||
|
||||
```bash
|
||||
make debug
|
||||
```
|
||||
|
||||
再在另一个终端连接：
|
||||
|
||||
```bash
|
||||
gdb build/x86_64/clks_kernel.elf
|
||||
(gdb) target remote :1234
|
||||
```
|
||||
|
||||
## User Shell 示例
|
||||
|
||||
```sh
|
||||
help
|
||||
ls /shell
|
||||
cat /shell/init.cmd
|
||||
grep -n exec /shell/init.cmd
|
||||
cat /shell/init.cmd | grep -n exec
|
||||
ls /shell > /temp/shell_list.txt
|
||||
```
|
||||
|
||||
## 文档
|
||||
|
||||
- Stage 索引：[`docs/README.md`](docs/README.md)
|
||||
- Syscall ABI 文档：[`docs/syscall.md`](docs/syscall.md)
|
||||
|
||||
## CI
|
||||
|
||||
GitHub Actions 工作流 [`build-os.yml`](.github/workflows/build-os.yml) 会在 push/PR 时自动构建 ISO，并上传为 artifact。
|
||||
|
||||
## 贡献指南
|
||||
|
||||
1. Fork 仓库并创建功能分支。
|
||||
2. 尽量按 Stage 组织改动，并同步更新文档。
|
||||
3. 提交 PR 前至少执行一次 `make iso`。
|
||||
4. 涉及可见行为变化时，附上启动日志片段或截图。
|
||||
|
||||
## 许可证
|
||||
|
||||
Apache-2.0。详见 [`License`](License)。
|
||||
Reference in New Issue
Block a user