labwc

[Website] [Scope] [IRC Channel] [Release Notes]

• 1. What is this?
• 2. Build and Installation
• 3. Configuration
• 4. Theming
• 5. Usage
• 6. Integration
• 7. Scope

1. What is this?

Labwc stands for Lab Wayland Compositor, where lab can mean any of the following:

• sense of experimentation and treading new ground
• inspired by BunsenLabs and ArchLabs
• your favorite pet

Labwc is a wlroots-based window-stacking compositor for wayland, inspired by openbox.

It is light-weight and independent with a focus on simply stacking windows well and rendering some window decorations. It takes a no-bling/frills approach and says no to features such as icons (except window buttons), animations, decorative gradients and any other options not required to reasonably render common themes. 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 it 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.

In order to avoid reinventing configuration and theme syntax, the openbox 3.6 specification is used. This does not mean that labwc is an openbox clone but rather that configuration files will look and feel familiar.

Labwc supports the following:

• Config files (rc.xml, autostart, environment, menu.xml)
• Theme files and xbm icons
• Basic root-menu and client-menu
• HiDPI
• wlroots protocols such as output-management, layer-shell and foreign-toplevel
• Optionally xwayland

See scope for full details on implemented features.

video link	date	content
Video (0:18)	16-Oct-2021	SnapToEdge feature
Video (1:10)	05-Aug-2021	window gymnastics, theming and waybar
Video (3:42)	25-Feb-2021	setting background and themes; xwayland/xdg-shell windows

2. Build and Installation

To build, simply run:

meson build/
ninja -C build/

Run-time dependencies include:

• wlroots, wayland, libinput, xkbcommon
• libxml2, cairo, pango, glib-2.0
• xwayland, xcb (optional)

Build dependencies include:

• meson, ninja, gcc/clang
• wayland-protocols

Disable xwayland with meson -Dxwayland=disabled build/

For OS/distribution specific details see see wiki.

3. Configuration

For a step-by-step initial configuration guide, see getting-started

User config files are located at ${XDG_CONFIG_HOME:-$HOME/.config/labwc/} with the following four files being used:

file	man page
rc.xml	labwc-config(5), labwc-actions(5)
menu.xml	labwc-menu(5)
autostart	labwc(1)
environment	labwc-config(5)

The example rc.xml has been kept simple. For all options and default values, see rc.xml.all

Configuration and theme files are reloaded on receiving SIGHUP (e.g. killall -s SIGHUP labwc)

For keyboard settings, see environment and xkeyboard-config(7)

4. Theming

Themes are located at ~/.local/share/themes/\<theme-name\>/openbox-3/ or equivalent XDG_DATA_{DIRS,HOME} location in accordance with freedesktop XDG directory specification.

For full theme options, see labwc-theme(5) or the themerc example file.

For themes, search the internet for "openbox themes" and place them in ~/.local/share/themes/. Some good starting points include:

• https://github.com/addy-dclxvi/openbox-theme-collections
• https://github.com/the-zero885/Lubuntu-Arc-Round-Openbox-Theme
• https://bitbucket.org/archlabslinux/themes/
• https://github.com/BunsenLabs/bunsen-themes

5. Usage

./build/labwc [-s <command>]

NOTE: If you are running on NVIDIA, you will need the nvidia-drm.modeset=1 kernel parameter.

If you have not created an rc.xml config file, default bindings will be:

combination	action
alt-tab	activate next window
super-return	alacritty
alt-F3	bemenu
alt-F4	close window
super-a	toggle maximize
alt-mouse-left	move window
alt-mouse-right	resize window
alt-arrow	move window to edge
super-arrow	resize window to fill half the output
XF86_AudioLowerVolume	amixer sset Master 5%-
XF86_AudioRaiseVolume	amixer sset Master 5%+
XF86_AudioMute	amixer sset Master toggle
XF86_MonBrightnessUp	brightnessctl set +10%
XF86_MonBrightnessDown	brightnessctl set 10%-

A root-menu can be opened by clicking on the desktop.

6. Integration

Suggested apps to use with labwc:

• Screen shooter: grim
• Screen recorder: wf-recorder
• Background image: swaybg
• Panel: waybar, yambar, lavalauncher, sfwbar
• Launchers: bemenu, fuzzel, wofi
• Output managers: wlopm, kanshi, wlr-randr
• Screen locker: swaylock

See integration for further details.

7. Scope

A lot of emphasis is put on code simplicity when considering features.

The main development effort is focused on producing a solid foundation for a stacking compositor rather than adding configuration and theming options.

See scope for details.

High-level summary of items which are not intended to be implemented:

• Icons (except window buttons)
• Animations
• Gradients for decoration and menus
• Any theme option not required to reasonably render common themes (it is amazing how few options are actually required).