CLeonOS

English | 简体中文

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/

Repository Layout

.
|- 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

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:

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:

make debug

Attach in another terminal:

gdb build/x86_64/clks_kernel.elf
(gdb) target remote :1234

User Shell Examples

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
• Syscall ABI reference: docs/syscall.md

CI

GitHub Actions workflow 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.