Jump to content

Labwc

From ArchWiki

Related articles

Labwc stands for Lab Wayland Compositor[1]. According to the official website:

Labwc is a wlroots-based window-stacking compositor for Wayland, inspired by Openbox.
It is lightweight and independent with a focus on simply stacking windows well, and rendering some window decorations. It relies on clients for panels, screenshots, wallpapers, and so on to create a full desktop environment.
Labwc tries to stay in keeping with wlroots and sway in terms of general approach and coding style.
Labwc only understands wayland-protocols & wlr-protocols, and cannot be controlled with dbus, sway/i3-IPC, or other technology. The reason for this is that we believe that custom IPCs and protocols create a fragmentation that hinders general Wayland adoption.

Installation

Labwc can be installed with the labwc package.

Note To able to start labwc, it needs access to your seat, requiring either...
  • Polkit package to be installed, or...
  • seatd package to be installed with your user added to the seat user group and the seatd.service enabled.

The lack thereof will cause labwc to fail to start.

Tip Before starting labwc, it is advisable to install a terminal emulator. By default, you can press Super (usually a key with a Window icon) with Enter to launch the first terminal emulator found on your system from a list of well-known terminal emulators or you can set a terminal emulator in the #Custom keybindings later.

Starting

You can start it by typing labwc in the Linux console or using a Wayland-compatible display manager.

Configuration

User-specific configuration files are located in ~/.config/labwc/.

See upstream documentation for more details. Example files are provided in /usr/share/doc/labwc/. Especially, /usr/share/doc/labwc/rc.xml.all contains all the default configurations.

To apply configuration changes reload the compositor (by sending SIGHUP to $LABWC_PID): 

$ labwc --reconfigure

See labwc(1) and labwc-config(5) for further details.

labwc-tweaks-gitAUR is a GUI settings application, which manages settings in rc.xml and environment.

Checking for syntax errors

To check the xml files for syntax errors, e.g. with xmllint from libxml2: 

$ if xmllint --noout ~/.config/labwc/rc.xml; then echo "xml syntax ok"; else echo "xml syntax error"; fi

In case a configuration file has a faulty syntax, a default config will be used.

Integration with systemd

Labwc ships a tiny labwc-session.target, which binds to graphical-session.target. Consider enabling it so that services such as mako and/or xdg-desktop-portal, which depend on graphical-session.target, automatically start when labwc is launched: 

~/.config/labwc/autostart
systemctl -q --no-block --user start labwc-session.target

~/.config/labwc/shutdown
systemctl -q --user stop graphical-session.target

HDR

First, set wlroots to use Vulkan as the renderer, as described in #wlroots renderer. Then set <core><hdr> to yes in ~/.config/labwc/rc.xml. See labwc-config(5) for more information.

Autostart

Preferred place for starting Wayland-only applications is ~/.config/labwc/autostart. Scripts are executed when launching labwc. & is not needed for daemons. For example: 

~/.config/labwc/autostart
kanshi >/dev/null 2>&1 &

fcitx5 -r -d

waybar --log-level off &

swaybg -i ~/Pictures/background.png >/dev/null 2>&1 &

lxqt-policykit-agent >/dev/null 2>&1 &

mako >/dev/null 2>&1 &

gammastep -O 3500 -b 0.8 >/dev/null 2>&1 &

Example to start a screenlocker after 300 seconds of idle time: 

~/.config/labwc/autostart
swayidle -w timeout 300 'waylock' &

Keymap

The keyboard layout can be configured by setting environment variables in ~/.config/labwc/environment. For example: 

~/.config/labwc/environment
XKB_DEFAULT_LAYOUT=us
XKB_DEFAULT_LAYOUT=us,de
XKB_DEFAULT_OPTIONS=grp:alt_shift_toggle
XKB_DEFAULT_OPTIONS=grp:shift_caps_toggle

See xkeyboard-config(7) for details.

Activating numlock on startup

Numlock is not set by default, set it yes in <keyboard><numlock> section: 

~/.config/labwc/rc.xml
<labwc_config>
  <keyboard>
    <numlock>yes</numlock>
  </keyboard>
</labwc_config>

Outputs

A CLI utility to manage outputs of a Wayland compositor is wlr-randr. For example: 

~/.config/labwc/autostart
wlr-randr --output HDMI-A-2 --preferred --pos 0,0 --output HDMI-A-1 --preferred --pos -1920,0

A Wayland equivalent for the X11 tool like autorandr is kanshi.

wdisplays is a graphical application for configuring Wayland displays.

When using an external program to manage output, it is recommended that you set <core><autoEnableOutputs> to no in ~/.config/labwc/rc.xml. See labwc-config(5) for more information.

Statusbar

Use external tools like waybar and sfwbarAUR can be used to show status bars. For example: 

~/.config/labwc/autostart
waybar --log-level off &

Wallpaper

Use external tools like swaybg, wpaperd and wbgAUR can be used to show backgrounds. For example: 

~/.config/labwc/autostart
swaybg -c '#113344' >/dev/null 2>&1 &

Custom keybindings

Keybindings are configured by adding <keyboard><keybind> sections with <action>. For example: 

~/.config/labwc/rc.xml
<labwc_config>
  <keyboard>
    <keybind key="W-q"><action name="Close" /></keybind>
    <keybind key="A-Tab"><action name="NextWindow" /></keybind>
    <keybind key="W-Tab"><action name="ToggleMaximize" /></keybind>
    <keybind key="W-s"><action name="Execute" command="foot" /></keybind>
    <keybind key="W-a"><action name="Execute" command="fuzzel" /></keybind>
  </keyboard>
</labwc_config>

Workspaces

Workspaces are configured in <desktops> section and switched with keybindings. For example: 

~/.config/labwc/rc.xml
<labwc_config>
  <desktops number="4" />
  <keyboard>
    <keybind key="W-1"><action name="GoToDesktop" to="1" /></keybind>
    <keybind key="W-2"><action name="GoToDesktop" to="2" /></keybind>
    <keybind key="W-3"><action name="GoToDesktop" to="3" /></keybind>
    <keybind key="W-4"><action name="GoToDesktop" to="4" /></keybind>
  </keyboard>
</labwc_config>

Labwc follows Openbox's syntax for menu configuration in ~/.config/labwc/menu.xml. For example: 

~/.config/labwc/menu.xml
<?xml version="1.0" ?>
<openbox_menu>
  <menu id="root-menu" label="">
    <item label="Firefox" icon="firefox">
      <action name="Execute" command="firefox" />
    </item>
    <item label="Terminal" icon="/usr/share/icons/Adwaita/symbolic/legacy/utilities-terminal-symbolic.svg">
      <action name="Execute" command="foot" />
    </item>
  </menu>
</openbox_menu>

Also, you can use menu generators for Openbox like archlinux-xdg-menu and obmenu-generatorAUR.

See labwc-menu(5) for details.

Themes

Labwc loosely follows Openbox 3 theme specification. You can install themes to the following directories:

  • ~/.local/share/themes/theme-name/labwc/
  • ~/.themes/theme-name/labwc/
  • /usr/share/themes/theme-name/labwc/
  • /usr/local/share/themes/theme-name/labwc/
  • /opt/share/themes/theme-name/labwc/
  • ~/.local/share/themes/theme-name/openbox-3/
  • ~/.themes/theme-name/openbox-3/
  • /usr/share/themes/theme-name/openbox-3/
  • /usr/local/share/themes/theme-name/openbox-3/
  • /opt/share/themes/theme-name/openbox-3/

These directories contain themerc which defines the theme colors and geometries, and button icon files like close-active.svg and close-inactive.svg. XBM, SVG and PNG formats are supported for icon files.

Additionally, you can override the theme entries with ~/.config/themerc-override.

labwc-artwork provides some themes for labwc.

See labwc-theme(5) for details.

Xwayland

To run X clients under Wayland, install the optional package xorg-xwayland. When installed, it is automatically used by labwc.

To specify which Xwayland implementation to use or e.g. disable it, set the wlroots environment for labwc: 

~/.config/labwc/environment
WLR_XWAYLAND=

wlroots renderer

The default renderer is OpenGL and sufficient for normal desktop usage.

To use another renderer such as Vulkan for modern gaming, heavy 3D workloads or advanced GPU compute, see Wayland#Use another renderer for wlroots based compositor. You can simply set this environment variable in ~/.config/labwc/environment.

Tips and tricks

Screen capture

See Screen capture#Wayland for selecting a Wayland / wlroots-based compatible compositor.

See also