man/weston.man

   1 .TH WESTON 1 "2012-11-27" "Weston __version__"
   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
  25 Weston also supports X clients via
  26 .BR XWayland ", see below."
  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.
  33 It supports multiple monitors in a unified desktop with DPMS. See
  34 .BR weston-drm (7),
  35 if installed.
  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 .\" ***************************************************************
  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.
  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 .
  91 .
  92 .\" ***************************************************************
  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
 103 .I __weston_native_backend__
 104 unless the environment suggests otherwise, see
 105 .IR DISPLAY " and " WAYLAND_DISPLAY .
 106 .TP
 107 .BR \-\-version
 108 Print the program version.
 109 .TP
 110 .BR \-\^h ", " \-\-help
 111 Print a summary of command line options, and quit.
 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.
 120 A value of 0 effectively disables the timeout.
 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
 127 \fB\-\-modules\fR=\fImodule1.so,module2.so\fR
 128 Load the comma-separated list of modules. Only used by the test
 129 suite. The file is searched for in
 130 .IR "__weston_modules_dir__" ,
 131 or you can pass an absolute path.
 132 .TP
 133 .BR \-\-no-config
 134 Do not read
 135 .I weston.ini
 136 for the compositor. Avoids e.g. loading compositor modules via the
 137 configuration file, which is useful for unit tests.
 138 .TP
 139 \fB\-\^S\fR\fIname\fR, \fB\-\-socket\fR=\fIname\fR
 140 Weston will listen in the Wayland socket called
 141 .IR name .
 142 Weston will export
 143 .B WAYLAND_DISPLAY
 144 with this value in the environment for all child processes to allow them to
 145 connect to the right server automatically.
 146 .SS DRM backend options:
 147 See
 148 .BR weston-drm (7).
 149 .
 150 .SS Wayland backend options:
 151 .TP
 152 \fB\-\-display\fR=\fIdisplay\fR
 153 Name of the Wayland display to connect to, see also
 154 .I WAYLAND_DISPLAY
 155 of the environment.
 156 .TP
 157 .B \-\-fullscreen
 158 Create a single fullscreen output
 159 .TP
 160 \fB\-\-output\-count\fR=\fIN\fR
 161 Create
 162 .I N
 163 Wayland windows to emulate the same number of outputs.
 164 .TP
 165 \fB\-\-width\fR=\fIW\fR, \fB\-\-height\fR=\fIH\fR
 166 Make all outputs have a size of
 167 .IR W x H " pixels."
 168 .TP
 169 .B \-\-scale\fR=\fIN\fR
 170 Give all outputs a scale factor of
 171 .I N.
 172 .TP
 173 .B \-\-use\-pixman
 174 Use the pixman renderer.  By default, weston will try to use EGL and
 175 GLES2 for rendering and will fall back to the pixman-based renderer for
 176 software compositing if EGL cannot be used.  Passing this option will force
 177 weston to use the pixman renderer.
 178 .
 179 .SS X11 backend options:
 180 .TP
 181 .B \-\-fullscreen
 182 .TP
 183 .B \-\-no\-input
 184 Do not provide any input devices. Used for testing input-less Weston.
 185 .TP
 186 \fB\-\-output\-count\fR=\fIN\fR
 187 Create
 188 .I N
 189 X windows to emulate the same number of outputs.
 190 .TP
 191 \fB\-\-width\fR=\fIW\fR, \fB\-\-height\fR=\fIH\fR
 192 Make the default size of each X window
 193 .IR W x H " pixels."
 194 .TP
 195 .B \-\-scale\fR=\fIN\fR
 196 Give all outputs a scale factor of
 197 .I N.
 198 .TP
 199 .B \-\-use\-pixman
 200 Use the pixman renderer.  By default weston will try to use EGL and
 201 GLES2 for rendering.  Passing this option will make weston use the
 202 pixman library for software compsiting.
 203 .
 204 .\" ***************************************************************
 205 .SH FILES
 206 .
 207 If the environment variable is set, the configuration file is read
 208 from the respective path, or the current directory if neither is set.
 209 .PP
 210 .BI $XDG_CONFIG_HOME /weston.ini
 211 .br
 212 .BI $HOME /.config/weston.ini
 213 .br
 214 .I ./weston.ini
 215 .br
 216 .
 217 .\" ***************************************************************
 218 .SH ENVIRONMENT
 219 .
 220 .TP
 221 .B DISPLAY
 222 The X display. If
 223 .B DISPLAY
 224 is set, and
 225 .B WAYLAND_DISPLAY
 226 is not set, the default backend becomes
 227 .IR x11-backend.so .
 228 .TP
 229 .B WAYLAND_DEBUG
 230 If set to any value, causes libwayland to print the live protocol
 231 to stderr.
 232 .TP
 233 .B WAYLAND_DISPLAY
 234 The name of the display (socket) of an already running Wayland server, without
 235 the path. The directory path is always taken from
 236 .BR XDG_RUNTIME_DIR .
 237 If
 238 .B WAYLAND_DISPLAY
 239 is not set, the socket name is "wayland-0".
 240
 241 If
 242 .B WAYLAND_DISPLAY
 243 is already set, the default backend becomes
 244 .IR wayland-backend.so .
 245 This allows launching Weston as a nested server.
 246 .TP
 247 .B WAYLAND_SOCKET
 248 For Wayland clients, holds the file descriptor of an open local socket
 249 to a Wayland server.
 250 .TP
 251 .B XCURSOR_PATH
 252 Set the list of paths to look for cursors in. It changes both
 253 libwayland-cursor and libXcursor, so it affects both Wayland and X11 based
 254 clients. See
 255 .B xcursor
 256 (3).
 257 .TP
 258 .B XCURSOR_SIZE
 259 This variable can be set for choosing an specific size of cursor. Affect
 260 Wayland and X11 clients. See
 261 .B xcursor
 262 (3).
 263 .TP
 264 .B XDG_CONFIG_HOME
 265 If set, specifies the directory where to look for
 266 .BR weston.ini .
 267 .TP
 268 .B XDG_RUNTIME_DIR
 269 The directory for Weston's socket and lock files.
 270 Wayland clients will automatically use this.
 271 .
 272 .\" ***************************************************************
 273 .SH DIAGNOSTICS
 274 Weston has a segmentation fault handler, that attempts to restore
 275 the virtual console or ungrab X before raising
 276 .BR SIGTRAP .
 277 If you run
 278 .BR weston " under " gdb (1)
 279 from an X11 terminal or a different virtual terminal, and tell gdb
 280 .IP
 281 handle SIGSEGV nostop
 282 .PP
 283 This will allow weston to switch back to gdb on crash and then
 284 gdb will catch the crash with SIGTRAP.
 285 .
 286 .\" ***************************************************************
 287 .SH BUGS
 288 Bugs should be reported to the freedesktop.org bugzilla at
 289 https://bugs.freedesktop.org with product "Wayland" and
 290 component "weston".
 291 .
 292 .\" ***************************************************************
 293 .SH WWW
 294 http://wayland.freedesktop.org/
 295 .
 296 .\" ***************************************************************
 297 .SH EXAMPLES
 298 .IP "Launch Weston with the DRM backend on a VT"
 299 weston-launch
 300 .IP "Launch Weston with the DRM backend and XWayland support"
 301 weston-launch -- --modules=xwayland.so
 302 .IP "Launch Weston (wayland-1) nested in another Weston instance (wayland-0)"
 303 WAYLAND_DISPLAY=wayland-0 weston -Swayland-1
 304 .IP "From an X terminal, launch Weston with the x11 backend"
 305 weston
 306 .
 307 .\" ***************************************************************
 308 .SH "SEE ALSO"
 309 .BR weston-drm (7)
 310 .\".BR weston-launch (1),
 311 .\".BR weston.ini (5)