How swaywm/sway works
Purpose and binaries
Sway is a C, i3-compatible Wayland compositor built with Meson/Ninja. The primary compositor executable starts at sway/main.c; companion processes are the status bar (swaybar/main.c), IPC CLI (swaymsg/main.c), and warning/error UI (swaynag/main.c). Top-level build composition is in meson.build.
Server and Wayland boundary
sway/server.c initializes and owns compositor-facing state, delegating protocol, rendering, output, and surface primitives to wlroots. Desktop protocol integration is separated in sway/desktop/xdg_shell.c, sway/desktop/layer_shell.c, and sway/desktop/xwayland.c, forming the boundary between Wayland/Xwayland clients and Sway’s internal window model.
Configuration and command execution
At startup or reload, sway/config.c parses i3-compatible configuration and creates persistent policy/state for inputs, outputs, seats, bars, bindings, and rules. sway/commands.c dispatches config and runtime commands into focused implementations under sway/commands/; criteria matching in sway/criteria.c selects target views/containers. Commands mutate compositor state rather than directly rendering.
Window tree, layout, and transactions
The canonical desktop model is the root/output/workspace/container/view tree under sway/tree/root.c, sway/tree/container.c, and sway/tree/view.c. Arrangement in sway/tree/arrange.c turns tiling/floating layout state into geometry. sway/desktop/transaction.c coordinates state transitions with clients, separating requested layout changes from committed visual state.
Input and interaction state machines
Input device discovery and lifecycle flow through sway/input/input-manager.c and sway/input/libinput.c. Seats, keyboards, cursors, touch/tablet, focus, and pointer-driven move/resize operations are mediated by sway/input/seat.c, sway/input/cursor.c, and specialized seatop_* modules. This layer maps wlroots/libinput events into tree focus and layout actions.
IPC and external control
The compositor publishes i3-compatible IPC through sway/ipc-server.c; sway/ipc-json.c serializes tree, workspace, input, output, and event data using json-c. Consumers use the reusable client transport in common/ipc-client.c, notably swaymsg/main.c and swaybar/ipc.c. IPC is the principal process boundary for automation and bar updates.
Bar, notifications, and shared rendering
swaybar/bar.c manages bar instances configured by Sway, consumes compositor IPC, and renders workspace/status/tray UI through swaybar/render.c; i3bar status input is handled in swaybar/i3bar.c. swaynag/swaynag.c is an independent Wayland notification/error surface. Shared Cairo/Pango drawing and Wayland buffer utilities live in common/cairo.c, common/pango.c, and client/pool-buffer.c.
Runtime dependencies and protocols
The system runs on Wayland and wlroots, with optional Xwayland support; libinput drives physical input. Cairo/Pango provide text and rendering, PCRE2 supports criteria, and json-c supports IPC. Local protocol definitions, including layer-shell and output power management, are in protocols/wlr-layer-shell-unstable-v1.xml and protocols/wlr-output-power-management-unstable-v1.xml.
Main entry points: meson.build Meson/Ninja build · commands.c Command dispatcher · root.c Desktop tree · main.c sway compositor
Components 20
Compositor Core
Primary Sway server, policy, desktop model, and rendering boundary.
- sway compositor · Primary compositor process.
sway/main.c - Server lifecycle · Owns compositor-facing wlroots state.
sway/server.c - Config policy · Parses persistent input, output, bar, binding, and rule policy.
sway/config.c - Command dispatcher
sway/commands.c - Criteria matcher
sway/criteria.c - Desktop tree · Canonical root, output, workspace, container, and view hierarchy.
sway/tree/root.c - Layout arrangement · Converts tiling and floating state into geometry.
sway/tree/arrange.c - Desktop transactions · Separates requested layout from client-committed visual state.
sway/desktop/transaction.c - Client protocol integration · XDG shell, layer shell, and optional Xwayland bridge.
sway/desktop/xdg_shell.c - wlroots / Wayland · Provides Wayland protocol, surface, output, and rendering primitives.
Input
Device and seat interaction state machines.
- Input manager · Maps libinput and wlroots device events into Sway input state.
sway/input/input-manager.c - Seats and interactions · Mediates focus, cursor, and move/resize seat operations.
sway/input/seat.c
IPC
i3-compatible external control and event transport.
- IPC server · Publishes i3-compatible commands, queries, and events.
sway/ipc-server.c - IPC JSON · Serializes tree, workspace, input, output, and event data.
sway/ipc-json.c - IPC client transport · Reusable client connection layer.
common/ipc-client.c
Companion Clients
Separate processes connected through IPC or Wayland.
- swaymsg
swaymsg/main.c - swaybar · Consumes IPC and renders workspace, status, and tray UI.
swaybar/bar.c - swaynag · Independent warning and error surface.
swaynag/swaynag.c - Shared drawing and buffers · Cairo/Pango drawing and Wayland buffer support.
common/cairo.c
Other components
- Meson/Ninja build
meson.build
Connections 26
- Meson/Ninja build → sway compositor: builds
- Meson/Ninja build → swaymsg: builds
- Meson/Ninja build → swaybar: builds
- Meson/Ninja build → swaynag: builds
- sway compositor → Server lifecycle: initializes
- sway compositor → Config policy: loads and reloads
- Server lifecycle → wlroots / Wayland: uses
- Client protocol integration → wlroots / Wayland: bridges clients through
- Config policy → Command dispatcher: defines commands for
- Command dispatcher → Criteria matcher: selects targets via
- Command dispatcher → Desktop tree: mutates
- Desktop tree → Layout arrangement: provides layout state
- Layout arrangement → Desktop transactions: requests geometry changes
- Desktop transactions → Client protocol integration: synchronizes clients
- Input manager → Seats and interactions: routes device events
- Seats and interactions → Desktop tree: updates focus and actions
- Input manager → wlroots / Wayland: uses input events
- IPC server → Command dispatcher: executes runtime commands
- IPC server → IPC JSON: serializes through
- IPC JSON → Desktop tree: queries state from
- swaymsg → IPC client transport: uses
- swaybar → IPC client transport: uses
- IPC client transport → IPC server: connects to
- swaybar → Shared drawing and buffers: renders with
- swaynag → Shared drawing and buffers: renders with
- swaynag → wlroots / Wayland: creates Wayland surface through