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