Go to file
Quentin Glidic d8b17bc452
share/cairo-util: Use wl_pointer_button_state enum directly
This silences two warnings:

clients/window.c:2450:20: warning: implicit conversion from enumeration
type 'enum wl_pointer_button_state' to different enumeration type 'enum
frame_button_state' [-Wenum-conversion]
                                              button, state);
                                                      ^~~~~

clients/window.c:2453:15: warning: implicit conversion from enumeration
type 'enum wl_pointer_button_state' to different enumeration type 'enum
frame_button_state' [-Wenum-conversion]
                                                button, state);
                                                        ^~~~~

Warning produced by Clang 3.8.

Signed-off-by: Quentin Glidic <sardemff7+git@sardemff7.net>
Reviewed-by: Giulio Camuffo <giuliocamuffo@gmail.com>
2016-09-24 11:52:56 +02:00
clients Revert "terminal: Fix crash due to race condition in init" 2016-09-09 19:53:38 +02:00
compositor Switch to use safe_strtoint instead of strtol 2016-08-06 18:19:22 -07:00
data data: Some client icons 2016-05-12 17:54:53 -07:00
desktop-shell desktop-shell: Add back the saved position and rotation for fullscreen/maximized 2016-09-07 12:21:09 +02:00
doc/doxygen doc: Correct absolute path in doxygen graphs. 2015-10-07 17:09:09 -07:00
fullscreen-shell fullscreen-shell: avoid access to freed data 2016-08-15 19:35:15 +02:00
ivi-shell libweston: Rename weston_surface::configure to ::committed 2016-08-14 09:28:50 +02:00
libweston share/cairo-util: Use wl_pointer_button_state enum directly 2016-09-24 11:52:56 +02:00
libweston-desktop libweston-desktop: Fix configure event for already well-sized surfaces 2016-09-14 10:07:43 +02:00
m4 build: Add (and use) an AC_SEARCH_LIBS wrapper 2016-04-25 13:37:10 +03:00
man Remove Raspberry Pi backend and renderer 2016-06-03 10:23:52 +03:00
protocol protocol: remove scaler.xml 2016-06-09 11:07:22 +03:00
shared share/cairo-util: Use wl_pointer_button_state enum directly 2016-09-24 11:52:56 +02:00
tests libweston: Rename weston_surface::configure to ::committed 2016-08-14 09:28:50 +02:00
tools/zunitc zunitc/junit-reporter: Silence pointer-sign warning 2016-09-24 11:46:36 +02:00
wcap include stdint.h for int32_t/uint32_t 2016-07-26 16:26:08 -07:00
xwayland share/cairo-util: Use wl_pointer_button_state enum directly 2016-09-24 11:52:56 +02:00
.gitignore Revert "clients: Add screensaver inhibitor client demo" 2016-08-30 12:04:05 -07:00
autogen.sh Update autotools configuration 2010-11-06 21:04:03 -04:00
configure.ac configure: Also update libweston version to match weston 2016-09-22 17:38:39 -07:00
COPYING COPYING: Specify origin of the library 2015-06-15 13:04:19 -07:00
Makefile.am Revert "compositor: Add public interface support for client-requested idle inhibition" 2016-08-30 12:05:01 -07:00
notes.txt notes: Don't manipulate lists while tranversing the list 2015-04-14 13:43:06 -07:00
README README: fix s/libwayland/libweston/ typo 2016-08-15 18:06:46 +02:00
releasing.txt releasing: Fix incorrect direction about how many lines need tweaked 2016-08-30 12:00:38 -07:00
weston.ini.in desktop-shell: make panel clock configurable 2016-03-10 14:58:16 -08:00

			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 http://wayland.freedesktop.org/building.html for building
weston and its dependencies.

The test suite can be invoked via `make check`; see
http://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
			=========

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
correctly implementing core Wayland protocols and interfacing with
input and output systems, so that people who just want to write a new
"Wayland window manager" (WM) or a small desktop environment (DE) can
focus on the WM part.

Libweston was first introduced in Weston 1.12, and is expected to
continue evolving through many Weston releases before it achieves a
stable API and feature completeness.


API/ABI (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/ABI and bump
the major version to signify that. For git snapshots of the master branch, the
API/ABI can break any time without warning.

Libweston major can be bumped only once during a development cycle. This should
happen on the first patch that breaks the API or ABI. Further breaks before the
next Weston major.0.0 release do not cause a bump. This means that libweston
API and ABI are allowed to break also after an alpha release, up to the final
release. However, breaks after alpha should be judged by the usual practices
for allowing minor features, fixes only, or critical fixes only.

To make things tolerable for libweston users despite API/ABI breakages,
different libweston major versions are designed to be perfectly
parallel-installable. This way external projects can easily depend on a
particular API/ABI-version. Thus they do not have to fight over which
ABI-version is installed in a user's system. This allows a user to install many
different compositors each requiring a different libweston ABI-version without
tricks or conflicts.

Note, that versions of Weston itself will not be parallel-installable,
only libweston is.

For more information about parallel installability, see
http://ometer.com/parallel.html


Versioning scheme
-----------------

In order to provide consistent, easy to use versioning, libweston
follows the rules in the Apache Portable Runtime Project
http://apr.apache.org/versioning.html.

The document provides the full details, with the gist summed below:
 - Major - backward incompatible changes.
 - Minor - new backward compatible features.
 - Patch - internal (implementation specific) fixes.

Weston and libweston have separate version numbers in configure.ac. All
releases are made by the Weston version number. Libweston version number
matches the Weston version number in all releases except maybe pre-releases.
Pre-releases have the Weston micro version 91 or greater.

A pre-release is allowed to install a libweston version greater than the Weston
version in case libweston major was bumped. In that case, the libweston version
must be Weston major + 1 and with minor and patch versions zero.

Pkg-config files are named after libweston major, but carry the Weston version
number. This means that Weston pre-release 2.1.91 may install libweston-3.pc
for the future libweston 3.0.0, but the .pc file says the version is still
2.1.91. When a libweston user wants to depend on the fully stable API and ABI
of a libweston major, he should use (e.g. for major 3):

	PKG_CHECK_MODULES(LIBWESTON, [libweston-3 >= 3.0.0])

Depending only on libweston-3 without a specific version number still allows
pre-releases which might have different API or ABI.


Forward compatibility
---------------------

Inspired by ATK, Qt and KDE programs/libraries, libjpeg-turbo, GDK,
NetworkManager, js17, lz4 and many others, libweston uses a macro to restrict
the API visible to the developer - REQUIRE_LIBWESTON_API_VERSION.

Note that different projects focus on different aspects - upper and/or lower
version check, default to visible/hidden old/new symbols and so on.

libweston aims to guard all newly introduced API, in order to prevent subtle
breaks that a simple recompile (against a newer version) might cause.

The macro is of the format 0x$MAJOR$MINOR and does not include PATCH version.
As mentioned in the Versioning scheme section, the latter does not reflect any
user visible API changes, thus should be not considered part of the API version.

All new symbols should be guarded by the macro like the example given below:

#if REQUIRE_LIBWESTON_API_VERSION >= 0x0101

bool
weston_ham_sandwich(void);

#endif

In order to use the said symbol, the one will have a similar code in their
configure.ac:

PKG_CHECK_MODULES(LIBWESTON, [libweston-1 >= 1.1])
AC_DEFINE(REQUIRE_LIBWESTON_API_VERSION, [0x0101])

If the user is _not_ interested in forward compatibility, they can use 0xffff
or similar high value. Yet doing so is not recommended.


Libweston design goals
----------------------

The high-level goal of libweston is to decouple the compositor from
the shell implementation (what used to be shell plugins).

Thus, instead of launching 'weston' with various arguments to choose the
shell, one would launch the shell itself, e.g. 'weston-desktop',
'weston-ivi', 'orbital', etc. The main executable (the hosting program)
will implement the shell, while libweston will be used for a fundamental
compositor implementation.

Libweston is also intended for use by other project developers who want
to create new "Wayland WMs".

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 ???

- weston-launch is still with libweston even though it can only launch
  Weston and nothing else. We would like to allow it to launch any compositor,
  but since it gives by design root access to input devices and DRM, how can
  we restrict it to intended programs?

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)

- fbdev-backend (depends on libudev...)

- rdp-backend (depends on freerdp)

- weston (the executable, not parallel-installable):
	+ desktop shell
	+ ivi-shell
	+ fullscreen shell
	+ weston-info, weston-terminal, etc. we install by default
	+ screen-share

- 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 major
ABI-versions (libweston-1.so, libweston-2.so, etc.), except those
explicitly mentioned.

Weston's build may not sanely allow this yet, but this is the
intention.