blob: fd1c7a5151e8ebc7e224fe4aba01ac363659b604 [file] [log] [blame]
Pekka Paalanen864c7842012-11-27 16:54:09 +02001.TH WESTON 1 "2012-11-27" "Weston __version__"
Pekka Paalanena91291c2012-08-29 15:49:48 +03002.SH NAME
3weston \- the reference Wayland server
4.SH SYNOPSIS
5.B weston
6.
7.\" ***************************************************************
8.SH DESCRIPTION
9.B weston
10is the reference implementation of a Wayland server. A Wayland server is a
11display server, a window manager, and a compositor all in one. Weston has
12several backends as loadable modules: it can run on Linux KMS (kernel
13modesetting via DRM), as an X client, or inside another Wayland server
14instance.
15
16Weston supports fundamentally different graphical user interface paradigms via
17shell plugins. Two plugins are provided: the desktop shell, and the tablet
18shell.
19
20When weston is started as the first windowing system (i.e. not under X nor
21under another Wayland server), it should be done with the command
22.B weston-launch
23to set up proper privileged access to devices.
24
Pekka Paalanen495cc242012-09-13 13:46:27 +030025Weston also supports X clients via
26.BR XWayland ", see below."
Pekka Paalanena91291c2012-08-29 15:49:48 +030027.
28.\" ***************************************************************
29.SH BACKENDS
30.TP
31.I drm-backend.so
32The DRM backend uses Linux KMS for output and evdev devices for input.
Pekka Paalanen424820f2012-11-27 16:54:08 +020033It supports multiple monitors in a unified desktop with DPMS. See
34.BR weston-drm (7),
35if installed.
Pekka Paalanena91291c2012-08-29 15:49:48 +030036.TP
37.I wayland-backend.so
38The Wayland backend runs on another Wayland server, a different Weston
39instance, for example. Weston shows up as a single desktop window on
40the parent server.
41.TP
42.I x11-backend.so
43The X11 backend runs on an X server. Each Weston output becomes an
44X window. This is a cheap way to test multi-monitor support of a
45Wayland shell, desktop, or applications.
46.
47.\" ***************************************************************
48.SH SHELLS
49.TP
50Desktop shell
51Desktop shell is like a modern X desktop environment, concentrating
52on traditional keyboard and mouse user interfaces and the familiar
53desktop-like window management. Desktop shell consists of the
54shell plugin
55.I desktop-shell.so
56and the special client
57.B weston-desktop-shell
58which provides the wallpaper, panel, and screen locking dialog.
59.TP
60Tablet shell
61Tablet shell is a graphical user interface aimed for tablet-like
62devices, where usually the only input method is a touch screen.
63It does not support freely floating windows or many other desktop
64features, but intends to provide a natural interface on tablets.
65Tablet shell consists of the shell plugin
66.I tablet-shell.so
67and the special client
68.B weston-tablet-shell
69which provides the basic user interface.
70.
71.\" ***************************************************************
Pekka Paalanen495cc242012-09-13 13:46:27 +030072.SH XWAYLAND
73XWayland requires a special X.org server to be installed. This X server will
74connect to a Wayland server as a Wayland client, and X clients will connect to
75the X server. XWayland provides backwards compatibility to X applications in a
76Wayland stack.
77
78XWayland is activated by instructing
79.BR weston " to load " xwayland.so " module, see " EXAMPLES .
80Weston starts listening on a new X display socket, and exports it in the
81environment variable
82.BR DISPLAY .
83When the first X client connects, Weston launches a special X server as a
84Wayland client to handle the X client and all future X clients.
Tiago Vignatti5643aa52012-09-28 16:29:47 +030085
86It has also its own X window manager where cursor themes and sizes can be
87chosen using
88.BR XCURSOR_PATH
89and
90.BR XCURSOR_SIZE " environment variables. See " ENVIRONMENT .
Pekka Paalanen495cc242012-09-13 13:46:27 +030091.
92.\" ***************************************************************
Pekka Paalanena91291c2012-08-29 15:49:48 +030093.SH OPTIONS
94.
95.SS Weston core options:
96.TP
97\fB\-\^B\fR\fIbackend.so\fR, \fB\-\-backend\fR=\fIbackend.so\fR
98Load
99.I backend.so
100instead of the default backend. The file is searched for in
101.IR "__weston_modules_dir__" ,
102or you can pass an absolute path. The default backend is
Pekka Paalanena51e6fa2012-11-07 12:25:12 +0200103.I __weston_native_backend__
Pekka Paalanena91291c2012-08-29 15:49:48 +0300104unless the environment suggests otherwise, see
105.IR DISPLAY " and " WAYLAND_DISPLAY .
106.TP
Scott Moreau12245142012-08-29 15:15:58 -0600107.BR \-\-version
108Print the program version.
109.TP
Pekka Paalanena91291c2012-08-29 15:49:48 +0300110.BR \-\^h ", " \-\-help
Scott Moreau12245142012-08-29 15:15:58 -0600111Print a summary of command line options, and quit.
Pekka Paalanena91291c2012-08-29 15:49:48 +0300112.TP
113\fB\-\^i\fR\fIN\fR, \fB\-\-idle\-time\fR=\fIN\fR
114Set the idle timeout to
115.I N
116seconds. The default timeout is 300 seconds. When there has not been any
117user input for the idle timeout, Weston enters an inactive mode. The
118screen fades to black, and depending on the shell in use, a screensaver
119may activate, monitors may switch off, and the shell may lock the session.
Scott Moreau650aab52013-03-09 11:55:40 -0700120A value of 0 effectively disables the timeout.
Pekka Paalanena91291c2012-08-29 15:49:48 +0300121.TP
122\fB\-\-log\fR=\fIfile.log\fR
123Append log messages to the file
124.I file.log
125instead of writing them to stderr.
126.TP
Kristian Høgsberga6813d22012-09-12 12:21:01 -0400127\fB\-\-modules\fR=\fImodule1.so,module2.so\fR
128Load the comma-separated list of modules. Only used by the test
Pekka Paalanena91291c2012-08-29 15:49:48 +0300129suite. The file is searched for in
130.IR "__weston_modules_dir__" ,
131or you can pass an absolute path.
132.TP
133\fB\-\^S\fR\fIname\fR, \fB\-\-socket\fR=\fIname\fR
134Weston will listen in the Wayland socket called
135.IR name .
136Weston will export
137.B WAYLAND_DISPLAY
138with this value in the environment for all child processes to allow them to
139connect to the right server automatically.
Pekka Paalanena91291c2012-08-29 15:49:48 +0300140.SS DRM backend options:
Pekka Paalanen424820f2012-11-27 16:54:08 +0200141See
142.BR weston-drm (7).
Pekka Paalanena91291c2012-08-29 15:49:48 +0300143.
144.SS Wayland backend options:
145.TP
146\fB\-\-display\fR=\fIdisplay\fR
147Name of the Wayland display to connect to, see also
148.I WAYLAND_DISPLAY
149of the environment.
150.TP
Jason Ekstrand399841d2013-11-10 17:26:28 -0600151.B \-\-fullscreen
152Create a single fullscreen output
153.TP
154\fB\-\-output\-count\fR=\fIN\fR
155Create
156.I N
157Wayland windows to emulate the same number of outputs.
158.TP
Pekka Paalanena91291c2012-08-29 15:49:48 +0300159\fB\-\-width\fR=\fIW\fR, \fB\-\-height\fR=\fIH\fR
Jason Ekstrand399841d2013-11-10 17:26:28 -0600160Make all outputs have a size of
Pekka Paalanena91291c2012-08-29 15:49:48 +0300161.IR W x H " pixels."
Jason Ekstrand399841d2013-11-10 17:26:28 -0600162.TP
163.B \-\-scale\fR=\fIN\fR
164Give all outputs a scale factor of
165.I N.
166.TP
167.B \-\-use\-pixman
168Use the pixman renderer. By default, weston will try to use EGL and
169GLES2 for rendering and will fall back to the pixman-based renderer for
170software compositing if EGL cannot be used. Passing this option will force
171weston to use the pixman renderer.
Pekka Paalanena91291c2012-08-29 15:49:48 +0300172.
173.SS X11 backend options:
174.TP
175.B \-\-fullscreen
176.TP
177.B \-\-no\-input
178Do not provide any input devices. Used for testing input-less Weston.
179.TP
180\fB\-\-output\-count\fR=\fIN\fR
181Create
182.I N
183X windows to emulate the same number of outputs.
184.TP
185\fB\-\-width\fR=\fIW\fR, \fB\-\-height\fR=\fIH\fR
186Make the default size of each X window
187.IR W x H " pixels."
Kristian Høgsbergefaca342013-01-07 15:52:44 -0500188.TP
Jason Ekstrandd89a0942014-03-07 15:29:14 -0600189.B \-\-scale\fR=\fIN\fR
190Give all outputs a scale factor of
191.I N.
192.TP
Kristian Høgsbergefaca342013-01-07 15:52:44 -0500193.B \-\-use\-pixman
194Use the pixman renderer. By default weston will try to use EGL and
195GLES2 for rendering. Passing this option will make weston use the
196pixman library for software compsiting.
Pekka Paalanena91291c2012-08-29 15:49:48 +0300197.
198.\" ***************************************************************
199.SH FILES
200.
Pekka Paalanen864c7842012-11-27 16:54:09 +0200201If the environment variable is set, the configuration file is read
202from the respective path, or the current directory if neither is set.
203.PP
204.BI $XDG_CONFIG_HOME /weston.ini
205.br
206.BI $HOME /.config/weston.ini
207.br
208.I ./weston.ini
209.br
210.
Pekka Paalanena91291c2012-08-29 15:49:48 +0300211.\" ***************************************************************
212.SH ENVIRONMENT
213.
214.TP
215.B DISPLAY
216The X display. If
217.B DISPLAY
218is set, and
219.B WAYLAND_DISPLAY
220is not set, the default backend becomes
221.IR x11-backend.so .
222.TP
223.B WAYLAND_DEBUG
224If set to any value, causes libwayland to print the live protocol
225to stderr.
226.TP
227.B WAYLAND_DISPLAY
228The name of the display (socket) of an already running Wayland server, without
229the path. The directory path is always taken from
230.BR XDG_RUNTIME_DIR .
231If
232.B WAYLAND_DISPLAY
233is not set, the socket name is "wayland-0".
234
235If
236.B WAYLAND_DISPLAY
237is already set, the default backend becomes
238.IR wayland-backend.so .
239This allows launching Weston as a nested server.
240.TP
241.B WAYLAND_SOCKET
Pekka Paalanen864c7842012-11-27 16:54:09 +0200242For Wayland clients, holds the file descriptor of an open local socket
243to a Wayland server.
Pekka Paalanena91291c2012-08-29 15:49:48 +0300244.TP
Tiago Vignatti5643aa52012-09-28 16:29:47 +0300245.B XCURSOR_PATH
246Set the list of paths to look for cursors in. It changes both
247libwayland-cursor and libXcursor, so it affects both Wayland and X11 based
248clients. See
249.B xcursor
250(3).
251.TP
Pekka Paalanena91291c2012-08-29 15:49:48 +0300252.B XCURSOR_SIZE
Tiago Vignatti5643aa52012-09-28 16:29:47 +0300253This variable can be set for choosing an specific size of cursor. Affect
254Wayland and X11 clients. See
255.B xcursor
256(3).
Pekka Paalanena91291c2012-08-29 15:49:48 +0300257.TP
258.B XDG_CONFIG_HOME
Pekka Paalanen864c7842012-11-27 16:54:09 +0200259If set, specifies the directory where to look for
260.BR weston.ini .
Pekka Paalanena91291c2012-08-29 15:49:48 +0300261.TP
262.B XDG_RUNTIME_DIR
263The directory for Weston's socket and lock files.
264Wayland clients will automatically use this.
265.
266.\" ***************************************************************
267.SH DIAGNOSTICS
Pekka Paalanen864c7842012-11-27 16:54:09 +0200268Weston has a segmentation fault handler, that attempts to restore
269the virtual console or ungrab X before raising
270.BR SIGTRAP .
271If you run
272.BR weston " under " gdb (1)
273from an X11 terminal or a different virtual terminal, and tell gdb
274.IP
275handle SIGSEGV nostop
276.PP
277This will allow weston to switch back to gdb on crash and then
278gdb will catch the crash with SIGTRAP.
Pekka Paalanena91291c2012-08-29 15:49:48 +0300279.
280.\" ***************************************************************
281.SH BUGS
282Bugs should be reported to the freedesktop.org bugzilla at
283https://bugs.freedesktop.org with product "Wayland" and
284component "weston".
285.
286.\" ***************************************************************
287.SH WWW
288http://wayland.freedesktop.org/
289.
290.\" ***************************************************************
291.SH EXAMPLES
Pekka Paalanen495cc242012-09-13 13:46:27 +0300292.IP "Launch Weston with the DRM backend on a VT"
Pekka Paalanena91291c2012-08-29 15:49:48 +0300293weston-launch
Pekka Paalanen495cc242012-09-13 13:46:27 +0300294.IP "Launch Weston with the DRM backend and XWayland support"
295weston-launch -- --modules=xwayland.so
Pekka Paalanena91291c2012-08-29 15:49:48 +0300296.IP "Launch Weston (wayland-1) nested in another Weston instance (wayland-0)"
297WAYLAND_DISPLAY=wayland-0 weston -Swayland-1
298.IP "From an X terminal, launch Weston with the x11 backend"
299weston
300.
301.\" ***************************************************************
Pekka Paalanen424820f2012-11-27 16:54:08 +0200302.SH "SEE ALSO"
303.BR weston-drm (7)
Pekka Paalanena91291c2012-08-29 15:49:48 +0300304.\".BR weston-launch (1),
305.\".BR weston.ini (5)