Skip to content

Commit 96f9e09

Browse files
johanmalmjohanmalm
committed
getting-started.md: re-write most of the document
1 parent ad14969 commit 96f9e09

File tree

1 file changed

+129
-126
lines changed

1 file changed

+129
-126
lines changed

‎src/getting-started.md

Lines changed: 129 additions & 126 deletions
Original file line numberDiff line numberDiff line change
@@ -1,152 +1,126 @@
11
# Getting Started
22

3-
Labwc is designed to be easy to get started with.
3+
## Introduction
44

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

9-
If labwc is not packaged by your OS/distribution of choice, it is quite easy
10-
to build (which should take no more than a few seconds) and run from the build
11-
directory.[^1]
12-
13-
[^1]: The compositor works fine without doing a system-wide installation, but
14-
just be aware that you will not get localized (translated to local
15-
language) window context menus, nor will you get a system-wide .desktop
16-
file where most display managers look for them (if you use one of them).
8+
[IRC Channel]: https://web.libera.chat/gamja/?channels=#labwc
9+
[Github Discussions]: https://github.com/labwc/labwc/discussions
1710

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

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

27-
```
28-
labwc -s alacritty
29-
```
22+
Pre-configured Desktop Environments exist using `labwc` as the compositor (see
23+
examples in list below), but in this document you will be guided to start the
24+
compositor without any such setup.
3025

31-
Alternatively, if you have bemenu installed, you can use the default keybind
32-
Alt-F3 to launch applications.
26+
- [Opensuse with Xfce](https://news.opensuse.org/2025/08/04/leap-16-rc/)
27+
- [Raspberry Pi](https://www.raspberrypi.com/news/a-new-release-of-raspberry-pi-os/)
28+
- [LXQt](https://lxqt-project.org/screenshots/labwc/)
29+
- [LXQt on Arch Linux](https://archlinux.org/packages/?name=lxqt-wayland-session)
30+
- [Mabox](https://forum.maboxlinux.org/t/labwc-in-mabox-status/2138)
31+
- [Puppy Linux](https://vanilla-dpup.github.io/)
3332

34-
<img src="img/scrot-first-start.png" />
33+
## Installation
3534

36-
# Configuration
35+
Install `labwc` with your package manager and come back here when done.
3736

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

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

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

49-
Run `labwc --reconfigure` to reload configuration and theme files.
47+
> TECHNICAL NOTE: labwc can be started from a TTY or nested in a Wayland/X11
48+
> session.
5049
51-
Your OS/Distribution of choice may include these example configuration files in
52-
`/usr/share/doc/labwc/` or similar. If not, you could download them with:
50+
If you start `labwc` with no prior configuration you will be greeted by a blank
51+
screen. If you click on the desktop you will see your root-menu containing only
52+
'Reconfigure' and 'Exit' (and 'Terminal' from version 0.9.0 onwards). Do not be
53+
put off by this sparse appearance. There is a lot more to this compositor than
54+
first meets the eye.
5355

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

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

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

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

70-
[rc.xml]: https://github.com/labwc/labwc/blob/master/docs/rc.xml
71-
[rc.xml.all]: https://github.com/labwc/labwc/blob/master/docs/rc.xml.all
72-
[menu.xml]: https://github.com/labwc/labwc/blob/master/docs/menu.xml
73-
[autostart]: https://github.com/labwc/labwc/blob/master/docs/autostart
74-
[environment]: https://github.com/labwc/labwc/blob/master/docs/environment
75-
[themerc-override]: https://github.com/labwc/labwc/blob/master/docs/themerc
76-
[labwc(1)]: https://labwc.github.io/labwc.1.html
77-
[labwc-config(5)]: https://labwc.github.io/labwc-config.5.html
78-
[labwc-menu(5)]: https://labwc.github.io/labwc-menu.5.html
79-
[labwc-environment(5)]: https://labwc.github.io/labwc-environment.5.html
80-
[labwc-theme(5)]: https://labwc.github.io/labwc-theme.5.html
81-
[labwc-actions(5)]: https://labwc.github.io/labwc-actions.5.html
82-
[IRC Channel]: https://web.libera.chat/gamja/?channels=#labwc
83-
[Github Discussions]: https://github.com/labwc/labwc/discussions
64+
In this guide we are going to cover some common setup steps which will give you
65+
a good feel for the four most important configuration files which are:
66+
[environment], [rc.xml], [autostart] and [menu.xml].
8467

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

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

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

91-
```
92-
XKB_DEFAULT_LAYOUT=se labwc
93-
```
77+
Set the environment variable `XKB_DEFAULT_LAYOUT` with your country code in
78+
`~/.config/labwc/environment`.
9479

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

9782
```
9883
XKB_DEFAULT_LAYOUT=se
9984
```
10085

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

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

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

108-
## Step 2 - Add some items to the root-menu
109-
110-
Create a `~/.config/labwc/menu.xml` to hand-craft a menu. See [docs/menu.xml]
111-
for inspiration, or use the simple example below
112-
113-
```
114-
<?xml version="1.0" ?>
115-
116-
<openbox_menu>
117-
<menu id="root-menu" label="">
118-
<item label="Web browser"><action name="Execute" command="firefox" /></item>
119-
<item label="Terminal"><action name="Execute" command="alacritty" /></item>
120-
<item label="Reconfigure"><action name="Reconfigure" /></item>
121-
<item label="Exit"><action name="Exit" /></item>
122-
</menu>
123-
</openbox_menu>
124-
```
125-
126-
See [integration#menu-generators] for ideas on how to automatically create
127-
menu.xml files.
96+
## Step 2 - Set some keybinds
12897

129-
## Step 3 - Set a shortcut to a launcher
130-
131-
If you want to bind a key-combination to a launcher such as rofi or wofi, or
132-
simply a terminal, create a configuration file `~/.config/labwc/rc.xml` and add
133-
a `<keybind>` entry as shown below. In this example `Super-d` is bound to the
134-
terminal sakura:
98+
If you want to bind a key-combination to an application like a launcher or
99+
terminal, create a configuration file `~/.config/labwc/rc.xml` and add a
100+
`<keyboard>` section as shown below.
135101

136102
```
137103
<?xml version="1.0" ?>
138104
<labwc_config>
139-
140105
<keyboard>
141106
<default />
142-
<keybind key="W-d"><action name="Execute" command="sakura" /></keybind>
143-
<keybind key="W-z"><action name="Execute" command="wofi --show drun" /></keybind>
107+
<!-- The W- prefix refers to the Super key -->
108+
<keybind key="W-d">
109+
<action name="Execute" command="sakura" />
110+
</keybind>
111+
<keybind key="W-z">
112+
<action name="Execute" command="wofi --show drun" />
113+
</keybind>
144114
</keyboard>
145-
146115
</labwc_config>
147116
```
148117

149-
See [docs/rc.xml.all] for all available configuration options.
118+
> TECHNICAL NOTE: The `<default/>` element includes all the built-in keybinds
119+
> as described [here].
120+
121+
[here]: https://labwc.github.io/labwc-config.5.html#entry_keyboard_default
122+
123+
See [rc.xml] for all available configuration options.
150124

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

158-
## Step 4 - Start a background-image client and a panel
132+
## Step 3 - Use a wallpaper and a panel
133+
134+
We recommend using `swaybg` for setting a background image or color. You can of
135+
course run `swaybg` directly from a launcher or panel, but for persistence add
136+
the example line below to `~/.config/labwc/autostart`
137+
138+
```
139+
swaybg -c '#334455' &
140+
```
159141

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

163144
```
164-
swaybg -i foo.png >/dev/null 2>&1 &
165-
waybar >/dev/null 2>&1 &
145+
swaybg -i ~/Pictures/wallpaper.png &
166146
```
167147

168-
The `>/dev/null 2>&1` is simply there to hide the logging.
169-
Don't forget the `&` at the end otherwise the compositor will get stuck on that
170-
line.
148+
> IMPORTANT: The `&` at the end is needed to prevent the compositor getting
149+
> stuck on that line.
150+
151+
There are many widely packaged bars and panels that can be used with `labwc`,
152+
for example `xfce4-panel`, `lxqt-panel`, `waybar` and `sfwbar`. Just take a
153+
pick and add one to your `~/.config/labwc/autostart` like this:
154+
155+
```
156+
xfce4-panel &
157+
```
171158

172-
See further examples in [docs/autostart]
159+
See further examples in [autostart]
173160

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

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

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

181170
```
182-
<theme>
183-
<name>Numix</name>
184-
</theme>
171+
<?xml version="1.0" ?>
172+
<openbox_menu>
173+
<menu id="root-menu" label="">
174+
<item label="Web browser"><action name="Execute" command="firefox"/></item>
175+
<item label="Terminal"><action name="Execute" command="alacritty"/></item>
176+
<item label="Reconfigure"><action name="Reconfigure"/></item>
177+
<item label="Exit"><action name="Exit"/></item>
178+
</menu>
179+
</openbox_menu>
185180
```
186181

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

189186
Refer to the [man pages] for full documentation.
190187

191188
Enjoy!
192189

190+
[labwc(1)]: https://labwc.github.io/labwc.1.html
191+
[labwc-config(5)]: https://labwc.github.io/labwc-config.5.html
192+
[labwc-menu(5)]: https://labwc.github.io/labwc-menu.5.html
193+
[labwc-environment(5)]: https://labwc.github.io/labwc-environment.5.html
194+
[labwc-theme(5)]: https://labwc.github.io/labwc-theme.5.html
195+
[labwc-actions(5)]: https://labwc.github.io/labwc-actions.5.html
196+
197+
[environment]: https://github.com/labwc/labwc/blob/master/docs/environment
198+
[rc.xml]: https://github.com/labwc/labwc/blob/master/docs/rc.xml.all
199+
[autostart]: https://github.com/labwc/labwc/blob/master/docs/autostart
200+
[menu.xml]: https://github.com/labwc/labwc/blob/master/docs/menu.xml
193201

194-
[docs/environment]: https://github.com/labwc/labwc/blob/master/docs/environment
195-
[docs/menu.xml]: https://github.com/labwc/labwc/blob/master/docs/menu.xml
196202
[integration#menu-generators]: https://labwc.github.io/integration.html#menu-generators
197-
[docs/rc.xml.all]: https://github.com/labwc/labwc/blob/master/docs/rc.xml.all
198-
[docs/autostart]: https://github.com/labwc/labwc/blob/master/docs/autostart
199-
[labwc-gtktheme]: https://github.com/johanmalm/labwc-gtktheme
200203
[man pages]: manual.html

0 commit comments

Comments
 (0)