
@c %start of fragment

@node Versioning Macros
@chapter Versioning Macros
Versioning utility macros

@section Overview
Clutter offers a set of macros for checking the version of the library
at compile time; it also provides a function to perform the same check
at run time.

Clutter adds version information to both API deprecations and additions;
by definining the macros @samp{CLUTTER_VERSION_MIN_REQUIRED} and
@samp{CLUTTER_VERSION_MAX_ALLOWED}, you can specify the range of Clutter
versions whose API you want to use. Functions that were deprecated
before, or introduced after, this range will trigger compiler warnings.
For instance, if we define the following symbols:

@example 

  CLUTTER_VERSION_MIN_REQUIRED = CLUTTER_VERSION_1_6
  CLUTTER_VERSION_MAX_ALLOWED  = CLUTTER_VERSION_1_8
@end example

and we have the following functions annotated in the Clutter headers:

@example 

  void clutter_function_A (void) CLUTTER_DEPRECATED_IN_1_4;
  void clutter_function_B (void) CLUTTER_DEPRECATED_IN_1_6;
  void clutter_function_C (void) CLUTTER_AVAILABLE_IN_1_8;
  void clutter_function_D (void) CLUTTER_AVAILABLE_IN_1_10;
@end example

then any application code using the functions above will get the output:

@example 

  clutter_function_A: deprecation warning
  clutter_function_B: no warning
  clutter_function_C: no warning
  clutter_function_D: symbol not available warning
@end example

It is possible to disable the compiler warnings by defining the macro
@samp{CLUTTER_DISABLE_DEPRECATION_WARNINGS} before including the
clutter.h header.

@section Usage
@include defuns-clutter-version.xml.texi

@c %end of fragment
