diff --git a/Makefile.am b/Makefile.am index 67670d3a..83bb2533 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1608,6 +1608,8 @@ SUFFIXES = .1 .5 .7 .man EXTRA_DIST += \ CONTRIBUTING.md \ + README.md \ + doc/wayland-screenshot.jpg \ doc/calibration-helper.bash \ man/weston.man \ man/weston-drm.man \ diff --git a/README b/README.md similarity index 69% rename from README rename to README.md index a0a078c4..d61b9322 100644 --- a/README +++ b/README.md @@ -1,33 +1,81 @@ - Weston - ====== - -Weston is the reference implementation of a Wayland compositor, and a -useful compositor in its own right. Weston has various backends that -lets it run on Linux kernel modesetting and evdev input as well as -under X11. Weston ships with a few example clients, from simple -clients that demonstrate certain aspects of the protocol to more -complete clients and a simplistic toolkit. There is also a quite -capable terminal emulator (weston-terminal) and an toy/example desktop -shell. Finally, weston also provides integration with the Xorg server -and can pull X clients into the Wayland desktop and act as an X window -manager. - -Refer to https://wayland.freedesktop.org/building.html for building -weston and its dependencies. - -The test suite can be invoked via `make check`; see -https://wayland.freedesktop.org/testing.html for additional details. - -Developer documentation can be built via `make doc`. Output will be in -the build root under - -docs/developer/html/index.html -docs/tools/html/index.html - - - - Libweston - ========= +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. + +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 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 a library. Libweston provides most of the boring and tedious bits of diff --git a/doc/wayland-screenshot.jpg b/doc/wayland-screenshot.jpg new file mode 100644 index 00000000..4d8f35c1 Binary files /dev/null and b/doc/wayland-screenshot.jpg differ