240 lines
8.7 KiB
Plaintext
240 lines
8.7 KiB
Plaintext
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 http://wayland.freedesktop.org/building.html for building
|
|
weston and its dependencies.
|
|
|
|
The test suite can be invoked via `make check`; see
|
|
http://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.
|