[glib/wip/version-bounds: 2/4] gmacros: Add flexible API version boundaries

[Emmanuele Bassi <ebassi src gnome org>]

commit 05660f4aa61f78247ba4ca4fde373335926aa908
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Mon Feb 20 16:20:15 2012 +0000

    gmacros: Add flexible API version boundaries
    
    There are cases when it should be possible to define at compile time
    what range of functions and types should be used, in order to get,
    or restrict, the compiler warnings for deprecated or newly added
    types or functions.
    
    For instance, if GLib introduces a deprecation warning on a type in
    version 2.32, application code can decide to specify the minimum and
    maximum boundary of the used API to be 2.30; when compiling against
    a new version of GLib, this would produce the following results:
    
      - all deprecations introduced prior to 2.32 would emit compiler
        warnings when used by the application code;
      - all deprecations introduced in 2.32 would not emit compiler
        warnings when used by the application code;
      - all new symbols introduced in 2.32 would emit a compiler warning.
    
    Using this scheme it should be possible to have fairly complex
    situations, like the following one:
    
      assuming that an application is compiled with:
        GLIB_VERSION_MIN_REQUIRED = GLIB_VERSION_2_30
        GLIB_VERSION_MAX_ALLOWED  = GLIB_VERSION_2_32
    
      and a GLib header containing:
    
        void function_A (void) GLIB_DEPRECATED_IN_2_26;
        void function_B (void) GLIB_DEPRECATED_IN_2_28;
        void function_C (void) GLIB_DEPRECATED_IN_2_30;
        void function_D (void) GLIB_AVAILABLE_IN_2_32;
        void function_E (void) GLIB_AVAILABLE_IN_2_34;
    
      any application code using the above functions will get the following
      compiler warnings:
    
        function_A: deprecated symbol warning
        function_B: deprecated symbol warning
        function_C: no warning
        function_D: no warning
        function_E: undefined symbol warning
    
    This means that it should be possible to gradually port code towards
    non-deprecated API gradually, on a per-release basis.

 glib/gmacros.h |  145 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 145 insertions(+), 0 deletions(-)
---
diff --git a/glib/gmacros.h b/glib/gmacros.h
index bfa7b4c..04f6c0c 100644
--- a/glib/gmacros.h
+++ b/glib/gmacros.h
@@ -321,6 +321,95 @@
 #define G_DEPRECATED_FOR(f) G_DEPRECATED
 #endif
 
+#define G_ENCODE_VERSION(major,minor)   ((major) << 16 | (minor) << 8)
+
+/**
+ * GLIB_VERSION_2_26:
+ *
+ * A macro that evaluates to the 2.26 version of GLib, in a format
+ * that can be used by the C pre-processor.
+ *
+ * Since: 2.32
+ */
+#define GLIB_VERSION_2_26       (G_ENCODE_VERSION (2, 26))
+
+/**
+ * GLIB_VERSION_2_28:
+ *
+ * A macro that evaluates to the 2.28 version of GLib, in a format
+ * that can be used by the C pre-processor.
+ *
+ * Since: 2.32
+ */
+#define GLIB_VERSION_2_28       (G_ENCODE_VERSION (2, 28))
+
+/**
+ * GLIB_VERSION_2_30:
+ *
+ * A macro that evaluates to the 2.30 version of GLib, in a format
+ * that can be used by the C pre-processor.
+ *
+ * Since: 2.32
+ */
+#define GLIB_VERSION_2_30       (G_ENCODE_VERSION (2, 30))
+
+/**
+ * GLIB_VERSION_2_32:
+ *
+ * A macro that evaluates to the 2.32 version of GLib, in a format
+ * that can be used by the C pre-processor.
+ *
+ * Since: 2.32
+ */
+#define GLIB_VERSION_2_32       (G_ENCODE_VERSION (2, 32))
+
+/**
+ * GLIB_VERSION_MIN_REQUIRED:
+ *
+ * A macro that should be defined by the user prior to including
+ * the glib.h header.
+ *
+ * This macro defines the lower bound for the GLib API to use.
+ *
+ * If a function has been deprecated in a newer version of GLib,
+ * it is possible to use this symbol to avoid the compiler warnings
+ * without disabling warning for every deprecated function.
+ *
+ * Since: 2.32
+ */
+#ifndef GLIB_VERSION_MIN_REQUIRED
+# define GLIB_VERSION_MIN_REQUIRED      (G_ENCODE_VERSION (2, 30))
+#endif
+
+/**
+ * GLIB_VERSION_MAX_ALLOWED:
+ *
+ * A macro that should be defined by the user prior to including
+ * the glib.h header.
+ *
+ * This macro defines the upper bound for the GLib API to use.
+ *
+ * If a function has been introduced in a newer version of GLib,
+ * it is possible to use this symbol to get compiler warnings when
+ * trying to use that function.
+ *
+ * Since: 2.32
+ */
+#ifndef GLIB_VERSION_MAX_ALLOWED
+# if GLIB_VERSION_MIN_REQUIRED > GLIB_VERSION_2_30
+#  define GLIB_VERSION_MAX_ALLOWED      GLIB_VERSION_MIN_REQUIRED
+# else
+#  define GLIB_VERSION_MAX_ALLOWED      GLIB_VERSION_2_30
+# endif
+#endif
+
+/* sanity checks */
+#if GLIB_VERSION_MAX_ALLOWED < GLIB_VERSION_MIN_REQUIRED
+#error "GLIB_VERSION_MAX_ALLOWED must be >= GLIB_VERSION_MIN_REQUIRED"
+#endif
+#if GLIB_VERSION_MIN_REQUIRED < GLIB_VERSION_2_26
+#error "GLIB_VERSION_MIN_REQUIRED must be >= GLIB_VERSION_2_26"
+#endif
 
 /* These macros are used to mark deprecated functions in GLib headers,
  * and thus have to be exposed in installed headers. But please
@@ -336,4 +425,60 @@
 #define GLIB_DEPRECATED_FOR(f) G_DEPRECATED_FOR(f)
 #endif
 
+#if GLIB_VERSION_MIN_REQUIRED >= GLIB_VERSION_2_26
+# define GLIB_DEPRECATED_IN_2_26                GLIB_DEPRECATED
+# define GLIB_DEPRECATED_IN_2_26_FOR(f)         GLIB_DEPRECATED_FOR(f)
+#else
+# define GLIB_DEPRECATED_IN_2_26
+# define GLIB_DEPRECATED_IN_2_26_FOR(f)
+#endif
+
+#if GLIB_VERSION_MAX_ALLOWED < GLIB_VERSION_2_26
+# define GLIB_AVAILABLE_IN_2_26                 G_GNUC_UNAVAILABLE
+#else
+# define GLIB_AVAILABLE_IN_2_26
+#endif
+
+#if GLIB_VERSION_MIN_REQUIRED >= GLIB_VERSION_2_28
+# define GLIB_DEPRECATED_IN_2_28                GLIB_DEPRECATED
+# define GLIB_DEPRECATED_IN_2_28_FOR(f)         GLIB_DEPRECATED_FOR(f)
+#else
+# define GLIB_DEPRECATED_IN_2_28
+# define GLIB_DEPRECATED_IN_2_28_FOR(f)
+#endif
+
+#if GLIB_VERSION_MAX_ALLOWED < GLIB_VERSION_2_28
+# define GLIB_AVAILABLE_IN_2_28                 G_GNUC_UNAVAILABLE
+#else
+# define GLIB_AVAILABLE_IN_2_28
+#endif
+
+#if GLIB_VERSION_MIN_REQUIRED >= GLIB_VERSION_2_30
+# define GLIB_DEPRECATED_IN_2_30                GLIB_DEPRECATED
+# define GLIB_DEPRECATED_IN_2_30_FOR(f)         GLIB_DEPRECATED_FOR(f)
+#else
+# define GLIB_DEPRECATED_IN_2_30
+# define GLIB_DEPRECATED_IN_2_30_FOR(f)
+#endif
+
+#if GLIB_VERSION_MAX_ALLOWED < GLIB_VERSION_2_30
+# define GLIB_AVAILABLE_IN_2_30                 G_GNUC_UNAVAILABLE
+#else
+# define GLIB_AVAILABLE_IN_2_30
+#endif
+
+#if GLIB_VERSION_MIN_REQUIRED >= GLIB_VERSION_2_32
+# define GLIB_DEPRECATED_IN_2_32                GLIB_DEPRECATED
+# define GLIB_DEPRECATED_IN_2_32_FOR(f)         GLIB_DEPRECATED_FOR(f)
+#else
+# define GLIB_DEPRECATED_IN_2_32
+# define GLIB_DEPRECATED_IN_2_32_FOR(f)
+#endif
+
+#if GLIB_VERSION_MAX_ALLOWED < GLIB_VERSION_2_32
+# define GLIB_AVAILABLE_IN_2_32                 G_GNUC_UNAVAILABLE
+#else
+# define GLIB_AVAILABLE_IN_2_32
+#endif
+
 #endif /* __G_MACROS_H__ */