Retired Techie

Introduction

Greetings, everyone! My goal for this article was to set up a Wayland-based graphical environment on a minimal Arch Linux installation using Labwc.

Achieving this goal without Xwayland has proven basically impossible. A large number of Linux application’s are still based on X11, which prevents a pure Wayland installation. While not the focus here it does make me wonder why are mainstream distributions and desktop environments are so bent on leaving X11 behind?

But I need to get off the soap box and proceed with creating a mostly Wayland based light Graphical User environment.

Yes, Wayland is the future! So I need to learn something about it. However, X11 can do things that Wayland compositors may never support, just as Wayland can do things X11 will never be capable of. Which is why it is impossible to have a pure Wayland experience.

For this project, I’ve chosen Labwc, mainly because I’m not a fan of tiling window managers. I’ve tried them under X11, but I’m too old and set in my ways to change my workflow. Labwc follows in the tradition of Openbox, a classic X11 window manager.

While I wanted a native to Wayland setup, the lack of a good selection of Wayland based applications doesn’t make that practical.

When building out the graphical user environment, there are plenty of Wayland tools for taskbar, wallpaper, login, etc. The problem shows up with productivity applications; many haven’t been converted to run under Wayland, and some may never be.

Since my goal is a usable Graphical User Environment (GUI), and Labwc is a basic light weight stacking Window manager Compositor, I will need to add additional functionality with some third party programs.
Also I am aiming for working, and not overly worried about look and feel at this point. In depth configuration is a subject for an entire article unto itself.

So, as a mater of length, I will be skipping over a lot of the look and feel configuration, and focusing on the functionality stuff.

The Labwc Home Page

Before getting into the details, visit the Labwc home page. It is well organized and easy to read, and its opening page provides a helpful overview of the Labwc project.

The README section explains the project’s current state and what to expect in the future. If you plan to use third-party applications with Labwc, such as panels or taskbars, be sure to read the integration section as well.

The Getting Started section gives you a good idea of what to expect when using Labwc before configuring it.

The Virtual Machine

I’m using the virtual machine (VM) I created for an earlier article about installing Arch with Btrfs. It’s a basic, minimal installation, with OpenSSH and Sudo as the main exceptions.

If you’re interested but haven’t read the previous article, you can find it here. It explains how I installed Arch with Btrfs, and the VM I’m using now is the result of that installation.

Because the VM is running an SSH server, I can connect to it from the host using SSH. I’m using Virt-Manager, and although the VM console can display either a terminal or a graphical desktop, it has some limitations. For example, in my setup, I can’t copy and paste text between the host and guest through the Virt-Manager console. Connecting to the VM through an SSH terminal lets me copy and paste text, though only within the terminal.

Installing Labwc

Since I’m new to both Wayland and Labwc, I’m keeping the initial setup simple. I don’t want extra complexity to distract me, but I do need a few utilities to make the desktop easier to use; a terminal emulator, a file manager, a text editor, a taskbar, and a way to set the wallpaper.

I’m using Arch, so I’ll install Labwc with pacman. Wayland will be installed as a dependency if it isn’t already present. I’ll also explicitly install Xwayland for X11 application compatibility, Foot as a Wayland terminal, PCManFM as a file manager, Geany as a text editor, wlr-randr for display-output management, swaybg for setting the wallpaper, and Waybar as a taskbar.

This list leaves out many features of a full desktop environment, but it should provide a good starting point. Later, I’ll consider adding a polkit authentication agent, a screen locker, and other utilities.

I’ll also update the system while installing the packages, using this command:

sudo pacman -Syu labwc xorg-xwayland pcmanfm-qt featherpad wlr-randr foot swaybg waybar

The -S option installs the named packages and their dependencies. The -y option refreshes the package databases, and -u option upgrades installed packages. Since I’m running this as a regular user, I use sudo to run the installation with administrative privileges.

For now, I’m avoiding a display manager (login manager) and will start Labwc from the VM’s local TTY.

Important: Use SSH only to run terminal commands in the guest. Don’t attempt to launch Labwc from an SSH session.

Important Labwc Locations

The following notes are based on reading the relevant man pages, exploring the Labwc website, and trying things out on my system. After installation, there are a few important files and locations to know about.

On my Arch installation, example configuration and theme files are installed in:

ls -al /usr/share/doc/labwc

XDG environment variables can change where Labwc looks for configuration and theme files. To check whether they are set, run:

echo $XDG_CONFIG_HOME
echo $XDG_CONFIG_DIRS
echo $XDG_DATA_HOME
echo $XDG_DATA_DIRS

These variables are unset in my base installation, so Labwc uses the default locations:

• User configuration ~/.config/labwc/
• System configuration /etc/xdg/labwc/
• User themes ~/.local/share/themes/<theme-name>/labwc/
• System themes /usr/local/share/themes/<theme-name>/labwc/ and /usr/share/themes/<theme-name>/labwc/

The labwc executable is installed at /usr/bin/labwc.

On my installation, Labwc didn’t create configuration or theme folders, and it can start without configuration files.

Starting Labwc

Unlike X11, you don’t use startx to start a Wayland session; you launch the compositor directly:

labwc

You should see a blank screen with a cursor. If you’ve used Openbox, this may look familiar; if not, it might be surprising. This is expected, as I haven’t configured a panel or taskbar, or started a program to set the background. Left click the desktop to open Labwc’s root menu. In Labwc 0.9.0 and later, the default menu includes a Terminal option.

Open the terminal and type:

pcmanfm-qt &

This should open the file manager. The & runs the process in the background, returning control to the terminal. You can launch the text editor the same way:

featherpad &

So far, so good, you can use Labwc this way. I once used LWM, a very small X11 window manager, for three months with a similarly minimal setup.

This shows that Labwc can start and run without a configuration file. But the bare setup can get tiring, so I’ll make a few changes to improve the experience.

Labwc Configuration Files

First, I want to look for existing configuration files. We know the default locations, so let’s check whether they exist:

ls ~/.config/labwc/
ls /etc/xdg/labwc/

On my installation, neither the files nor the directories exist. To be clear, this is just what I found on my system; other distributions may create these directories or set XDG variables during installation. My Arch installation left me with a blank slate. The same is true of the theme directories.

There are the example configuration and theme files in /usr/share/doc/labwc, which can be used as references.

Next, I’ll create directories for my user configuration and theme:

mkdir -p ~/.config/labwc
mkdir -p ~/.local/share/themes/rt-theme/labwc

The -p option creates any missing directories in the path. You could also create them with a file manager.

Labwc can run without configuration files, so I’ll add files only when I need them rather than creating empty placeholders. I’ll start by copying the example menu file, since I want to keep the existing menu and customize it later. First, I’ll check the exact filenames in the documentation directory:

ls -al /usr/share/doc/labwc

The menu example is named menu.xml, and I can copy it with:

cp /usr/share/doc/labwc/menu.xml ~/.config/labwc/

To apply changes to most configuration and theme files, select Reconfigure from the Labwc menu or run:

labwc –reconfigure

Autostart Configuration File

The first thing I want to configure is the autostart file. Since it’s in my home directory, I don’t need sudo to edit it. I can use nano in the terminal or geany as a graphical editor.

First, I want to correct the display resolution. I’ll check the available output names and modes by running wlr-randr from within Labwc:

wlr-randr

This displays information about my outputs and their available resolutions. I’ll use the output name and a supported resolution from that list in the autostart file:

nano ~/.config/labwc/autostart

For my VM, I’ll add:

wlr-randr --output Virtual-1 --mode 1920x1080 --scale 1

After saving the file and restarting Labwc, this should set the display to the correct resolution on my system.

Next, I want to check that background settings are working. I’ll add this line to autostart:

swaybg -c '#774400' > /dev/null 2>&1 &

This sets the background to a dark orange-brown color. The redirections send standard output and error output to /dev/null, and & runs the process in the background.

Finally, I’ll start the taskbar by adding:

Waybar > /dev/null 2>&1 &

After saving the changes, I’ll restart Labwc to run the updated autostart file. Labwc’s documentation describes autostart as a startup shell script and specifies that changes to it require restarting the compositor.

Labwc Menu

I want to edit ~/.config/labwc/menu.xml to add the file manager and text editor to the root menu.

The file defines different menus. The client-menu is associated with windows; how it opens depends on the mouse bindings. The root-menu is the menu shown when I click the desktop. The file may also define custom menus, but those won’t appear automatically unless they’re added to another menu or connected to an action.

In the root-menu, I’ll find the Terminal entry:

<item label="Terminal">
    <action name="Execute" command="lab-sensible-terminal" />
</item>

The lab-sensible-terminal looks for a compatible terminal emulator and launches one. I want to use Foot specifically, so I’ll change the command:

<item label="Terminal">
    <action name="Execute" command="foot" />
</item>

Then I’ll add these two entries inside the same <menu id=”root-menu”> section:

<item label="File Manager">
    <action name="Execute" command="pcmanfm-qt" />
</item>
<item label="Text Editor">
    <action name="Execute" command="featherpad" />
</item>

After saving the file, I’ll run labwc –reconfigure. The root menu should then include the File Manager and Text Editor entries.

Next Steps & Advanced Configuration

To keep this guide concise and practical, I won’t dive into deep customization or theming today. The main goal was to get Labwc up, running, and completely usable, and we’ve achieved that!

However, if you want to push Labwc from a simple window manager into a fully customized desktop environment, you will want to explore its more advanced configuration files:

• environment – For setting session variables.

• rc.xml – For defining keybindings, mouse actions, and window rules.

• themerc – For custom styling, fonts, and window borders.

• shutdown – For running clean-up scripts upon exit.

Want to see more Labwc guides? Let me know in the comments below, and I will cover these advanced topics and theming tricks in a future article!

Conclusion

This is where my long road starts. I need to make copies of my config and theme files, so I have no issue making local changes. If I mess things up to badly, I can just overwrite the file with a copy of the original.

I also have a number of programs to investigate that will add functionality. The question is are they the best choices.

Plus I need to add a few application’s so I can play with the menu system. Since I have included xwayland, this has expanded what’s available.

Regardless, I got it working, so the objective has been meet. The next objective is making it a more usable environment. So Next Time!