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 a X window
  13 manager.
  14
  15 Refer to http://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 http://wayland.freedesktop.org/testing.html for additional details.
  20
  21
  22
  23                         Libweston
  24                         =========
  25
  26 Libweston is an effort to separate the re-usable parts of Weston into
  27 a library. Libweston provides most of the boring and tedious bits of
  28 correctly implementing core Wayland protocols and interfacing with
  29 input and output systems, so that people who just want to write a new
  30 "Wayland window manager" (WM) or a small desktop environment (DE) can
  31 focus on the WM part.
  32
  33 Libweston was first introduced in Weston 1.9, and is expected to
  34 continue evolving through many Weston releases before it achieves a
  35 stable API and feature completeness.
  36
  37
  38 API (in)stability and parallel installability
  39 ---------------------------------------------
  40
  41 As libweston's API surface is huge, it is impossible to get it right
  42 in one go. Therefore developers reserve the right to break the API
  43 between every 1.x.0 Weston release (minor version bumps), just like
  44 Weston's plugin API does. For git snapshots of the master branch, the
  45 API can break any time without warning or version bump.
  46
  47 Libweston API or ABI will not be broken between Weston's stable
  48 releases 1.x.0 and 1.x.y, where y < 90.
  49
  50 To make things tolerable for libweston users despite ABI breakages,
  51 libweston is designed to be perfectly parallel-installable. An
  52 ABI-version is defined for libweston, and it is bumped for releases as
  53 needed. Different ABI-versions of libweston can be installed in
  54 parallel, so that external projects can easily depend on a particular
  55 ABI-version, and they do not have to fight over which ABI-version is
  56 installed in a user's system. This allows a user to install many
  57 different compositors each requiring a different libweston ABI-version
  58 without tricks or conflicts.
  59
  60 Note, that versions of Weston itself will not be parallel-installable,
  61 only libweston is.
  62
  63 For more information about parallel installability, see
  64 http://ometer.com/parallel.html
  65
  66
  67 Libweston design goals
  68 ----------------------
  69
  70 The high-level goal of libweston is that what used to be shell plugins
  71 will be main executables. Instead of launching 'weston' with various
  72 arguments to choose the shell, one would be launching
  73 'weston-desktop', 'weston-ivi', 'orbital', etc. The main executable
  74 (the hosting program) links to libweston for a fundamental compositor
  75 implementation. Libweston is also intended for use by other projects
  76 who want to create new "Wayland WMs".
  77
  78 The libweston API/ABI will be separating the shell logic and main
  79 program from the rest of the "Weston compositor" (libweston
  80 internals).
  81
  82 Details:
  83
  84 - All configuration and user interfaces will be outside of libweston.
  85   This includes command line parsing, configuration files, and runtime
  86   (graphical) UI.
  87
  88 - The hosting program (main executable) will be in full control of all
  89   libweston options. Libweston should not have user settable options
  90   that would work behind the hosting program's back, except perhaps
  91   debugging features and such.
  92
  93 - Signal handling will be outside of libweston.
  94
  95 - Child process execution and management will be outside of libweston.
  96
  97 - The different backends (drm, fbdev, x11, etc) will be an internal
  98   detail of libweston. Libweston will not support third party
  99   backends. However, hosting programs need to handle
 100   backend-specific configuration due to differences in behaviour and
 101   available features.
 102
 103 - Renderers will be libweston internal details too, though again the
 104   hosting program may affect the choice of renderer if the backend
 105   allows, and maybe set renderer-specific options.
 106
 107 - plugin design ???
 108
 109 - xwayland ???
 110
 111 There are still many more details to be decided.
 112
 113
 114 For packagers
 115 -------------
 116
 117 Always build Weston with --with-cairo=image.
 118
 119 The Weston project is (will be) intended to be split into several
 120 binary packages, each with its own dependencies. The maximal split
 121 would be roughly like this:
 122
 123 - libweston (minimal dependencies):
 124         + headless backend
 125         + wayland backend
 126
 127 - gl-renderer (depends on GL libs etc.)
 128
 129 - drm-backend (depends on libdrm, libgbm, libudev, libinput, ...)
 130
 131 - x11-backend (depends of X11/xcb libs)
 132
 133 - xwayland (depends on X11/xcb libs)
 134
 135 - rpi-backend (depends on DispmanX, libudev, ...)
 136
 137 - fbdev-backend (depends on libudev...)
 138
 139 - rdp-backend (depends on freerdp)
 140         + screen-share
 141
 142 - weston (the executable, not parallel-installable):
 143         + desktop shell
 144         + ivi-shell
 145         + fullscreen shell
 146         + weston-info, weston-terminal, etc. we install by default
 147
 148 - weston demos (not parallel-installable)
 149         + weston-simple-* programs
 150         + possibly all the programs we build but do not install by
 151           default
 152
 153 - and possibly more...
 154
 155 Everything should be parallel-installable across libweston
 156 ABI-versions, except those explicitly mentioned.
 157
 158 Weston's build may not sanely allow this yet, but this is the
 159 intention.