| Weston | |
| ====== | |
| Weston is the reference implementation of a Wayland compositor, and a | |
| useful compositor in its own right. Weston has various backends that | |
| lets it run on Linux kernel modesetting and evdev input as well as | |
| under X11. Weston ships with a few example clients, from simple | |
| clients that demonstrate certain aspects of the protocol to more | |
| complete clients and a simplistic toolkit. There is also a quite | |
| capable terminal emulator (weston-terminal) and an toy/example desktop | |
| shell. Finally, weston also provides integration with the Xorg server | |
| and can pull X clients into the Wayland desktop and act as an X window | |
| manager. | |
| Refer to https://wayland.freedesktop.org/building.html for building | |
| weston and its dependencies. | |
| The test suite can be invoked via `make check`; see | |
| https://wayland.freedesktop.org/testing.html for additional details. | |
| Developer documentation can be built via `make doc`. Output will be in | |
| the build root under | |
| docs/developer/html/index.html | |
| docs/tools/html/index.html | |
| Libweston | |
| ========= | |
| Libweston is an effort to separate the re-usable parts of Weston into | |
| a library. Libweston provides most of the boring and tedious bits of | |
| correctly implementing core Wayland protocols and interfacing with | |
| input and output systems, so that people who just want to write a new | |
| "Wayland window manager" (WM) or a small desktop environment (DE) can | |
| focus on the WM part. | |
| Libweston was first introduced in Weston 1.12, and is expected to | |
| continue evolving through many Weston releases before it achieves a | |
| stable API and feature completeness. | |
| API/ABI (in)stability and parallel installability | |
| ------------------------------------------------- | |
| As libweston's API surface is huge, it is impossible to get it right | |
| in one go. Therefore developers reserve the right to break the API/ABI and bump | |
| the major version to signify that. For git snapshots of the master branch, the | |
| API/ABI can break any time without warning. | |
| Libweston major can be bumped only once during a development cycle. This should | |
| happen on the first patch that breaks the API or ABI. Further breaks before the | |
| next Weston major.0.0 release do not cause a bump. This means that libweston | |
| API and ABI are allowed to break also after an alpha release, up to the final | |
| release. However, breaks after alpha should be judged by the usual practices | |
| for allowing minor features, fixes only, or critical fixes only. | |
| To make things tolerable for libweston users despite API/ABI breakages, | |
| different libweston major versions are designed to be perfectly | |
| parallel-installable. This way external projects can easily depend on a | |
| particular API/ABI-version. Thus they do not have to fight over which | |
| ABI-version is installed in a user's system. This allows a user to install many | |
| different compositors each requiring a different libweston ABI-version without | |
| tricks or conflicts. | |
| Note, that versions of Weston itself will not be parallel-installable, | |
| only libweston is. | |
| For more information about parallel installability, see | |
| http://ometer.com/parallel.html | |
| Versioning scheme | |
| ----------------- | |
| In order to provide consistent, easy to use versioning, libweston | |
| follows the rules in the Apache Portable Runtime Project | |
| http://apr.apache.org/versioning.html. | |
| The document provides the full details, with the gist summed below: | |
| - Major - backward incompatible changes. | |
| - Minor - new backward compatible features. | |
| - Patch - internal (implementation specific) fixes. | |
| Weston and libweston have separate version numbers in configure.ac. All | |
| releases are made by the Weston version number. Libweston version number | |
| matches the Weston version number in all releases except maybe pre-releases. | |
| Pre-releases have the Weston micro version 91 or greater. | |
| A pre-release is allowed to install a libweston version greater than the Weston | |
| version in case libweston major was bumped. In that case, the libweston version | |
| must be Weston major + 1 and with minor and patch versions zero. | |
| Pkg-config files are named after libweston major, but carry the Weston version | |
| number. This means that Weston pre-release 2.1.91 may install libweston-3.pc | |
| for the future libweston 3.0.0, but the .pc file says the version is still | |
| 2.1.91. When a libweston user wants to depend on the fully stable API and ABI | |
| of a libweston major, he should use (e.g. for major 3): | |
| PKG_CHECK_MODULES(LIBWESTON, [libweston-3 >= 3.0.0]) | |
| Depending only on libweston-3 without a specific version number still allows | |
| pre-releases which might have different API or ABI. | |
| Forward compatibility | |
| --------------------- | |
| Inspired by ATK, Qt and KDE programs/libraries, libjpeg-turbo, GDK, | |
| NetworkManager, js17, lz4 and many others, libweston uses a macro to restrict | |
| the API visible to the developer - REQUIRE_LIBWESTON_API_VERSION. | |
| Note that different projects focus on different aspects - upper and/or lower | |
| version check, default to visible/hidden old/new symbols and so on. | |
| libweston aims to guard all newly introduced API, in order to prevent subtle | |
| breaks that a simple recompile (against a newer version) might cause. | |
| The macro is of the format 0x$MAJOR$MINOR and does not include PATCH version. | |
| As mentioned in the Versioning scheme section, the latter does not reflect any | |
| user visible API changes, thus should be not considered part of the API version. | |
| All new symbols should be guarded by the macro like the example given below: | |
| #if REQUIRE_LIBWESTON_API_VERSION >= 0x0101 | |
| bool | |
| weston_ham_sandwich(void); | |
| #endif | |
| In order to use the said symbol, the one will have a similar code in their | |
| configure.ac: | |
| PKG_CHECK_MODULES(LIBWESTON, [libweston-1 >= 1.1]) | |
| AC_DEFINE(REQUIRE_LIBWESTON_API_VERSION, [0x0101]) | |
| If the user is _not_ interested in forward compatibility, they can use 0xffff | |
| or similar high value. Yet doing so is not recommended. | |
| Libweston design goals | |
| ---------------------- | |
| The high-level goal of libweston is to decouple the compositor from | |
| the shell implementation (what used to be shell plugins). | |
| Thus, instead of launching 'weston' with various arguments to choose the | |
| shell, one would launch the shell itself, e.g. 'weston-desktop', | |
| 'weston-ivi', 'orbital', etc. The main executable (the hosting program) | |
| will implement the shell, while libweston will be used for a fundamental | |
| compositor implementation. | |
| Libweston is also intended for use by other project developers who want | |
| to create new "Wayland WMs". | |
| Details: | |
| - All configuration and user interfaces will be outside of libweston. | |
| This includes command line parsing, configuration files, and runtime | |
| (graphical) UI. | |
| - The hosting program (main executable) will be in full control of all | |
| libweston options. Libweston should not have user settable options | |
| that would work behind the hosting program's back, except perhaps | |
| debugging features and such. | |
| - Signal handling will be outside of libweston. | |
| - Child process execution and management will be outside of libweston. | |
| - The different backends (drm, fbdev, x11, etc) will be an internal | |
| detail of libweston. Libweston will not support third party | |
| backends. However, hosting programs need to handle | |
| backend-specific configuration due to differences in behaviour and | |
| available features. | |
| - Renderers will be libweston internal details too, though again the | |
| hosting program may affect the choice of renderer if the backend | |
| allows, and maybe set renderer-specific options. | |
| - plugin design ??? | |
| - xwayland ??? | |
| - weston-launch is still with libweston even though it can only launch | |
| Weston and nothing else. We would like to allow it to launch any compositor, | |
| but since it gives by design root access to input devices and DRM, how can | |
| we restrict it to intended programs? | |
| There are still many more details to be decided. | |
| For packagers | |
| ------------- | |
| Always build Weston with --with-cairo=image. | |
| The Weston project is (will be) intended to be split into several | |
| binary packages, each with its own dependencies. The maximal split | |
| would be roughly like this: | |
| - libweston (minimal dependencies): | |
| + headless backend | |
| + wayland backend | |
| - gl-renderer (depends on GL libs etc.) | |
| - drm-backend (depends on libdrm, libgbm, libudev, libinput, ...) | |
| - x11-backend (depends of X11/xcb libs) | |
| - xwayland (depends on X11/xcb libs) | |
| - fbdev-backend (depends on libudev...) | |
| - rdp-backend (depends on freerdp) | |
| - weston (the executable, not parallel-installable): | |
| + desktop shell | |
| + ivi-shell | |
| + fullscreen shell | |
| + weston-info, weston-terminal, etc. we install by default | |
| + screen-share | |
| - weston demos (not parallel-installable) | |
| + weston-simple-* programs | |
| + possibly all the programs we build but do not install by | |
| default | |
| - and possibly more... | |
| Everything should be parallel-installable across libweston major | |
| ABI-versions (libweston-1.so, libweston-2.so, etc.), except those | |
| explicitly mentioned. | |
| Weston's build may not sanely allow this yet, but this is the | |
| intention. |