Skip to main content
Version: 2.2 (dev)

AwesomeWM compatibility

SomeWM 2.1 develops independently of AwesomeWM. Shared Lua names do not guarantee identical behaviour. The reference for this version defines the supported API.

NeedDocumentation
Move an AwesomeWM configuration to WaylandMigrating from AwesomeWM
Change SomeWM releasesUpgrade from 2.0 to 2.1
Understand the compatibility policyAwesomeWM compatibility
Understand the platformWayland vs X11

Platform differences​

AreaSomeWM behaviour
System traywibox.widget.systray uses StatusNotifierItem over D-Bus. XEmbed-only tray applications do not appear.
ClipboardWayland clipboard and primary-selection protocols replace X selections. See protocol support.
ScreenshotsThe compositor captures the scene. See screenshots.
Monitor and input configurationThe compositor owns these settings. See output and awful.input.
Configuration pathsSomeWM uses somewm/ configuration and cache directories. See configuration search order.
GTK theme discoverybeautiful.gtk reads GTK settings files instead of creating GTK widgets. GTK CSS is not fully represented. The fallback is Adwaita Dark.
Xresourcesgears.xresources reads ~/.Xresources, with fallback values. Updating the X server's resource database with xrdb does not update these values.

Drawing and shapes​

Widgets describe elements in one tree per output. declare.c declares the tree. render.c owns visible scene changes. Custom painter widgets are omitted with a warning. See How SomeWM draws and widget compatibility.

client.shape controls client corners. The mask properties shape_bounding, shape_clip and shape_input are ignored and warn. The corresponding client_shape_* getters return nil. Wibox masks are also ignored. Use its shape property. See rounded corners and wibox.

client.content_radius, client.content_background_color and titlebar corner_padding are SomeWM additions. See Client corners for independent content rounding, corner fill and titlebar insets.

Client geometry excludes the border. Titlebars occupy space inside the decorated client geometry. The border surrounds the content and titlebars. Together they form 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.

X-property APIs​

APIBehaviour
awesome.register_xproperty(name, type)Accepts the declaration but registers no X11 property.
awesome.get_xproperty, awesome.set_xpropertyNot defined. Calling either raises a Lua error.
client:get_xproperty, client:set_xpropertySee client properties below.

Client properties​

client:get_xproperty(name) reads a client-owned value. A missing name returns nil. client:set_xproperty(name, value) accepts booleans, numbers and strings. nil removes the entry. Other types raise an error. Registration is unnecessary.

The values survive Lua hot reloads and are freed with the client. They are not X11 properties, are not visible to other applications, and do not survive a compositor exit.

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.

PropertyBehaviour
client.idCompositor-assigned client identifier, also used by somewm-client.
client.aspect_ratioWidth-to-height constraint. 0 or nil disables it.
client.xdg_fullscreenRead-only fullscreen state scheduled for an XDG client. Falls back to client.fullscreen for other clients.
client.xdg_maximizedRead-only maximised state scheduled for an XDG client. Falls back to client.maximized for other clients.
client.shadowPer-client shadow configuration. See shadows.

Client-drawn maximise and minimise buttons request the same Lua state changes as configuration actions. awful.permissions handles the resulting geometry requests. Protocol state can differ from Lua state. The xdg_* properties expose that distinction.

Signals​

Selected C-generated signals are queued. Lua-emitted signals and synchronous C requests run inline. The signal reference lists the exact dispatch rules.

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. awesome._active_modifiers lists the modifiers held right now from the keyboard's xkb state, so a faked press shows until its release:

root.fake_input("key_press", "Control_L")
root.fake_input("key_press", "Alt_L")
print(table.concat(awesome._active_modifiers, ", ")) -- {"Control", "Mod1"}
root.fake_input("key_release", "Alt_L")
root.fake_input("key_release", "Control_L")
print(table.concat(awesome._active_modifiers, ", ")) -- {}

XWayland limits​

These limits concern X11 applications running through XWayland, not native Wayland clients.

EWMH propertyLimit
_NET_FRAME_EXTENTSSomeWM does not publish frame extents.
_NET_DESKTOP_GEOMETRYThe EWMH value is fixed at 1920 by 1080, rather than the output layout's size.
_NET_WM_DESKTOP at initial mapThe requested desktop is read but does not assign the client's tag. Configure placement through client rules.

SomeWM extensions​

AreaAPI and documentation
Input devices and NumLockawful.input. awesome._set_keyboard_setting for NumLock
Lua utilitiesgears.xresources reads resource files. gears.bitwise provides bitwise operations on Lua versions without the operators
IPCsomewm-client, backed by awful.ipc
Identifying SomeWMawesome.release is "somewm" and awesome.version holds SomeWM's own version, not an AwesomeWM one. Check the release before comparing versions: the two projects' numbers overlap.
Outputs and scalingoutput, screen.scale
Capturescreen.content, awful.screenshot
Cursor themesroot.cursor_theme, root.cursor_size. input devices
ShadowsClient and wibox shadows. shadow reference
Tray integrationawful.systray, awful.statusnotifierwatcher, wibox.widget.systray_icon. wibox widgets
Layer-shell rulesruled.layer_surface. layer surfaces
Scrolling layoutsawful.layout.suit.carousel. carousel
Monitor reconnectionTag persistence. Saved state is keyed by connector name
Idle and lockingLock, idle and DPMS, session lock
Tree inspectionscreen.inspector, somewm.inspector, somewm-client clay tree. Reading the tree
Animationsomewm.animation, client and wibox animation policies. Animation

Changes from 2.0​

For upgrade steps, see Upgrading from 2.0 to 2.1. These tables list removed APIs and changed behaviour.

Removed APIs and properties​

Calling a removed function raises attempt to call ... (a nil value). Setting a removed widget, wallpaper or layout_animation property warns once that it is ignored. Setting surface_scale, shape_border or carousel.scroll_duration is silent and does nothing. Remove unused settings and replace calls as listed below.

Widget methods and drawing​

GoneInstead
fit, draw, layout, before_draw_children, after_draw_children on every stock widget, container and layout classUse built-in components, a Clay description or an image surface. See Port a custom widget.
wibox.hierarchy and all its methodsThe old hierarchy API has no replacement. Inspect calculated widget boxes in the tree dump and inspector.
wibox.widget.base.fit_widget, layout_widget, place_widget_at, place_widget_via_matrix, rect_to_device_geometry, and no_parent_I_know_what_I_am_doingUse widget layouts and containers. Clay computes their geometry.
wibox.widget.draw_to_cairo_context, draw_to_image_surface, draw_to_svg_file, wibox:to_widget, wibox:save_to_svgUse screen capture: root.content(), screen.content or somewm-client screenshot.
wibox.widget.textbox:get_height_for_width, get_height_for_width_at_dpiThe container sizes itself. Give a popup a maximum_width.
the drawable refresh method and surface property, the drawin surface_scale and shape_border propertiesDrawables no longer have surfaces. The renderer draws a shaped wibox's border from border_width and border_color.
the scroll container's context, first_x, first_y, fit_width, fit_height, hierarchy, surface_width, surface_heightThe container is a scroll element of the tree.
the wibox __tostringtostring(wibox) prints the table.

Classes and properties​

GoneInstead
wibox.container.borderwibox.container.background with border_width, border_color and shape. Loading the old module is an error.
horizontal_offset (stack)none. Stacked widgets share one box
minimum_column_width, superpose (grid)none. A widget added over another is refused
inner_fill_strategy (ratio)none
stretch_horizontally, stretch_vertically (background)none. The child fills the container
paddings (radialprogressbar)none
horizontal_crop, vertical_crop (tile)none
auto_dpi, source_width (imagebox)none. The output's scale applies
ticks_gap (progressbar)none
bar_border_color, bar_border_width, handle_margins (slider)none
empty_cell_mode, empty_color, empty_widget (calendar)none
check_border_color, check_border_width, check_shape (checkbox)shape draws the check
awful.wallpaper uncovered_areas_color, dpi, get_dpithe root wallpaper shows in uncovered areas. The output scale applies
awful.client.shape: get_transformed, update.all, update.bounding, update.clip, update.inputclient.shape
carousel.scroll_durationtheme.animation_layout_duration. See Animation.
somewm.layout_animation.easingNo equivalent. Use the built-in animation curves.
awesome.start_animationUse object animation policies. somewm.layout_animation is also deprecated.
awesome.systraywibox.widget.systray. The C painter entry point is gone
_wiboxwibox. The private surface-backed C module is gone
ruled.client.completed_with_payload_callbackruled.client.execute

Theme variables​

Gone with the properties that read them: slider_bar_border_color, slider_bar_border_width, slider_handle_margins, calendar_empty_color, checkbox_check_border_color, checkbox_check_border_width, checkbox_check_shape and radialprogressbar_paddings. Setting one does nothing.

Widget restrictions​

These values produce one warning naming the class, property and resulting behaviour:

You setWhat happens
bgimage to a functionwibox.drawable: bgimage functions are not drawn. A surface or a file path still draws, once at its own size in the top-left corner. To cover a bar, prepare the image at the bar's size (Put a PNG texture on your wibar).
a shape function that does more than trace a pathonly the path is taken. A colour it sets or anything it paints is dropped. gears.shape.rounded_rect and the other gears.shape functions are fine.
a widget tree of more than 4096 nodes in one wiboxthe wibox shows nothing and warns once that it is over the output's element budget.
a textbox with more than one line under a rotate or mirrorleft out with a warning. Rotated text is one line.
a wibox.container.scroll under a rotate or mirror, or a rotate inside a rotateleft out with a warning.
a grid with superpose, or a row spana widget added over another is refused. A span occupies its first row and warns.
a padding, gap or border width below 0it is 0, with a warning.
a colour that is not a solid or a gradient (a surface or mesh pattern)transparent, with a warning naming the property.

A textbox with ellipsize = "none" wraps at words; with it set, the default, it keeps one line per newline and is cut with an ellipsis instead. wrap = "char" warns that character wrapping is not applied. wibox.container.tile draws one copy of its widget and warns that tiling is not applied.

Layout, rendering and client behaviour​

Area2.1
Client shapeChanging c.shape emits property::shape and arranges the screen.
Entrance inputWidgets receive pointer events during their wibox or popup’s entrance animation.
Bordered popupsContent larger than the slot is clipped while the popup keeps its slot geometry.
Popup placementA popup placed next to a widget takes the first entry of preferred_positions and of preferred_anchors, whether or not it fits, and nothing keeps it on screen. 2.0 tried each entry in turn. The default order starts with "right", so a popup opened from a top wibar sits beside its widget, over the bar, and can run past the screen edge. Set preferred_positions = "bottom" and preferred_anchors = "back" to open it below the widget, right-aligned.
Popup geometrymove_next_to declares an attachment and the frame solves it. Until then a popup's x, y, width and height hold their earlier values, 1x1 at 0,0 for a popup not yet shown, so don't read them straight after the call.
Size-hint signalsproperty::size_hints fires when a Wayland client’s committed bounds change.
Layout leavesA leaf placed and sized with grow, fit or percent on one axis is omitted with a warning naming the client.
Fractional dimensionsPadding, gaps, offsets and border widths round to the nearest whole pixel.
Screenshot overlayInteractive selection covers the pointer’s screen.
Xwayland geometryContent-size requests pass through the Clay client frame. Geometry replies use the completed solve.
Render verificationrender_verify is removed. The verifier runs only in sanitizer and test builds.
Imagebox sizingAn imagebox without a forced size takes its size from an explicit ancestor size, as 2.0's fit did. With none on either axis it declares the image's own size and can overflow a flex or fixed layout. An imagebox forced on one axis scales its image to that axis.
Hotkeys help and menubarThey scroll instead of paging. Hotkeys: one column per group, continued every beautiful.hotkeys_rows rows (default 20), PgDn and PgUp scroll by one viewport. Menubar: left_label and right_label show while items lie beyond that side.
GridA non-homogeneous grid no longer sizes its columns to the widest cell across rows. A homogeneous grid inside a content-sized box takes content-sized cells and warns. Border dashes draw solid and gradient border colours are transparent, both with a warning.
Clients under a layoutAn ontop, above or below client tiles into its slot, as in AwesomeWM. A client whose protocol minimum exceeds its tiled cell overhangs the cell. The workarea and its neighbours keep their size. A client that draws a size other than the one it was given is drawn at the drawn size, cut at its cell.
Max and magnifierA floating client is above the layout's clients whatever the raise order, and a transient of a max or magnifier client is above every client of that layout.
Size hintsc.size_hints reports min and max width and height for Wayland clients, from the toplevel's committed bounds. A Wayland client whose min equals max reports is_fixed and floats.
Border widthA client whose rules set no border_width draws no border, as in AwesomeWM. 2.0 applied the theme's width from C. property::border_color also fires when the focus recolour changes the drawn border.
Overflow scroll signalsproperty::scroll_factor fires once the frame has applied a change, with the applied value, including for the mouse wheel and for a content or viewport change that moves the factor.
GradientsA slider bar_color gradient, an arcchart colors gradient and a separator color gradient are drawn in the bar's, the box's and the line's own box. Upstream used the widget's box or a centred square. A slider bar_active_color gradient now draws.
RotateA widget under a rotate receives press coordinates relative to its rotated box. Text under a rotate or mirror draws as one line.
Shapesshape_bounding, shape_clip and shape_input on a client or a wibox are accepted and never read, and warn by name. A client's corners come from client.shape and a wibox's from its shape.
Align with expand = "none"An outer widget wider than its half pushes the centre widget off centre instead of being cut at the half.
Stacking2.0 kept six fixed scene layers, background to overlay, and moved each client's and wibox's node between them in C. 2.1 has no layers: order is a band the tree declares (Scene Graph).
Layouts2.0's arrange computed a rectangle per client in Lua. 2.1 declares the layout as a Clay subtree. An arrange layout still works, with its numbers marked legacy in the dump.
Widget sizingClay computes widget geometry, replacing the per-widget fit and layout calls used in 2.0.
Client-local propertiesclient:set_xproperty stores scalar values across Lua hot reloads. The 2.0 method did nothing. See client properties.
Shadowsclip_directional is accepted but has no effect. Shadows fade on every side. Remove the setting. See shadow reference.
Layout animationA client frame declares no transition until something configures animation: c.animation, theme.animation_duration or any theme.animation_*_duration set to a number (0 included), theme.animation_appear or animation_disappear, or somewm.animation.layout_duration above 0. Requiring somewm.layout_animation sets that to 0.15 and is deprecated. A client's first frame after that, or after a reload, does not animate unless it has an entrance.

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.