[PATCH weston] README: introduce libweston

[Bryce Harrington]

On Tue, Jul 14, 2015 at 01:07:47PM +0300, Pekka Paalanen wrote:
> From: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
> 
> What is libweston and where do we intend to go with it.
> 
> Cc: Giulio Camuffo <giuliocamuffo at gmail.com>
> Signed-off-by: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
> ---
>  README | 139 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
>  1 file changed, 138 insertions(+), 1 deletion(-)
> 
> diff --git a/README b/README
> index 3821e5d..beab3df 100644
> --- a/README
> +++ b/README
> @@ -1,4 +1,5 @@
> -Weston
> +			Weston
> +			======
>  
>  Weston is the reference implementation of a Wayland compositor, and a
>  useful compositor in its own right.  Weston has various backends that
> @@ -16,3 +17,139 @@ weston and its dependencies.
>  
>  The test suite can be invoked via `make check`; see
>  http://wayland.freedesktop.org/testing.html for additional details.
> +
> +
> +
> +			Libweston
> +			=========
> +
> +Writing a full-fledged Wayland compositor from scratch is lots of
> +work. Libweston is an effort to separate the re-usable parts of Weston
> +into a library. Libweston's aim is to provide most of the boring and
> +tedious bits of correctly implementing core Wayland protocols and
> +interfacing with input and output systems, so that people who just
> +want to write a new "Wayland WM" or a small DE can focus on the WM
> +part.

Drop the first sentence; it's just stating the obvious, and the piece
reads better if it starts with a declaration of what it is.

The last sentence is a bit long.  Maybe if it started with "Libweston
provides..." it'd help eliminate some extraneous words.

The final statement of who libweston's target audience is really good.
Make sure to define the 'WM' acronym here, though.

> +The libweston effort started landing on the Weston 1.9 development
> +cycle, and is expected to continue through many Weston releases
> +towards a stable API and feature completeness.

"effort started landing" sounds weird.  Also, I suspect you meant to
emphasize that its still experimental, as a transition to the next
section on API stability.  How about just:

libweston was first introduced in Weston 1.9, and is expected to
continue evolving through many Weston releases until it one day achieves
a stable API and feature completeness.

> +
> +
> +API (in)stability and parallel installability
> +---------------------------------------------
> +
> +As libweston's API surface is huge, it is impossible to get it right
> +in one go. Therefore developers reserve the right to break the API
> +between every 1.x.0 Weston release (minor version bumps), just like
> +Weston's plugin API does. For git snapshots of the master branch, the
> +API can break any time without any warning or any version bumps.

I think "without warning or version bump" might be grammatically better.

> +
> +Libweston API or ABI will not be broken between Weston's stable
> +releases 1.x.0 and 1.x.y, where y < 90.
> +
> +To make things tolerable for libweston users in spite of ABI

s/in spite of/despite/ ?  (not sure)

> +breakages, libweston is designed to be perfectly parallel-installable.
> +An ABI-version is defined for libweston, and it is bumped for releases
> +as needed. Different ABI-versions of libweston can be installed in
> +parallel, so that external projects can easily depend on a particular
> +ABI-version, and they do not have to fight over which ABI-version is
> +installed in a user's system.
> +
> +Note, that versions of Weston itself will not be parallel-installable,
> +only libweston is.

Do we need to give more of an explanation of what "parallel-installable"
means, or can we expect our audience to generally know?  Perhaps a short
example file listing would be illustrative.

> +
> +Libweston design goals
> +----------------------
> +
> +The high-level goal of libweston is that what used to be shell plugins
> +will be main executables. Instead of launching 'weston' with various
> +arguments to choose the shell, one would be launching
> +'weston-desktop', 'weston-ivi', 'orbital', etc. The main executable
> +(the hosting program) links to libweston for a fundamental compositor
> +implementation. Libweston is also intended for use by other projects
> +who want to create new "Wayland WMs".
> +
> +The libweston API/ABI will be separating the shell logic and main
> +program from the rest of the "Weston compositor" (libweston
> +internals).
> +
> +Details:
> +
> +- All configuration and user interfaces will be outside of libweston.
> +  This includes command line parsing, configuration files, and runtime
> +  (graphical) UI.
> +
> +- The hosting program (main executable) will be in full control of all
> +  libweston options. Libweston should not have user settable options
> +  that would work behind the hosting program's back, except perhaps
> +  debugging features and such.
> +
> +- Signal handling will be outside of libweston.
> +
> +- Child process execution and management will be outside of libweston.
> +
> +- The different backends (drm, fbdev, x11, etc) will be an internal
> +  detail of libweston. Libweston will not support third party
> +  backends. However, hosting programs need to handle
> +  backend-specific configuration due to differences in behaviour and
> +  available features.
> +
> +- Renderers will be libweston internal details too, though again the
> +  hosting program may affect the choice of renderer if the backend
> +  allows, and maybe set renderer-specific options.
> +
> +- plugin design ???
> +
> +- xwayland ???
> +
> +There are still many more details to be decided.
> +
> +
> +For packagers
> +-------------
> +
> +Always build Weston with --with-cairo=image.
> +
> +The Weston project is (will be) intended to be split into several
> +binary packages, each with its own dependencies. The maximal split
> +would be roughly like this:
> +
> +- libweston (minimal dependencies):
> +	+ headless backend
> +	+ wayland backend
> +
> +- gl-renderer (depends on GL libs etc.)
> +
> +- drm-backend (depends on libdrm, libgbm, libudev, libinput, ...)
> +
> +- x11-backend (depends of X11/xcb libs)
> +
> +- xwayland (depends on X11/xcb libs)
> +
> +- rpi-backend (depends on DispmanX, libudev, ...)
> +
> +- fbdev-backend (depends on libudev...)
> +
> +- rdp-backend (depends on freerdp)
> +	+ screen-share
> +
> +- weston (the executable, not parallel-installable):
> +	+ desktop shell
> +	+ ivi-shell
> +	+ fullscreen shell
> +	+ weston-info, weston-terminal, etc. we install by default
> +
> +- weston demos (not parallel-installable)
> +	+ weston-simple-* programs
> +	+ possibly all the programs we build but do not install by
> +	  default
> +
> +- and possibly more...
> +
> +Everything should be parallel-installable across libweston
> +ABI-versions, except those explicitly mentioned.
> +
> +Weston's build may not sanely allow this yet, but this is the
> +intention.

Overall, very good declaration of intent for libweston and gives
definitive answers to some of the questions that have been floating
about.  Apart from the trivial copyedits above, the scope and
development approach sounds good to me:

Reviewed-by: Bryce Harrington <bryce at osg.samsung.com>