[PATCH weston] README: introduce libweston
ppaalanen at gmail.com
Tue Jul 14 03:07:47 PDT 2015
From: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
What is libweston and where do we intend to go with it.
Cc: Giulio Camuffo <giuliocamuffo at gmail.com>
Signed-off-by: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
README | 139 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 138 insertions(+), 1 deletion(-)
diff --git a/README b/README
index 3821e5d..beab3df 100644
@@ -1,4 +1,5 @@
Weston is the reference implementation of a Wayland compositor, and a
useful compositor in its own right. Weston has various backends that
@@ -16,3 +17,139 @@ weston and its dependencies.
The test suite can be invoked via `make check`; see
http://wayland.freedesktop.org/testing.html for additional details.
+Writing a full-fledged Wayland compositor from scratch is lots of
+work. Libweston is an effort to separate the re-usable parts of Weston
+into a library. Libweston's aim is to provide 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 WM" or a small DE can focus on the WM
+The libweston effort started landing on the Weston 1.9 development
+cycle, and is expected to continue through many Weston releases
+towards a stable API and feature completeness.
+API (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
+between every 1.x.0 Weston release (minor version bumps), just like
+Weston's plugin API does. For git snapshots of the master branch, the
+API can break any time without any warning or any version bumps.
+Libweston API or ABI will not be broken between Weston's stable
+releases 1.x.0 and 1.x.y, where y < 90.
+To make things tolerable for libweston users in spite of ABI
+breakages, libweston is designed to be perfectly parallel-installable.
+An ABI-version is defined for libweston, and it is bumped for releases
+as needed. Different ABI-versions of libweston can be installed in
+parallel, so that external projects can easily depend on a particular
+ABI-version, and they do not have to fight over which ABI-version is
+installed in a user's system.
+Note, that versions of Weston itself will not be parallel-installable,
+only libweston is.
+Libweston design goals
+The high-level goal of libweston is that what used to be shell plugins
+will be main executables. Instead of launching 'weston' with various
+arguments to choose the shell, one would be launching
+'weston-desktop', 'weston-ivi', 'orbital', etc. The main executable
+(the hosting program) links to libweston for a fundamental compositor
+implementation. Libweston is also intended for use by other projects
+who want to create new "Wayland WMs".
+The libweston API/ABI will be separating the shell logic and main
+program from the rest of the "Weston compositor" (libweston
+- 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 ???
+There are still many more details to be decided.
+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)
+- rpi-backend (depends on DispmanX, libudev, ...)
+- fbdev-backend (depends on libudev...)
+- rdp-backend (depends on freerdp)
+ + screen-share
+- weston (the executable, not parallel-installable):
+ + desktop shell
+ + ivi-shell
+ + fullscreen shell
+ + weston-info, weston-terminal, etc. we install by default
+- weston demos (not parallel-installable)
+ + weston-simple-* programs
+ + possibly all the programs we build but do not install by
+- and possibly more...
+Everything should be parallel-installable across libweston
+ABI-versions, except those explicitly mentioned.
+Weston's build may not sanely allow this yet, but this is the
More information about the wayland-devel