weston.man 11.3 KB
Newer Older
1
.TH WESTON 1 "2012-11-27" "Weston @version@"
Pekka Paalanen's avatar
Pekka Paalanen committed
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
.SH NAME
weston \- the reference Wayland server
.SH SYNOPSIS
.B weston
.
.\" ***************************************************************
.SH DESCRIPTION
.B weston
is the reference implementation of a Wayland server. A Wayland server is a
display server, a window manager, and a compositor all in one. Weston has
several backends as loadable modules: it can run on Linux KMS (kernel
modesetting via DRM), as an X client, or inside another Wayland server
instance.

Weston supports fundamentally different graphical user interface paradigms via
shell plugins. Two plugins are provided: the desktop shell, and the tablet
shell.

When weston is started as the first windowing system (i.e. not under X nor
under another Wayland server), it should be done with the command
.B weston-launch
23
24
25
26
to set up proper privileged access to devices. If your system supports
the logind D-Bus API and the support has been built into weston as well,
it is possible to start weston with just
.BR weston .
Pekka Paalanen's avatar
Pekka Paalanen committed
27

28
Weston also supports X clients via
29
.BR XWayland ", see below."
Pekka Paalanen's avatar
Pekka Paalanen committed
30
31
32
33
34
35
.
.\" ***************************************************************
.SH BACKENDS
.TP
.I drm-backend.so
The DRM backend uses Linux KMS for output and evdev devices for input.
Pekka Paalanen's avatar
Pekka Paalanen committed
36
37
38
It supports multiple monitors in a unified desktop with DPMS. See
.BR weston-drm (7),
if installed.
Pekka Paalanen's avatar
Pekka Paalanen committed
39
40
41
42
43
44
45
46
47
48
.TP
.I wayland-backend.so
The Wayland backend runs on another Wayland server, a different Weston
instance, for example. Weston shows up as a single desktop window on
the parent server.
.TP
.I x11-backend.so
The X11 backend runs on an X server. Each Weston output becomes an
X window. This is a cheap way to test multi-monitor support of a
Wayland shell, desktop, or applications.
49
50
51
52
53
54
55
.TP
.I rdp-backend.so
The RDP backend runs in memory without the need of graphical hardware. Access
to the desktop is done by using the RDP protocol. Each connecting
client has its own seat making it a cheap way to test multi-seat support. See
.BR weston-rdp (7),
if installed.
Pekka Paalanen's avatar
Pekka Paalanen committed
56
57
58
.
.\" ***************************************************************
.SH SHELLS
Pekka Paalanen's avatar
Pekka Paalanen committed
59
60
61
Each of these shells have its own public protocol interface for clients.
This means that a client must be specifically written for a shell protocol,
otherwise it will not work.
Pekka Paalanen's avatar
Pekka Paalanen committed
62
63
64
65
66
67
68
69
70
71
72
.TP
Desktop shell
Desktop shell is like a modern X desktop environment, concentrating
on traditional keyboard and mouse user interfaces and the familiar
desktop-like window management. Desktop shell consists of the
shell plugin
.I desktop-shell.so
and the special client
.B weston-desktop-shell
which provides the wallpaper, panel, and screen locking dialog.
.TP
Pekka Paalanen's avatar
Pekka Paalanen committed
73
74
75
76
77
78
79
80
81
82
83
84
85
86
Fullscreen shell
Fullscreen shell is intended for a client that needs to take over
whole outputs, often all outputs. This is primarily intended for
running another compositor on Weston. The other compositor does not
need to handle any platform-specifics like DRM/KMS or evdev/libinput.
The shell consists only of the shell plugin
.IR fullscreen-shell.so .
.TP
IVI-shell
In-vehicle infotainment shell is a special purpose shell that exposes
a GENIVI Layer Manager compatible API to controller modules, and a very
simple shell protocol towards clients. IVI-shell starts with loading
.IR ivi-shell.so ,
and then a controller module which may launch helper clients.
Pekka Paalanen's avatar
Pekka Paalanen committed
87
88
.
.\" ***************************************************************
89
90
91
92
93
94
95
.SH XWAYLAND
XWayland requires a special X.org server to be installed. This X server will
connect to a Wayland server as a Wayland client, and X clients will connect to
the X server. XWayland provides backwards compatibility to X applications in a
Wayland stack.

XWayland is activated by instructing
96
.BR weston " to load the XWayland module, see " EXAMPLES .
97
98
99
100
101
Weston starts listening on a new X display socket, and exports it in the
environment variable
.BR DISPLAY .
When the first X client connects, Weston launches a special X server as a
Wayland client to handle the X client and all future X clients.
102
103
104
105
106
107

It has also its own X window manager where cursor themes and sizes can be
chosen using
.BR XCURSOR_PATH
and
.BR XCURSOR_SIZE " environment variables. See " ENVIRONMENT .
108
109
.
.\" ***************************************************************
Pekka Paalanen's avatar
Pekka Paalanen committed
110
111
112
113
114
115
116
117
.SH OPTIONS
.
.SS Weston core options:
.TP
\fB\-\^B\fR\fIbackend.so\fR, \fB\-\-backend\fR=\fIbackend.so\fR
Load
.I backend.so
instead of the default backend. The file is searched for in
118
.IR "@weston_modules_dir@" ,
119
or you can pass an absolute path. The default backend is
120
.I @weston_native_backend@
Pekka Paalanen's avatar
Pekka Paalanen committed
121
122
123
unless the environment suggests otherwise, see
.IR DISPLAY " and " WAYLAND_DISPLAY .
.TP
124
125
126
127
128
129
130
131
132
133
134
135
\fB\-\^c\fR\fIconfig.ini\fR, \fB\-\-config\fR=\fIconfig.ini\fR
Load
.IR config.ini " instead of " weston.ini .
The argument can also be an absolute path starting with a
.IR / .
If the path is not absolute, it will be searched in the normal config
paths, see
.BR weston.ini (5).
If also
.B --no-config
is given, no configuration file will be read.
.TP
136
137
138
139
140
141
142
143
.BR \-\-debug
Enable debug protocol extension
.I weston_debug_v1
which any client can use to receive debugging messages from the compositor.

.B WARNING:
This is risky for two reasons. First, a client may cause a denial-of-service
blocking the compositor by providing an unsuitable file descriptor, and
144
145
146
147
148
second, the debug messages may expose sensitive information.
Additionally this will expose weston-screenshooter interface allowing the user
to take screenshots of the outputs using weston-screenshooter application,
which can lead to silently leaking the output contents.  This option should
not be used in production.
149
.TP
Scott Moreau's avatar
Scott Moreau committed
150
151
152
.BR \-\-version
Print the program version.
.TP
Pekka Paalanen's avatar
Pekka Paalanen committed
153
.BR \-\^h ", " \-\-help
Scott Moreau's avatar
Scott Moreau committed
154
Print a summary of command line options, and quit.
Pekka Paalanen's avatar
Pekka Paalanen committed
155
156
157
158
159
160
.TP
\fB\-\^i\fR\fIN\fR, \fB\-\-idle\-time\fR=\fIN\fR
Set the idle timeout to
.I N
seconds. The default timeout is 300 seconds. When there has not been any
user input for the idle timeout, Weston enters an inactive mode. The
161
162
screen fades to black, monitors may switch off, and the shell may lock
the session.
163
A value of 0 effectively disables the timeout.
Pekka Paalanen's avatar
Pekka Paalanen committed
164
165
166
167
168
169
.TP
\fB\-\-log\fR=\fIfile.log\fR
Append log messages to the file
.I file.log
instead of writing them to stderr.
.TP
170
171
172
\fB\-\-xwayland\fR
Ask Weston to load the XWayland module.
.TP
173
174
\fB\-\-modules\fR=\fImodule1.so,module2.so\fR
Load the comma-separated list of modules. Only used by the test
Pekka Paalanen's avatar
Pekka Paalanen committed
175
suite. The file is searched for in
176
.IR "@weston_modules_dir@" ,
Pekka Paalanen's avatar
Pekka Paalanen committed
177
178
or you can pass an absolute path.
.TP
179
180
181
182
183
184
.BR \-\-no-config
Do not read
.I weston.ini
for the compositor. Avoids e.g. loading compositor modules via the
configuration file, which is useful for unit tests.
.TP
Pekka Paalanen's avatar
Pekka Paalanen committed
185
186
187
188
189
190
191
\fB\-\^S\fR\fIname\fR, \fB\-\-socket\fR=\fIname\fR
Weston will listen in the Wayland socket called
.IR name .
Weston will export
.B WAYLAND_DISPLAY
with this value in the environment for all child processes to allow them to
connect to the right server automatically.
192
193
194
195
196
197
198
199
.TP
\fB\-\-wait-for-debugger\fR
Raises SIGSTOP before initializing the compositor. This allows the user to
attach with a debugger and continue execution by sending SIGCONT. This is
useful for debugging a crash on start-up when it would be inconvenient to
launch weston directly from a debugger. There is also a
.IR weston.ini " option to do the same."
.
Pekka Paalanen's avatar
Pekka Paalanen committed
200
.SS DRM backend options:
Pekka Paalanen's avatar
Pekka Paalanen committed
201
202
See
.BR weston-drm (7).
Pekka Paalanen's avatar
Pekka Paalanen committed
203
204
205
206
207
208
209
210
.
.SS Wayland backend options:
.TP
\fB\-\-display\fR=\fIdisplay\fR
Name of the Wayland display to connect to, see also
.I WAYLAND_DISPLAY
of the environment.
.TP
211
212
213
214
215
216
217
218
.B \-\-fullscreen
Create a single fullscreen output
.TP
\fB\-\-output\-count\fR=\fIN\fR
Create
.I N
Wayland windows to emulate the same number of outputs.
.TP
Pekka Paalanen's avatar
Pekka Paalanen committed
219
\fB\-\-width\fR=\fIW\fR, \fB\-\-height\fR=\fIH\fR
220
Make all outputs have a size of
Pekka Paalanen's avatar
Pekka Paalanen committed
221
.IR W x H " pixels."
222
223
224
225
226
227
228
229
230
231
.TP
.B \-\-scale\fR=\fIN\fR
Give all outputs a scale factor of
.I N.
.TP
.B \-\-use\-pixman
Use the pixman renderer.  By default, weston will try to use EGL and
GLES2 for rendering and will fall back to the pixman-based renderer for
software compositing if EGL cannot be used.  Passing this option will force
weston to use the pixman renderer.
Pekka Paalanen's avatar
Pekka Paalanen committed
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
.
.SS X11 backend options:
.TP
.B \-\-fullscreen
.TP
.B \-\-no\-input
Do not provide any input devices. Used for testing input-less Weston.
.TP
\fB\-\-output\-count\fR=\fIN\fR
Create
.I N
X windows to emulate the same number of outputs.
.TP
\fB\-\-width\fR=\fIW\fR, \fB\-\-height\fR=\fIH\fR
Make the default size of each X window
.IR W x H " pixels."
248
.TP
249
250
251
252
.B \-\-scale\fR=\fIN\fR
Give all outputs a scale factor of
.I N.
.TP
253
254
255
256
.B \-\-use\-pixman
Use the pixman renderer.  By default weston will try to use EGL and
GLES2 for rendering.  Passing this option will make weston use the
pixman library for software compsiting.
Pekka Paalanen's avatar
Pekka Paalanen committed
257
.
258
259
260
261
262
.SS RDP backend options:
See
.BR weston-rdp (7).
.
.
Pekka Paalanen's avatar
Pekka Paalanen committed
263
264
265
.\" ***************************************************************
.SH FILES
.
266
If the environment variable is set, the configuration file is read
267
from the respective path.
268
269
270
271
272
273
.PP
.BI $XDG_CONFIG_HOME /weston.ini
.br
.BI $HOME /.config/weston.ini
.br
.
Pekka Paalanen's avatar
Pekka Paalanen committed
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
.\" ***************************************************************
.SH ENVIRONMENT
.
.TP
.B DISPLAY
The X display. If
.B DISPLAY
is set, and
.B WAYLAND_DISPLAY
is not set, the default backend becomes
.IR x11-backend.so .
.TP
.B WAYLAND_DEBUG
If set to any value, causes libwayland to print the live protocol
to stderr.
.TP
.B WAYLAND_DISPLAY
The name of the display (socket) of an already running Wayland server, without
the path. The directory path is always taken from
.BR XDG_RUNTIME_DIR .
If
.B WAYLAND_DISPLAY
is not set, the socket name is "wayland-0".

If
.B WAYLAND_DISPLAY
is already set, the default backend becomes
.IR wayland-backend.so .
This allows launching Weston as a nested server.
.TP
.B WAYLAND_SOCKET
305
306
For Wayland clients, holds the file descriptor of an open local socket
to a Wayland server.
Pekka Paalanen's avatar
Pekka Paalanen committed
307
.TP
308
309
310
311
312
313
314
315
316
.B WESTON_CONFIG_FILE
Weston sets this variable to the absolute path of the configuration file
it loads, or to the empty string if no file is used. Programs that use
.I weston.ini
will read the file specified by this variable instead, or do not read any
file if it is empty. Unset variable causes falling back to the default
name
.IR weston.ini .
.TP
317
318
319
320
321
322
323
.B XCURSOR_PATH
Set the list of paths to look for cursors in. It changes both
libwayland-cursor and libXcursor, so it affects both Wayland and X11 based
clients. See
.B xcursor
(3).
.TP
Pekka Paalanen's avatar
Pekka Paalanen committed
324
.B XCURSOR_SIZE
325
326
327
328
This variable can be set for choosing an specific size of cursor. Affect
Wayland and X11 clients. See
.B xcursor
(3).
Pekka Paalanen's avatar
Pekka Paalanen committed
329
330
.TP
.B XDG_CONFIG_HOME
331
332
If set, specifies the directory where to look for
.BR weston.ini .
Pekka Paalanen's avatar
Pekka Paalanen committed
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
.TP
.B XDG_RUNTIME_DIR
The directory for Weston's socket and lock files.
Wayland clients will automatically use this.
.
.\" ***************************************************************
.SH BUGS
Bugs should be reported to the freedesktop.org bugzilla at
https://bugs.freedesktop.org with product "Wayland" and
component "weston".
.
.\" ***************************************************************
.SH WWW
http://wayland.freedesktop.org/
.
.\" ***************************************************************
.SH EXAMPLES
350
.IP "Launch Weston with the DRM backend on a VT"
Pekka Paalanen's avatar
Pekka Paalanen committed
351
weston-launch
352
.IP "Launch Weston with the DRM backend and XWayland support"
353
weston-launch -- --xwayland
Pekka Paalanen's avatar
Pekka Paalanen committed
354
355
356
357
358
359
.IP "Launch Weston (wayland-1) nested in another Weston instance (wayland-0)"
WAYLAND_DISPLAY=wayland-0 weston -Swayland-1
.IP "From an X terminal, launch Weston with the x11 backend"
weston
.
.\" ***************************************************************
Pekka Paalanen's avatar
Pekka Paalanen committed
360
361
.SH "SEE ALSO"
.BR weston-drm (7)
362
.BR weston-rdp (7)
Pekka Paalanen's avatar
Pekka Paalanen committed
363
364
.\".BR weston-launch (1),
.\".BR weston.ini (5)