Skip to main content
Version: 2.2 (dev)

Architecture

C handles Wayland protocols and core objects. Lua configures their behaviour. Clay calculates layout, and SomeWM's renderer updates the scene that wlroots displays.

Who owns the work​

PartResponsibility
C coreProtocols, input, outputs and Lua bindings for client, screen, tag, output, awesome and root
Lua librariesWindow policy, widgets, rules, themes, signals and layout descriptions
Your rc.lua and modulesChoose layouts, compose widgets, register bindings and configure rules
ClayCalculate sizes and positions from the declarations
Renderer and wlrootsUpdate scene nodes and present application surfaces and desktop content

SomeWM's Lua libraries originated in AwesomeWM but have changed in 2.x. Updates replace the installed libraries. Keep customisations in your configuration rather than editing installed files.

LibraryPurpose
awfulWindow management, bindings, layouts and spawning
gearsTimers, shapes, filesystem and table helpers
wiboxWidgets, containers and widget layouts
beautifulTheme values
naughtyNotifications
ruledRules for clients, notifications and layer surfaces

How the parts interact​

Lua reads properties, calls methods and connects signal handlers. For example, c.floating = true changes client state, c:move_to_tag(t) changes tag membership, and a focus handler reacts to a focus event. Client geometry is a method, c:geometry(), rather than a writable table property.

Selected C notifications wait until the current operation finishes. The main loop delivers them before refresh and layout. Lua-emitted signals and requests needing an immediate response run inline. See signal timing.

From state to a displayed frame​

A state change marks affected outputs for an update. Lua prepares widget and client descriptions. C assembles the output tree, Clay calculates geometry, and the renderer applies the resulting commands to the wlroots scene.

Lua declarations feed Clay layout, then SomeWM updates the scene before presentation.

Applications draw their own client content. SomeWM places their surface trees alongside widget content, borders and decorations. How SomeWM draws explains the layout and rendering stages.

Startup and reload​

rc.lua runs before existing clients are managed. It loads the theme and registers handlers. Screen-decoration handlers create tags and bars. Client scanning then requests rules and bindings, manages existing clients, and ends with the startup signal. See startup order.

awesome.restart() rebuilds the Lua state in the same compositor process and runs the configuration again. Application connections survive, but Lua objects, timers and module state are recreated. See debugging and reload.

The object model explains which objects a configuration acts on.