weston(1)

1WESTON(1)                   General Commands Manual                  WESTON(1)
2
3
4

NAME

6       weston - the reference Wayland server
7

SYNOPSIS

9       weston
10

DESCRIPTION

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
16       another Wayland server instance.
17
18       Weston  supports fundamentally different graphical user interface para‐
19       digms via shell plugins. Two plugins are provided: the  desktop  shell,
20       and the tablet shell.
21
22       When  weston is started as the first windowing system (i.e. not under X
23       nor under another Wayland server), it should be done with  the  command
24       weston-launch  to  set  up proper privileged access to devices. If your
25       system supports the logind D-Bus API and the  support  has  been  built
26       into weston as well, it is possible to start weston with just weston.
27
28       Weston also supports X clients via XWayland, see below.
29

BACKENDS

31       drm-backend.so
32              The  DRM backend uses Linux KMS for output and evdev devices for
33              input.  It supports multiple monitors in a unified desktop  with
34              DPMS. See weston-drm(7), if installed.
35
36       wayland-backend.so
37              The  Wayland backend runs on another Wayland server, a different
38              Weston instance, for example. Weston shows up as a single  desk‐
39              top window on the parent server.
40
41       x11-backend.so
42              The  X11 backend runs on an X server. Each Weston output becomes
43              an X window. This is a cheap way to test  multi-monitor  support
44              of a Wayland shell, desktop, or applications.
45
46       rdp-backend.so
47              The  RDP  backend  runs  in memory without the need of graphical
48              hardware. Access to the desktop is done by using the RDP  proto‐
49              col.  Each  connecting client has its own seat making it a cheap
50              way to test multi-seat support. See weston-rdp(7), if installed.
51

SHELLS

53       Each of these  shells  have  its  own  public  protocol  interface  for
54       clients.   This  means that a client must be specifically written for a
55       shell protocol, otherwise it will not work.
56
57       Desktop shell
58              Desktop shell is like a modern X  desktop  environment,  concen‐
59              trating  on  traditional  keyboard and mouse user interfaces and
60              the familiar desktop-like window management. Desktop shell  con‐
61              sists  of  the  shell  plugin  desktop-shell.so  and the special
62              client weston-desktop-shell which provides the wallpaper, panel,
63              and screen locking dialog.
64
65       Fullscreen shell
66              Fullscreen  shell  is  intended  for a client that needs to take
67              over  whole  outputs,  often  all  outputs.  This  is  primarily
68              intended  for  running  another  compositor on Weston. The other
69              compositor does not need to handle any  platform-specifics  like
70              DRM/KMS or evdev/libinput.  The shell consists only of the shell
71              plugin fullscreen-shell.so.
72
73       IVI-shell
74              In-vehicle infotainment shell is a special  purpose  shell  that
75              exposes a GENIVI Layer Manager compatible API to controller mod‐
76              ules, and a very simple shell  protocol  towards  clients.  IVI-
77              shell  starts  with  loading ivi-shell.so, and then a controller
78              module which may launch helper clients.
79

XWAYLAND

81       XWayland requires a special X.org server to be installed. This X server
82       will  connect  to  a  Wayland server as a Wayland client, and X clients
83       will connect to the X server. XWayland provides backwards compatibility
84       to X applications in a Wayland stack.
85
86       XWayland  is  activated by instructing weston to load the XWayland mod‐
87       ule, see EXAMPLES.  Weston starts listening on a new X display  socket,
88       and  exports  it in the environment variable DISPLAY.  When the first X
89       client connects, Weston launches a special X server as a Wayland client
90       to handle the X client and all future X clients.
91
92       It  has also its own X window manager where cursor themes and sizes can
93       be chosen using XCURSOR_PATH and  XCURSOR_SIZE  environment  variables.
94       See ENVIRONMENT.
95

OPTIONS

97   Weston core options:
98       -Bbackend.so, --backend=backend.so
99              Load  backend.so  instead  of  the  default backend. The file is
100              searched for in /usr/lib64/weston, or you can pass  an  absolute
101              path.  The default backend is drm-backend.so unless the environ‐
102              ment suggests otherwise, see DISPLAY and WAYLAND_DISPLAY.
103
104       -cconfig.ini, --config=config.ini
105              Load config.ini instead of weston.ini.  The argument can also be
106              an  absolute  path  starting with a /.  If the path is not abso‐
107              lute, it will be  searched  in  the  normal  config  paths,  see
108              weston.ini(5).   If  also --no-config is given, no configuration
109              file will be read.
110
111       --debug
112              Enable debug protocol extension weston_debug_v1 which any client
113              can use to receive debugging messages from the compositor.
114
115              WARNING:  This  is  risky  for  two reasons. First, a client may
116              cause a denial-of-service blocking the compositor  by  providing
117              an  unsuitable  file  descriptor, and second, the debug messages
118              may expose sensitive information.  Additionally this will expose
119              weston-screenshooter interface allowing the user to take screen‐
120              shots of the  outputs  using  weston-screenshooter  application,
121              which  can  lead  to silently leaking the output contents.  This
122              option should not be used in production.
123
124       -lscope1,scope2, --logger-scopes=scope1,scope2
125              Specify to which log scopes should subscribe to. When no  scopes
126              are supplied, the log "log" scope will be subscribed by default.
127              Useful to control which streams to write data  into  the  logger
128              and can be helpful in diagnosing early start-up code.
129
130       -fscope1,scope2, --flight-rec-scopes=scope1,scope2
131              Specify  to  which scopes should subscribe to. Useful to control
132              which streams to write data into  the  flight  recorder.  Flight
133              recorder has limited space, once the flight recorder is full new
134              data will overwrite the old data. Without any scopes  specified,
135              it subscribes to 'log' and 'drm-backend' scopes.
136
137       --version
138              Print the program version.
139
140       -h, --help
141              Print a summary of command line options, and quit.
142
143       -iN, --idle-time=N
144              Set  the  idle  timeout to N seconds. The default timeout is 300
145              seconds. When there has not been any user  input  for  the  idle
146              timeout,  Weston  enters  an  inactive mode. The screen fades to
147              black, monitors may switch off, and the shell may lock the  ses‐
148              sion.  A value of 0 effectively disables the timeout.
149
150       --log=file.log
151              Append log messages to the file file.log instead of writing them
152              to stderr.
153
154       --xwayland
155              Ask Weston to load the XWayland module.
156
157       --modules=module1.so,module2.so
158              Load the comma-separated list of modules. Only used by the  test
159              suite. The file is searched for in /usr/lib64/weston, or you can
160              pass an absolute path.
161
162       --no-config
163              Do not read weston.ini for the compositor. Avoids  e.g.  loading
164              compositor  modules  via the configuration file, which is useful
165              for unit tests.
166
167       -Sname, --socket=name
168              Weston will listen in the Wayland socket  called  name.   Weston
169              will  export  WAYLAND_DISPLAY with this value in the environment
170              for all child processes to allow them to connect  to  the  right
171              server automatically.
172
173       --wait-for-debugger
174              Raises  SIGSTOP  before initializing the compositor. This allows
175              the user to attach with a debugger  and  continue  execution  by
176              sending  SIGCONT. This is useful for debugging a crash on start-
177              up when it would be inconvenient to launch weston directly  from
178              a debugger. There is also a weston.ini option to do the same.
179
180   DRM backend options:
181       See weston-drm(7).
182
183   Wayland backend options:
184       --display=display
185              Name of the Wayland display to connect to, see also WAYLAND_DIS‐
186              PLAY of the environment.
187
188       --fullscreen
189              Create a single fullscreen output
190
191       --output-count=N
192              Create N Wayland windows to emulate the same number of outputs.
193
194       --width=W, --height=H
195              Make all outputs have a size of WxH pixels.
196
197       --scale=N
198              Give all outputs a scale factor of N.
199
200       --use-pixman
201              Use the pixman renderer.  By default, weston will try to use EGL
202              and  GLES2  for rendering and will fall back to the pixman-based
203              renderer for software compositing if EGL cannot be used.   Pass‐
204              ing this option will force weston to use the pixman renderer.
205
206   X11 backend options:
207       --fullscreen
208
209       --no-input
210              Do  not  provide  any input devices. Used for testing input-less
211              Weston.
212
213       --output-count=N
214              Create N X windows to emulate the same number of outputs.
215
216       --width=W, --height=H
217              Make the default size of each X window WxH pixels.
218
219       --scale=N
220              Give all outputs a scale factor of N.
221
222       --use-pixman
223              Use the pixman renderer.  By default weston will try to use  EGL
224              and  GLES2  for rendering.  Passing this option will make weston
225              use the pixman library for software compsiting.
226
227   RDP backend options:
228       See weston-rdp(7).
229

FILES

231       If the environment variable is set, the configuration file is read from
232       the respective path.
233
234       $XDG_CONFIG_HOME/weston.ini
235       $HOME/.config/weston.ini
236

ENVIRONMENT

238       DISPLAY
239              The  X  display.  If  DISPLAY is set, and WAYLAND_DISPLAY is not
240              set, the default backend becomes x11-backend.so.
241
242       WAYLAND_DEBUG
243              If set to any value, causes libwayland to print the live  proto‐
244              col to stderr.
245
246       WAYLAND_DISPLAY
247              The  name  of the display (socket) of an already running Wayland
248              server, without the path. The directory  path  is  always  taken
249              from XDG_RUNTIME_DIR.  If WAYLAND_DISPLAY is not set, the socket
250              name is "wayland-0".
251
252              If WAYLAND_DISPLAY is already set, the default  backend  becomes
253              wayland-backend.so.   This  allows  launching Weston as a nested
254              server.
255
256       WAYLAND_SOCKET
257              For Wayland clients, holds the file descriptor of an open  local
258              socket to a Wayland server.
259
260       WESTON_CONFIG_FILE
261              Weston sets this variable to the absolute path of the configura‐
262              tion file it loads, or to the empty string if no file  is  used.
263              Programs  that  use  weston.ini  will read the file specified by
264              this variable instead, or do not read any file if it  is  empty.
265              Unset   variable   causes  falling  back  to  the  default  name
266              weston.ini.
267
268       XCURSOR_PATH
269              Set the list of paths to look for cursors in.  It  changes  both
270              libwayland-cursor and libXcursor, so it affects both Wayland and
271              X11 based clients. See xcursor (3).
272
273       XCURSOR_SIZE
274              This variable can be set for choosing an specific size  of  cur‐
275              sor. Affect Wayland and X11 clients. See xcursor (3).
276
277       XDG_CONFIG_HOME
278              If set, specifies the directory where to look for weston.ini.
279
280       XDG_RUNTIME_DIR
281              The  directory  for  Weston's  socket  and  lock files.  Wayland
282              clients will automatically use this.
283

BUGS

285       Bugs  should  be  reported   to   the   freedesktop.org   bugzilla   at
286       https://bugs.freedesktop.org   with  product  "Wayland"  and  component
287       "weston".
288

WWW

290       http://wayland.freedesktop.org/
291

EXAMPLES

293       Launch Weston with the DRM backend on a VT
294              weston-launch
295
296       Launch Weston with the DRM backend and XWayland support
297              weston-launch -- --xwayland
298
299       Launch Weston (wayland-1) nested in another Weston instance (wayland-0)
300              WAYLAND_DISPLAY=wayland-0 weston -Swayland-1
301
302       From an X terminal, launch Weston with the x11 backend
303              weston
304