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