Skip to main content
Version: 2.2 (dev)

Migrating from AwesomeWM

Work on a copy of your AwesomeWM configuration. Check X11 dependencies, removed APIs and custom widget implementations, then test it in a nested session.

SomeWM 2.1 keeps Lua widgets, themes, tags, rules and signals. Widgets that implement their own fit, layout or draw callbacks need porting. Custom widgets built from supported components can keep their existing structure. See Upgrading from 2.0 to 2.1 before testing third-party widget libraries.

Check first​

somewm --check ~/.config/awesome/rc.lua

The checker parses Lua, scans known compatibility patterns and missing imports, and runs Luacheck if installed. It does not execute the config or prove that callbacks work.

SeverityMeaning
CRITICALCode that can fail or block the compositor
WARNINGCode that may need a Wayland alternative
INFOA possible compatibility difference

Warnings and critical findings produce a non-zero exit status by default. To fail only on critical findings while still showing the full report:

somewm --check ~/.config/awesome/rc.lua --check-level=critical

A reviewed false positive can be suppressed with -- somewm:ignore on that line. Both the checker and startup scan recognise it.

The startup scan is advisory. SomeWM still attempts the config. A ten-second timeout interrupts a config that hangs during loading, after which SomeWM attempts a fallback. The timeout does not protect later signal or timer callbacks.

X11 tools and their replacements​

X11 dependencyReplacement
xrandr, xdpyinfos.geometry, s.outputs, and the output API
xpropClient properties. Native Wayland clients expose their application ID as c.class, while XWayland clients can also supply X11 metadata
xdotoolroot.fake_input() from Lua, or a tool using an input protocol SomeWM supports
scrot, maim, ImageMagick importScreenshot APIs or grim
xset r rateawful.input.keyboard_repeat_delay in milliseconds and keyboard_repeat_rate in repeats per second
xbacklightbrightnessctl as a separate process
xrdbConfigure native applications directly. SomeWM's gears.xresources reads resource files, not the X server database

geometry is a property. The outputs value is an array:

for s in screen do
print(s.geometry.width, s.geometry.height)
for _, o in ipairs(s.outputs) do
print(o.name)
end
end

GTK and GDK inside the compositor​

Display initialisation inside the compositor can deadlock: GTK or GDK waits for a display-server response while SomeWM is still executing that code. Deferring the call to a timer or signal handler does not help because those callbacks use the same thread.

SomeWM suppresses GTK initialisation, but this does not make display-dependent GTK operations usable. Gtk.IconTheme.get_default() needs an initialised display. Importing Gdk can still block through LGI overrides. Run settings windows as separate processes instead of calling Gtk.main() or app:run() inside the config.

GdkPixbuf decodes images without a display. For icon lookup without GTK:

local menubar = require("menubar")
local path = menubar.utils.lookup_icon_uncached("firefox")

Client icons​

Native Wayland clients do not provide the X11 window-icon property. SomeWM attempts desktop-entry lookup when c.icon is missing. If that finds nothing, try the application's c.class with an icon lookup. XWayland clients can supply their own icons.

X11 properties​

APISomeWM behaviour
awesome.get_xproperty, awesome.set_xpropertyUndefined. Calling either raises a Lua error
awesome.register_xpropertyAccepts the declaration but does nothing
client:get_xproperty, client:set_xpropertyReturn nil and do nothing, respectively

These properties cannot preserve state across reloads. awesome.startup is true while the 2.1 config loads on both initial startup and Lua reload, so it does not distinguish them. Use the autostart guide for startup-only processes.

APIs removed in SomeWM 2.0​

The 1.4-to-2.0 upgrade guide lists replacements for notification helpers, lifecycle signals, awful.util, API levels and other aliases. Check third-party modules as well as your own configuration.

For the additional widget and rendering changes, follow Upgrading from 2.0 to 2.1. Signal timing also matters if code expects a handler to run immediately after changing a property.

Try it​

Start a named test instance with your copied config:

somewm-client test start --name migration --config ~/somewm-test/rc.lua
somewm-client test logs --name migration

Use --host x11 on an X11 host. Test shortcuts, widget updates, application rules and reloads. A successful startup ping does not prove your config loaded, because SomeWM may have used a fallback. Read the log.

somewm-client test stop --name migration

See nested testing for the full workflow. Wayland vs X11 explains the platform differences behind these changes.