On Mon, 6 Aug 2018 12:09:22 +0100 Daniel Stone <dani...@collabora.com> wrote:
> 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. Hi, here could be a note about where the screenshot is from, so one could track it's author and copyright if necessary, or at least keep it not any more vague than it already was. > > Signed-off-by: Daniel Stone <dani...@collabora.com> > Reviewed-by: Quentin Glidic <sardemff7+...@sardemff7.net> > --- > Makefile.am | 2 + > README => README.md | 108 ++++++++++++++++++++++++++----------- > doc/wayland-screenshot.jpg | Bin 0 -> 143832 bytes > 3 files changed, 80 insertions(+), 30 deletions(-) > rename README => README.md (70%) > create mode 100644 doc/wayland-screenshot.jpg > > diff --git a/Makefile.am b/Makefile.am > index 67670d3ad..83bb25339 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 70% > rename from README > rename to README.md > index a0a078c46..11ed7b3ca 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. A thought: should we have some words about how weston aims for production quality for non-desktop use cases? I think that is what the above paragraph is trying to say. > + > +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 commit of Weston is built using GitLab CI. > +[Reading the configuration](.gitlab-ci.yml) may provide a useful example of > how > +to build and install Weston. Btw. do we actually have it building every commit rather than every push? Anyway, this patch is: Reviewed-by: Pekka Paalanen <pekka.paala...@collabora.co.uk> Thanks, pq > + > +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
pgpCQ8x445LDD.pgp
Description: OpenPGP digital signature
_______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/wayland-devel