GNOME.org
 

[clutter] Add flexible versioning scheme

commit 780a11b926ec8eacd58d9ba57be8d88beacdd726
Author: Emmanuele Bassi <ebassi linux intel com>
Date:   Mon Feb 27 14:59:00 2012 +0000

    Add flexible versioning scheme
    
    GLib introduced macros that allows defining the lower and upper bounds
    of the API to be used by application code.
    
    The lower bound allows to define the minimum version that will trigger
    deprecation warnings; the upper bound defines the maximum version that
    will trigger compiler warnings for unavailable symbols.
    
    This scheme allows gradually porting application code to a new version
    of the API, especially in case of resynchronization after multiple
    development cycles.

 clutter/clutter-macros.h     |  209 ++++++++++++++++++++++++++++++++++++++++--
 clutter/clutter-version.h.in |  108 ++++++++++++++--------
 2 files changed, 269 insertions(+), 48 deletions(-)
---
diff --git a/clutter/clutter-macros.h b/clutter/clutter-macros.h
index 8561ea3..2e70a6b 100644
--- a/clutter/clutter-macros.h
+++ b/clutter/clutter-macros.h
@@ -26,6 +26,72 @@
 #ifndef __CLUTTER_MACROS_H__
 #define __CLUTTER_MACROS_H__
 
+#include <clutter/clutter-version.h>
+
+/**
+ * CLUTTER_FLAVOUR:
+ *
+ * GL Windowing system used
+ *
+ * Since: 0.4
+ *
+ * Deprecated: 1.10: The macro evaluates to "deprecated" as Clutter can be
+ *   compiled with multiple windowing system backends. Use the various
+ *   CLUTTER_WINDOWING_* macros to detect the windowing system that Clutter
+ *   is being compiled against, and the type check macros for the
+ *   #ClutterBackend for a run-time check.
+ */
+#define CLUTTER_FLAVOUR         "deprecated"
+
+/**
+ * CLUTTER_COGL
+ *
+ * Cogl (internal GL abstraction utility library) backend. Can be "gl" or
+ * "gles" currently
+ *
+ * Since: 0.4
+ *
+ * Deprecated: 1.10: The macro evaluates to "deprecated" as Cogl can be
+ *   compiled against multiple GL implementations.
+ */
+#define CLUTTER_COGL            "deprecated"
+
+/**
+ * CLUTTER_STAGE_TYPE:
+ *
+ * The default GObject type for the Clutter stage.
+ *
+ * Since: 0.8
+ *
+ * Deprecated: 1.10: The macro evaluates to "deprecated" as Clutter can
+ *   be compiled against multiple windowing systems. You can use the
+ *   CLUTTER_WINDOWING_* macros for compile-time checks, and the type
+ *   check macros for run-time checks.
+ */
+#define CLUTTER_STAGE_TYPE      "deprecated"
+
+/**
+ * CLUTTER_NO_FPU:
+ *
+ * Set to 1 if Clutter was built without FPU (i.e fixed math), 0 otherwise
+ *
+ * @Deprecated: 0.6: This macro is no longer defined (identical code is used
+ *  regardless the presence of FPU).
+ */
+#define CLUTTER_NO_FPU          (0)
+
+/* some structures are meant to be opaque and still be allocated on the stack;
+ * in order to avoid people poking at their internals, we use this macro to
+ * ensure that users don't accidentally access a struct private members.
+ *
+ * we use the CLUTTER_COMPILATION define to allow us easier access, though.
+ */
+#ifdef CLUTTER_COMPILATION
+#define CLUTTER_PRIVATE_FIELD(x)        x
+#else
+#define CLUTTER_PRIVATE_FIELD(x)        clutter_private_ ## x
+#endif
+
 /* these macros are used to mark deprecated functions, and thus have to be
  * exposed in a public header.
  *
@@ -35,22 +101,151 @@
 #ifdef CLUTTER_DISABLE_DEPRECATION_WARNINGS
 #define CLUTTER_DEPRECATED
 #define CLUTTER_DEPRECATED_FOR(f)
+#define CLUTTER_UNAVAILABLE(maj,min)
 #else
 #define CLUTTER_DEPRECATED G_DEPRECATED
 #define CLUTTER_DEPRECATED_FOR(f) G_DEPRECATED_FOR(f)
+#define CLUTTER_UNAVAILABLE(maj,min) G_UNAVAILABLE(maj,min)
 #endif
 
-/* some structures are meant to be opaque and still be allocated on the stack;
- * in order to avoid people poking at their internals, we use this macro to
- * ensure that users don't accidentally access a struct private members.
+/**
+ * CLUTTER_VERSION_MIN_REQUIRED:
  *
- * we use the CLUTTER_COMPILATION define to allow us easier access, though.
+ * A macro that should be defined by the user prior to including the
+ * clutter.h header.
+ *
+ * The definition should be one of the predefined Clutter version macros,
+ * such as: %CLUTTER_VERSION_1_0, %CLUTTER_VERSION_1_2, ...
+ *
+ * This macro defines the lower bound for the Clutter API to be used.
+ *
+ * If a function has been deprecated in a newer version of Clutter, it
+ * is possible to use this symbol to avoid the compiler warnings without
+ * disabling warnings for every deprecated function.
+ *
+ * Since: 1.10
  */
-#ifdef CLUTTER_COMPILATION
-#define CLUTTER_PRIVATE_FIELD(x)        x
+#ifndef CLUTTER_VERSION_MIN_REQUIRED
+# define CLUTTER_VERSION_MIN_REQUIRED   (CLUTTER_VERSION_PREV_STABLE)
+#endif
+
+/**
+ * CLUTTER_VERSION_MAX_ALLOWED:
+ *
+ * A macro that should be define by the user prior to including the
+ * clutter.h header.
+ *
+ * The definition should be one of the predefined Clutter version macros,
+ * such as: %CLUTTER_VERSION_1_0, %CLUTTER_VERSION_1_2, ...
+ *
+ * This macro defines the upper bound for the Clutter API to be used.
+ *
+ * If a function has been introduced in a newer version of Clutter, it
+ * is possible to use this symbol to get compiler warnings when trying
+ * to use that function.
+ *
+ * Since: 1.10
+ */
+#ifndef CLUTTER_VERSION_MAX_ALLOWED
+# if CLUTTER_VERSION_MIN_REQUIRED > CLUTTER_VERSION_PREV_STABLE
+#  define CLUTTER_VERSION_MAX_ALLOWED   CLUTTER_VERSION_MIN_REQUIRED
+# else
+#  define CLUTTER_VERSION_MAX_ALLOWED   CLUTTER_VERSION_CUR_STABLE
+# endif
+#endif
+
+/* sanity checks */
+#if CLUTTER_VERSION_MAX_ALLOWED < CLUTTER_VERSION_MIN_REQUIRED
+# error "CLUTTER_VERSION_MAX_ALLOWED must be >= CLUTTER_VERSION_MIN_REQUIRED"
+#endif
+#if CLUTTER_VERSION_MIN_REQUIRED < CLUTTER_VERSION_1_0
+# error "CLUTTER_VERSION_MIN_REQUIRED must be >= CLUTTER_VERSION_1_0"
+#endif
+
+/* XXX: Every new stable minor release should add a set of macros here */
+
+#if CLUTTER_VERSION_MIN_REQUIRED >= CLUTTER_VERSION_1_0
+# define CLUTTER_DEPRECATED_IN_1_0              CLUTTER_DEPRECATED
+# define CLUTTER_DEPRECATED_IN_1_0_FOR(f)       CLUTTER_DEPRECATED_FOR(f)
 #else
-#define CLUTTER_PRIVATE_FIELD(x)        clutter_private_ ## x
+# define CLUTTER_DEPRECATED_IN_1_0
+# define CLUTTER_DEPRECATED_IN_1_0_FOR(f)
+#endif
+
+#if CLUTTER_VERSION_MAX_ALLOWED < CLUTTER_VERSION_1_0
+# define CLUTTER_AVAILABLE_IN_1_0               CLUTTER_UNAVAILABLE(1, 0)
+#else
+# define CLUTTER_AVAILABLE_IN_1_0
+#endif
+
+#if CLUTTER_VERSION_MIN_REQUIRED >= CLUTTER_VERSION_1_2
+# define CLUTTER_DEPRECATED_IN_1_2              CLUTTER_DEPRECATED
+# define CLUTTER_DEPRECATED_IN_1_2_FOR(f)       CLUTTER_DEPRECATED_FOR(f)
+#else
+# define CLUTTER_DEPRECATED_IN_1_2
+# define CLUTTER_DEPRECATED_IN_1_2_FOR(f)
+#endif
+
+#if CLUTTER_VERSION_MAX_ALLOWED < CLUTTER_VERSION_1_2
+# define CLUTTER_AVAILABLE_IN_1_2               CLUTTER_UNAVAILABLE(1, 2)
+#else
+# define CLUTTER_AVAILABLE_IN_1_2
+#endif
+
+#if CLUTTER_VERSION_MIN_REQUIRED >= CLUTTER_VERSION_1_4
+# define CLUTTER_DEPRECATED_IN_1_4              CLUTTER_DEPRECATED
+# define CLUTTER_DEPRECATED_IN_1_4_FOR(f)       CLUTTER_DEPRECATED_FOR(f)
+#else
+# define CLUTTER_DEPRECATED_IN_1_4
+# define CLUTTER_DEPRECATED_IN_1_4_FOR(f)
+#endif
+
+#if CLUTTER_VERSION_MAX_ALLOWED < CLUTTER_VERSION_1_4
+# define CLUTTER_AVAILABLE_IN_1_4               CLUTTER_UNAVAILABLE(1, 4)
+#else
+# define CLUTTER_AVAILABLE_IN_1_4
+#endif
+
+#if CLUTTER_VERSION_MIN_REQUIRED >= CLUTTER_VERSION_1_6
+# define CLUTTER_DEPRECATED_IN_1_6              CLUTTER_DEPRECATED
+# define CLUTTER_DEPRECATED_IN_1_6_FOR(f)       CLUTTER_DEPRECATED_FOR(f)
+#else
+# define CLUTTER_DEPRECATED_IN_1_6
+# define CLUTTER_DEPRECATED_IN_1_6_FOR(f)
+#endif
+
+#if CLUTTER_VERSION_MAX_ALLOWED < CLUTTER_VERSION_1_6
+# define CLUTTER_AVAILABLE_IN_1_6               CLUTTER_UNAVAILABLE(1, 6)
+#else
+# define CLUTTER_AVAILABLE_IN_1_6
 #endif
 
+#if CLUTTER_VERSION_MIN_REQUIRED >= CLUTTER_VERSION_1_8
+# define CLUTTER_DEPRECATED_IN_1_8              CLUTTER_DEPRECATED
+# define CLUTTER_DEPRECATED_IN_1_8_FOR(f)       CLUTTER_DEPRECATED_FOR(f)
+#else
+# define CLUTTER_DEPRECATED_IN_1_8
+# define CLUTTER_DEPRECATED_IN_1_8_FOR(f)
+#endif
+
+#if CLUTTER_VERSION_MAX_ALLOWED < CLUTTER_VERSION_1_8
+# define CLUTTER_AVAILABLE_IN_1_8               CLUTTER_UNAVAILABLE(1, 8)
+#else
+# define CLUTTER_AVAILABLE_IN_1_8
+#endif
+
+#if CLUTTER_VERSION_MIN_REQUIRED >= CLUTTER_VERSION_1_10
+# define CLUTTER_DEPRECATED_IN_1_10             CLUTTER_DEPRECATED
+# define CLUTTER_DEPRECATED_IN_1_10_FOR(f)      CLUTTER_DEPRECATED_FOR(f)
+#else
+# define CLUTTER_DEPRECATED_IN_1_10
+# define CLUTTER_DEPRECATED_IN_1_10_FOR(f)
+#endif
+
+#if CLUTTER_VERSION_MAX_ALLOWED < CLUTTER_VERSION_1_10
+# define CLUTTER_AVAILABLE_IN_1_10              CLUTTER_UNAVAILABLE(1, 10)
+#else
+# define CLUTTER_AVAILABLE_IN_1_10
+#endif
 
 #endif /* __CLUTTER_MACROS_H__ */
diff --git a/clutter/clutter-version.h.in b/clutter/clutter-version.h.in
index 13d9bdf..b6cd128 100644
--- a/clutter/clutter-version.h.in
+++ b/clutter/clutter-version.h.in
@@ -87,71 +87,97 @@ G_BEGIN_DECLS
                                  (CLUTTER_MINOR_VERSION << 16) | \
                                  (CLUTTER_MICRO_VERSION << 8))
 
+/* XXX - Every new stable minor release bump should add a macro here */
+
 /**
- * CLUTTER_CHECK_VERSION:
- * @major: major version, like 1 in 1.2.3
- * @minor: minor version, like 2 in 1.2.3
- * @micro: micro version, like 3 in 1.2.3
+ * CLUTTER_VERSION_1_0:
  *
- * Evaluates to %TRUE if the version of the Clutter library is greater
- * than @major, @minor and @micro
+ * A macro that evaluates to the 1.0 version of Clutter, in a format
+ * that can be used by the C pre-processor.
+ *
+ * Since: 1.10
  */
-#define CLUTTER_CHECK_VERSION(major,minor,micro) \
-        (CLUTTER_MAJOR_VERSION > (major) || \
-         (CLUTTER_MAJOR_VERSION == (major) && CLUTTER_MINOR_VERSION > (minor)) || \
-         (CLUTTER_MAJOR_VERSION == (major) && CLUTTER_MINOR_VERSION == (minor) && CLUTTER_MICRO_VERSION >= (micro)))
+#define CLUTTER_VERSION_1_0     (G_ENCODE_VERSION (1, 0))
 
 /**
- * CLUTTER_FLAVOUR:
- *
- * GL Windowing system used
+ * CLUTTER_VERSION_1_2:
  *
- * Since: 0.4
+ * A macro that evaluates to the 1.2 version of Clutter, in a format
+ * that can be used by the C pre-processor.
  *
- * Deprecated: 1.10: The macro evaluates to "deprecated" as Clutter can be
- *   compiled with multiple windowing system backends. Use the various
- *   CLUTTER_WINDOWING_* macros to detect the windowing system that Clutter
- *   is being compiled against, and the type check macros for the
- *   #ClutterBackend for a run-time check.
+ * Since: 1.10
  */
-#define CLUTTER_FLAVOUR         "@CLUTTER_FLAVOUR@"
+#define CLUTTER_VERSION_1_2     (G_ENCODE_VERSION (1, 2))
 
 /**
- * CLUTTER_COGL
+ * CLUTTER_VERSION_1_4:
  *
- * Cogl (internal GL abstraction utility library) backend. Can be "gl" or
- * "gles" currently
+ * A macro that evaluates to the 1.4 version of Clutter, in a format
+ * that can be used by the C pre-processor.
  *
- * Since: 0.4
- *
- * Deprecated: 1.10: The macro evaluates to "deprecated" as Cogl can be
- *   compiled against multiple GL implementations.
+ * Since: 1.10
  */
-#define CLUTTER_COGL            "@CLUTTER_COGL@"
+#define CLUTTER_VERSION_1_4     (G_ENCODE_VERSION (1, 4))
 
 /**
- * CLUTTER_STAGE_TYPE:
+ * CLUTTER_VERSION_1_6:
  *
- * The default GObject type for the Clutter stage. 
+ * A macro that evaluates to the 1.6 version of Clutter, in a format
+ * that can be used by the C pre-processor.
  *
- * Since: 0.8
+ * Since: 1.10
+ */
+#define CLUTTER_VERSION_1_6     (G_ENCODE_VERSION (1, 6))
+
+/**
+ * CLUTTER_VERSION_1_8:
  *
- * Deprecated: 1.10: The macro evaluates to "deprecated" as Clutter can
- *   be compiled against multiple windowing systems. You can use the
- *   CLUTTER_WINDOWING_* macros for compile-time checks, and the type
- *   check macros for run-time checks.
+ * A macro that evaluates to the 1.8 version of Clutter, in a format
+ * that can be used by the C pre-processor.
+ *
+ * Since: 1.10
  */
-#define CLUTTER_STAGE_TYPE @CLUTTER_STAGE_TYPE@
+#define CLUTTER_VERSION_1_8     (G_ENCODE_VERSION (1, 8))
 
 /**
- * CLUTTER_NO_FPU:
+ * CLUTTER_VERSION_1_10:
  *
- * Set to 1 if Clutter was built without FPU (i.e fixed math), 0 otherwise
+ * A macro that evaluates to the 1.10 version of Clutter, in a format
+ * that can be used by the C pre-processor.
  *
- * @Deprecated: 0.6: This macro is no longer defined (identical code is used
- *  regardless the presence of FPU).
+ * Since: 1.10
  */
-#define CLUTTER_NO_FPU          CLUTTER_NO_FPU_MACRO_WAS_REMOVED
+#define CLUTTER_VERSION_1_10    (G_ENCODE_VERSION (1, 10))
+
+/* evaluates to the current stable version; for development cycles,
+ * this means the next stable target
+ */
+#if (CLUTTER_MINOR_VERSION % 2)
+# define CLUTTER_VERSION_CUR_STABLE      (G_ENCODE_VERSION (CLUTTER_MAJOR_VERSION, CLUTTER_MINOR_VERSION + 1))
+#else
+# define CLUTTER_VERSION_CUR_STABLE      (G_ENCODE_VERSION (CLUTTER_MAJOR_VERSION, CLUTTER_MINOR_VERSION))
+#endif
+
+/* evaluates to the previous stable version */
+#if (CLUTTER_MINOR_VERSION % 2)
+# define CLUTTER_VERSION_PREV_STABLE     (G_ENCODE_VERSION (CLUTTER_MAJOR_VERSION, CLUTTER_MINOR_VERSION - 1))
+#else
+# define CLUTTER_VERSION_PREV_STABLE     (G_ENCODE_VERSION (CLUTTER_MAJOR_VERSION, CLUTTER_MINOR_VERSION - 2))
+#endif
+
+/**
+ * CLUTTER_CHECK_VERSION:
+ * @major: major version, like 1 in 1.2.3
+ * @minor: minor version, like 2 in 1.2.3
+ * @micro: micro version, like 3 in 1.2.3
+ *
+ * Evaluates to %TRUE if the version of the Clutter library is greater
+ * than @major, @minor and @micro
+ */
+#define CLUTTER_CHECK_VERSION(major,minor,micro) \
+        (CLUTTER_MAJOR_VERSION > (major) || \
+         (CLUTTER_MAJOR_VERSION == (major) && CLUTTER_MINOR_VERSION > (minor)) || \
+         (CLUTTER_MAJOR_VERSION == (major) && CLUTTER_MINOR_VERSION == (minor) && CLUTTER_MICRO_VERSION >= (micro)))
 
 /**
  * clutter_major_version:
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]