README

Three kernel wizards shipwrecked on the island of Sloptopia.
Armed with Rust, mass AI token consumption, and zero fear of unsafe,
they built an operating system that boots—when the Wheel of Fate allows it.

Win the spin → enter the shell.
Lose → reboot and try again.
The house always wins. Eventually.

Get It Running

You need: QEMU, xorriso, mkfs.ext2, just, and mass skill issue tolerance

# macOS
brew install qemu xorriso e2fsprogs just

# Debian/Ubuntu
sudo apt install qemu-system-x86 xorriso e2fsprogs
cargo install just  # or: https://github.com/casey/just#installation

# Arch (btw)
sudo pacman -S qemu-full xorriso e2fsprogs just

# Then:
just setup          # installs rust nightly
just boot           # spins the wheel

macOS Note: The Cocoa display backend is automatically detected and used. If you see display errors, run qemu-system-x86_64 -display help to check available backends.

	Command	What it does
	`just boot`	Boot with display window
	`just boot-headless`	Headless boot (serial only)
	`just boot-log`	Boot with timeout, saves to `test_output.log`
	`just test`	Run the test harness
	`just --list`	Show all available recipes

Advanced Options

QEMU_DISPLAY=cocoa just boot           # Force Cocoa (macOS default)
QEMU_DISPLAY=sdl just boot             # Force SDL (if installed)
just show-qemu-resolution              # Show detected framebuffer mode
QEMU_FB_AUTO=0 just boot               # Disable auto-detection, use defaults
QEMU_FB_WIDTH=2560 QEMU_FB_HEIGHT=1440 just boot  # Manual override
QEMU_FB_AUTO_POLICY=max just boot      # Multi-monitor: pick largest display
QEMU_FB_AUTO_OUTPUT=DP-1 just boot     # Multi-monitor: pin specific output
DEBUG=1 just boot                      # Debug logging
just boot-log video=1                  # Timed boot with display window

Note: On macOS, GTK is not available. The justfile automatically uses Cocoa display.

What's Inside

                          ┌─────────────────────────────────────┐
                          │            USERLAND (Ring 3)        │
                          │  ┌─────────┐ ┌────────┐ ┌─────────┐ │
                          │  │  Shell  │ │Roulette│ │Composit.│ │
                          │  └────┬────┘ └───┬────┘ └────┬────┘ │
                          └───────┼──────────┼──────────┼───────┘
                                  │ SYSCALL  │          │
                          ┌───────▼──────────▼──────────▼───────┐
                          │             KERNEL (Ring 0)         │
                          │  ┌────────┐ ┌────────┐ ┌──────────┐ │
                          │  │ Sched  │ │   MM   │ │  Video   │ │
                          │  └────────┘ └────────┘ └──────────┘ │
                          │  ┌────────┐ ┌────────┐ ┌──────────┐ │
                          │  │  VirtIO│ │  ext2  │ │  PS/2    │ │
                          │  └────────┘ └────────┘ └──────────┘ │
                          └─────────────────────────────────────┘

	Feature
	Buddy allocator + demand paging
	Ring 0/3 with proper TSS isolation
	Preemptive scheduler
	SYSCALL/SYSRET fast path
	IOAPIC + LAPIC interrupts
	PS/2 keyboard & mouse
	ext2 on VirtIO block
	Framebuffer graphics
	The Wheel of Fate + W/L currency

Project Layout

slopos/
├── boot/       → GDT, IDT, TSS, early init, SYSCALL MSRs
├── core/       → scheduler, syscall handlers, task management  
├── mm/         → physical frames, virtual memory, ELF loader
├── drivers/    → PIT, PS/2, IOAPIC, VirtIO, PCI enumeration
├── video/      → framebuffer, graphics primitives, roulette wheel
├── fs/         → ext2 implementation
├── userland/   → shell, compositor, roulette, file manager
├── kernel/     → main entry point
└── lore/       → the sacred chronicles (worth reading)

_{"still no progress but ai said it works soo it has t be working :)"

— from the sacred commit logs}

GPL-3.0-only