Skip to content

README.md

Latest commit

 

History

History
142 lines (105 loc) · 6.37 KB

README.md

File metadata and controls

142 lines (105 loc) · 6.37 KB
Raw

MarsOS

MarsOS is an in-progress experiment in building a Linux desktop from the distribution image up through its native interface components. It uses Debian Trixie and KDE Plasma as a working base while replacing parts of the desktop experience with custom Rust applications built directly on Wayland.

Important

MarsOS is a research prototype. The image pipeline, bootable development environment, and several desktop components work, but substantial integration, packaging, reliability, and UX work remains. It is not ready to be installed as a general-purpose or daily-use operating system.

What is implemented

  • Reproducible Debian Trixie image construction for ARM64 and x86_64 targets
  • KDE Plasma desktop running on Wayland with system-wide configuration overlays
  • UTM/QEMU development loop with SSH access from a macOS host
  • A custom Rust dock with Wayland window tracking
  • A custom Rust header surface
  • A Spotlight-style application launcher with fuzzy search and global shortcut integration
  • A reusable Rust UI framework for layout, drawing, input, scrolling, animation, icons, and common control state

Why build this

MarsOS is a way to study the systems work hidden beneath a desktop environment: producing bootable images, configuring a Linux userspace, talking to a compositor, drawing pixels, dispatching input, tracking windows, and integrating programs into an existing session.

The Debian/KDE layer provides enough of a usable system to iterate. The custom components make it possible to replace the visible desktop piece by piece instead of beginning with a kernel or an empty framebuffer.

Architecture

┌─────────────────────────────────────────────────────────┐
│ Custom desktop components                               │
│ dock · header · spotlight · reusable Rust UI framework  │
├─────────────────────────────────────────────────────────┤
│ KDE Plasma services and KWin Wayland compositor         │
├─────────────────────────────────────────────────────────┤
│ MarsOS packages, configuration, overlays, and scripts   │
├─────────────────────────────────────────────────────────┤
│ Debian Trixie userspace and Linux kernel                │
└─────────────────────────────────────────────────────────┘

The native components use smithay-client-toolkit and Wayland client protocols for surfaces and events. Rendering is software-based through Skia or tiny-skia, while Taffy provides flexbox/grid layout in the shared UI crate.

Repository map

os/
├── ui/                 # Shared Rust UI framework
├── dock/               # Dock and Wayland window tracking
├── header/             # Desktop header surface and controls
├── spotlight/          # Fuzzy application launcher
├── config/
│   ├── packages/       # Base and desktop package manifests
│   ├── kde/            # System-wide Plasma, KWin, input, and SDDM config
│   └── kernel/         # Kernel configuration experiments
├── overlays/           # Files installed directly into the target image
├── scripts/            # Build, VM, image, and deployment automation
├── Dockerfile.build    # ARM64 image-build environment
└── Cargo.toml          # Rust workspace

Technical highlights

  • Wayland layer-shell surfaces and event loops
  • Window discovery through KDE/Wayland protocols
  • Skia display lists and Taffy-powered layout
  • Hit testing, event propagation, reactive state, scrolling, text input, and spring animation
  • Freedesktop application and icon discovery
  • Global shortcut integration through KDE's kglobalaccel D-Bus interface
  • Cross-architecture disk image construction with Docker, debootstrap, GRUB, and QEMU/UTM
  • 147 Rust unit tests across the desktop components and UI framework

Run the development image on Apple Silicon

Prerequisites

  • macOS on Apple Silicon
  • UTM for the GPU-accelerated development VM
  • Docker Desktop when rebuilding an image
  • sshpass for the overlay deployment script
brew install --cask utm
brew install sshpass

With build/mars-os-arm64.qcow2 present, create or boot the development VM:

bash scripts/test-qemu-arm64.sh

The VM exposes SSH on port 2222:

ssh -p 2222 mars@localhost
# development password: mars

Apply changes from overlays/ and config/kde/ to the running VM:

bash scripts/apply-overlays.sh
ssh -p 2222 root@localhost 'reboot'

Build an image

The image scripts require privileged Linux filesystem operations. On macOS, those operations run inside the supplied Docker build environment:

bash scripts/build-local.sh --desktop

The x86_64 path is intended to run on a Debian or Ubuntu build machine:

sudo bash scripts/setup-ec2.sh
sudo bash scripts/build.sh --desktop
sudo bash scripts/make-iso.sh

Build and test the Rust workspace

The desktop crates depend on Linux and Wayland libraries and should be built inside a Linux environment, not directly on a macOS host.

cargo build --workspace
cargo test --workspace

See spotlight/README.md for a component-level build and installation example.

Next milestones

  • Integrate and package all custom Rust components as part of the image build
  • Replace remaining stock desktop surfaces with a coherent MarsOS shell
  • Stabilize input, multi-display, scaling, and session lifecycle behavior
  • Automate end-to-end VM tests for image creation and overlay deployment
  • Complete installation and recovery flows
  • Establish release images, upgrade strategy, and hardware-support boundaries

License

Original MarsOS code and assets are available under the PolyForm Noncommercial License 1.0.0. Debian, KDE, the Linux kernel, and other bundled upstream projects retain their own licenses.