You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
349 lines
13 KiB
349 lines
13 KiB
Weston
|
|
======
|
|
|
|
|
|
|
|
Weston is the reference implementation of a Wayland compositor, as well as a
|
|
useful environment in and of itself.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
If you are after a more mainline desktop experience, the
|
|
[GNOME](https://www.gnome.org) and [KDE](https://www.kde.org) projects provide
|
|
full-featured desktop environments built on the Wayland protocol. Many other
|
|
projects also exist providing Wayland clients and desktop environments: you are
|
|
not limited to just what you can find in Weston.
|
|
|
|
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
|
|
===============
|
|
|
|
Weston is built using [Meson](https://mesonbuild.com/). Weston often depends
|
|
on the current release versions of
|
|
[Wayland](https://gitlab.freedesktop.org/wayland/wayland) and
|
|
[wayland-protocols](https://cgit.freedesktop.org/wayland/wayland-protocols).
|
|
|
|
If necessary, the latest Meson can be installed as a user with:
|
|
|
|
$ pip3 install --user meson
|
|
|
|
Weston's Meson build does not do autodetection and it defaults to all
|
|
features enabled, which means you likely hit missing dependencies on the first
|
|
try. If a dependency is avoidable through a build option, the error message
|
|
should tell you what option can be used to avoid it. You may need to disable
|
|
several features if you want to avoid certain dependencies.
|
|
|
|
$ git clone https://gitlab.freedesktop.org/wayland/weston.git
|
|
$ cd weston
|
|
$ meson build/ --prefix=...
|
|
$ ninja -C build/ install
|
|
$ cd ..
|
|
|
|
The `meson` command populates the build directory. This step can
|
|
fail due to missing dependencies. Any build options you want can be added on
|
|
that line, e.g. `meson build/ --prefix=... -Ddemo-clients=false`. All the build
|
|
options can be found in the file [meson_options.txt](meson_options.txt).
|
|
|
|
Once the build directory has been successfully populated, you can inspect the
|
|
configuration with `meson configure build/`. If you need to change an
|
|
option, you can do e.g. `meson configure build/ -Ddemo-clients=false`.
|
|
|
|
Every push to the Weston master repository and its forks is built using GitLab
|
|
CI. [Reading the configuration](.gitlab-ci.yml) may provide a useful example of
|
|
how to build and install Weston.
|
|
|
|
More [detailed documentation on building Weston](https://wayland.freedesktop.org/building.html)
|
|
is available on the Wayland site. There are also more details on
|
|
[how to run and write tests](https://wayland.freedesktop.org/testing.html).
|
|
|
|
For building the documentation see [documentation](#documentation).
|
|
|
|
Running Weston
|
|
==============
|
|
|
|
Once Weston is installed, most users can simply run it by typing `weston`. This
|
|
will launch Weston inside whatever environment you launch it from: when launched
|
|
from a text console, it will take over that console. When launched from inside
|
|
an existing Wayland or X11 session, it will start a 'nested' instance of Weston
|
|
inside a window in that session.
|
|
|
|
Help is available by running `weston --help`, or `man weston`, which will list
|
|
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`.
|
|
|
|
Documentation
|
|
=============
|
|
|
|
To read the Weston documentation online, head over to
|
|
[the Weston website](https://wayland.pages.freedesktop.org/weston/).
|
|
|
|
For documenting weston we use [sphinx](http://www.sphinx-doc.org/en/master/)
|
|
together with [breathe](https://breathe.readthedocs.io/en/latest/) that
|
|
understands XMLs databases generated by doxygen. So far, this is a compromise
|
|
until better tools are available in order to remove the doxygen
|
|
dependency. You should be able to install both sphinx and breathe extension
|
|
using pip3 command, or your package manager.
|
|
Doxygen should be available using your distribution package manager.
|
|
|
|
Once those are set-up, run `meson` with `-Ddoc=true` option in order to enable
|
|
building the documentation. Installation will place the documentation in the
|
|
prefix's path under datadir (i.e., `share/doc`).
|
|
|
|
Adding and improving documentation
|
|
----------------------------------
|
|
|
|
For re-generating the documentation a special `docs` target has been added.
|
|
Although first time you build (and subsequently install) weston, you'll see the
|
|
documentation being built, updates to the spinx documentation files or to the
|
|
source files will only be updated when using `docs` target!
|
|
|
|
Example:
|
|
|
|
~~~~
|
|
$ ninja install # generates and installs the documentation
|
|
# time passes, hack hack, add doc in sources or rST files
|
|
$ ninja install # not sufficient, docs will not be updated
|
|
$ 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.
|
|
|
|
|
|
Forward compatibility
|
|
---------------------
|
|
|
|
Inspired by ATK, Qt and KDE programs/libraries, libjpeg-turbo, GDK,
|
|
NetworkManager, js17, lz4 and many others, libweston uses a macro to restrict
|
|
the API visible to the developer - REQUIRE_LIBWESTON_API_VERSION.
|
|
|
|
Note that different projects focus on different aspects - upper and/or lower
|
|
version check, default to visible/hidden old/new symbols and so on.
|
|
|
|
libweston aims to guard all newly introduced API, in order to prevent subtle
|
|
breaks that a simple recompile (against a newer version) might cause.
|
|
|
|
The macro is of the format 0x$MAJOR$MINOR and does not include PATCH version.
|
|
As mentioned in the Versioning scheme section, the latter does not reflect any
|
|
user visible API changes, thus should be not considered part of the API version.
|
|
|
|
All new symbols should be guarded by the macro like the example given below:
|
|
|
|
~~~~
|
|
#if REQUIRE_LIBWESTON_API_VERSION >= 0x0101
|
|
|
|
bool
|
|
weston_ham_sandwich(void);
|
|
|
|
#endif
|
|
~~~~
|
|
|
|
In order to use the said symbol, the one will have a similar code in their
|
|
configure.ac:
|
|
|
|
~~~~
|
|
PKG_CHECK_MODULES(LIBWESTON, [libweston-1 >= 1.1])
|
|
AC_DEFINE(REQUIRE_LIBWESTON_API_VERSION, [0x0101])
|
|
~~~~
|
|
|
|
If the user is _not_ interested in forward compatibility, they can use 0xffff
|
|
or similar high value. Yet doing so is not recommended.
|
|
|
|
|
|
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.
|
|
|
|
|
|
For packagers
|
|
-------------
|
|
|
|
Always build Weston with --with-cairo=image.
|
|
|
|
The Weston project is (will be) intended to be split into several
|
|
binary packages, each with its own dependencies. The maximal split
|
|
would be roughly like this:
|
|
|
|
- libweston (minimal dependencies):
|
|
+ headless backend
|
|
+ wayland backend
|
|
|
|
- gl-renderer (depends on GL libs etc.)
|
|
|
|
- drm-backend (depends on libdrm, libgbm, libudev, libinput, ...)
|
|
|
|
- x11-backend (depends of X11/xcb libs)
|
|
|
|
- xwayland (depends on X11/xcb libs)
|
|
|
|
- rdp-backend (depends on freerdp)
|
|
|
|
- weston (the executable, not parallel-installable):
|
|
+ desktop shell
|
|
+ ivi-shell
|
|
+ fullscreen shell
|
|
+ weston-terminal, etc. we install by default
|
|
+ screen-share
|
|
|
|
- weston demos (not parallel-installable)
|
|
+ weston-simple-* programs
|
|
+ possibly all the programs we build but do not install by
|
|
default
|
|
|
|
- and possibly more...
|
|
|
|
Everything should be parallel-installable across libweston major
|
|
ABI-versions (libweston-1.so, libweston-2.so, etc.), except those
|
|
explicitly mentioned.
|
|
|
|
Weston's build may not sanely allow this yet, but this is the
|
|
intention.
|
|
|