Repository files navigation

Weston is the reference implementation of a Wayland compositor, as well as auseful environment in and of itself.

Out of the box, Weston provides a very basic desktop, or a full-featuredenvironment for non-desktop uses such as automotive, embedded, in-flight,industrial, kiosks, set-top boxes and TVs. It also provides a library allowingother projects to build their own full-featured environments on top of Weston'score.

The core focus of Weston is correctness and reliability. Weston aims to be leanand fast, but more importantly, to be predictable. Whilst Weston does have knownbugs and shortcomings, we avoid unknown or variable behaviour as much aspossible, including variable performance such as occasional spikes in framedisplay time.

A small suite of example or demo clients are also provided: though they can beuseful in themselves, their main purpose is to be an example or test case forothers building compositors or clients.

If you are after a more mainline desktop experience, theGNOME andKDE projects providefull-featured desktop environments built on the Wayland protocol. Many otherprojects also exist providing Wayland clients and desktop environments: you arenot limited to just what you can find in Weston.

Weston's development ishosted on freedesktop.org GitLab.Please also seethe contributing document, which details howto make code or non-technical contributions to Weston.

Weston is built usingMeson. Weston often dependson the current release versions ofWayland andwayland-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 allfeatures enabled, which means you likely hit missing dependencies on the firsttry. If a dependency is avoidable through a build option, the error messageshould tell you what option can be used to avoid it. You may need to disableseveral 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 ..

Themeson command populates the build directory. This step canfail due to missing dependencies. Any build options you want can be added onthat line, e.g.meson build/ --prefix=... -Ddemo-clients=false. All the buildoptions can be found in the filemeson_options.txt.

Once the build directory has been successfully populated, you can inspect theconfiguration withmeson configure build/. If you need to change anoption, you can do e.g.meson configure build/ -Ddemo-clients=false.

Every push to the Weston master repository and its forks is built using GitLabCI.Reading the configuration may provide a useful example ofhow to build and install Weston.

Moredetailed documentation on building Westonis available on the Wayland site. There are also more details onhow to run and write tests.

For building the documentation seeweston-doc.

Once Weston is installed, most users can simply run it by typingweston. Thiswill launch Weston inside whatever environment you launch it from: when launchedfrom a text console, it will take over that console. When launched from insidean existing Wayland or X11 session, it will start a 'nested' instance of Westoninside a window in that session.

Help is available by runningweston --help, orman weston, which will listthe available configuration options and display backends. It can also beconfigured through a file on disk; more information on this can be found throughman weston.ini.

In some special cases, such as when running remotely or without logind's sessioncontrol, Weston may not be able to run directly from a text console. In thesesituations, you can instead execute theweston-launch helper, which will gainprivileged access to input and output devices by running as root, then grantingaccess to the main Weston binary running as your user. Running Weston this wayis not recommended unless necessary.

For documenting weston we usesphinxtogether withbreathe thatunderstands XMLs databases generated by doxygen. So far, this is a compromiseuntil better tools are available in order to remove the doxygendependency. You should be able to install both sphinx and breathe extensionusing pip3 command, or your package manager.Doxygen should be available using your distribution package manager.

Once those are set-up, runmeson with-Ddoc=true option in order to enablebuilding the documentation. Installation will place the documentation in theprefix's path under datadir (i.e.,share/doc).

For re-generating the documentation a specialdocs target has been added.Although first time you build (and subsequently install) weston, you'll see thedocumentation being built, updates to the spinx documentation files or to thesource files will only be updated when usingdocs 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 underdoc/sphinx/ directory or by modifying the source code using doxygendirectives.

Libweston is an effort to separate the re-usable parts of Weston intoa library. Libweston provides most of the boring and tedious bits ofcorrectly implementing core Wayland protocols and interfacing withinput and output systems, so that people who just want to write a new"Wayland window manager" (WM) or a small desktop environment (DE) canfocus on the WM part.

Libweston was first introduced in Weston 1.12, and is expected tocontinue evolving through many Weston releases before it achieves astable API and feature completeness.

Libweston's primary purpose is exporting an API for creating Waylandcompositors. Libweston's secondary purpose is to export the weston_config APIso that third party plugins and helper programs can readweston.ini if theywant to. However, these two scopes are orthogonal and independent. At no pointwill the compositor functionality use or depend on the weston_configfunctionality.

As libweston's API surface is huge, it is impossible to get it rightin one go. Therefore developers reserve the right to break the API/ABI and bumpthe major version to signify that. For git snapshots of the master branch, theAPI/ABI can break any time without warning.

Libweston major can be bumped only once during a development cycle. This shouldhappen on the first patch that breaks the API or ABI. Further breaks before thenext Weston major.0.0 release do not cause a bump. This means that libwestonAPI and ABI are allowed to break also after an alpha release, up to the finalrelease. However, breaks after alpha should be judged by the usual practicesfor 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 perfectlyparallel-installable. This way external projects can easily depend on aparticular API/ABI-version. Thus they do not have to fight over whichABI-version is installed in a user's system. This allows a user to install manydifferent compositors each requiring a different libweston ABI-version withouttricks or conflicts.

Note, that versions of Weston itself will not be parallel-installable,only libweston is.

For more information about parallel installability, seehttp://ometer.com/parallel.html

In order to provide consistent, easy to use versioning, libwestonfollows the rules in the Apache Portable Runtime Projecthttp://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. Allreleases are made by the Weston version number. Libweston version numbermatches 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 Westonversion in case libweston major was bumped. In that case, the libweston versionmust be Weston major + 1.

Pkg-config files are named after libweston major, but carry the Weston versionnumber. This means that Weston pre-release 2.1.91 may install libweston-3.pcfor the future libweston 3.0.0, but the .pc file says the version is still2.1.91. When a libweston user wants to depend on the fully stable API and ABIof 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 allowspre-releases which might have different API or ABI.

Inspired by ATK, Qt and KDE programs/libraries, libjpeg-turbo, GDK,NetworkManager, js17, lz4 and many others, libweston uses a macro to restrictthe API visible to the developer - REQUIRE_LIBWESTON_API_VERSION.

Note that different projects focus on different aspects - upper and/or lowerversion check, default to visible/hidden old/new symbols and so on.

libweston aims to guard all newly introduced API, in order to prevent subtlebreaks 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 anyuser 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 >= 0x0101boolweston_ham_sandwich(void);#endif

In order to use the said symbol, the one will have a similar code in theirconfigure.ac:

PKG_CHECK_MODULES(LIBWESTON, [libweston-1 >= 1.1])AC_DEFINE(REQUIRE_LIBWESTON_API_VERSION, [0x0101])

If the user isnot interested in forward compatibility, they can use 0xffffor similar high value. Yet doing so is not recommended.

The high-level goal of libweston is to decouple the compositor fromthe shell implementation (what used to be shell plugins).

Thus, instead of launching 'weston' with various arguments to choose theshell, 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 fundamentalcompositor implementation.

Libweston is also intended for use by other project developers who wantto 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 alllibweston options. Libweston should not have user settable optionsthat would work behind the hosting program's back, except perhapsdebugging features and such.

• Signal handling will be outside of libweston.

• Child process execution and management will be outside of libweston.

• The different backends (drm, fbdev, x11, etc) will be an internaldetail of libweston. Libweston will not support third partybackends. However, hosting programs need to handlebackend-specific configuration due to differences in behaviour andavailable features.

• Renderers will be libweston internal details too, though again thehosting program may affect the choice of renderer if the backendallows, and maybe set renderer-specific options.

• plugin design ???

• xwayland ???

• weston-launch is still with libweston even though it can only launchWeston and nothing else. We would like to allow it to launch any compositor,but since it gives by design root access to input devices and DRM, how canwe restrict it to intended programs?

There are still many more details to be decided.

Always build Weston with --with-cairo=image.

The Weston project is (will be) intended to be split into severalbinary packages, each with its own dependencies. The maximal splitwould 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)

• fbdev-backend (depends on libudev...)

• rdp-backend (depends on freerdp)

• weston (the executable, not parallel-installable):

  • desktop shell
  • ivi-shell
  • fullscreen shell
  • weston-info (deprecated), 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 bydefault

• and possibly more...

Everything should be parallel-installable across libweston majorABI-versions (libweston-1.so, libweston-2.so, etc.), except thoseexplicitly mentioned.

Weston's build may not sanely allow this yet, but this is theintention.