NAME¶
weston - the reference Wayland server
SYNOPSIS¶
weston
DESCRIPTION¶
weston is the reference implementation of a Wayland server. A Wayland
server is a display server, a window manager, and a compositor all in one.
Weston has several backends as loadable modules: it can run on Linux KMS
(kernel modesetting via DRM), as an X client, or inside another Wayland server
instance.
Weston supports fundamentally different graphical user interface paradigms via
shell plugins. Two plugins are provided: the desktop shell, and the tablet
shell.
When weston is started as the first windowing system (i.e. not under X nor under
another Wayland server), it should be done with the command
weston-launch to set up proper privileged access to devices.
Weston also supports X clients via
XWayland, see below.
BACKENDS¶
- drm-backend.so
- The DRM backend uses Linux KMS for output and evdev devices for input. It
supports multiple monitors in a unified desktop with DPMS. See
weston-drm(7), if installed.
- wayland-backend.so
- The Wayland backend runs on another Wayland server, a different Weston
instance, for example. Weston shows up as a single desktop window on the
parent server.
- x11-backend.so
- The X11 backend runs on an X server. Each Weston output becomes an X
window. This is a cheap way to test multi-monitor support of a Wayland
shell, desktop, or applications.
SHELLS¶
- Desktop shell
- Desktop shell is like a modern X desktop environment, concentrating on
traditional keyboard and mouse user interfaces and the familiar
desktop-like window management. Desktop shell consists of the shell plugin
desktop-shell.so and the special client weston-desktop-shell
which provides the wallpaper, panel, and screen locking dialog.
- Tablet shell
- Tablet shell is a graphical user interface aimed for tablet-like devices,
where usually the only input method is a touch screen. It does not support
freely floating windows or many other desktop features, but intends to
provide a natural interface on tablets. Tablet shell consists of the shell
plugin tablet-shell.so and the special client
weston-tablet-shell which provides the basic user interface.
XWAYLAND¶
XWayland requires a special X.org server to be installed. This X server will
connect to a Wayland server as a Wayland client, and X clients will connect to
the X server. XWayland provides backwards compatibility to X applications in a
Wayland stack.
XWayland is activated by instructing
weston to load
xwayland.so
module, see
EXAMPLES. Weston starts listening on a new X display
socket, and exports it in the environment variable
DISPLAY. When the
first X client connects, Weston launches a special X server as a Wayland
client to handle the X client and all future X clients.
It has also its own X window manager where cursor themes and sizes can be chosen
using
XCURSOR_PATH and
XCURSOR_SIZE environment variables. See
ENVIRONMENT.
OPTIONS¶
Weston core options:¶
- -Bbackend.so, --backend=backend.so
- Load backend.so instead of the default backend. The file is
searched for in /usr/lib/x86_64-linux-gnu/weston, or you can pass
an absolute path. The default backend is drm-backend.so unless the
environment suggests otherwise, see DISPLAY and
WAYLAND_DISPLAY.
- --version
- Print the program version.
- -h, --help
- Print a summary of command line options, and quit.
- -iN, --idle-time=N
- Set the idle timeout to N seconds. The default timeout is 300
seconds. When there has not been any user input for the idle timeout,
Weston enters an inactive mode. The screen fades to black, and depending
on the shell in use, a screensaver may activate, monitors may switch off,
and the shell may lock the session. A value of 0 effectively disables the
timeout.
- --log=file.log
- Append log messages to the file file.log instead of writing them to
stderr.
- --modules=module1.so,module2.so
- Load the comma-separated list of modules. Only used by the test suite. The
file is searched for in /usr/lib/x86_64-linux-gnu/weston, or you
can pass an absolute path.
- --no-config
- Do not read weston.ini for the compositor. Avoids e.g. loading
compositor modules via the configuration file, which is useful for unit
tests.
- -Sname, --socket=name
- Weston will listen in the Wayland socket called name. Weston will
export WAYLAND_DISPLAY with this value in the environment for all
child processes to allow them to connect to the right server
automatically.
DRM backend options:¶
See
weston-drm(7).
Wayland backend options:¶
- --display=display
- Name of the Wayland display to connect to, see also WAYLAND_DISPLAY
of the environment.
- --fullscreen
- Create a single fullscreen output
- --output-count=N
- Create N Wayland windows to emulate the same number of
outputs.
- --width=W, --height=H
- Make all outputs have a size of WxH pixels.
- --scale=N
- Give all outputs a scale factor of N.
- --use-pixman
- Use the pixman renderer. By default, weston will try to use EGL and GLES2
for rendering and will fall back to the pixman-based renderer for software
compositing if EGL cannot be used. Passing this option will force weston
to use the pixman renderer.
X11 backend options:¶
- --fullscreen
- --no-input
- Do not provide any input devices. Used for testing input-less Weston.
- --output-count=N
- Create N X windows to emulate the same number of outputs.
- --width=W, --height=H
- Make the default size of each X window WxH pixels.
- --scale=N
- Give all outputs a scale factor of N.
- --use-pixman
- Use the pixman renderer. By default weston will try to use EGL and GLES2
for rendering. Passing this option will make weston use the pixman library
for software compsiting.
FILES¶
If the environment variable is set, the configuration file is read from the
respective path, or the current directory if neither is set.
$XDG_CONFIG_HOME/weston.ini
$HOME/.config/weston.ini
./weston.ini
ENVIRONMENT¶
- DISPLAY
- The X display. If DISPLAY is set, and WAYLAND_DISPLAY is not
set, the default backend becomes x11-backend.so.
- WAYLAND_DEBUG
- If set to any value, causes libwayland to print the live protocol to
stderr.
- WAYLAND_DISPLAY
- The name of the display (socket) of an already running Wayland server,
without the path. The directory path is always taken from
XDG_RUNTIME_DIR. If WAYLAND_DISPLAY is not set, the socket
name is "wayland-0".
If WAYLAND_DISPLAY is already set, the default backend becomes
wayland-backend.so. This allows launching Weston as a nested
server.
- WAYLAND_SOCKET
- For Wayland clients, holds the file descriptor of an open local socket to
a Wayland server.
- XCURSOR_PATH
- Set the list of paths to look for cursors in. It changes both
libwayland-cursor and libXcursor, so it affects both Wayland and X11 based
clients. See xcursor (3).
- XCURSOR_SIZE
- This variable can be set for choosing an specific size of cursor. Affect
Wayland and X11 clients. See xcursor (3).
- XDG_CONFIG_HOME
- If set, specifies the directory where to look for weston.ini.
- XDG_RUNTIME_DIR
- The directory for Weston's socket and lock files. Wayland clients will
automatically use this.
DIAGNOSTICS¶
Weston has a segmentation fault handler, that attempts to restore the virtual
console or ungrab X before raising
SIGTRAP. If you run
weston
under
gdb(1) from an X11 terminal or a different virtual terminal, and
tell gdb
- handle SIGSEGV nostop
This will allow weston to switch back to gdb on crash and then gdb will catch
the crash with SIGTRAP.
BUGS¶
Bugs should be reported to the freedesktop.org bugzilla at
https://bugs.freedesktop.org with product "Wayland" and component
"weston".
WWW¶
http://wayland.freedesktop.org/
EXAMPLES¶
- Launch Weston with the DRM backend on a VT
- weston-launch
- Launch Weston with the DRM backend and XWayland support
- weston-launch -- --modules=xwayland.so
- Launch Weston (wayland-1) nested in another Weston instance
(wayland-0)
- WAYLAND_DISPLAY=wayland-0 weston -Swayland-1
- From an X terminal, launch Weston with the x11 backend
- weston
SEE ALSO¶
weston-drm(7)