Skip to content

getting-started.md: re-write most of the document #73

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 11, 2025
Merged

getting-started.md: re-write most of the document #73

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
250 changes: 124 additions & 126 deletions src/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,152 +1,121 @@
# Getting Started

Labwc is designed to be easy to get started with.
## Introduction

To use the compositor for the first time, there is no need for configuration
files, theme files or even a session file. It should be enough to simply run
the labwc binary from a TTY or Wayland/X11 session.
If you are coming to labwc for the first time, this is the page to read. Should
you get stuck, do reach out on the [IRC Channel] or [Github Discussions].

If labwc is not packaged by your OS/distribution of choice, it is quite easy
to build (which should take no more than a few seconds) and run from the build
directory.[^1]

[^1]: The compositor works fine without doing a system-wide installation, but
just be aware that you will not get localized (translated to local
language) window context menus, nor will you get a system-wide .desktop
file where most display managers look for them (if you use one of them).
[IRC Channel]: https://web.libera.chat/gamja/?channels=#labwc
[Github Discussions]: https://github.com/labwc/labwc/discussions

The first time you run labwc, you'll be greeted by a blank screen. If you click
on the desktop you will see your root-menu containing 'Reconfigure' and 'Exit'.
Although this initial appearance is minimalist and sparse, it is easy to get
started.
## Context

Before doing any configuration, you can start labwc with the following command
to start an application (alacritty is used in the example, but it could of
course be any application):
Labwc is a system level software component for which the entry barrier is
higher compared with that of many user applications. It can be perceived as
difficult to set up due to the need for manual configuration and because it is
a base component upon which Desktop Environments can be built which means that
there are many ways in which it can be used and that work is required to get
the best out of it. But fret not, with a small amount of work some very
creative experiences will be opened up that will most likely be worth the
effort.

```
labwc -s alacritty
```
Pre-configured [Desktop Environments] exist using `labwc` as the compositor,
but in this document you will be guided to start the compositor without any
such setup.

Alternatively, if you have bemenu installed, you can use the default keybind
Alt-F3 to launch applications.
[Desktop Environments]: links.html#desktops

<img src="img/scrot-first-start.png" />
## Installation

# Configuration
Install `labwc` with your package manager and come back here when done.

User config files are located at `${XDG_CONFIG_HOME:-$HOME/.config/labwc/}`
(usually `~/.config/labwc/`) with the following five files being used:
[rc.xml], [menu.xml], [autostart], [environment] and [themerc-override].
Also install `alacritty` (a terminal emulator which is available in most
distros' repositories). There is of course nothing forcing you to use
`alacritty` but it is likely to be useful the first time the start the
compositor.

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

For full details on configuration options, see the man pages:
[labwc(1)], [labwc-config(5)], [labwc-theme(5)], [labwc-actions(5)] and
[labwc-menu(5)].
Launch labwc by typing `labwc` in your terminal. Some Display Managers (like
`SDDM` or `GDM`) will show labwc, so you can also start from there.

Run `labwc --reconfigure` to reload configuration and theme files.
> TECHNICAL NOTE: labwc can be started from a TTY or nested in a Wayland/X11
> session.

Your OS/Distribution of choice may include these example configuration files in
`/usr/share/doc/labwc/` or similar. If not, you could download them with:
If you start `labwc` with no prior configuration you will be greeted by a blank
screen. If you click on the desktop you will see your root-menu containing only
'Reconfigure' and 'Exit' (and 'Terminal' from version 0.9.0 onwards). Do not be
put off by this sparse appearance. There is a lot more to this compositor than
first meets the eye.

```bash
mkdir -p ~/.config/labwc
wget https://raw.githubusercontent.com/labwc/labwc/master/docs/environment -O ~/.config/labwc/environment
wget https://raw.githubusercontent.com/labwc/labwc/master/docs/autostart -O ~/.config/labwc/autostart
wget https://raw.githubusercontent.com/labwc/labwc/master/docs/menu.xml -O ~/.config/labwc/menu.xml
wget https://raw.githubusercontent.com/labwc/labwc/master/docs/rc.xml -O ~/.config/labwc/rc.xml
```
You can start a terminal by pressing `Super + Return`.

> **_NOTE:_** Before using these configuration files, please read them through
> and modify the content to suit your specific needs.
<img src="img/scrot-first-start.png" />

For more information about each configuration file and to help create a setup
that work for you, please read through the sections below.
# Configuration

If you get stuck, do reach out on the [IRC Channel] or [Github Discussions].
Configuration files are located in `$HOME/.config/labwc/`

[rc.xml]: https://github.com/labwc/labwc/blob/master/docs/rc.xml
[rc.xml.all]: https://github.com/labwc/labwc/blob/master/docs/rc.xml.all
[menu.xml]: https://github.com/labwc/labwc/blob/master/docs/menu.xml
[autostart]: https://github.com/labwc/labwc/blob/master/docs/autostart
[environment]: https://github.com/labwc/labwc/blob/master/docs/environment
[themerc-override]: https://github.com/labwc/labwc/blob/master/docs/themerc
[labwc(1)]: https://labwc.github.io/labwc.1.html
[labwc-config(5)]: https://labwc.github.io/labwc-config.5.html
[labwc-menu(5)]: https://labwc.github.io/labwc-menu.5.html
[labwc-environment(5)]: https://labwc.github.io/labwc-environment.5.html
[labwc-theme(5)]: https://labwc.github.io/labwc-theme.5.html
[labwc-actions(5)]: https://labwc.github.io/labwc-actions.5.html
[IRC Channel]: https://web.libera.chat/gamja/?channels=#labwc
[Github Discussions]: https://github.com/labwc/labwc/discussions
In this guide we are going to cover some common setup steps which will give you
a good feel for the four most important configuration files which are:
[environment], [rc.xml], [autostart] and [menu.xml].

## Step 1 - Set your keyboard layout
Whenever a configuration or theme file has been changed, the command `labwc
--reconfigure` has be run for the settings to take affect. With additions to
`autostart` you will need to re-start the compositor.

Set the environment variable `XKB_DEFAULT_LAYOUT` with your country code.
It is generally recommended not to copy the example configuration files, but to
build them from scratch.

For example to start with Swedish keyboard layout, run
## Step 1 - Set your keyboard layout

```
XKB_DEFAULT_LAYOUT=se labwc
```
Set the environment variable `XKB_DEFAULT_LAYOUT` with your country code in
`~/.config/labwc/environment`.

Or simply add this line to `~/.config/labwc/environment`
For example to use a Swedish keyboard layout, add this line:

```
XKB_DEFAULT_LAYOUT=se
```

If you are unsure what your country code is, refer to the 'layout' section of
`/usr/share/X11/xkb/rules/evdev.lst`
If you are unsure what your country code is, use the website
[xkeyboard-config.freedesktop.org] or search the 'layout' section of your
local copy of `evdev.lst` which is typically located at
`/usr/share/X11/xkb/rules/evdev.lst`.

See further details, see [docs/environment] and [xkeyboard-config(7)].
See further details, see [environment] and [xkeyboard-config(7)].

[xkeyboard-config.freedesktop.org]: https://xkeyboard-config.freedesktop.org/layouts/gallery
[xkeyboard-config(7)]: https://manpages.debian.org/testing/xkb-data/xkeyboard-config.7.en.html

## Step 2 - Add some items to the root-menu

Create a `~/.config/labwc/menu.xml` to hand-craft a menu. See [docs/menu.xml]
for inspiration, or use the simple example below

```
<?xml version="1.0" ?>

<openbox_menu>
<menu id="root-menu" label="">
<item label="Web browser"><action name="Execute" command="firefox" /></item>
<item label="Terminal"><action name="Execute" command="alacritty" /></item>
<item label="Reconfigure"><action name="Reconfigure" /></item>
<item label="Exit"><action name="Exit" /></item>
</menu>
</openbox_menu>
```

See [integration#menu-generators] for ideas on how to automatically create
menu.xml files.
## Step 2 - Set some keybinds

## Step 3 - Set a shortcut to a launcher

If you want to bind a key-combination to a launcher such as rofi or wofi, or
simply a terminal, create a configuration file `~/.config/labwc/rc.xml` and add
a `<keybind>` entry as shown below. In this example `Super-d` is bound to the
terminal sakura:
If you want to bind a key-combination to an application like a launcher or
terminal, create a configuration file `~/.config/labwc/rc.xml` and add a
`<keyboard>` section as shown below.

```
<?xml version="1.0" ?>
<labwc_config>

<keyboard>
<default />
<keybind key="W-d"><action name="Execute" command="sakura" /></keybind>
<keybind key="W-z"><action name="Execute" command="wofi --show drun" /></keybind>
<!-- The W- prefix refers to the Super key -->
<keybind key="W-d">
<action name="Execute" command="sakura" />
</keybind>
<keybind key="W-z">
<action name="Execute" command="wofi --show drun" />
</keybind>
</keyboard>

</labwc_config>
```

See [docs/rc.xml.all] for all available configuration options.
> TECHNICAL NOTE: The `<default/>` element includes all the built-in keybinds
> as described [here].

[here]: https://labwc.github.io/labwc-config.5.html#entry_keyboard_default

See [rc.xml] for all available configuration options.

To figure out the name of a key, you can use either xev (widely available,
runs via xwayland) or [wev]. Alternatively, search for keysym names directly in
Expand All @@ -155,46 +124,75 @@ runs via xwayland) or [wev]. Alternatively, search for keysym names directly in
[wev]: https://git.sr.ht/~sircmpwn/wev
[xkbcommon-keysyms.h]: https://github.com/xkbcommon/libxkbcommon/blob/master/include/xkbcommon/xkbcommon-keysyms.h

## Step 4 - Start a background-image client and a panel
## Step 3 - Use a wallpaper and a panel

We recommend using `swaybg` for setting a background image or color. You can of
course run `swaybg` directly from a launcher or panel, but for persistence add
the example line below to `~/.config/labwc/autostart`

```
swaybg -c '#334455' &
```

To use a background-color/image client or a panel, simply add the command
to `~/.config/labwc/autostart`. See example below for using swaybg and waybar:
...or for an image try something like this:

```
swaybg -i foo.png >/dev/null 2>&1 &
waybar >/dev/null 2>&1 &
swaybg -i ~/Pictures/wallpaper.png &
```

The `>/dev/null 2>&1` is simply there to hide the logging.
Don't forget the `&` at the end otherwise the compositor will get stuck on that
line.
> IMPORTANT: The `&` at the end is needed to prevent the compositor getting
> stuck on that line.

There are many widely packaged bars and panels that can be used with `labwc`,
for example `xfce4-panel`, `lxqt-panel`, `waybar` and `sfwbar`. Just take a
pick and add one to your `~/.config/labwc/autostart` like this:

```
xfce4-panel &
```

See further examples in [docs/autostart]
See further examples in [autostart]

## Step 5 - install some themes for server-side-decorations
## Step 4 - Build a root-menu

Some commonly packaged themes support openbox (and therefore labwc) out of the
box, for example `Numix` and `Adapta`.
Whether or not you take this step really comes down to how you want to use the
compositor. For example, if you prefer to use a desktop client like `xfdesktop`
or `pcmanfm-qt --desktop` which provide their own root menus.

Install a theme and set it in rc.xml:
To handcraft a menu, create a `~/.config/labwc/menu.xml` and populate with
your favourite applications as in the example below:

```
<theme>
<name>Numix</name>
</theme>
<?xml version="1.0" ?>
<openbox_menu>
<menu id="root-menu" label="">
<item label="Web browser"><action name="Execute" command="firefox"/></item>
<item label="Terminal"><action name="Execute" command="alacritty"/></item>
<item label="Reconfigure"><action name="Reconfigure"/></item>
<item label="Exit"><action name="Exit"/></item>
</menu>
</openbox_menu>
```

To just use the current GTK theme, you can use [labwc-gtktheme]
A lot can be done with the compositor menu. See [integration#menu-generators]
and [menu.xml] for ideas on how to automatically create menu.xml files as well
as creating pipemenus.

Refer to the [man pages] for full documentation.

Enjoy!

[labwc(1)]: https://labwc.github.io/labwc.1.html
[labwc-config(5)]: https://labwc.github.io/labwc-config.5.html
[labwc-menu(5)]: https://labwc.github.io/labwc-menu.5.html
[labwc-environment(5)]: https://labwc.github.io/labwc-environment.5.html
[labwc-theme(5)]: https://labwc.github.io/labwc-theme.5.html
[labwc-actions(5)]: https://labwc.github.io/labwc-actions.5.html

[environment]: https://github.com/labwc/labwc/blob/master/docs/environment
[rc.xml]: https://github.com/labwc/labwc/blob/master/docs/rc.xml.all
[autostart]: https://github.com/labwc/labwc/blob/master/docs/autostart
[menu.xml]: https://github.com/labwc/labwc/blob/master/docs/menu.xml

[docs/environment]: https://github.com/labwc/labwc/blob/master/docs/environment
[docs/menu.xml]: https://github.com/labwc/labwc/blob/master/docs/menu.xml
[integration#menu-generators]: https://labwc.github.io/integration.html#menu-generators
[docs/rc.xml.all]: https://github.com/labwc/labwc/blob/master/docs/rc.xml.all
[docs/autostart]: https://github.com/labwc/labwc/blob/master/docs/autostart
[labwc-gtktheme]: https://github.com/johanmalm/labwc-gtktheme
[man pages]: manual.html
45 changes: 45 additions & 0 deletions src/links.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,15 @@
# Links

## Desktops

- [Opensuse with Xfce](https://news.opensuse.org/2025/08/04/leap-16-rc/)
- [Raspberry Pi](https://www.raspberrypi.com/news/a-new-release-of-raspberry-pi-os/)
- [LXQt](https://lxqt-project.org/screenshots/labwc/)
- [LXQt on Arch Linux](https://archlinux.org/packages/?name=lxqt-wayland-session)
- [Mabox](https://forum.maboxlinux.org/t/labwc-in-mabox-status/2138)
- [Puppy Linux](https://vanilla-dpup.github.io/)
- [TrixiePup64 Wayland 11.0.0 Beta-2](https://forum.puppylinux.com/viewtopic.php?t=14554)

## Openbox

- [redtide-openbox-wiki] - A clone of the openbox wiki
Expand Down Expand Up @@ -45,3 +55,38 @@

[randfall]: https://gitlab.freedesktop.org/vyivel/randfall/

<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>