[PATCH weston 1/2] libweston: introduce LIBWESTON_API_VERSION macro

[Quentin Glidic]

On 15/08/2016 17:31, Emil Velikov wrote:
> From: Emil Velikov <emil.velikov at collabora.com>
>
> Provides some ease wrt constructing the required version.
>
> Cc: Quentin Glidic <sardemff7+git at sardemff7.net>
> Suggested-by: Quentin Glidic <sardemff7+git at sardemff7.net>
> Signed-off-by: Emil Velikov <emil.velikov at collabora.com>
> ---
>
> I've swapped ENCODE with API since it makes comparisons a lot better and
> it implies a full version including PATCH/MICRO. Yes, GTK/GDK does not
> have have it yet every project that has ENCODE macro on my system:
> cairo, pango, nm and json-glib does. Perhaps I have the wrong software
> installed for my grep search ;-)
 >
>  #if REQUIRED_foo >= foo(x,y)
>
> Can bring ENCODE back if people miss it.

SOMETHING_VERSION is often a macro defined to the actual installed 
version, while SOMETHING_ENCODE_VERSION clearly brings the meaning of 
its purpose.


> Having a look at the file...
>  - wasn't the file meant to be installed alongside the weston binary,
> since the latter exports symbols like Xorg and binaries depend on those.

Which binaries depend on it?


>  - alternatively should we just rename the defines to LIBWESTON_VERS...
>
> Personally I'm leaning that the following might be a good idea:
>  - move all the exports to libweston, make the compositor(s) expose as
> little symbols as possible. there's a few left in weston atm.
>  - use LIBWESTON_VERSION... unless there's (m)any open-source users
> that depend on the WESTON_VERSION... macros.
>
> I don't have a strong preference on the route taken, just some ideas.

I think it is fine for Weston-specific modules to use Weston-specific 
functions exported by Weston. But the less exported by Weston the better.

Cheers,


> ---
>  README                 | 16 +++++++++-------
>  libweston/version.h.in |  2 ++
>  2 files changed, 11 insertions(+), 7 deletions(-)
>
> diff --git a/README b/README
> index 37090d5..d0c8a64 100644
> --- a/README
> +++ b/README
> @@ -96,13 +96,14 @@ 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.
> +The macro must be compared against LIBWESTON_API_VERSION($MAJOR, $MINOR) and
> +does not include PATCH version. As mentioned in the Versioning scheme section,
> +PATCH 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
> +#if REQUIRE_LIBWESTON_API_VERSION >= LIBWESTON_API_VERSION(1,1)
>
>  bool
>  weston_ham_sandwich(void);
> @@ -113,10 +114,11 @@ In order to use the said symbol, the one will have a similar code in their
>  configure.ac:
>
>  PKG_CHECK_MODULES(LIBWAYLAND, [libwayland-1 >= 1.1])
> -AC_DEFINE(REQUIRE_LIBWESTON_API_VERSION, [0x0101])
> +AC_DEFINE(REQUIRE_LIBWESTON_API_VERSION, [LIBWESTON_API_VERSION(1,1)])
>
> -If the user is _not_ interested in forward compatibility, they can use 0xffff
> -or similar high value. Yet doing so is not recommended.
> +If the user is _not_ interested in forward compatibility, they can use high
> +value for MAJOR/MINOR - LIBWESTON_API_VERSION(99,99) or alike. Yet doing so is
> +not recommended.
>
>
>  Libweston design goals
> diff --git a/libweston/version.h.in b/libweston/version.h.in
> index b2379d0..892c5c4 100644
> --- a/libweston/version.h.in
> +++ b/libweston/version.h.in
> @@ -26,6 +26,8 @@
>  #ifndef WESTON_VERSION_H
>  #define WESTON_VERSION_H
>
> +#define LIBWESTON_API_VERSION(major,minor)   ((major) << 16 | (minor) << 8)
> +
>  #define WESTON_VERSION_MAJOR @WESTON_VERSION_MAJOR@
>  #define WESTON_VERSION_MINOR @WESTON_VERSION_MINOR@
>  #define WESTON_VERSION_MICRO @WESTON_VERSION_MICRO@
>


-- 

Quentin “Sardem FF7” Glidic