README

   1                         Weston
   2                         ======
   3
   4 Weston is the reference implementation of a Wayland compositor, and a
   5 useful compositor in its own right.  Weston has various backends that
   6 lets it run on Linux kernel modesetting and evdev input as well as
   7 under X11.  Weston ships with a few example clients, from simple
   8 clients that demonstrate certain aspects of the protocol to more
   9 complete clients and a simplistic toolkit.  There is also a quite
  10 capable terminal emulator (weston-terminal) and an toy/example desktop
  11 shell.  Finally, weston also provides integration with the Xorg server
  12 and can pull X clients into the Wayland desktop and act as an X window
  13 manager.
  14
  15 Refer to https://wayland.freedesktop.org/building.html for building
  16 weston and its dependencies.
  17
  18 The test suite can be invoked via `make check`; see
  19 https://wayland.freedesktop.org/testing.html for additional details.
  20
  21 Developer documentation can be built via `make doc`. Output will be in
  22 the build root under
  23
  24 docs/developer/html/index.html
  25 docs/tools/html/index.html
  26
  27
  28
  29                         Libweston
  30                         =========
  31
  32 Libweston is an effort to separate the re-usable parts of Weston into
  33 a library. Libweston provides most of the boring and tedious bits of
  34 correctly implementing core Wayland protocols and interfacing with
  35 input and output systems, so that people who just want to write a new
  36 "Wayland window manager" (WM) or a small desktop environment (DE) can
  37 focus on the WM part.
  38
  39 Libweston was first introduced in Weston 1.12, and is expected to
  40 continue evolving through many Weston releases before it achieves a
  41 stable API and feature completeness.
  42
  43
  44 API/ABI (in)stability and parallel installability
  45 -------------------------------------------------
  46
  47 As libweston's API surface is huge, it is impossible to get it right
  48 in one go. Therefore developers reserve the right to break the API/ABI and bump
  49 the major version to signify that. For git snapshots of the master branch, the
  50 API/ABI can break any time without warning.
  51
  52 Libweston major can be bumped only once during a development cycle. This should
  53 happen on the first patch that breaks the API or ABI. Further breaks before the
  54 next Weston major.0.0 release do not cause a bump. This means that libweston
  55 API and ABI are allowed to break also after an alpha release, up to the final
  56 release. However, breaks after alpha should be judged by the usual practices
  57 for allowing minor features, fixes only, or critical fixes only.
  58
  59 To make things tolerable for libweston users despite API/ABI breakages,
  60 different libweston major versions are designed to be perfectly
  61 parallel-installable. This way external projects can easily depend on a
  62 particular API/ABI-version. Thus they do not have to fight over which
  63 ABI-version is installed in a user's system. This allows a user to install many
  64 different compositors each requiring a different libweston ABI-version without
  65 tricks or conflicts.
  66
  67 Note, that versions of Weston itself will not be parallel-installable,
  68 only libweston is.
  69
  70 For more information about parallel installability, see
  71 http://ometer.com/parallel.html
  72
  73
  74 Versioning scheme
  75 -----------------
  76
  77 In order to provide consistent, easy to use versioning, libweston
  78 follows the rules in the Apache Portable Runtime Project
  79 http://apr.apache.org/versioning.html.
  80
  81 The document provides the full details, with the gist summed below:
  82  - Major - backward incompatible changes.
  83  - Minor - new backward compatible features.
  84  - Patch - internal (implementation specific) fixes.
  85
  86 Weston and libweston have separate version numbers in configure.ac. All
  87 releases are made by the Weston version number. Libweston version number
  88 matches the Weston version number in all releases except maybe pre-releases.
  89 Pre-releases have the Weston micro version 91 or greater.
  90
  91 A pre-release is allowed to install a libweston version greater than the Weston
  92 version in case libweston major was bumped. In that case, the libweston version
  93 must be Weston major + 1 and with minor and patch versions zero.
  94
  95 Pkg-config files are named after libweston major, but carry the Weston version
  96 number. This means that Weston pre-release 2.1.91 may install libweston-3.pc
  97 for the future libweston 3.0.0, but the .pc file says the version is still
  98 2.1.91. When a libweston user wants to depend on the fully stable API and ABI
  99 of a libweston major, he should use (e.g. for major 3):
 100
 101         PKG_CHECK_MODULES(LIBWESTON, [libweston-3 >= 3.0.0])
 102
 103 Depending only on libweston-3 without a specific version number still allows
 104 pre-releases which might have different API or ABI.
 105
 106
 107 Forward compatibility
 108 ---------------------
 109
 110 Inspired by ATK, Qt and KDE programs/libraries, libjpeg-turbo, GDK,
 111 NetworkManager, js17, lz4 and many others, libweston uses a macro to restrict
 112 the API visible to the developer - REQUIRE_LIBWESTON_API_VERSION.
 113
 114 Note that different projects focus on different aspects - upper and/or lower
 115 version check, default to visible/hidden old/new symbols and so on.
 116
 117 libweston aims to guard all newly introduced API, in order to prevent subtle
 118 breaks that a simple recompile (against a newer version) might cause.
 119
 120 The macro is of the format 0x$MAJOR$MINOR and does not include PATCH version.
 121 As mentioned in the Versioning scheme section, the latter does not reflect any
 122 user visible API changes, thus should be not considered part of the API version.
 123
 124 All new symbols should be guarded by the macro like the example given below:
 125
 126 #if REQUIRE_LIBWESTON_API_VERSION >= 0x0101
 127
 128 bool
 129 weston_ham_sandwich(void);
 130
 131 #endif
 132
 133 In order to use the said symbol, the one will have a similar code in their
 134 configure.ac:
 135
 136 PKG_CHECK_MODULES(LIBWESTON, [libweston-1 >= 1.1])
 137 AC_DEFINE(REQUIRE_LIBWESTON_API_VERSION, [0x0101])
 138
 139 If the user is _not_ interested in forward compatibility, they can use 0xffff
 140 or similar high value. Yet doing so is not recommended.
 141
 142
 143 Libweston design goals
 144 ----------------------
 145
 146 The high-level goal of libweston is to decouple the compositor from
 147 the shell implementation (what used to be shell plugins).
 148
 149 Thus, instead of launching 'weston' with various arguments to choose the
 150 shell, one would launch the shell itself, e.g. 'weston-desktop',
 151 'weston-ivi', 'orbital', etc. The main executable (the hosting program)
 152 will implement the shell, while libweston will be used for a fundamental
 153 compositor implementation.
 154
 155 Libweston is also intended for use by other project developers who want
 156 to create new "Wayland WMs".
 157
 158 Details:
 159
 160 - All configuration and user interfaces will be outside of libweston.
 161   This includes command line parsing, configuration files, and runtime
 162   (graphical) UI.
 163
 164 - The hosting program (main executable) will be in full control of all
 165   libweston options. Libweston should not have user settable options
 166   that would work behind the hosting program's back, except perhaps
 167   debugging features and such.
 168
 169 - Signal handling will be outside of libweston.
 170
 171 - Child process execution and management will be outside of libweston.
 172
 173 - The different backends (drm, fbdev, x11, etc) will be an internal
 174   detail of libweston. Libweston will not support third party
 175   backends. However, hosting programs need to handle
 176   backend-specific configuration due to differences in behaviour and
 177   available features.
 178
 179 - Renderers will be libweston internal details too, though again the
 180   hosting program may affect the choice of renderer if the backend
 181   allows, and maybe set renderer-specific options.
 182
 183 - plugin design ???
 184
 185 - xwayland ???
 186
 187 - weston-launch is still with libweston even though it can only launch
 188   Weston and nothing else. We would like to allow it to launch any compositor,
 189   but since it gives by design root access to input devices and DRM, how can
 190   we restrict it to intended programs?
 191
 192 There are still many more details to be decided.
 193
 194
 195 For packagers
 196 -------------
 197
 198 Always build Weston with --with-cairo=image.
 199
 200 The Weston project is (will be) intended to be split into several
 201 binary packages, each with its own dependencies. The maximal split
 202 would be roughly like this:
 203
 204 - libweston (minimal dependencies):
 205         + headless backend
 206         + wayland backend
 207
 208 - gl-renderer (depends on GL libs etc.)
 209
 210 - drm-backend (depends on libdrm, libgbm, libudev, libinput, ...)
 211
 212 - x11-backend (depends of X11/xcb libs)
 213
 214 - xwayland (depends on X11/xcb libs)
 215
 216 - fbdev-backend (depends on libudev...)
 217
 218 - rdp-backend (depends on freerdp)
 219
 220 - weston (the executable, not parallel-installable):
 221         + desktop shell
 222         + ivi-shell
 223         + fullscreen shell
 224         + weston-info, weston-terminal, etc. we install by default
 225         + screen-share
 226
 227 - weston demos (not parallel-installable)
 228         + weston-simple-* programs
 229         + possibly all the programs we build but do not install by
 230           default
 231
 232 - and possibly more...
 233
 234 Everything should be parallel-installable across libweston major
 235 ABI-versions (libweston-1.so, libweston-2.so, etc.), except those
 236 explicitly mentioned.
 237
 238 Weston's build may not sanely allow this yet, but this is the
 239 intention.