blob: 228cfe5acbd182651a646aedcc195a65864200ac [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
107.BR \-\^h ", " \-\-help
108Print the program version and a summary of command line options, and quit.
109.TP
110\fB\-\^i\fR\fIN\fR, \fB\-\-idle\-time\fR=\fIN\fR
111Set the idle timeout to
112.I N
113seconds. The default timeout is 300 seconds. When there has not been any
114user input for the idle timeout, Weston enters an inactive mode. The
115screen fades to black, and depending on the shell in use, a screensaver
116may activate, monitors may switch off, and the shell may lock the session.
117.TP
118\fB\-\-log\fR=\fIfile.log\fR
119Append log messages to the file
120.I file.log
121instead of writing them to stderr.
122.TP
Kristian Høgsberga6813d22012-09-12 12:21:01 -0400123\fB\-\-modules\fR=\fImodule1.so,module2.so\fR
124Load the comma-separated list of modules. Only used by the test
Pekka Paalanena91291c2012-08-29 15:49:48 +0300125suite. The file is searched for in
126.IR "__weston_modules_dir__" ,
127or you can pass an absolute path.
128.TP
129\fB\-\^S\fR\fIname\fR, \fB\-\-socket\fR=\fIname\fR
130Weston will listen in the Wayland socket called
131.IR name .
132Weston will export
133.B WAYLAND_DISPLAY
134with this value in the environment for all child processes to allow them to
135connect to the right server automatically.
Pekka Paalanena91291c2012-08-29 15:49:48 +0300136.SS DRM backend options:
Pekka Paalanen424820f2012-11-27 16:54:08 +0200137See
138.BR weston-drm (7).
Pekka Paalanena91291c2012-08-29 15:49:48 +0300139.
140.SS Wayland backend options:
141.TP
142\fB\-\-display\fR=\fIdisplay\fR
143Name of the Wayland display to connect to, see also
144.I WAYLAND_DISPLAY
145of the environment.
146.TP
147\fB\-\-width\fR=\fIW\fR, \fB\-\-height\fR=\fIH\fR
148Make the desktop size
149.IR W x H " pixels."
150.
151.SS X11 backend options:
152.TP
153.B \-\-fullscreen
154.TP
155.B \-\-no\-input
156Do not provide any input devices. Used for testing input-less Weston.
157.TP
158\fB\-\-output\-count\fR=\fIN\fR
159Create
160.I N
161X windows to emulate the same number of outputs.
162.TP
163\fB\-\-width\fR=\fIW\fR, \fB\-\-height\fR=\fIH\fR
164Make the default size of each X window
165.IR W x H " pixels."
166.
167.\" ***************************************************************
168.SH FILES
169.
Pekka Paalanen864c7842012-11-27 16:54:09 +0200170If the environment variable is set, the configuration file is read
171from the respective path, or the current directory if neither is set.
172.PP
173.BI $XDG_CONFIG_HOME /weston.ini
174.br
175.BI $HOME /.config/weston.ini
176.br
177.I ./weston.ini
178.br
179.
Pekka Paalanena91291c2012-08-29 15:49:48 +0300180.\" ***************************************************************
181.SH ENVIRONMENT
182.
183.TP
184.B DISPLAY
185The X display. If
186.B DISPLAY
187is set, and
188.B WAYLAND_DISPLAY
189is not set, the default backend becomes
190.IR x11-backend.so .
191.TP
192.B WAYLAND_DEBUG
193If set to any value, causes libwayland to print the live protocol
194to stderr.
195.TP
196.B WAYLAND_DISPLAY
197The name of the display (socket) of an already running Wayland server, without
198the path. The directory path is always taken from
199.BR XDG_RUNTIME_DIR .
200If
201.B WAYLAND_DISPLAY
202is not set, the socket name is "wayland-0".
203
204If
205.B WAYLAND_DISPLAY
206is already set, the default backend becomes
207.IR wayland-backend.so .
208This allows launching Weston as a nested server.
209.TP
210.B WAYLAND_SOCKET
Pekka Paalanen864c7842012-11-27 16:54:09 +0200211For Wayland clients, holds the file descriptor of an open local socket
212to a Wayland server.
Pekka Paalanena91291c2012-08-29 15:49:48 +0300213.TP
Tiago Vignatti5643aa52012-09-28 16:29:47 +0300214.B XCURSOR_PATH
215Set the list of paths to look for cursors in. It changes both
216libwayland-cursor and libXcursor, so it affects both Wayland and X11 based
217clients. See
218.B xcursor
219(3).
220.TP
Pekka Paalanena91291c2012-08-29 15:49:48 +0300221.B XCURSOR_SIZE
Tiago Vignatti5643aa52012-09-28 16:29:47 +0300222This variable can be set for choosing an specific size of cursor. Affect
223Wayland and X11 clients. See
224.B xcursor
225(3).
Pekka Paalanena91291c2012-08-29 15:49:48 +0300226.TP
227.B XDG_CONFIG_HOME
Pekka Paalanen864c7842012-11-27 16:54:09 +0200228If set, specifies the directory where to look for
229.BR weston.ini .
Pekka Paalanena91291c2012-08-29 15:49:48 +0300230.TP
231.B XDG_RUNTIME_DIR
232The directory for Weston's socket and lock files.
233Wayland clients will automatically use this.
234.
235.\" ***************************************************************
236.SH DIAGNOSTICS
Pekka Paalanen864c7842012-11-27 16:54:09 +0200237Weston has a segmentation fault handler, that attempts to restore
238the virtual console or ungrab X before raising
239.BR SIGTRAP .
240If you run
241.BR weston " under " gdb (1)
242from an X11 terminal or a different virtual terminal, and tell gdb
243.IP
244handle SIGSEGV nostop
245.PP
246This will allow weston to switch back to gdb on crash and then
247gdb will catch the crash with SIGTRAP.
Pekka Paalanena91291c2012-08-29 15:49:48 +0300248.
249.\" ***************************************************************
250.SH BUGS
251Bugs should be reported to the freedesktop.org bugzilla at
252https://bugs.freedesktop.org with product "Wayland" and
253component "weston".
254.
255.\" ***************************************************************
256.SH WWW
257http://wayland.freedesktop.org/
258.
259.\" ***************************************************************
260.SH EXAMPLES
Pekka Paalanen495cc242012-09-13 13:46:27 +0300261.IP "Launch Weston with the DRM backend on a VT"
Pekka Paalanena91291c2012-08-29 15:49:48 +0300262weston-launch
Pekka Paalanen495cc242012-09-13 13:46:27 +0300263.IP "Launch Weston with the DRM backend and XWayland support"
264weston-launch -- --modules=xwayland.so
Pekka Paalanena91291c2012-08-29 15:49:48 +0300265.IP "Launch Weston (wayland-1) nested in another Weston instance (wayland-0)"
266WAYLAND_DISPLAY=wayland-0 weston -Swayland-1
267.IP "From an X terminal, launch Weston with the x11 backend"
268weston
269.
270.\" ***************************************************************
Pekka Paalanen424820f2012-11-27 16:54:08 +0200271.SH "SEE ALSO"
272.BR weston-drm (7)
Pekka Paalanena91291c2012-08-29 15:49:48 +0300273.\".BR weston-launch (1),
274.\".BR weston.ini (5)