1Weston 2====== 3 4 5 6Weston is the reference implementation of a Wayland compositor, as well as a 7useful environment in and of itself. 8 9Out of the box, Weston provides a very basic desktop, or a full-featured 10environment for non-desktop uses such as automotive, embedded, in-flight, 11industrial, kiosks, set-top boxes and TVs. It also provides a library allowing 12other projects to build their own full-featured environments on top of Weston's 13core. 14 15The core focus of Weston is correctness and reliability. Weston aims to be lean 16and fast, but more importantly, to be predictable. Whilst Weston does have known 17bugs and shortcomings, we avoid unknown or variable behaviour as much as 18possible, including variable performance such as occasional spikes in frame 19display time. 20 21A small suite of example or demo clients are also provided: though they can be 22useful in themselves, their main purpose is to be an example or test case for 23others building compositors or clients. 24 25If you are after a more mainline desktop experience, the 26[GNOME](https://www.gnome.org) and [KDE](https://www.kde.org) projects provide 27full-featured desktop environments built on the Wayland protocol. Many other 28projects also exist providing Wayland clients and desktop environments: you are 29not limited to just what you can find in Weston. 30 31Reporting issues and contributing 32================================= 33 34Weston's development is 35[hosted on freedesktop.org GitLab](https://gitlab.freedesktop.org/wayland/weston/). 36Please also see [the contributing document](CONTRIBUTING.md), which details how 37to make code or non-technical contributions to Weston. 38 39Building Weston 40=============== 41 42Weston is built using [Meson](https://mesonbuild.com/). Weston often depends 43on the current release versions of 44[Wayland](https://gitlab.freedesktop.org/wayland/wayland) and 45[wayland-protocols](https://cgit.freedesktop.org/wayland/wayland-protocols). 46 47If necessary, the latest Meson can be installed as a user with: 48 49 $ pip3 install --user meson 50 51Weston's Meson build does not do autodetection and it defaults to all 52features enabled, which means you likely hit missing dependencies on the first 53try. If a dependency is avoidable through a build option, the error message 54should tell you what option can be used to avoid it. You may need to disable 55several features if you want to avoid certain dependencies. 56 57 $ git clone https://gitlab.freedesktop.org/wayland/weston.git 58 $ cd weston 59 $ meson build/ --prefix=... 60 $ ninja -C build/ install 61 $ cd .. 62 63The `meson` command populates the build directory. This step can 64fail due to missing dependencies. Any build options you want can be added on 65that line, e.g. `meson build/ --prefix=... -Ddemo-clients=false`. All the build 66options can be found in the file [meson_options.txt](meson_options.txt). 67 68Once the build directory has been successfully populated, you can inspect the 69configuration with `meson configure build/`. If you need to change an 70option, you can do e.g. `meson configure build/ -Ddemo-clients=false`. 71 72Every push to the Weston master repository and its forks is built using GitLab 73CI. [Reading the configuration](.gitlab-ci.yml) may provide a useful example of 74how to build and install Weston. 75 76More [detailed documentation on building Weston](https://wayland.freedesktop.org/building.html) 77is available on the Wayland site. There are also more details on 78[how to run and write tests](https://wayland.freedesktop.org/testing.html). 79 80For building the documentation see [weston-doc](#weston-doc). 81 82Running Weston 83============== 84 85Once Weston is installed, most users can simply run it by typing `weston`. This 86will launch Weston inside whatever environment you launch it from: when launched 87from a text console, it will take over that console. When launched from inside 88an existing Wayland or X11 session, it will start a 'nested' instance of Weston 89inside a window in that session. 90 91Help is available by running `weston --help`, or `man weston`, which will list 92the available configuration options and display backends. It can also be 93configured through a file on disk; more information on this can be found through 94`man weston.ini`. 95 96In some special cases, such as when running remotely or without logind's session 97control, Weston may not be able to run directly from a text console. In these 98situations, you can instead execute the `weston-launch` helper, which will gain 99privileged access to input and output devices by running as root, then granting 100access to the main Weston binary running as your user. Running Weston this way 101is not recommended unless necessary. 102 103Weston-doc 104========== 105 106For documenting weston we use [sphinx](http://www.sphinx-doc.org/en/master/) 107together with [breathe](https://breathe.readthedocs.io/en/latest/) that 108understands XMLs databases generated by doxygen. So far, this is a compromise 109until better tools are available in order to remove the doxygen 110dependency. You should be able to install both sphinx and breathe extension 111using pip3 command, or your package manager. 112Doxygen should be available using your distribution package manager. 113 114Once those are set-up, run `meson` with `-Ddoc=true` option in order to enable 115building the documentation. Installation will place the documentation in the 116prefix's path under datadir (i.e., `share/doc`). 117 118Adding and improving documentation 119---------------------------------- 120 121For re-generating the documentation a special `docs` target has been added. 122Although first time you build (and subsequently install) weston, you'll see the 123documentation being built, updates to the spinx documentation files or to the 124source files will only be updated when using `docs` target! 125 126Example: 127 128~~~~ 129$ ninja install # generates and installs the documentation 130# time passes, hack hack, add doc in sources or rST files 131$ ninja install # not sufficient, docs will not be updated 132$ ninja docs && ninja install # run 'docs' then install 133~~~~ 134 135Improving/adding documentation can be done by modifying rST files under 136`doc/sphinx/` directory or by modifying the source code using doxygen 137directives. 138 139Libweston 140========= 141 142Libweston is an effort to separate the re-usable parts of Weston into 143a library. Libweston provides most of the boring and tedious bits of 144correctly implementing core Wayland protocols and interfacing with 145input and output systems, so that people who just want to write a new 146"Wayland window manager" (WM) or a small desktop environment (DE) can 147focus on the WM part. 148 149Libweston was first introduced in Weston 1.12, and is expected to 150continue evolving through many Weston releases before it achieves a 151stable API and feature completeness. 152 153Libweston's primary purpose is exporting an API for creating Wayland 154compositors. Libweston's secondary purpose is to export the weston_config API 155so that third party plugins and helper programs can read `weston.ini` if they 156want to. However, these two scopes are orthogonal and independent. At no point 157will the compositor functionality use or depend on the weston_config 158functionality. 159 160 161API/ABI (in)stability and parallel installability 162------------------------------------------------- 163 164As libweston's API surface is huge, it is impossible to get it right 165in one go. Therefore developers reserve the right to break the API/ABI and bump 166the major version to signify that. For git snapshots of the master branch, the 167API/ABI can break any time without warning. 168 169Libweston major can be bumped only once during a development cycle. This should 170happen on the first patch that breaks the API or ABI. Further breaks before the 171next Weston major.0.0 release do not cause a bump. This means that libweston 172API and ABI are allowed to break also after an alpha release, up to the final 173release. However, breaks after alpha should be judged by the usual practices 174for allowing minor features, fixes only, or critical fixes only. 175 176To make things tolerable for libweston users despite API/ABI breakages, 177different libweston major versions are designed to be perfectly 178parallel-installable. This way external projects can easily depend on a 179particular API/ABI-version. Thus they do not have to fight over which 180ABI-version is installed in a user's system. This allows a user to install many 181different compositors each requiring a different libweston ABI-version without 182tricks or conflicts. 183 184Note, that versions of Weston itself will not be parallel-installable, 185only libweston is. 186 187For more information about parallel installability, see 188http://ometer.com/parallel.html 189 190 191Versioning scheme 192----------------- 193 194In order to provide consistent, easy to use versioning, libweston 195follows the rules in the Apache Portable Runtime Project 196http://apr.apache.org/versioning.html. 197 198The document provides the full details, with the gist summed below: 199 - Major - backward incompatible changes. 200 - Minor - new backward compatible features. 201 - Patch - internal (implementation specific) fixes. 202 203Weston and libweston have separate version numbers in meson.build. All 204releases are made by the Weston version number. Libweston version number 205matches the Weston version number in all releases except maybe pre-releases. 206Pre-releases have the Weston micro version 91 or greater. 207 208A pre-release is allowed to install a libweston version greater than the Weston 209version in case libweston major was bumped. In that case, the libweston version 210must be Weston major + 1. 211 212Pkg-config files are named after libweston major, but carry the Weston version 213number. This means that Weston pre-release 2.1.91 may install libweston-3.pc 214for the future libweston 3.0.0, but the .pc file says the version is still 2152.1.91. When a libweston user wants to depend on the fully stable API and ABI 216of a libweston major, he should use (e.g. for major 3): 217 218 PKG_CHECK_MODULES(LIBWESTON, [libweston-3 >= 3.0.0]) 219 220Depending only on libweston-3 without a specific version number still allows 221pre-releases which might have different API or ABI. 222 223 224Forward compatibility 225--------------------- 226 227Inspired by ATK, Qt and KDE programs/libraries, libjpeg-turbo, GDK, 228NetworkManager, js17, lz4 and many others, libweston uses a macro to restrict 229the API visible to the developer - REQUIRE_LIBWESTON_API_VERSION. 230 231Note that different projects focus on different aspects - upper and/or lower 232version check, default to visible/hidden old/new symbols and so on. 233 234libweston aims to guard all newly introduced API, in order to prevent subtle 235breaks that a simple recompile (against a newer version) might cause. 236 237The macro is of the format 0x$MAJOR$MINOR and does not include PATCH version. 238As mentioned in the Versioning scheme section, the latter does not reflect any 239user visible API changes, thus should be not considered part of the API version. 240 241All new symbols should be guarded by the macro like the example given below: 242 243~~~~ 244#if REQUIRE_LIBWESTON_API_VERSION >= 0x0101 245 246bool 247weston_ham_sandwich(void); 248 249#endif 250~~~~ 251 252In order to use the said symbol, the one will have a similar code in their 253configure.ac: 254 255~~~~ 256PKG_CHECK_MODULES(LIBWESTON, [libweston-1 >= 1.1]) 257AC_DEFINE(REQUIRE_LIBWESTON_API_VERSION, [0x0101]) 258~~~~ 259 260If the user is _not_ interested in forward compatibility, they can use 0xffff 261or similar high value. Yet doing so is not recommended. 262 263 264Libweston design goals 265---------------------- 266 267The high-level goal of libweston is to decouple the compositor from 268the shell implementation (what used to be shell plugins). 269 270Thus, instead of launching 'weston' with various arguments to choose the 271shell, one would launch the shell itself, e.g. 'weston-desktop', 272'weston-ivi', 'orbital', etc. The main executable (the hosting program) 273will implement the shell, while libweston will be used for a fundamental 274compositor implementation. 275 276Libweston is also intended for use by other project developers who want 277to create new "Wayland WMs". 278 279Details: 280 281- All configuration and user interfaces will be outside of libweston. 282 This includes command line parsing, configuration files, and runtime 283 (graphical) UI. 284 285- The hosting program (main executable) will be in full control of all 286 libweston options. Libweston should not have user settable options 287 that would work behind the hosting program's back, except perhaps 288 debugging features and such. 289 290- Signal handling will be outside of libweston. 291 292- Child process execution and management will be outside of libweston. 293 294- The different backends (drm, fbdev, x11, etc) will be an internal 295 detail of libweston. Libweston will not support third party 296 backends. However, hosting programs need to handle 297 backend-specific configuration due to differences in behaviour and 298 available features. 299 300- Renderers will be libweston internal details too, though again the 301 hosting program may affect the choice of renderer if the backend 302 allows, and maybe set renderer-specific options. 303 304- plugin design ??? 305 306- xwayland ??? 307 308- weston-launch is still with libweston even though it can only launch 309 Weston and nothing else. We would like to allow it to launch any compositor, 310 but since it gives by design root access to input devices and DRM, how can 311 we restrict it to intended programs? 312 313There are still many more details to be decided. 314 315 316For packagers 317------------- 318 319Always build Weston with --with-cairo=image. 320 321The Weston project is (will be) intended to be split into several 322binary packages, each with its own dependencies. The maximal split 323would be roughly like this: 324 325- libweston (minimal dependencies): 326 + headless backend 327 + wayland backend 328 329- gl-renderer (depends on GL libs etc.) 330 331- drm-backend (depends on libdrm, libgbm, libudev, libinput, ...) 332 333- x11-backend (depends of X11/xcb libs) 334 335- xwayland (depends on X11/xcb libs) 336 337- fbdev-backend (depends on libudev...) 338 339- rdp-backend (depends on freerdp) 340 341- weston (the executable, not parallel-installable): 342 + desktop shell 343 + ivi-shell 344 + fullscreen shell 345 + weston-info (deprecated), weston-terminal, etc. we install by default 346 + screen-share 347 348- weston demos (not parallel-installable) 349 + weston-simple-* programs 350 + possibly all the programs we build but do not install by 351 default 352 353- and possibly more... 354 355Everything should be parallel-installable across libweston major 356ABI-versions (libweston-1.so, libweston-2.so, etc.), except those 357explicitly mentioned. 358 359Weston's build may not sanely allow this yet, but this is the 360intention. 361
