Skip to content
Commits on Source (10)
Hide whitespace changes
Inline Side-by-side
README.md
View file @ 50809097
......@@ -3,44 +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.
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
===============
......@@ -48,7 +21,7 @@ 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).
[wayland-protocols](https://gitlab.freedesktop.org/wayland/wayland-protocols).
If necessary, the latest Meson can be installed as a user with:
......@@ -85,6 +58,7 @@ is available on the Wayland site. There are also more details on
For building the documentation see [documentation](#documentation).
Running Weston
==============
......@@ -99,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
=============
......@@ -106,14 +122,12 @@ 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
together with [breathe](https://breathe.readthedocs.io/en/latest/) to process
and augment code documentation from Doxygen. You should be able to install
both sphinx and the 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`).
......@@ -137,217 +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.
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
-------------
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.
man/weston.man
View file @ 50809097
......@@ -18,7 +18,7 @@ shell plugins. Two plugins are provided: the desktop shell, and the kiosk
shell.
Weston also supports X clients via
.BR XWayland ", see below."
.BR Xwayland ", see below."
.
.\" ***************************************************************
.SH BACKENDS
......@@ -86,18 +86,16 @@ and then a controller module which may launch helper clients.
.
.\" ***************************************************************
.SH XWAYLAND
XWayland requires a special X.org server to be installed. This X server will
connect to a Wayland server as a Wayland client, and X clients will connect to
the X server. XWayland provides backwards compatibility to X applications in a
Wayland stack.
XWayland is activated by instructing
.BR weston " to load the XWayland module, see " EXAMPLES .
Weston starts listening on a new X display socket, and exports it in the
environment variable
.BR DISPLAY .
When the first X client connects, Weston launches a special X server as a
Wayland client to handle the X client and all future X clients.
Weston can support X11 clients running within a Weston session via an
X server called
.BR Xwayland "."
Xwayland is built as a separate executable, provided by X.Org. Once built
and installed, it can be activated with the
.BR \-\-xwayland
option. Weston will listen on a new X11 display socket and export it
through the
.BR DISPLAY
environment variable.
It has also its own X window manager where cursor themes and sizes can be
chosen using
......@@ -130,9 +128,9 @@ The argument can also be an absolute path starting with a
If the path is not absolute, it will be searched in the normal config
paths, see
.BR weston.ini (5).
If also
This option is ignored if the
.B --no-config
is given, no configuration file will be read.
option is passed.
.TP
.BR \-\-debug
Enable debug protocol extension
......@@ -148,12 +146,6 @@ to take screenshots of the outputs using weston-screenshooter application,
which can lead to silently leaking the output contents. This option should
not be used in production.
.TP
\fB\-\^l\fIscope1,scope2\fR, \fB\-\-logger-scopes\fR=\fIscope1,scope2\fR
Specify to which log scopes should subscribe to. When no scopes are supplied,
the log "log" scope will be subscribed by default. Useful to control which
streams to write data into the logger and can be helpful in diagnosing early
start-up code.
.TP
\fB\-\^f\fIscope1,scope2\fR, \fB\-\-flight-rec-scopes\fR=\fIscope1,scope2\fR
Specify to which scopes should subscribe to. Useful to control which streams to
write data into the flight recorder. Flight recorder has limited space, once
......@@ -161,9 +153,6 @@ the flight recorder is full new data will overwrite the old data. Without any
scopes specified, it subscribes to 'log' and 'drm-backend' scopes. Passing
an empty value would disable the flight recorder entirely.
.TP
.BR \-\-version
Print the program version.
.TP
.BR \-\^h ", " \-\-help
Print a summary of command line options, and quit.
.TP
......@@ -181,8 +170,11 @@ Append log messages to the file
.I file.log
instead of writing them to stderr.
.TP
\fB\-\-xwayland\fR
Ask Weston to load the XWayland module.
\fB\-\^l\fIscope1,scope2\fR, \fB\-\-logger-scopes\fR=\fIscope1,scope2\fR
Specify to which log scopes should subscribe to. When no scopes are supplied,
the log "log" scope will be subscribed by default. Useful to control which
streams to write data into the logger and can be helpful in diagnosing early
start-up code.
.TP
\fB\-\-modules\fR=\fImodule1.so,module2.so\fR
Load the comma-separated list of modules. Only used by the test
......@@ -196,6 +188,7 @@ Do not read
for the compositor. Avoids e.g. loading compositor modules via the
configuration file, which is useful for unit tests.
.TP
.TP
\fB\-\^S\fR\fIname\fR, \fB\-\-socket\fR=\fIname\fR
Weston will listen in the Wayland socket called
.IR name .
......@@ -203,13 +196,17 @@ Weston will export
.B WAYLAND_DISPLAY
with this value in the environment for all child processes to allow them to
connect to the right server automatically.
.TP
.BR \-\-version
Print the program version.
\fB\-\-wait-for-debugger\fR
Raises SIGSTOP before initializing the compositor. This allows the user to
attach with a debugger and continue execution by sending SIGCONT. This is
useful for debugging a crash on start-up when it would be inconvenient to
launch weston directly from a debugger. There is also a
.IR weston.ini " option to do the same."
.TP
\fB\-\-xwayland\fR
Support X11 clients through the Xwayland server.
.
.SS DRM backend options:
See
......@@ -355,13 +352,12 @@ Wayland clients will automatically use this.
.
.\" ***************************************************************
.SH BUGS
Bugs should be reported to the freedesktop.org bugzilla at
https://bugs.freedesktop.org with product "Wayland" and
component "weston".
Bugs should be reported to
.BR https://gitlab.freedesktop.org/wayland/weston/ "."
.
.\" ***************************************************************
.SH WWW
http://wayland.freedesktop.org/
https://wayland.freedesktop.org/
.
.\" ***************************************************************
.SH EXAMPLES
......