[PATCH wayland v3 1/3] introduce new headers wayland-client-core.h and wayland-server-core.h

[Pekka Paalanen]

On Wed, 29 Apr 2015 16:34:47 +0300
Giulio Camuffo <giuliocamuffo at gmail.com> wrote:

> wayland-client.h and wayland-server.h include the protocol headers generated
> at build time. This means that a libwayland user cannot generate and use
> protocol code created from a wayland.xml newer than the installed libwayand,
> because it is not possible to only include the API header.
> Another use case is language bindings, which would generate their own protocol
> code and which only need to use the library ABI, not the C generated code.
> This commit adds wayland-client-core.h and wayland-server-core.h which do not
> include the protocol headers and any deprecated code.
> ---
> 
> v3: - added the new headers for the docs generation
>     - added a comment in the old headers saying to use the new ones
> 
>  Makefile.am               |   2 +
>  doc/doxygen/Makefile.am   |   7 +-
>  src/wayland-client-core.h | 180 +++++++++++++++++++++
>  src/wayland-client.h      | 160 +-----------------
>  src/wayland-server-core.h | 405 ++++++++++++++++++++++++++++++++++++++++++++++
>  src/wayland-server.h      | 384 ++-----------------------------------------
>  6 files changed, 610 insertions(+), 528 deletions(-)
>  create mode 100644 src/wayland-client-core.h
>  create mode 100644 src/wayland-server-core.h

Okay. To get a good look on what changed in docs and all, I build both
without and with this patch, and did a 'make install DESTDIR=...' to
different empty directories, then diffed those.

I see we are generating a man page for wl_object, whose content is a
bit... unhelpful. I only noticed because it changes a bit.


> diff --git a/src/wayland-client.h b/src/wayland-client.h
> index 71cd822..37b0d7f 100644
> --- a/src/wayland-client.h
> +++ b/src/wayland-client.h

>  
> -/** \class wl_event_queue
> - *
> - * \brief A queue for \ref wl_proxy object events.
> - *
> - * Event queues allows the events on a display to be handled in a thread-safe
> - * manner. See \ref wl_display for details.
> - *
> +/** Use of this header file is discouraged. Prefer including
> + *  wayland-client-core.h instead, which does not include the
> + *  client protocol header and as such only defines the library
> + *  API.
>   */

This Doxygen style comment accidentally gets associated with wl_object,
which causes the docs to have headings like: "wl_object - Use of this
header file is discouraged."

Let's fix those in a follow-up, I want this big change in before the
alpha.


> diff --git a/src/wayland-server.h b/src/wayland-server.h
> index af2f03d..9fe19f5 100644
> --- a/src/wayland-server.h
> +++ b/src/wayland-server.h
> @@ -20,249 +20,22 @@
>   * OF THIS SOFTWARE.
>   */
>  
> +
> +/** Use of this header file is discouraged. Prefer including
> + *  wayland-server-core.h instead, which does not include the
> + *  client protocol header and as such only defines the library
> + *  API, excluding the deprecated API below.
> + */

This too... I think this is the one that hits wl_object, not the above.

> +
>  #ifndef WAYLAND_SERVER_H
>  #define WAYLAND_SERVER_H
>  
> +#include "wayland-server-core.h"
> +
>  #ifdef  __cplusplus
>  extern "C" {
>  #endif
>  
> -#include <sys/types.h>
> -#include <stdint.h>
> -#include "wayland-util.h"
> -#include "wayland-version.h"

The diffs look good otherwise. With my and Jason's R-b, pushed.
   70d3c0f..d74a9c0  master -> master


Thanks,
pq