From 26b993749d0ea984d283973e2e5ed57eb1fcfb59 Mon Sep 17 00:00:00 2001
From: Drew DeVault <sir@cmpwn.com>
Date: Thu, 12 Apr 2018 21:29:45 -0400
Subject: Update README.md
---
README.md | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++-------------
1 file changed, 65 insertions(+), 17 deletions(-)
diff --git a/README.md b/README.md
index a0160ce9..d2d75227 100644
--- a/README.md
+++ b/README.md
@@ -1,49 +1,97 @@
# wlroots
-Pluggable, composable modules for building a
-[Wayland](http://wayland.freedesktop.org/) compositor.
+Pluggable, composable, unopinionated modules for building a
+[Wayland](http://wayland.freedesktop.org/) compositor; or about 40,000 lines of
+code you were going to write anyway.
-This is a WIP: [status](https://github.com/swaywm/wlroots/issues/9)
+- wlroots provides backends that abstract the underlying display and input
+ hardware, including KMS/DRM, libinput, Wayland, X11, and headless backends,
+ plus any custom backends you choose to write, which can all be created or
+ destroyed at runtime and used in concert with each other.
+- wlroots provides unopinionated, mostly standalone implementations of many
+ Wayland interfaces, both from wayland.xml and various protocol extensions.
+ We also promote the standardization of portable extensions across
+ many compositors.
+- wlroots provides an Xwayland abstraction that allows you to have excellent
+ Xwayland support without worrying about writing your own X11 window manager
+ on top of writing your compositor.
+- wlroots provides a renderer abstraction that simple compositors can use to
+ avoid writing GL code directly, but which steps out of the way when your
+ needs demand custom rendering code.
-## Contributing
+wlroots implements a huge variety of Wayland compositor features and implements
+them *right*, so you can focus on the features that make your compositor
+unique. By using wlroots, you get high performance, excellent hardware
+compatability, broad support for many wayland interfaces, and comfortable
+development tools - or any subset of these features you like, because all of
+them work independently of one another and freely compose with anything you want
+to implement yourself.
+
+**Status**: prior to 1.0 the API is not stable, but we've done most of the work
+and various projects are using wlroots to build Wayland compositors with.
-See [CONTRIBUTING.md](https://github.com/swaywm/wlroots/blob/master/CONTRIBUTING.md)
+wlroots is developed under the direction of the
+[sway](https://github.com/swaywm/sway) project. A variety of wrapper libraries
+[are available](https://github.com/swaywm) for using it with your favorite
+programming language.
## Building
Install dependencies:
+* meson
* wayland
* wayland-protocols
* EGL
* GLESv2
-* DRM
+* libdrm
* GBM
* libinput
+* xkbcommon
* udev
* pixman
* systemd (optional, for logind support)
* elogind (optional, for logind support on systems without systemd)
* libcap (optional, for capability support)
-* asciidoc (optional, for man pages)
+
+If you choose to enable X11 support:
+
+* xkb
+* xkb-composite
+* xkb-xfixes
+* xkb-image
+* xkb-render
+* x11-xcb
+* xcb-errors (optional, for improved error reporting)
+* x11-icccm (optional, for improved Xwayland introspection)
+* xkb-xcb (optional, for improved keyboard handling on the X11 backend)
Run these commands:
meson build
ninja -C build
-(On FreeBSD, you need to pass an extra flag to prevent a linking error: `meson build -D b_lundef=false`)
+On FreeBSD, you need to pass an extra flag to prevent a linking error:
+`meson build -D b_lundef=false`.
-## Running the Reference Compositor
+Install like so:
-wlroots comes with a reference compositor called rootston that demonstrates the
-features of the library.
+ sudo ninja -C build install
-After building, run rootston from a terminal or VT with:
+## Running the test compositor
- ./build/rootston/rootston
+wlroots comes with a test compositor called rootston, which demonstrates the
+features of the library and is used as a testbed for the development of the
+library. It may also be useful as a reference for understanding how to use
+various wlroots features.
+
+If you followed the build instructions above the rootston executable can be
+found at `./build/rootston/rootston`. To use it, refer to the example config at
+[./rootston/rootston.ini.example](https://github.com/swaywm/wlroots/blob/master/rootston/rootston.ini.example)
+and place a config file of your own at `rootston.ini` in the working directory
+(or in an arbitrary location via `rootston -C`). Other options are available,
+refer to `rootston -h`.
+
+## Contributing
-Now you can run windows in the compositor from the command line or by
-configuring bindings in your
-[`rootston.ini`](https://github.com/swaywm/wlroots/blob/master/rootston/rootston.ini.example)
-file.
+See [CONTRIBUTING.md](https://github.com/swaywm/wlroots/blob/master/CONTRIBUTING.md).
--
cgit v1.2.3