Wayland support

The latest version of Cairo-Dock (3.6.0) includes support for running on Wayland, under compositors that support the layer shell protocol. It has been tested with recent versions of Wayfire, labwc, KWin / KDE Plasma, Cosmic, sway, Hyprland and niri. Note that GNOME Shell / Mutter, including the default Ubuntu desktop, is unfortunately not supported.

Requirements

Compilation: see the guide. Note that all optional dependencies are required. When configuring, the CMake summary should include the following:

--  * With EGL support    : yes (1.5)
--  * With Wayland support: yes (1.22.0)
--  * With Wayland taskbar: yes
--  * With Wayfire IPC    : yes
--  * With gtk-layer-shell: yes

To be usable, the following protocols need to be supported by the compositor:

• layer-shell: this is required for positioning the dock on the screen (recommended at least version 4 to allow the dock to receive keyboard events).
• one of the following protocols to provide taskbar functionality: wlr-foreign-toplevel-management, plasma-window-management or cosmic-toplevel-management

Optionally, if using Wayfire, this plugin provides the "present windows" feature (when an icon with a group of windows is clicked).

Using Cairo-Dock in a Wayland session

For now, it is recommended to first set up your session as normal (using any session files provided with your compositor) and then configure your compositor to autostart Cairo-Dock upon log in. This typically requires a compositor-specific setting (e.g. if using Wayfire, you can use WCM, or if using KWin / KDE Plasma, you can add autostart programs in your system settings).

Alternatively, if you session is based on systemd, you can use the unit provided by Cairo-Dock to make it start automatically -- see here.

An unofficial "desktop session" based on Wayfire is also provided here: https://github.com/dkondor/cairo-dock-wayland-session

Main features working

• Dock positioning along a screen edge and keeping above / below and reserving space with the layer-shell protocol.
• Proper positioning of subdocks, menus and dialogs.
• Hardware acceleration with EGL.
• Taskbar.
• Hiding and recalling docks hidden or kept below.
• HiDPI displays only with integer scale factors.
• Wayfire-specific features: custom protocol for recalling the dock, scale for "present windows", toggle menu feature, global keybindings ("shortkeys").
• KWin-specific features: workspaces, detecting if windows overlap the dock, tracking window positions among workspaces
• Labwc / Cosmic: basic support for workspaces (display and switching; only one "workspace group" supported, this can lead to problems with multiple monitors)
• Cosmic: detecting if windows overlap the dock, tracking window positions on workspaces

Known issues and limitations

• Global keyboard shortcuts for actions ("shortkeys"): only supported on Wayfire.
• Subdocks disappear when an app is activated (this is a limitation of using xdg-popups; seems not the be an issue on KWin).
• "Keep the dock below" option is buggy on older KWin (at least version 5.24). Works well on recent versions (tested on version 6.4.1).
• Multi-monitor support is limited: docks can be placed only on a single screen.
• Tracking virtual desktops / workspaces: displayed layout can be wrong (KWin).
• Tracking virtual desktops / workspaces: only one "workspace group" is supported, with multiple monitors, not all workspaces will be tracked (Cosmic / Labwc).
• Cosmic: tracking window positions across multiple monitors is buggy.
• EGL rendering under Wayland relies on an officially unsupported interface in GTK (i.e. it uses gtk_widget_set_double_buffered() which is only supported on X11); in practice it works well at least with GTK versions 3.22.30 -- 3.24.41 on recent versions of all compositors tested.
• EGL / OpenGL does not work very old KWin versions (5.20). An error message complains about some layer-shell surfaces having a zero size set; this might be related to the above point. Run the dock with the -c switch.
• Placement of desklets does not work; desklets behave as regular windows and need to be positioned manually (see below for an example).

Positioning desklets

This requires either manually setting a position, or setting up a "window rule" if your compositor has such a functionality. See here for setting this up on Wayfire

Supported compositors

To be included here, at least the main features (positioning docks and taskbar, recalling hidden docks) should work; only additional features beyond these are listed below. Feel free to update or expand this section if you were able to test Cairo-Dock on a compositor not listed here. Note that all functionality requires at least the latest stable version of Cairo-Dock (3.6.0); where indicated, some functionality only works on the development versions.

Wayfire

Tested version: 0.10.0 release and newer, main features work on older versions as well Extra features:

• scale / overview, show desktop, expo (need to enable the "IPC protocol" Wayfire plugin)
• scale for grouped windows (need this additional Wayfire plugin)
• keyboard shortcuts ("shortkeys"; only on 3.6.93 and newer)
• additional windows states (sticky and always on top; only on 3.6.95 and newer; see here on how to enable it)
• hiding the dock on overlap with windows (only on 3.6.95 and newer; needs the following Wayfire plugins: "IPC", "Window Rules IPC Interface")
• desktop session available here

KWin / KDE Plasma

Tested version: 6.5.3 (but main features already work on KWin 5) Extra features:

• scale / overview, show desktop, expo (need to enable the "Overview" effect in "System Settings")
• scale for grouped windows
• tracking window positions
• hiding the dock on overlap with windows
• tracking and switching virtual desktops / workspaces
• tracking windows across workspaces
• session integration (log out, shutdown, lock screen, etc.)

Cosmic

Tested version: 0.1.0 (version in Arch Linux) Extra features:

• tracking window positions
• hiding the dock on overlap with windows
• tracking and switching virtual desktops / workspaces
• tracking windows across workspaces Limitation: only one workspace group, tracking workspaces and windows will not work with multiple monitors

Labwc

Tested version: 0.9.2 (but main features should work on older versions as well) Extra features: tracking workspaces (but not window positions on them) Limitation: only one workspace group

Others

• Hyprland: main features have worked for a long time, but have not tested on recent versions
• niri: see here, main features work, Overview can be activated via IPC
• sway: main features have worked for a long time, but have not tested on recent versions

Supporting other compositors

For full functionality, Cairo-Dock requires support for two main features in a compositor:

• window positioning
• information on currently running apps

While these were available by default to any app on X11, this is not the case on Wayland (due to core design decisions to better separate running apps from each other). Individual compositors might provide these as specific extensions (custom protocols) or plugins. To provide a reasonable user experience in Cairo-Dock, some form of support from the compositor side for these will be necessary.

Window positioning

Currently, Cairo-Dock uses the layer-shell protocol, which is created to provide desktop shell functionality and is emerging as a standard for this purpose (see here for explicit standardization efforts). Layer-shell is based on the concept that the compositor works together with a client app (such as Cairo-Dock) to determine its position. However, this is not a strict requirement. An alternative could be a compositor automatically positioning docks without any involvement on the Cairo-Dock side. Several compositors already provide this kind of functionality, such as a "window rules" option or similar (or such functionality can be easily added as a plugin / addon).

Taskbar

Currently, Cairo-Dock needs to receive info about running apps from the compositor, and supports several protocols for this purpose. Adding support for additional compositors that use their custom protocol would be relatively easy. Similarly, some other IPC method could be used and will be considered as necessary. For a compositor that currently does not support any such method, writing an extension or plugin would be necessary of course. An alternative is to use Cairo-Dock's DBus interface to add icons that represent running apps. However, this would require at least some modifications to how the DBus interface works and of course a matching IPC plugin on the compositor side.