1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
|
# Running Wayland Maker
If not done yet, please follow the [detailled build instructions](BUILD.md) to
build and install from source.
The commands below assume that dependencies and `wlmaker` were installed to
`${HOME}/.local`.
Once running: Press `Ctrl-Window-Alt+T` to open a terminal (`foot`), or
`Ctrl-Window-Alt+Q` to exit.
## Option 1: Run in a window
The most accessible option is to run Wayland Maker in a window in your
already-running graphical environment. It can run both on a X11 or a Wayland
session.
```bash
${HOME}/.local/bin/wlmaker
```
## Option 2: Run from a Linux virtual terminal
> [!IMPORTANT]
> Make sure your distribution has `seatd` installed and running.
```
${HOME}/.local/bin/wlmaker
```
Note: You may need to `su -c "pkill seatd"` to stop `seatd` after you're done.
## Option 3: Run as wayland session
> [!NOTE]
> As of 2024-07-14, this appears to work only with Wayland-only display
> managers. `gdm3` has been found to work, but `lightdm` did not.
> [!IMPORTANT]
> It is not yet recommended to run wlmaker as your only compositor. This
> approach will not work if dependencies are not all operating correctly, and
> is hardest to debug.
* Copy `${HOME}/.local/share/wlmaker.desktop` to `/usr/share/wayland-sessions/wlmaker.desktop`
* Restart your session manager, to reload the sessions.
The desktop entry will execute `${HOME}/.local/bin/wlmaker`.
## Customize it!
* [etc/Config.plist](../etc/Config.plist) is the where keyboard options, key
bindings, screensaver details and more can be configured. That file in the
source tree is the compiled-in default.
To extend: Create a copy of the file to `~/.config/wlmaker/Config.plist` and
modify it according to your needs. Or, move it somewhere else and call
`wlmaker` with the `--config_file=...` arugment.
* [etc/Themes/Default.plist](../etc/Themes/Default.plist) is the compiled-in
default theme. With [etc/Themes/Debian.plist](../etc/Themes/Debian.plist),
there is an alternative theme you can use -- or extend it on your own.
Run `wlmaker` with `--theme_file=...` to use an alternative theme. Or create
your own in `/etc/xdg/wlmaker/Themes/Default.plist` or
`~/.config/wlmaker/Themes/Default.plist`.
* [etc/RootMenu.plist](../etc/RootMenu.plist) defines the contents of the
root menu. To customize, copy to `~/.config/wlmaker/RootMenu.plist` or
provide via the `--root_menu_file` argument.
* [etc/State.plist](../etc/State.plist) stores state of dock and clip. To
customize, copy to `~/.config/wlmaker/State.plist` or provide via the
`--state_file` argument.
* To run X11 applications in Wayland Maker, XWayland must be enabled. It is
compiled in, if the `xwayland` package is installed. In that case, use the
`--start_xwayland` option. The `DISPLAY` environment variable will be set
suitably.
* To make Wayland Maker look well on a high-resolution screen, you can either
set the `Output` `Scale` in [etc/Config.plist](../etc/Config.plist) (and
use `--config_file=...`). This will scale all surfaces.
Or, you can configure the theme with larger decorations & fonts, as is done
in [etc/Themes/Debian.plist](../etc/Themes/Debian.plist). That approach will
not scale application surfaces.
# Debugging issues
> [!NOTE]
> Run `wlmaker` with the `--log_level=DEBUG` argument to get more verbose debug
> information.
1. `wlmaker` fails with an *ERROR* log of `Could not initialize renderer`.
This indicates that `wlroots` was unable to pick a suitable renderer. For
triaging & debugging, try the following:
1. Verify whether another `wlroots`-based compositor [^1] starts up. If
not, it's a `wlroots` issue, please follow up there.
2. Try using a different renderer, eg. by setting `WLR_RENDERER=pixman` [^2].
If that does not help: Please file an issue, including a full paste of your
the configuration & build log, and of the startup attempt.
[^1]: https://gitlab.freedesktop.org/wlroots/wlroots/-/wikis/Projects-which-use-wlroots#compositors
[^2]: https://gitlab.freedesktop.org/wlroots/wlroots/-/blob/master/docs/env_vars.md?ref_type=heads
|
