AwesomeWM compatibility reference
SomeWM 1.4 mirrors AwesomeWM master and is maintained as the upstream-compatible line. Wayland requires differences in protocols and desktop integration.
| Need | Documentation |
|---|---|
| Move an AwesomeWM configuration to Wayland | Migrating from AwesomeWM |
| Change SomeWM releases | Upgrade from 1.4 to 2.0 |
| Understand the compatibility policy | AwesomeWM compatibility |
| Understand the platform | Wayland vs X11 |
Platform differences
| Area | SomeWM behaviour |
|---|---|
| System tray | wibox.widget.systray uses StatusNotifierItem over D-Bus. XEmbed-only tray applications do not appear. |
| Clipboard | Wayland clipboard and primary-selection protocols replace X selections; see protocol support. |
| Screenshots | The compositor captures the scene; see screenshots. |
| Monitor and input configuration | The compositor owns these settings; see output and awful.input. |
| Configuration paths | SomeWM uses somewm/ configuration and cache directories; see configuration search order. |
| GTK theme discovery | beautiful.gtk reads GTK settings files instead of creating GTK widgets. GTK CSS is not fully represented; the fallback is Adwaita Dark. |
| Xresources | gears.xresources reads ~/.Xresources, with fallback values. Updating the X server's resource database with xrdb does not update these values. |
Drawing and shapes
Widgets paint into drawable surfaces. The compositor places these surfaces alongside application surfaces in its scene. See Architecture.
Client X11 shape masks have no Wayland implementation. See the wibox reference for widget and wibox shapes.
Client geometry excludes the border. Titlebars occupy space inside the decorated client geometry; the border surrounds the client frame.
Restart and reload
awesome.restart() rebuilds the Lua state in the existing compositor. Application clients remain connected. It does not load a newly installed compositor executable.
Modules holding GLib sources or D-Bus registrations must release them on exit before their Lua state closes. See signals and tag persistence.
awesome.quit(1) requests a new process when launched through somewm-session; applications lose their Wayland connections during a process restart.
X-property APIs
| API | Behaviour |
|---|---|
awesome.register_xproperty(name, type) | Accepts the declaration but registers no X11 property. |
awesome.get_xproperty, awesome.set_xproperty | Not defined. Calling either raises a Lua error. |
client:get_xproperty, client:set_xproperty | See client properties below. |
Client properties
client:get_xproperty(name) returns nil; client:set_xproperty(name, value) does nothing. These client methods allow configurations to load, but do not persist values across a Lua reload.
Keyboard layouts
awesome.xkb_get_group_names(), awesome.xkb_get_layout_group() and awesome.xkb_set_layout_group() are implemented. Layout indices are zero-based.
Layout toggles
The grp:* XKB toggle options do not reliably switch the compositor's keyboard group. Explicit bindings can call awesome.xkb_set_layout_group() instead. Static options such as ctrl:nocaps and compose:ralt work. See keyboard layouts.
Client metadata and state
Native Wayland clients provide an application ID, exposed as client.class. X11 instance, machine and icon_name metadata is unavailable for native clients; match rules by class instead. XWayland clients can supply X11 metadata.
| Property | Behaviour |
|---|---|
client.id | Compositor-assigned client identifier, also used by somewm-client. |
client.aspect_ratio | Width-to-height constraint; 0 or nil disables it. |
client.xdg_fullscreen | Read-only fullscreen state scheduled for an XDG client; falls back to client.fullscreen for other clients. |
client.shadow | Per-client shadow configuration; see shadows. |
Protocol fullscreen state can differ from Lua state; client.xdg_fullscreen exposes that distinction.
Signals
The 1.4 line preserves AwesomeWM signal dispatch semantics. The signal reference lists signal names and arguments.
spawn::change and spawn::canceled are not emitted: Wayland activation does not provide X11 startup-notification progress and cancellation. Key press and release handlers, root.fake_input() and dynamic keybinding removal through root._remove_key() are supported.
XWayland limits
These limits concern X11 applications running through XWayland, not native Wayland clients.
| EWMH property | Limit |
|---|---|
_NET_FRAME_EXTENTS | SomeWM does not publish frame extents. |
_NET_DESKTOP_GEOMETRY | The EWMH value is fixed at 1920 by 1080, rather than the output layout's size. |
_NET_WM_DESKTOP at initial map | The requested desktop is read but does not assign the client's tag. Configure placement through client rules. |
SomeWM extensions
| Area | API and documentation |
|---|---|
| Input devices and NumLock | awful.input; awesome._set_keyboard_setting for NumLock |
| Lua utilities | gears.xresources reads resource files; gears.bitwise provides bitwise operations on Lua versions without the operators |
| IPC | somewm-client, backed by awful.ipc |
| Outputs and scaling | output, screen.scale |
| Capture | screen.content, awful.screenshot |
| Cursor themes | root.cursor_theme, root.cursor_size; input devices |
| Shadows | Client and wibox shadows; shadow reference |
| Tray integration | awful.systray, awful.statusnotifierwatcher, wibox.widget.systray_icon; wibox widgets |
| Layer-shell rules | ruled.layer_surface; layer surfaces |
| Scrolling layouts | awful.layout.suit.carousel; carousel |
| Monitor reconnection | Tag persistence; saved state is keyed by connector name |
| Idle and locking | Lock, idle and DPMS, session lock |
Drawable scale
drawin.surface_scale overrides the drawable's raster scale: 0 selects the output scale, and a positive value selects that factor. Changing it recreates the surface. See display scaling.
Testing compatibility
Tests relying on X11 properties or native clients' X11 metadata need a Wayland-specific expectation. Supported key release, keyboard-layout and input-injection APIs can be tested directly. Nested compositor testing keeps configuration checks separate from the desktop session.