README: Move to Markdown, rewrite introduction

Move the README file to Markdown, and update it to attempt to explain
the current status and use of Weston.

The first sections are user-facing, so they can quickly understand what
Weston is, what it does, what it doesn't do, and how to go about using
it. The following sections on libweston and for distribution packagers
are left intact, but should probably be moved to separate documents.

This includes a screenshot of Weston running weston-terminal, Chrome and
simple-egl, which was taken by myself and subject to the same licensing
terms as the rest of the tree.

Signed-off-by: Daniel Stone <daniels@collabora.com>
Reviewed-by: Quentin Glidic <sardemff7+git@sardemff7.net>
Reviewed-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
dev
Daniel Stone 6 years ago
parent 3a6fa200b7
commit f987cb98ef
  1. 2
      Makefile.am
  2. 108
      README.md
  3. BIN
      doc/wayland-screenshot.jpg

@ -1608,6 +1608,8 @@ SUFFIXES = .1 .5 .7 .man
EXTRA_DIST += \ EXTRA_DIST += \
CONTRIBUTING.md \ CONTRIBUTING.md \
README.md \
doc/wayland-screenshot.jpg \
doc/calibration-helper.bash \ doc/calibration-helper.bash \
man/weston.man \ man/weston.man \
man/weston-drm.man \ man/weston-drm.man \

@ -1,33 +1,81 @@
Weston Weston
====== ======
Weston is the reference implementation of a Wayland compositor, and a ![screenshot of skeletal Weston desktop](doc/wayland-screenshot.jpg)
useful compositor in its own right. Weston has various backends that
lets it run on Linux kernel modesetting and evdev input as well as Weston is the reference implementation of a Wayland compositor, as well as a
under X11. Weston ships with a few example clients, from simple useful environment in and of itself.
clients that demonstrate certain aspects of the protocol to more
complete clients and a simplistic toolkit. There is also a quite Out of the box, Weston provides a very basic desktop, or a full-featured
capable terminal emulator (weston-terminal) and an toy/example desktop environment for non-desktop uses such as automotive, embedded, in-flight,
shell. Finally, weston also provides integration with the Xorg server industrial, kiosks, set-top boxes and TVs. It also provides a library allowing
and can pull X clients into the Wayland desktop and act as an X window other projects to build their own full-featured environments on top of Weston's
manager. core.
Refer to https://wayland.freedesktop.org/building.html for building The core focus of Weston is correctness and reliability. Weston aims to be lean
weston and its dependencies. 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
The test suite can be invoked via `make check`; see possible, including variable performance such as occasional spikes in frame
https://wayland.freedesktop.org/testing.html for additional details. display time.
Developer documentation can be built via `make doc`. Output will be in A small suite of example or demo clients are also provided: though they can be
the build root under useful in themselves, their main purpose is to be an example or test case for
others building compositors or clients.
docs/developer/html/index.html
docs/tools/html/index.html 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
Libweston 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 autotools, with `autogen.sh` and `make`. It 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).
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).
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`.
In some special cases, such as when running remotely or without logind's session
control, Weston may not be able to run directly from a text console. In these
situations, you can instead execute the `weston-launch` helper, which will gain
privileged access to input and output devices by running as root, then granting
access to the main Weston binary running as your user. Running Weston this way
is not recommended unless necessary.
Libweston
=========
Libweston is an effort to separate the re-usable parts of Weston into 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 a library. Libweston provides most of the boring and tedious bits of

Binary file not shown.

After

Width:  |  Height:  |  Size: 140 KiB

Loading…
Cancel
Save