luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-10-02 19:59:21 +02:00
Code Issues Packages Projects Releases Wiki Activity

Add flexible API version boundaries

Browse Source 
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.

https://bugzilla.gnome.org/show_bug.cgi?id=670542
This commit is contained in:
Emmanuele Bassi
2012-02-20 16:20:15 +00:00
committed by Matthias Clasen
parent d70634526d
commit 34aeeb7d64
10 changed files with 284 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
glib/docs.c
View File

@@ -2019,6 +2019,38 @@
* Since: 2.32
*/
/**
* G_DEPRECATED:
*
* This macro is similar to %G_GNUC_DEPRECATED, and can be used to mark
* functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED, it is
* meant to be portable across different compilers and must be placed
* before the function declaration.
*
* Since: 2.32
*/
/**
* G_DEPRECATED_FOR:
*
* This macro is similar to %G_GNUC_DEPRECATED_FOR, and can be used to mark
* functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED_FOR, it is
* meant to be portable across different compilers and must be placed
* before the function declaration.
*
* Since: 2.32
*/
/**
* G_UNAVAILABLE:
*
* This macro can be used to mark a function declaration as unavailable.
* It must be placed before the function declaration. Use of a function
* that has been annotated with this macros will produce a compiler warning.
*
* Since: 2.32
*/
/**
* G_GNUC_NORETURN:
*