Pekka Paalanen | 2abe445 | 2015-07-14 13:05:34 +0300 | [diff] [blame] | 1 | Weston |
| 2 | ====== |
Kristian Høgsberg | a6f6999 | 2010-09-14 12:41:26 -0400 | [diff] [blame] | 3 | |
Kristian Høgsberg | 72e023c | 2012-07-20 12:26:23 -0400 | [diff] [blame] | 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 | |
Bryce W. Harrington | c74ab15 | 2014-02-03 21:37:06 +0000 | [diff] [blame] | 15 | Refer to http://wayland.freedesktop.org/building.html for building |
Kristian Høgsberg | 72e023c | 2012-07-20 12:26:23 -0400 | [diff] [blame] | 16 | weston and its dependencies. |
Bryce W. Harrington | c74ab15 | 2014-02-03 21:37:06 +0000 | [diff] [blame] | 17 | |
| 18 | The test suite can be invoked via `make check`; see |
| 19 | http://wayland.freedesktop.org/testing.html for additional details. |
Pekka Paalanen | 2abe445 | 2015-07-14 13:05:34 +0300 | [diff] [blame] | 20 | |
Jon A. Cruz | 179c186 | 2015-07-15 19:22:43 -0700 | [diff] [blame] | 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 | |
Pekka Paalanen | 2abe445 | 2015-07-14 13:05:34 +0300 | [diff] [blame] | 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.9, 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 (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 |
| 49 | between every 1.x.0 Weston release (minor version bumps), just like |
| 50 | Weston's plugin API does. For git snapshots of the master branch, the |
| 51 | API can break any time without warning or version bump. |
| 52 | |
| 53 | Libweston API or ABI will not be broken between Weston's stable |
| 54 | releases 1.x.0 and 1.x.y, where y < 90. |
| 55 | |
| 56 | To make things tolerable for libweston users despite ABI breakages, |
| 57 | libweston is designed to be perfectly parallel-installable. An |
| 58 | ABI-version is defined for libweston, and it is bumped for releases as |
| 59 | needed. Different ABI-versions of libweston can be installed in |
| 60 | parallel, so that external projects can easily depend on a particular |
| 61 | ABI-version, and they do not have to fight over which ABI-version is |
| 62 | installed in a user's system. This allows a user to install many |
| 63 | different compositors each requiring a different libweston ABI-version |
| 64 | without tricks or conflicts. |
| 65 | |
| 66 | Note, that versions of Weston itself will not be parallel-installable, |
| 67 | only libweston is. |
| 68 | |
| 69 | For more information about parallel installability, see |
| 70 | http://ometer.com/parallel.html |
| 71 | |
| 72 | |
| 73 | Libweston design goals |
| 74 | ---------------------- |
| 75 | |
| 76 | The high-level goal of libweston is that what used to be shell plugins |
| 77 | will be main executables. Instead of launching 'weston' with various |
| 78 | arguments to choose the shell, one would be launching |
| 79 | 'weston-desktop', 'weston-ivi', 'orbital', etc. The main executable |
| 80 | (the hosting program) links to libweston for a fundamental compositor |
| 81 | implementation. Libweston is also intended for use by other projects |
| 82 | who want to create new "Wayland WMs". |
| 83 | |
| 84 | The libweston API/ABI will be separating the shell logic and main |
| 85 | program from the rest of the "Weston compositor" (libweston |
| 86 | internals). |
| 87 | |
| 88 | Details: |
| 89 | |
| 90 | - All configuration and user interfaces will be outside of libweston. |
| 91 | This includes command line parsing, configuration files, and runtime |
| 92 | (graphical) UI. |
| 93 | |
| 94 | - The hosting program (main executable) will be in full control of all |
| 95 | libweston options. Libweston should not have user settable options |
| 96 | that would work behind the hosting program's back, except perhaps |
| 97 | debugging features and such. |
| 98 | |
| 99 | - Signal handling will be outside of libweston. |
| 100 | |
| 101 | - Child process execution and management will be outside of libweston. |
| 102 | |
| 103 | - The different backends (drm, fbdev, x11, etc) will be an internal |
| 104 | detail of libweston. Libweston will not support third party |
| 105 | backends. However, hosting programs need to handle |
| 106 | backend-specific configuration due to differences in behaviour and |
| 107 | available features. |
| 108 | |
| 109 | - Renderers will be libweston internal details too, though again the |
| 110 | hosting program may affect the choice of renderer if the backend |
| 111 | allows, and maybe set renderer-specific options. |
| 112 | |
| 113 | - plugin design ??? |
| 114 | |
| 115 | - xwayland ??? |
| 116 | |
Pekka Paalanen | 58f98c9 | 2016-06-03 16:45:21 +0300 | [diff] [blame] | 117 | - weston-launch is still with libweston even though it can only launch |
| 118 | Weston and nothing else. We would like to allow it to launch any compositor, |
| 119 | but since it gives by design root access to input devices and DRM, how can |
| 120 | we restrict it to intended programs? |
| 121 | |
Pekka Paalanen | 2abe445 | 2015-07-14 13:05:34 +0300 | [diff] [blame] | 122 | There are still many more details to be decided. |
| 123 | |
| 124 | |
| 125 | For packagers |
| 126 | ------------- |
| 127 | |
| 128 | Always build Weston with --with-cairo=image. |
| 129 | |
| 130 | The Weston project is (will be) intended to be split into several |
| 131 | binary packages, each with its own dependencies. The maximal split |
| 132 | would be roughly like this: |
| 133 | |
| 134 | - libweston (minimal dependencies): |
| 135 | + headless backend |
| 136 | + wayland backend |
| 137 | |
| 138 | - gl-renderer (depends on GL libs etc.) |
| 139 | |
| 140 | - drm-backend (depends on libdrm, libgbm, libudev, libinput, ...) |
| 141 | |
| 142 | - x11-backend (depends of X11/xcb libs) |
| 143 | |
| 144 | - xwayland (depends on X11/xcb libs) |
| 145 | |
Pekka Paalanen | 2abe445 | 2015-07-14 13:05:34 +0300 | [diff] [blame] | 146 | - fbdev-backend (depends on libudev...) |
| 147 | |
| 148 | - rdp-backend (depends on freerdp) |
Pekka Paalanen | 2abe445 | 2015-07-14 13:05:34 +0300 | [diff] [blame] | 149 | |
| 150 | - weston (the executable, not parallel-installable): |
| 151 | + desktop shell |
| 152 | + ivi-shell |
| 153 | + fullscreen shell |
| 154 | + weston-info, weston-terminal, etc. we install by default |
Pekka Paalanen | 58f98c9 | 2016-06-03 16:45:21 +0300 | [diff] [blame] | 155 | + screen-share |
Pekka Paalanen | 2abe445 | 2015-07-14 13:05:34 +0300 | [diff] [blame] | 156 | |
| 157 | - weston demos (not parallel-installable) |
| 158 | + weston-simple-* programs |
| 159 | + possibly all the programs we build but do not install by |
| 160 | default |
| 161 | |
| 162 | - and possibly more... |
| 163 | |
| 164 | Everything should be parallel-installable across libweston |
| 165 | ABI-versions, except those explicitly mentioned. |
| 166 | |
| 167 | Weston's build may not sanely allow this yet, but this is the |
| 168 | intention. |