1WESTON(1) General Commands Manual WESTON(1)
2
6 weston - the reference Wayland server
7
9 weston
10
12 weston is the reference implementation of a Wayland server. A Wayland
13 server is a display server, a window manager, and a compositor all in
14 one. Weston has several backends as loadable modules: it can run on
15 Linux KMS (kernel modesetting via DRM), as an X client, or inside an‐
16 other Wayland server instance.
17 Weston supports fundamentally different graphical user interface para‐
19 digms via shell plugins. Two plugins are provided: the desktop shell,
20 and the kiosk shell.
21 Weston also supports X clients via Xwayland, see below.
23
25 drm The DRM backend uses Linux KMS for output and evdev devices for
26 input. It supports multiple monitors in a unified desktop with
27 DPMS. See weston-drm(7), if installed.
28 wayland
30 The Wayland backend runs on another Wayland server, a different
31 Weston instance, for example. Weston shows up as a single desk‐
32 top window on the parent server.
33 x11 The X11 backend runs on an X server. Each Weston output becomes
35 an X window. This is a cheap way to test multi-monitor support
36 of a Wayland shell, desktop, or applications.
37 rdp The RDP backend runs in memory without the need of graphical
39 hardware. Access to the desktop is done by using the RDP proto‐
40 col. Each connecting client has its own seat making it a cheap
41 way to test multi-seat support. See weston-rdp(7), if installed.
42 vnc The VNC backend runs in memory without the need of graphical
44 hardware. Access to the desktop is done by using the RFB proto‐
45 col. Currently only one connecting client is supported. See we‐
46 ston-vnc(7), if installed.
47 pipewire
49 The PipeWire backend runs in memory without the need of graphi‐
50 cal hardware and creates a PipeWire node for each output. It can
51 be used to capture Weston outputs for processing with another
52 application.
53
55 Weston's user interface is implemented by individual 'shell' plugins.
56 A number of shells are provided for different usecases.
57 desktop
59 The desktop shell is Weston's default mode. It provides an exam‐
60 ple of a desktop-like environment, featuring a panel with
61 launchers and a clock, a background, and an interactive task
62 switcher. Whilst not intended to be a full-fledged desktop envi‐
63 ronment in and of itself, it is an example of how such an envi‐
64 ronment can be built.
65 kiosk The kiosk shell is intended for environments which want to run a
67 single application at a time. Applications will be made full
68 screen and activated as they are started.
69 fullscreen
71 The fullscreen shell is a deprecated implementation of the ideas
72 behind the kiosk shell. It requires specific client support for
73 the zwp_fullscreen_shell_v1 interface.
74 ivi The IVI shell is a special-purpose shell which exposes an API
76 compatible with the GENIVI Layer Manager to user-provided HMI
77 controller modules. It is intended for use in automotive envi‐
78 ronments.
79
81 Weston can support X11 clients running within a Weston session via an X
82 server called Xwayland. Xwayland is built as a separate executable,
83 provided by X.Org. Once built and installed, it can be activated with
84 the --xwayland option. Weston will listen on a new X11 display socket
85 and export it through the DISPLAY environment variable.
86 It has also its own X window manager where cursor themes and sizes can
88 be chosen using XCURSOR_PATH and XCURSOR_SIZE environment variables.
89 See ENVIRONMENT.
90
92 Weston core options:
93 -Bbackend, --backend=backend
94 Load backend instead of the default backend, see BACKENDS. The
95 backend module is searched for in /usr/lib64/weston. The de‐
96 fault backend is drm unless the environment suggests otherwise,
97 see DISPLAY and WAYLAND_DISPLAY.
98 -cconfig.ini, --config=config.ini
100 Load config.ini instead of weston.ini. The argument can also be
101 an absolute path starting with a /. If the path is not abso‐
102 lute, it will be searched in the normal config paths, see we‐
103 ston.ini(5). This option is ignored if the --no-config option
104 is passed.
105 --debug
107 Enable debug protocol extension weston_debug_v1 which any client
108 can use to receive debugging messages from the compositor.
109 WARNING: This is risky for two reasons. First, a client may
111 cause a denial-of-service blocking the compositor by providing
112 an unsuitable file descriptor, and second, the debug messages
113 may expose sensitive information. Additionally this will expose
114 weston-screenshooter interface allowing the user to take screen‐
115 shots of the outputs using weston-screenshooter application,
116 which can lead to silently leaking the output contents. This
117 option should not be used in production.
118 -fscope1,scope2, --flight-rec-scopes=scope1,scope2
120 Specify to which scopes should subscribe to. Useful to control
121 which streams to write data into the flight recorder. Flight
122 recorder has limited space, once the flight recorder is full new
123 data will overwrite the old data. Without any scopes specified,
124 it subscribes to 'log' and 'drm-backend' scopes. Passing an
125 empty value would disable the flight recorder entirely.
126 -h, --help
128 Print a summary of command line options, and quit.
129 -iN, --idle-time=N
131 Set the idle timeout to N seconds. The default timeout is 300
132 seconds. When there has not been any user input for the idle
133 timeout, Weston enters an inactive mode. The screen fades to
134 black, monitors may switch off, and the shell may lock the ses‐
135 sion. A value of 0 effectively disables the timeout.
136 --log=file.log
138 Append log messages to the file file.log instead of writing them
139 to stderr.
140 -lscope1,scope2, --logger-scopes=scope1,scope2
142 Specify to which log scopes should subscribe to. When no scopes
143 are supplied, the log "log" scope will be subscribed by default.
144 Useful to control which streams to write data into the logger
145 and can be helpful in diagnosing early start-up code.
146 --modules=module1.so,module2.so
148 Load the comma-separated list of modules. Only used by the test
149 suite. The file is searched for in /usr/lib64/weston, or you can
150 pass an absolute path.
151 --no-config
153 Do not read weston.ini for the compositor. Avoids e.g. loading
154 compositor modules via the configuration file, which is useful
155 for unit tests.
156 --renderer=renderer
158 Select which renderer to use for Weston's internal composition.
159 Defaults to automatic selection.
160 --shell=shell
162 Select which shell to load to provide Weston's user interface.
163 See ENVIRONMENT.
164 -Sname, --socket=name
166 Weston will listen in the Wayland socket called name. Weston
167 will export WAYLAND_DISPLAY with this value in the environment
168 for all child processes to allow them to connect to the right
169 server automatically. --version Print the program version.
170 --wait-for-debugger
172 Raises SIGSTOP before initializing the compositor. This allows
173 the user to attach with a debugger and continue execution by
174 sending SIGCONT. This is useful for debugging a crash on start-
175 up when it would be inconvenient to launch weston directly from
176 a debugger. There is also a weston.ini option to do the same.
177 --xwayland
179 Support X11 clients through the Xwayland server.
180 DRM backend options:
182 See weston-drm(7).
183 Wayland backend options:
185 --display=display
186 Name of the Wayland display to connect to, see also WAYLAND_DIS‐
187 PLAY of the environment.
188 --fullscreen
190 Create a single fullscreen output
191 --output-count=N
193 Create N Wayland windows to emulate the same number of outputs.
194 --width=W, --height=H
196 Make all outputs have a size of WxH pixels.
197 --scale=N
199 Give all outputs a scale factor of N.
200 --use-pixman
202 Deprecated in favour of the --renderer option. Use the pixman
203 renderer. By default weston will try to use EGL and GLES2 for
204 rendering and will fall back to the pixman-based renderer for
205 software compositing if EGL cannot be used. Passing this option
206 will force weston to use the pixman renderer.
207 X11 backend options:
209 --fullscreen
210 --no-input
212 Do not provide any input devices. Used for testing input-less
213 Weston.
214 --output-count=N
216 Create N X windows to emulate the same number of outputs.
217 --width=W, --height=H
219 Make the default size of each X window WxH pixels.
220 --scale=N
222 Give all outputs a scale factor of N.
223 --use-pixman
225 Deprecated in favour of the --renderer option. Use the pixman
226 renderer. By default weston will try to use EGL and GLES2 for
227 rendering. Passing this option will make weston use the pixman
228 library for software compsiting.
229 RDP backend options:
231 See weston-rdp(7).
232 VNC backend options:
234 See weston-vnc(7).
235
237 If the environment variable is set, the configuration file is read from
238 the respective path.
239 $XDG_CONFIG_HOME/weston.ini
241 $HOME/.config/weston.ini
242
244 DISPLAY
245 The X display. If DISPLAY is set, and WAYLAND_DISPLAY is not
246 set, the default backend becomes x11.
247 WAYLAND_DEBUG
249 If set to any value, causes libwayland to print the live proto‐
250 col to stderr.
251 WAYLAND_DISPLAY
253 The name of the display (socket) of an already running Wayland
254 server, without the path. The directory path is always taken
255 from XDG_RUNTIME_DIR. If WAYLAND_DISPLAY is not set, the socket
256 name is "wayland-0".
257 If WAYLAND_DISPLAY is already set, the default backend becomes
259 wayland. This allows launching Weston as a nested server.
260 WAYLAND_SOCKET
262 For Wayland clients, holds the file descriptor of an open local
263 socket to a Wayland server.
264 WESTON_CONFIG_FILE
266 Weston sets this variable to the absolute path of the configura‐
267 tion file it loads, or to the empty string if no file is used.
268 Programs that use weston.ini will read the file specified by
269 this variable instead, or do not read any file if it is empty.
270 Unset variable causes falling back to the default name we‐
271 ston.ini.
272 XCURSOR_PATH
274 Set the list of paths to look for cursors in. It changes both
275 libwayland-cursor and libXcursor, so it affects both Wayland and
276 X11 based clients. See xcursor (3).
277 XCURSOR_SIZE
279 This variable can be set for choosing an specific size of cur‐
280 sor. Affect Wayland and X11 clients. See xcursor (3).
281 XDG_CONFIG_HOME
283 If set, specifies the directory where to look for weston.ini.
284 XDG_RUNTIME_DIR
286 The directory for Weston's socket and lock files. Wayland
287 clients will automatically use this.
288
290 Bugs should be reported to https://gitlab.freedesktop.org/wayland/we‐
291 ston/.
292
294 https://wayland.freedesktop.org/
295
297 Launch Weston with the DRM backend on a VT
298 weston
299 Launch Weston with the DRM backend and XWayland support
301 weston --xwayland
302 Launch Weston (wayland-1) nested in another Weston instance (wayland-0)
304 WAYLAND_DISPLAY=wayland-0 weston -Swayland-1
305 From an X terminal, launch Weston with the x11 backend
307 weston
308
310 weston-bindings(7), weston-debug(1), weston-drm(7), weston-rdp(7), we‐
311 ston-vnc(7), weston.ini(5)
312Weston 12.0.2 2019-03-23 WESTON(1)