diff --git a/README.md b/README.md index 39bb7e7b..62ea6725 100644 --- a/README.md +++ b/README.md @@ -3,39 +3,17 @@ Weston ![screenshot of skeletal Weston desktop](doc/wayland-screenshot.jpg) -Weston is the reference implementation of a Wayland compositor, as well as a -useful environment in and of itself. +Weston is a Wayland compositor designed for correctness, reliability, +predictability, and performance. Out of the box, Weston provides a very basic desktop, or a full-featured environment for non-desktop uses such as automotive, embedded, in-flight, -industrial, kiosks, set-top boxes and TVs. It also provides a library allowing -other projects to build their own full-featured environments on top of Weston's -core. +industrial, kiosks, set-top boxes and TVs. -The core focus of Weston is correctness and reliability. Weston aims to be lean -and fast, but more importantly, to be predictable. Whilst Weston does have known -bugs and shortcomings, we avoid unknown or variable behaviour as much as -possible, including variable performance such as occasional spikes in frame -display time. +It also provides a library called [libweston](#libweston) which allows +users to build their own custom full-featured environments on top of +Weston's core. -Weston and libweston are not suitable for memory constrained environments -where the compositor is expected to continue running even in the face of -trivial memory allocations failing. If standard functions like `malloc()` -fail for small allocations, -[you can expect libweston to abort](https://gitlab.freedesktop.org/wayland/weston/-/issues/631). - -A small suite of example or demo clients are also provided: though they can be -useful in themselves, their main purpose is to be an example or test case for -others building compositors or clients. - - -Reporting issues and contributing -================================= - -Weston's development is -[hosted on freedesktop.org GitLab](https://gitlab.freedesktop.org/wayland/weston/). -Please also see [the contributing document](CONTRIBUTING.md), which details how -to make code or non-technical contributions to Weston. Building Weston =============== @@ -80,6 +58,7 @@ is available on the Wayland site. There are also more details on For building the documentation see [documentation](#documentation). + Running Weston ============== @@ -94,6 +73,48 @@ the available configuration options and display backends. It can also be configured through a file on disk; more information on this can be found through `man weston.ini`. +A small suite of example or demo clients are also provided: though they can be +useful in themselves, their main purpose is to be an example or test case for +others building compositors or clients. + + +Using libweston +=============== + +libweston is designed to allow users to use Weston's core - its client support, +backends and renderers - whilst implementing their own user interface, policy, +configuration, and lifecycle. If you would like to implement your own window +manager or desktop environment, we recommend building your project using the +libweston API. + +Building and installing Weston will also install libweston's shared library +and development headers. libweston is both API-compatible and ABI-compatible +within a single stable release. It is parallel-installable, so multiple stable +releases can be installed and used side by side. + +Documentation for libweston's API can be found within the source (see the +[documentation](#documentation) section), and also on +[Weston's online documentation](https://wayland.pages.freedesktop.org/weston/) +for the current stable release. + + +Reporting issues and contributing +================================= + +Weston's development is +[hosted on freedesktop.org GitLab](https://gitlab.freedesktop.org/wayland/weston/). +Please also see [the contributing document](CONTRIBUTING.md), which details how +to make code or non-technical contributions to Weston. + +Weston and libweston are not suitable for severely memory-constrained environments +where the compositor is expected to continue running even in the face of +trivial memory allocations failing. If standard functions like `malloc()` +fail for small allocations, +[you can expect libweston to abort](https://gitlab.freedesktop.org/wayland/weston/-/issues/631). +This is only likely to occur if you have disabled your OS's 'overcommit' +functionality, and not in common cases. + + Documentation ============= @@ -130,134 +151,3 @@ $ ninja docs && ninja install # run 'docs' then install Improving/adding documentation can be done by modifying rST files under `doc/sphinx/` directory or by modifying the source code using doxygen directives. - -Libweston -========= - -Libweston is an effort to separate the re-usable parts of Weston into -a library. Libweston provides 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 window manager" (WM) or a small desktop environment (DE) can -focus on the WM part. - -Libweston was first introduced in Weston 1.12, and is expected to -continue evolving through many Weston releases before it achieves a -stable API and feature completeness. - -Libweston's primary purpose is exporting an API for creating Wayland -compositors. Libweston's secondary purpose is to export the weston_config API -so that third party plugins and helper programs can read `weston.ini` if they -want to. However, these two scopes are orthogonal and independent. At no point -will the compositor functionality use or depend on the weston_config -functionality. - - -API/ABI (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/ABI and bump -the major version to signify that. For git snapshots of the master branch, the -API/ABI can break any time without warning. - -Libweston major can be bumped only once during a development cycle. This should -happen on the first patch that breaks the API or ABI. Further breaks before the -next Weston major.0.0 release do not cause a bump. This means that libweston -API and ABI are allowed to break also after an alpha release, up to the final -release. However, breaks after alpha should be judged by the usual practices -for allowing minor features, fixes only, or critical fixes only. - -To make things tolerable for libweston users despite API/ABI breakages, -different libweston major versions are designed to be perfectly -parallel-installable. This way external projects can easily depend on a -particular API/ABI-version. Thus they do not have to fight over which -ABI-version is installed in a user's system. This allows a user to install many -different compositors each requiring a different libweston ABI-version without -tricks or conflicts. - -Note, that versions of Weston itself will not be parallel-installable, -only libweston is. - -For more information about parallel installability, see -http://ometer.com/parallel.html - - -Versioning scheme ------------------ - -In order to provide consistent, easy to use versioning, libweston -follows the rules in the Apache Portable Runtime Project -http://apr.apache.org/versioning.html. - -The document provides the full details, with the gist summed below: - - Major - backward incompatible changes. - - Minor - new backward compatible features. - - Patch - internal (implementation specific) fixes. - -Weston and libweston have separate version numbers in meson.build. All -releases are made by the Weston version number. Libweston version number -matches the Weston version number in all releases except maybe pre-releases. -Pre-releases have the Weston micro version 91 or greater. - -A pre-release is allowed to install a libweston version greater than the Weston -version in case libweston major was bumped. In that case, the libweston version -must be Weston major + 1. - -Pkg-config files are named after libweston major, but carry the Weston version -number. This means that Weston pre-release 2.1.91 may install libweston-3.pc -for the future libweston 3.0.0, but the .pc file says the version is still -2.1.91. When a libweston user wants to depend on the fully stable API and ABI -of a libweston major, he should use (e.g. for major 3): - - PKG_CHECK_MODULES(LIBWESTON, [libweston-3 >= 3.0.0]) - -Depending only on libweston-3 without a specific version number still allows -pre-releases which might have different API or ABI. - - -Libweston design goals ----------------------- - -The high-level goal of libweston is to decouple the compositor from -the shell implementation (what used to be shell plugins). - -Thus, instead of launching 'weston' with various arguments to choose the -shell, one would launch the shell itself, e.g. 'weston-desktop', -'weston-ivi', 'orbital', etc. The main executable (the hosting program) -will implement the shell, while libweston will be used for a fundamental -compositor implementation. - -Libweston is also intended for use by other project developers who want -to create new "Wayland WMs". - -Details: - -- 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, 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.