tile-manager/README.md

tile-manager

A Rust Wayland tiling compositor project, built in small stages.

The target is a simple desktop tile manager in the same general space as Hyprland or niri, but with a much narrower first scope:

1. nested compositor first
2. one output first
3. one workspace first
4. one tiling layout first

This project should grow in the same order a Codecrafters-style guide would teach it: build the minimum working compositor, then add input, tiling, workspaces, multi-output, and finally standalone session support and polish.

Scope

This is not an X11 window manager.

It is intended to become a Wayland compositor that can:

1. accept Wayland clients
2. track windows, focus, outputs, and workspaces
3. process keyboard and pointer input
4. render surfaces
5. apply a tiling layout

Planned Stack

Primary Rust crates:

• smithay: Wayland compositor foundation
• calloop: event loop
• xkbcommon: keyboard layout and modifiers
• tracing: structured logging
• tracing-subscriber: log output/filtering
• anyhow: application-level error handling
• thiserror: typed internal errors
• bitflags: internal state flags

Likely later additions:

• serde + toml: config loading
• clap: CLI flags
• zbus: desktop integration
• XWayland-related Smithay features: X11 app support

Development Order

Stage 0: Nested compositor

Start inside an existing desktop session before touching DRM/KMS.

Goal:

• boot the compositor
• open a Wayland client
• confirm logs and state changes

Stage 1: Event loop and Wayland server

Implement:

1. logging setup
2. calloop::EventLoop
3. Wayland display state
4. core Smithay globals

Deliverable:

• the process starts and stays alive cleanly

Stage 2: XDG toplevel support

Implement:

1. compositor state
2. shared memory support
3. XDG shell support
4. seat support

Deliverable:

• a client can create a toplevel surface

Stage 3: Internal state model

Add plain Rust types for:

• compositor state
• outputs
• seats
• workspaces
• windows
• tile layout state

Deliverable:

• stable state snapshots after every map/unmap/focus/layout event

Stage 4: Render one output

Implement:

1. one output
2. solid background
3. mapped surface rendering
4. frame presentation

Deliverable:

• one client is visible on screen

Stage 5: Input and bindings

Implement:

1. keyboard input
2. pointer input
3. compositor modifier handling
4. a few core commands

Minimum commands:

• spawn terminal
• close focused window
• cycle focus

Stage 6: Tiling

Start with one layout only.

Recommended first layouts:

1. equal columns
2. master-stack

Deliverable:

• new windows retile the workspace correctly

Stage 7: Workspaces

Implement:

1. workspace switching
2. moving windows between workspaces
3. independent workspace layout state

Stage 8: Multi-output

Implement:

1. output tracking
2. per-output active workspace
3. correct focus and new-window placement

Stage 9: Standalone session

Only after the nested compositor is solid, add:

1. DRM/KMS
2. libinput
3. session/seat handling
4. VT switching

Stage 10: Polish

Later features:

• config file
• IPC
• floating windows
• fullscreen
• layer-shell support
• screencopy
• animations
• XWayland

Suggested Layout

src/
  main.rs
  app.rs
  state.rs
  backend/
    mod.rs
    nested.rs
    tty.rs
  input/
    mod.rs
    keyboard.rs
    pointer.rs
    bindings.rs
  layout/
    mod.rs
    columns.rs
    master.rs
  shell/
    mod.rs
    xdg.rs
    window.rs
  render/
    mod.rs
    scene.rs
  workspace/
    mod.rs
  config/
    mod.rs

Guiding rule:

• keep Smithay integration near the edges
• keep layout and workspace logic in plain Rust types

System Dependencies

The final compositor will also need Linux graphics/input libraries, depending on backend choice:

• libwayland
• libxkbcommon
• libudev
• libinput
• libdrm
• gbm
• egl / gles2
• pixman
• xwayland for X11 clients

References

• Smithay docs: https://docs.rs/smithay/latest/smithay/
• Smithay project docs: https://smithay.github.io/smithay/smithay/
• wayland-server docs: https://smithay.github.io/wayland-rs/wayland_server/
• calloop docs: https://docs.rs/calloop/latest/calloop/
• xkbcommon docs: https://docs.rs/xkbcommon/latest/xkbcommon/

Status

Right now the repo is still at the very beginning. The current documentation is the roadmap.

For a fuller step-by-step build guide, see GUIDE.md.