README: Reorder sections, rewrite intro + libweston
Reorder the sections into what people care about: what is it, how do I build it, how do I run it, where are the docs for when I want to do more? The libweston section has been substantially rewritten to trim the details down to what is accurate and relevant, and the introduction has accordingly been updated to reflect the reality of Weston as a project today. Signed-off-by: Daniel Stone <daniels@collabora.com>
This commit is contained in:
Daniel Stone
Marius Vlad
parent
6c3eb6b17e
commit
515708040a
208
README.md
208
README.md
|
|
@ -3,39 +3,17 @@ Weston
|
|||
|
||||
|
||||
|
||||
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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue