Documentation

Contents

• Overview
• Dependencies
• Building & Installing
• Running LuraWM
• Choosing Status Bars
• Configuration
• Default Keybindings
• Mouse Bindings
• Layouts
• Tags
• Monitors
• Trackpad & Input
• Client Rules
• Patches
• Applying dwl Patches
• Status Bar Integration
• Environment & Session
• Troubleshooting

Overview

LuraWM is a minimal Wayland compositor forked from dwl. It follows the same suckless philosophy. Simple, fast, and easily extensible through patches. If you have ever used dwm on X11, you will feel at home here.

Dependencies

Required:

Additional for XWayland support:

On distributions with split packages (e.g. Debian, Fedora), install the -devel or -dev counterparts as well.

Building & Installing

git clone https://codeberg.org/Mandy/LuraWM
cd LuraWM
cp config.def.h config.h
# Edit config.h to your liking
sudo make install

This installs the lurawm binary to /usr/local/bin, the man page to /usr/local/share/man/man1, and a Wayland session desktop entry to /usr/local/share/wayland-sessions.

To change the install prefix, edit config.mk:

PREFIX = /usr

Enabling XWayland: Uncomment the XWayland flags in config.mk:

XWAYLAND = -DXWAYLAND
XLIBS = xcb xcb-icccm

To uninstall:

sudo make uninstall

Running LuraWM

LuraWM can be started directly from a TTY, or from within an existing Wayland or X11 session (useful for testing).

From a TTY:

lurawm

With a startup command (autostart.sh, status bar, etc.):

lurawm -s 'lurabar'

The -s command is run as a child process. LuraWM sends it SIGTERM at shutdown and waits for it to exit. This makes it suitable for launching service managers like s6, dinit, or systemd --user.

Command-line flags:

From a display manager: LuraWM installs a lurawm.desktop file. Display managers that support Wayland sessions will pick it up automatically.

If you are using the lurawm.desktop file, you can add the -s flag to add a startup script to your session. For example:

[Desktop Entry]
Name=LuraWM
Comment=Lura's Window Manager
Exec=sh -c 'lurawm -s "$HOME/path/to/autostart.sh"'
Type=Application

Choosing Status Bars

There hasn't been a huge variety of bars tested on LuraWM. LuraBar is the status bar made for LuraWM to address the unreliability of other alternatives. It is forked from dwlb and is actively maintained for LuraWM.

Other than LuraBar, Waybar works well.
With more hopefully coming soon.

dwlb & somebar, which are status bars made for dwl, are both unmaintained projects and do not work on LuraWM well.. Or at all.

As of now, there isn't a patch for adding a bar to LuraWM like the bar patch from dwl's repository. And as of writing this, that patch has been barely maintained by it's maintainer, sewn.

If you would like to rewrite or port that patch over to LuraWM's patches repository, go ahead! Create an issue, a pull request, or contact a maintainer.

Configuration

There are no runtime configuration files, configuring is done by editing config.h and recompiling.

cp config.def.h config.h
# Edit config.h to your liking
sudo make clean install

The file config.def.h is the default configuration template. Copy it to config.h.

Colors are defined as 32-bit hex RGBA values using the COLOR() macro:

static const float rootcolor[]   = COLOR(0x222222ff);
static const float bordercolor[] = COLOR(0x444444ff); /* Inactive */
static const float focuscolor[]  = COLOR(0x555555ff); /* Active */
static const float urgentcolor[] = COLOR(0xff0000ff);

Other settings in config.h:

To use the Super (Logo/Windows) key instead of Alt, change the define:

#define MODKEY WLR_MODIFIER_LOGO

Default Keybindings

The default MODKEY is Alt.
All keybindings below use Mod to mean whatever MODKEY is set to.

Window Management

Layout Control

Tag Navigation

Monitor Control

Session

Mouse Bindings

Layouts

LuraWM ships with three layouts.
The active layout is shown in the status bar area as its symbol, if you have a status bar like LuraBar which supports this.

You can adjust the master area ratio with Mod + h / Mod + l (5% by default), and add or remove windows from the master area with Mod + i / Mod + d.

Tags

Unlike traditional workspaces, tags are a bitmask. A window can belong to one or more tags simultaneously, and you can view one or more tags at the same time.

By default there are 9 tags, accessed via Mod + [1-9]. The maximum is 31 (defined by TAGCOUNT in config.h).

Sticky windows: To make a window visible on all tags, press Mod + Shift + 0 (assigns all tags). This is useful for always-visible terminals or music players.

Monitors

Multi-monitor configuration is handled via the monrules array in config.h. Each rule matches an output by name and specifies:

Example for a HiDPI laptop display:

{ "eDP-1", 0.5f, 1, 2, &layouts[0], WL_OUTPUT_TRANSFORM_NORMAL, -1, -1 },

To find your output names, run wlr-randr or check LuraWM debug output with lurawm -d.

Trackpad & Input

Trackpad and input settings are configured via libinput variables in config.h:

Keyboard layouts are configured via XKB rules:

static const struct xkb_rule_names xkb_rules = {
    .options = NULL,
};

Examples:

.layout = "us,de" for US/German
.options = "ctrl:nocaps" to map Caps Lock to Ctrl, or .options = "grp:alt_shift_toggle" to toggle layouts with Alt + Shift.

Client Rules

Client rules match windows by app_id (or WM_CLASS for XWayland) and title, then apply settings automatically. Defined in the rules[] array:

static const Rule rules[] = {
    /* app_id           title  tags mask  isfloating  monitor */
    { "Gimp_EXAMPLE",   NULL,  0,         1,          -1 },
    { "firefox_EXAMPLE", NULL, 1 << 8,    0,          -1 },
};

To find an application's app_id, focus its window and check the status output, or use tools like wlr-randr and wlprop.

Patches

All patches are available in the patches repository.

IPC Patch

Enables inter-process communication between LuraWM and external programs. The IPC protocol is based on dwl-ipc-unstable-v2 and is primarily used by LuraBar and other bars to receive tag, layout, and window information directly from the compositor, rather than parsing stdout.

With IPC enabled, LuraBar can respond to tag clicks and display live compositor state without the stdin/stdout pipe mechanism.

Gaps Patch

Adds configurable inner and outer gaps between tiled windows. Gap sizes are set in config.h after the patch is applied.

To apply a patch:

patch -p1 < patchfile.patch

Applying dwl Patches

Since LuraWM is a fork of dwl, many community patches from the dwl-patches repository can be ported with minimal effort.

Applying patches straight from dwl's patches repository is not recommended, but if you wish to, some hunks may fail. In that case, look at the .rej files and apply the changes manually. This applies to LuraWM patches too if they are unmaintained.

Status Bar Integration

LuraWM writes status information (tags, layout symbol, window title) to the stdout of the compositor, which is piped into the stdin of the -s command. This means any script that reads line-by-line from stdin can act as a status bar.

Using LuraBar:

lurawm -s 'lurabar'

Automatically detects IPC to handle tag clicks and live state updates.

Using a custom script:

lurawm -s 'your-bar-script'

lurawm -s 'foot --server <&-'

Inside a shell script, use exec <&- to close stdin for all subsequent commands.

Environment & Session

Wayland requires XDG_RUNTIME_DIR to be set. This is normally handled by your login manager or elogind/systemd-logind.

If you're launching without a session manager:

export XDG_RUNTIME_DIR=/tmp/xdg-runtime-$(id -u)
mkdir -p $XDG_RUNTIME_DIR
lurawm

Seat access: Depending on your setup, you may need to:

• Add yourself to the video and input groups, or
• Use elogind/systemd-logind with polkit installed, or
• Add yourself to the seat group and enable/start seatd

Java applications: Some Java AWT applications (e.g. Xilinx Vivado, IntelliJ) may not render correctly. Set this before launching:

export _JAVA_AWT_WM_NONREPARENTING=1

Troubleshooting

Screen sharing does not work

Wayland screen sharing requires xdg-desktop-portal-wlr and PipeWire. Make sure both are installed and running. Some applications also need the WAYLAND_DISPLAY and XDG_CURRENT_DESKTOP environment variables set.

XWayland applications look blurry on HiDPI

X11 applications are not aware of Wayland scaling. They render at 1x and the compositor scales them up. There is no general fix; some applications support GDK_SCALE or QT_SCALE_FACTOR.

No output / black screen after starting

Run lurawm -d for debug output. Common causes:

• Missing seat access (see Environment & Session)
• Wrong wlroots version (must be 0.19.x)
• GPU driver not loaded or incompatible

Borders do not change size

The borderpx variable in config.def.h may not visually change for higher values in the current release. This is a known issue tracked for the next release.

How do I restart LuraWM without losing my session?

You cannot. In the Wayland architecture, the compositor is the display server. Restarting it ends the session. Recompile and restart from a TTY.