← Back to all projects

WAYLAND X11 COMPOSITOR LEARNING PROJECTS

Understanding Wayland: Deep Dive Through C Programming

Core Concept Analysis

To truly understand Wayland (and how it differs from X11), you need to grasp these fundamental building blocks:

Concept What It Teaches
Display Protocol Model How clients communicate with the display server
Compositor Architecture Why Wayland merges server + compositor (vs X11’s separation)
Object-Oriented Protocol Wayland’s proxy/resource model vs X11’s request/reply
Buffer Management Shared memory, DMA-BUF, and zero-copy rendering
Shell Protocols xdg-shell, layer-shell, and window management
Input Handling Seats, keyboards, pointers, and the security model
EGL/OpenGL Integration Hardware-accelerated rendering in Wayland

X11 vs Wayland: The Key Architectural Difference

X11 Architecture:
┌──────────┐    ┌──────────────┐    ┌────────────┐
│  Client  │───▶│  X Server    │───▶│ Compositor │
└──────────┘    │ (rendering)  │    │ (separate) │
                └──────────────┘    └────────────┘
                      │
              (Complex protocol,
               network transparent,
               extensions galore)

Wayland Architecture:
┌──────────┐    ┌─────────────────────────┐
│  Client  │───▶│  Compositor (Wayland)   │
└──────────┘    │  - Display server       │
                │  - Window manager       │
                │  - Compositing          │
                └─────────────────────────┘
                      │
              (Simple protocol,
               clients render themselves,
               security by design)

Project 1: Bare-Metal Wayland Client

  • File: WAYLAND_X11_COMPOSITOR_LEARNING_PROJECTS.md
  • Programming Language: C
  • Coolness Level: Level 4: Hardcore Tech Flex
  • Business Potential: 1. The “Resume Gold”
  • Difficulty: Level 3: Advanced
  • Knowledge Area: Graphics / Window Systems
  • Software or Tool: Wayland Protocol
  • Main Book: “The Wayland Book” by Drew DeVault

What you’ll build: A Wayland client from scratch that displays a colored window using only libwayland-client and shared memory—no toolkits, no helpers.

Why it teaches Wayland: Forces you to understand the entire client lifecycle: connecting to the compositor, negotiating protocols via wl_registry, creating surfaces, attaching buffers, and handling the frame callback loop.

Core challenges you’ll face:

  • Understanding the Wayland object model (proxies, listeners, callbacks)
  • Negotiating global interfaces through wl_registry
  • Creating and managing wl_shm shared memory buffers
  • Implementing the xdg-shell surface lifecycle (map/unmap/configure)
  • Building a proper event loop with wl_display_dispatch

Key Concepts:

  • Wayland Protocol Basics: “The Wayland Book” by Drew DeVault (Chapters 1-4) - https://wayland-book.com
  • Shared Memory in Unix: “Advanced Programming in the UNIX Environment” by Stevens & Rago (Chapter 15)
  • C Memory Management: “Effective C, 2nd Edition” by Robert C. Seacord (Chapter 6)
  • Event-Driven Programming: “The Linux Programming Interface” by Michael Kerrisk (Chapter 63)

Difficulty: Intermediate Time estimate: 1-2 weeks Prerequisites: C programming, basic Linux/Unix concepts, familiarity with system calls

Real world outcome: A standalone executable that opens a window on your Wayland desktop with a solid color that you can resize and close. You’ll see your rectangle appear alongside your other applications.

Learning milestones:

  1. Connect to Wayland, enumerate globals → understand the protocol negotiation model
  2. Create an xdg_toplevel surface → understand shell protocols and window lifecycle
  3. Attach a shared memory buffer and see pixels → understand buffer management
  4. Handle resize events properly → understand the configure/ack/commit cycle

Project 2: Simple Wayland Compositor with wlroots

  • File: WAYLAND_X11_COMPOSITOR_LEARNING_PROJECTS.md
  • Programming Language: C
  • Coolness Level: Level 5: Pure Magic (Super Cool)
  • Business Potential: 4. The “Open Core” Infrastructure
  • Difficulty: Level 5: Master
  • Knowledge Area: Window Managers / Graphics Pipeline
  • Software or Tool: wlroots
  • Main Book: “The Wayland Book” by Drew DeVault

What you’ll build: A minimal but functional Wayland compositor using the wlroots library that can display client windows, handle keyboard/mouse input, and manage window focus.

Why it teaches compositors: wlroots abstracts the hard parts (DRM/KMS, libinput) while exposing the compositor logic. You’ll implement window stacking, damage tracking, and the compositor’s view of the Wayland protocol.

Core challenges you’ll face:

  • Understanding the compositor’s role as protocol implementer
  • Managing the scene graph (which windows are where, z-order)
  • Implementing focus and keyboard grab semantics
  • Handling output (monitor) configuration
  • Rendering the final composited frame

Resources for key challenges:

  • “tinywl” reference compositor in wlroots - The canonical minimal example
  • wlroots documentation and source code - https://gitlab.freedesktop.org/wlroots/wlroots

Key Concepts:

  • Compositor Architecture: wlroots wiki and tinywl source code
  • DRM/KMS Subsystem: “The Linux Programming Interface” by Kerrisk + kernel documentation
  • Input Handling: libinput documentation
  • Scene Graphs: wlroots scene API documentation

Difficulty: Advanced Time estimate: 1 month+ Prerequisites: Project 1 completed, understanding of graphics pipelines, event-driven C

Real world outcome: A working compositor you can log into! Launch it from a TTY, and it will display a background, let you open terminals and applications, move windows around, and switch focus with keyboard shortcuts.

Learning milestones:

  1. Display a background and handle output hotplug → understand DRM/KMS
  2. Accept client connections and display their buffers → understand server-side protocol
  3. Implement keyboard focus and pointer events → understand input routing
  4. Add window decorations and move/resize → understand interactive grabs

Project 3: Custom Wayland Protocol Extension

  • File: WAYLAND_X11_COMPOSITOR_LEARNING_PROJECTS.md
  • Main Programming Language: C
  • Alternative Programming Languages: Rust, C++, Zig
  • Coolness Level: Level 4: Hardcore Tech Flex
  • Business Potential: Level 1: The “Resume Gold”
  • Difficulty: Level 3: Advanced (The Engineer)
  • Knowledge Area: Graphics, Windowing Systems
  • Software or Tool: Wayland, wayland-scanner
  • Main Book: The Wayland Book by Drew DeVault

What you’ll build: Define and implement a custom Wayland protocol (XML) that extends functionality—for example, a “screenshot” protocol or a “system tray” protocol—with both client and compositor sides.

Why it teaches protocols: Wayland is extensible through XML protocol definitions that generate C code. Understanding this mechanism demystifies how xdg-shell, wlr-layer-shell, and other protocols work.

Core challenges you’ll face:

  • Writing Wayland protocol XML definitions
  • Using wayland-scanner to generate C bindings
  • Implementing the server-side (compositor) interface
  • Implementing the client-side usage
  • Understanding versioning and backwards compatibility

Key Concepts:

  • Protocol Design: “The Wayland Book” by Drew DeVault (Chapter 5: Protocol Design)
  • Code Generation: wayland-scanner documentation
  • Existing Protocols: wayland-protocols repository examples

Difficulty: Intermediate-Advanced Time estimate: 1-2 weeks Prerequisites: Project 1 completed

Real world outcome: A custom protocol that you can use to take screenshots from any Wayland client, or implement a system tray, or control your compositor’s behavior programmatically.

Learning milestones:

  1. Write XML and generate code → understand protocol-first design
  2. Implement server-side in your compositor → understand resource management
  3. Write a client using your protocol → see both sides of the API
  4. Handle edge cases (client disconnect, version mismatch) → understand robustness

Project 4: Wayland Panel/Bar (Layer Shell)

  • File: WAYLAND_X11_COMPOSITOR_LEARNING_PROJECTS.md
  • Programming Language: C
  • Coolness Level: Level 3: Genuinely Clever
  • Business Potential: 2. The “Micro-SaaS / Pro Tool”
  • Difficulty: Level 3: Advanced
  • Knowledge Area: Linux Desktop / Wayland Protocol
  • Software or Tool: Layer Shell Protocol
  • Main Book: “The Wayland Book” by Drew DeVault

What you’ll build: A status bar/panel using the wlr-layer-shell protocol—something like waybar or yambar but simpler, showing time, workspaces, and system info.

Why it teaches shell concepts: Layer shell lets you create surfaces that exist outside the normal window hierarchy (panels, overlays, backgrounds). This teaches you how desktop environments are built on top of Wayland.

Core challenges you’ll face:

  • Using zwlr_layer_shell_v1 protocol
  • Anchoring to screen edges and reserving exclusive zones
  • Rendering text and graphics (Cairo or custom)
  • Responding to compositor events (workspace changes, etc.)
  • Handling multiple outputs (monitors)

Key Concepts:

  • Layer Shell Protocol: wlr-protocols documentation
  • Cairo Graphics: cairographics.org tutorial
  • Output Management: “The Wayland Book” (Outputs chapter)
  • IPC Mechanisms: Understanding how bars communicate with compositors (e.g., Sway IPC)

Difficulty: Intermediate Time estimate: 2-3 weeks Prerequisites: Project 1 completed, some graphics/drawing knowledge helpful

Real world outcome: A functional panel at the top (or bottom) of your screen showing the current time, battery status, and workspace indicator that updates in real-time.

Learning milestones:

  1. Create a layer surface anchored to top edge → understand layer shell semantics
  2. Draw text and shapes with Cairo → understand rendering on Wayland
  3. Update content without flickering (damage tracking) → understand efficient redraw
  4. Handle multi-monitor setups → understand output enumeration

Project 5: X11 Comparison Project - Bare-Metal X11 Client

  • File: WAYLAND_X11_COMPOSITOR_LEARNING_PROJECTS.md
  • Main Programming Language: C
  • Alternative Programming Languages: C++, Rust, Zig
  • Coolness Level: Level 3: Genuinely Clever
  • Business Potential: Level 1: The “Resume Gold”
  • Difficulty: Level 2: Intermediate (The Developer)
  • Knowledge Area: Graphics, Windowing Systems
  • Software or Tool: X11, Xlib
  • Main Book: Xlib Programming Manual (O’Reilly)

What you’ll build: The exact same colored window as Project 1, but using raw Xlib to viscerally feel the differences between X11 and Wayland.

Why it teaches X11 vs Wayland: Nothing teaches the difference better than implementing the same thing in both. You’ll feel X11’s complexity (window properties, atoms, event masks) vs Wayland’s simplicity (but also Wayland’s “you do the work” philosophy).

Core challenges you’ll face:

  • Understanding X11’s request/reply model
  • Dealing with X atoms and properties
  • The expose event and redraw model (X11 stores nothing)
  • Window manager hints (ICCCM, EWMH)
  • Input focus model differences

Key Concepts:

  • Xlib Programming: “Xlib Programming Manual” (O’Reilly, available online)
  • ICCCM/EWMH: freedesktop.org window manager specifications
  • X11 Protocol: X.org protocol documentation

Difficulty: Intermediate Time estimate: 1 week Prerequisites: Project 1 completed (for comparison)

Real world outcome: An X11 window that looks identical to your Wayland window. The journey getting there will cement why Wayland exists.

Learning milestones:

  1. Open display, create window → compare to wl_display_connect
  2. Handle Expose events → understand why Wayland’s “client renders” is simpler
  3. Set WM_NAME, WM_HINTS → understand X11’s property-based metadata
  4. Compare the two codebases → internalize architectural differences

Project Comparison Table

Project Difficulty Time Depth of Understanding Fun Factor
Bare-Metal Wayland Client Intermediate 1-2 weeks ⭐⭐⭐⭐ ⭐⭐⭐
Compositor with wlroots Advanced 1 month+ ⭐⭐⭐⭐⭐ ⭐⭐⭐⭐⭐
Custom Protocol Extension Intermediate-Advanced 1-2 weeks ⭐⭐⭐⭐ ⭐⭐⭐⭐
Layer Shell Panel/Bar Intermediate 2-3 weeks ⭐⭐⭐ ⭐⭐⭐⭐
X11 Comparison Client Intermediate 1 week ⭐⭐⭐ (comparative) ⭐⭐⭐

Recommendation

Start with Project 1 (Bare-Metal Wayland Client), then immediately do Project 5 (X11 Comparison) while the Wayland code is fresh in your mind. This side-by-side experience will cement your understanding of why Wayland was designed the way it was.

Then progress to Project 2 (Compositor with wlroots)—this is where the real magic happens. Building a compositor gives you the “other side” of the protocol and reveals how desktop environments actually work.

Suggested progression:

Week 1-2: Project 1 (Wayland client)
Week 3:   Project 5 (X11 comparison)
Week 4-5: Project 4 (Layer shell panel) - optional but fun
Week 6+:  Project 2 (Compositor) - the deep dive

Final Capstone Project: Your Own Desktop Environment

What you’ll build: A complete (minimal) desktop environment: your compositor from Project 2 + your panel from Project 4 + a custom protocol for inter-component communication + a simple app launcher.

Why this is the ultimate test: A desktop environment is the integration of everything: compositor, shell protocols, input handling, configuration, and IPC. Building one—even a minimal one—means you truly understand the full stack.

Core challenges you’ll face:

  • Session management (starting/stopping the compositor)
  • Configuration system (keybindings, theme, layout)
  • Application launching and focus management
  • Multi-monitor support with per-output configuration
  • Popup menus and overlay surfaces

Key Concepts:

  • Session Management: systemd user sessions or custom session scripts
  • D-Bus Integration: freedesktop.org specifications
  • Configuration Formats: Your choice (INI, TOML, Lua, etc.)
  • Desktop Entry Spec: freedesktop.org desktop entry specification

Difficulty: Advanced Time estimate: 2-3 months Prerequisites: Projects 1, 2, and 4 completed

Real world outcome: Boot your computer, log in, and use your desktop environment. Open apps, arrange windows, see your panel, use your keybindings. This is your Linux desktop.

Learning milestones:

  1. Compositor + panel working together → understand component integration
  2. Keybindings and app launcher functional → understand input routing and process spawning
  3. Multi-monitor with configuration → understand output management
  4. Daily-driveable (for an hour) → you’ve built a desktop environment

Essential Resources

  • “The Wayland Book” by Drew DeVault - https://wayland-book.com - The definitive guide, read this first
  • wlroots source code - https://gitlab.freedesktop.org/wlroots/wlroots - The best reference implementation
  • wayland-protocols - https://gitlab.freedesktop.org/wayland/wayland-protocols - Official protocol extensions
  • Sway source code - A production compositor built on wlroots, great reference