Skip to content
  • Emmanuele Bassi's avatar
    Add flexible API version boundaries · 34aeeb7d
    Emmanuele Bassi authored and Matthias Clasen's avatar Matthias Clasen committed
    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
    34aeeb7d