On 7/14/18 3:09 PM, Daniel Stone wrote:
Move the README file to Markdown, and update it to attempt to explain
the current status and use of Weston.
From patch 1:
> The patch is a single logical change. If the commit message addresses
> multiple points, it is a hint that the commit might need splitting up.
Ultimately, I’d split the markdown move to its own commit, but I’m
probably nitpicky here.
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.
Signed-off-by: Daniel Stone <dani...@collabora.com>
---
README => README.md | 108 ++++++++++++++++++++++++++-----------
doc/wayland-screenshot.jpg | Bin 0 -> 143832 bytes
2 files changed, 78 insertions(+), 30 deletions(-)
rename README => README.md (69%)
create mode 100644 doc/wayland-screenshot.jpg
diff --git a/README b/README.md
similarity index 69%
rename from README
rename to README.md
index a0a078c46..404859548 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
+======
+
+
+
+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 partly-featured 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 and provide their own full-featured environments.
That’s way too full of features, don’t you think? :-)
Then, all four patches are:
Reviewed-by: Quentin Glidic <sardemff7+...@sardemff7.net>
(With or without the split.)
Thanks,
+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. The core compositor's performance should always be predictable and
+measurable.
+
+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.
+
+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
[snip]
--
Quentin “Sardem FF7” Glidic
_______________________________________________
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/wayland-devel
