Sprint 0: Project Setup

Goal: Buildable skeleton that connects to X server and appears in the display manager greeter.

Objectives

• Initialize Rust project with proper workspace structure
• Establish logging and error handling patterns
• Connect to X server and become a window manager
• Create a stable event loop
• Make gar selectable from the login greeter

Tasks

0.1 Initialize Cargo Project

• Create Cargo.toml with workspace members (gar, garctl)
• Set up src/main.rs entry point
• Set up src/lib.rs for library code
• Create module structure skeleton

Dependencies to add:

[dependencies]
x11rb = { version = "0.13", features = ["allow-unsafe-code"] }
tracing = "0.1"
tracing-subscriber = "0.3"
thiserror = "1.0"

0.2 Logging Infrastructure

• Initialize tracing subscriber in main
• Set up log levels (RUST_LOG environment variable)
• Add structured logging for key events
• Log to file for debugging sessions

0.3 X Server Connection

• Create src/x11/mod.rs module
• Create src/x11/connection.rs
• Connect to X server using x11rb::connect()
• Get root window and screen info
• Handle connection errors gracefully

Key code pattern:

use x11rb::connection::Connection;
use x11rb::rust_connection::RustConnection;

pub fn connect() -> Result<(RustConnection, usize), Error> {
    let (conn, screen_num) = x11rb::connect(None)?;
    Ok((conn, screen_num))
}

0.4 Become Window Manager

• Request SubstructureRedirect on root window
• Handle "another WM running" error gracefully
• Set up necessary event masks on root window

Critical X11 concept: Only ONE client can have SubstructureRedirect on the root window. This is how X11 ensures only one window manager runs.

let change = ChangeWindowAttributesAux::new()
    .event_mask(EventMask::SUBSTRUCTURE_REDIRECT | EventMask::SUBSTRUCTURE_NOTIFY);
conn.change_window_attributes(root, &change)?.check()?;

0.5 Event Loop

• Create src/x11/events.rs
• Implement basic event loop structure
• Handle ConfigureRequest (pass through for now)
• Handle MapRequest (map windows for now)
• Log all received events
• Clean shutdown on SIGTERM/SIGINT

Event loop pattern:

loop {
    let event = conn.wait_for_event()?;
    match event {
        Event::ConfigureRequest(e) => handle_configure_request(&conn, e)?,
        Event::MapRequest(e) => handle_map_request(&conn, e)?,
        _ => tracing::trace!("Unhandled event: {:?}", event),
    }
}

0.6 Desktop Entry

• Create gar.desktop file
• Install to /usr/share/xsessions/ (or document install location)
• Test selection from GDM/LightDM/SDDM

Desktop entry content:

[Desktop Entry]
Name=gar
Comment=Tiling window manager with smart splits
Exec=gar
Type=XSession

Acceptance Criteria

1. cargo build succeeds without errors
2. cargo run connects to X server (or fails gracefully if one isn't available)
3. Running in a nested X session (Xephyr) shows gar as the WM
4. gar.desktop can be created and would appear in a greeter
5. Existing windows are not lost (ConfigureRequest/MapRequest passthrough)
6. Logs show event activity

Testing Strategy

Manual testing with Xephyr:

# Terminal 1: Start nested X server
Xephyr -br -ac -noreset -screen 1280x720 :1

# Terminal 2: Run gar in nested session
DISPLAY=:1 cargo run

# Terminal 3: Launch apps in nested session
DISPLAY=:1 xterm

Notes

• Keep this sprint minimal - just enough to have a working foundation
• Don't implement actual window management yet (Sprint 1)
• Focus on correctness over features
• Document any X11 quirks encountered

Resources

• x11rb documentation
• X11 Protocol Reference
• ICCCM Spec